Document supported targets and host runtime behavior

CONTRIBUTING.md

@@ -57,7 +57,7 @@ CI separates source validation, cross-target compilation, and native execution.
 Every example is compiled for each target declared in `platform/main.roc`:
 `x64mac`, `arm64mac`, `x64win`, `x64musl`, and `arm64musl`. Target-specific
 binary artifacts are then downloaded and executed on matching native runners;
-`arm64musl` remains compile-only until an arm64 Linux runner is available.
+this includes `arm64musl`, which runs on an arm64 Linux runner.
 
 The operations can also be run independently:
 

README.md

@@ -9,6 +9,48 @@ A Roc [platform](https://github.com/roc-lang/roc/wiki/Roc-concepts-explained#pla
 
 `basic-cli` supports command execution, directories, environment variables, files, HTTP, locales, paths, random seeds, sleeping, SQLite, standard input/output/error, TCP, terminal raw mode, and UTC time.
 
+## Supported targets
+
+The platform builds and runs on these targets in CI:
+
+| Roc target | Operating system | Architecture |
+| --- | --- | --- |
+| `x64mac` | macOS | x86-64 |
+| `arm64mac` | macOS | ARM64 |
+| `x64musl` | Linux (musl) | x86-64 |
+| `arm64musl` | Linux (musl) | ARM64 |
+| `x64win` | Windows | x86-64 |
+
+Other targets are not currently supported. In particular, Windows support is
+x86-64 only.
+
+## Host runtime behavior
+
+These current host-level limitations may affect application design:
+
+- HTTP and HTTPS use HTTP/1 only. [Issue #455](https://github.com/roc-lang/basic-cli/issues/455)
+  tracks research into HTTP/2 support and its tradeoffs.
+- HTTPS certificates are validated against bundled WebPKI roots, not the
+  operating system trust store. A certificate trusted only through a locally
+  installed OS root will therefore be rejected. [Issue #454](https://github.com/roc-lang/basic-cli/issues/454)
+  tracks research into the appropriate trust configuration for basic-cli.
+- The timeout configured on an HTTP `Request` covers the request and response;
+  `NoTimeout` leaves it unbounded. Responses are buffered completely without a
+  configurable size limit ([issue #436](https://github.com/roc-lang/basic-cli/issues/436)),
+  and several network and TLS failures currently use a generic transport error
+  ([issue #438](https://github.com/roc-lang/basic-cli/issues/438)).
+- TCP connect, read, and write operations have no caller-configurable timeouts.
+  They can block until the operation completes or the operating system returns
+  an error. `Tcp.Stream.read_until!` and `read_line!` also have no size limit and
+  buffer until the delimiter or EOF. [Issue #437](https://github.com/roc-lang/basic-cli/issues/437)
+  tracks timeout and bounded-read APIs.
+- SQLite caches one connection per database path for the life of the process.
+  Reusing a path reuses its connection, so repeated use of `:memory:` accesses
+  the same in-memory database. Using many distinct paths retains all of those
+  connections. Prepared statements are finalized after their last reference is
+  dropped, but the cached connections remain open. [Issue #435](https://github.com/roc-lang/basic-cli/issues/435)
+  tracks connection ownership and cleanup.
+
 ## Examples
 
 The [examples](examples/) directory contains executable, application-shaped CLI

platform/Cmd.roc

@@ -166,7 +166,7 @@ Cmd :: {
 	new_str = |program| new(OsStr.from_str(program))
 
 	## Add a single argument to the command.
-	## ❗ Shell features like variable subsitition (e.g. `$FOO`), glob patterns (e.g. `*.txt`), ... are not available.
+	## ❗ Shell features like variable substitution (e.g. `$FOO`), glob patterns (e.g. `*.txt`), ... are not available.
 	##
 	## ```roc
 	## cmd = Cmd.new("ls").arg("-l")
@@ -182,7 +182,7 @@ Cmd :: {
 	arg_str = |cmd, a| arg(cmd, OsStr.from_str(a))
 
 	## Add multiple arguments to the command.
-	## ❗ Shell features like variable subsitition (e.g. `$FOO`), glob patterns (e.g. `*.txt`), ... are not available.
+	## ❗ Shell features like variable substitution (e.g. `$FOO`), glob patterns (e.g. `*.txt`), ... are not available.
 	##
 	## ```roc
 	## cmd = Cmd.new("ls").args(["-l", "-a"])

platform/Http.roc

@@ -8,6 +8,9 @@ import http.Response
 ## [`roc-lang/http`](https://github.com/roc-lang/http) `Request` and `Response`
 ## types. This module supplies effects and small JSON/UTF-8 conveniences while
 ## leaving pure request and response construction to that package.
+##
+## See the [host runtime behavior](https://github.com/roc-lang/basic-cli#host-runtime-behavior)
+## for HTTP protocol, TLS trust-store, and timeout details.
 Http :: [].{
 
 	## Errors raised by the host while sending a request, before a real HTTP

platform/Sqlite.roc

@@ -16,6 +16,8 @@ import Path
 ## `Stmt`, and `ErrCode` types below; raw host ABI records remain internal.
 ##
 ## Database paths use basic-cli's byte-preserving `Path` type.
+## See the [host runtime behavior](https://github.com/roc-lang/basic-cli#host-runtime-behavior)
+## for connection caching and lifetime details.
 Sqlite :: [].{
 
 	## A value accepted by a SQLite binding or returned from a column.

platform/Stdin.roc

@@ -17,7 +17,7 @@ Stdin :: [].{
 	## This function can read no more than 16,384 bytes at a time. Use [read_to_end!] if you need more.
 	##
 	## > This is typically used in combination with [Tty.enable_raw_mode!],
-	## which disables defaults terminal bevahiour and allows reading input
+	## which disables default terminal behaviour and allows reading input
 	## without buffering until Enter key is pressed.
 	bytes! : () => Try(List(U8), [EndOfFile, StdinErr(IOErr), ..])
 	bytes! = || widen_stdin_eof_err(Host.stdin_bytes!())

platform/Tcp.roc

@@ -1,6 +1,9 @@
 import Host
 
 ## Connect to TCP servers and exchange buffered byte streams.
+##
+## See the [host runtime behavior](https://github.com/roc-lang/basic-cli#host-runtime-behavior)
+## for current timeout and buffering limitations.
 Tcp :: [].{
 
 	## Represents a TCP stream.

platform/Tty.roc

@@ -4,7 +4,7 @@ import Host
 ## This is useful for running an app like vim or a game in the terminal.
 Tty :: [].{
 
-	## Enable terminal [raw mode](https://en.wikipedia.org/wiki/Terminal_mode) to disable some default terminal bevahiour.
+	## Enable terminal [raw mode](https://en.wikipedia.org/wiki/Terminal_mode) to disable some default terminal behaviour.
 	##
 	## This leads to the following changes:
 	## - Input will not be echoed to the terminal screen.