# TCP, TLS and HTTP

Network functions return a `Result` and take timeouts in milliseconds.

- With `--deny-net` (or `--sandbox`), every DNS lookup, connect and listen returns an error that begins with `denied: --deny-net`, before any DNS query. With `--deny-fs`, a TLS call that names a file (a CA file, a certificate or a key) returns `denied: --deny-fs`.
- Sockets, listeners, clients and servers are handles: `IO.inspect` prints `<TCP.Socket>`, they cannot be compared, and they close when the program ends.
- A handle belongs to the task that opened it and closes when that task ends, so open it in the task that keeps it. [Task.spawn_owning](https://www.agentica-lang.com/agentica/library/concurrency/task/index.md#taskspawn_owning) gives one to a new task.
- Timeouts are positive milliseconds, up to the largest `Int`, taken as given: `0` or a negative one returns `network: timeout must be positive milliseconds`. A timeout covers the whole call, including the wait for another task using the same socket. After a timeout during active I/O the socket is closed, and later calls fail at once with `network: socket is closed`; a timeout while only waiting for a lock keeps it open.

## DNS

### DNS.lookup

```signature
DNS.lookup(host: String, timeout_ms: Int = 30000) -> Result[List[String]]
```

The addresses of a host name from the system resolver, the one `TCP.connect` uses, so the hosts file and the platform's DNS settings apply. Every IPv4 and IPv6 address comes as text (`"127.0.0.1"`, `"::1"`), in the resolver's order and without duplicates. An IP address gives itself, an IPv6 one in its short form. A name that does not resolve is an error that begins with `network: host not found`, followed by the host and the resolver's reason. An empty name or one that holds a NUL is an error, and so is a timeout (`network: operation timed out`). Only the task waits; a cancelled task stops waiting, and the lookup ends in the background.

```agentica
def main() -> Void
  IO.inspect(DNS.lookup("127.0.0.1"))
  IO.inspect(DNS.lookup("2001:DB8:0:0:0:0:0:1"))
  IO.inspect(DNS.lookup(""))
end
```

```output
ok(["127.0.0.1"])
ok(["2001:db8::1"])
error("network: the host name is empty", kind: "argument")
```

## TCP

### TCP.listen and TCP.local_port

```signature
TCP.listen(host: String, port: Int) -> Result[TCP.Listener]
TCP.local_port(listener: TCP.Listener) -> Int
```

Port `0` picks a free port, and `local_port` tells which (ports are 0 to 65535 here, 1 to 65535 in `connect`). A host that holds a NUL is an error. The listener takes every address the host name stands for: `"localhost"` accepts `127.0.0.1` and `::1`.

```agentica
def main() -> Void
  listener = TCP.listen("127.0.0.1", 0).unwrap!
  puts(TCP.local_port(listener) > 0)
  TCP.close_listener(listener)
end
```

```output
true
```

### TCP.connect and TCP.accept

```signature
TCP.connect(host: String, port: Int, timeout_ms: Int) -> Result[TCP.Socket]
TCP.accept(listener: TCP.Listener, timeout_ms: Int) -> Result[TCP.Socket]
```

`connect` opens a connection to a server. `accept` waits for the next client of a listener.

### TCP.remote_address

```signature
TCP.remote_address(socket: TCP.Socket) -> String
```

The IP address of the other side, without the port: `"127.0.0.1"` or `"::1"`, like Rack's `REMOTE_ADDR`. An IPv4 client of an IPv6 listener shows as IPv4 (`"127.0.0.1"`, not `"::ffff:127.0.0.1"`). The IPv6 scope id is dropped, so link-local peers (`fe80::...`) on different interfaces can look the same. A closed socket gives `""`. TLS sockets have it too.

```agentica
def main() -> Void
  listener = TCP.listen("127.0.0.1", 0).unwrap!
  client = TCP.connect("127.0.0.1", TCP.local_port(listener), 2000).unwrap!
  server = TCP.accept(listener, 2000).unwrap!
  puts(TCP.remote_address(server))
  TCP.close(server)
  IO.inspect(TCP.remote_address(server))
  TCP.close(client)
  TCP.close_listener(listener)
end
```

```output
127.0.0.1
""
```

### TCP.send and TCP.read_line

```signature
TCP.send(socket: TCP.Socket, text: String, timeout_ms: Int) -> Result[Void]
TCP.read_line(socket: TCP.Socket, timeout_ms: Int) -> Result[String]
```

`send` writes UTF-8 text and flushes. `read_line` reads one line without its line ending (LF or CRLF).

- A last line without a line ending counts when the other side closes.
- `read_line` errors at the end of input, when the connection breaks (even mid-line), and for a line over 1 MiB (which also closes the socket).
- TCP is a byte stream: one `send` can arrive in several reads and one `read_line` can cover several sends. A character split between reads is joined before the UTF-8 check.

A program that talks to itself, with a task as the server:

```agentica
def echo_once(listener: TCP.Listener) -> Result[Void]
  client = try TCP.accept(listener, 2000)
  line = try TCP.read_line(client, 2000)
  try TCP.send(client, "echo: #{line}\n", 2000)
  TCP.close(client)
  ok()
end

def main() -> Void
  listener = TCP.listen("127.0.0.1", 0).unwrap!
  server = Task.spawn(&echo_once, listener)
  socket = TCP.connect("127.0.0.1", TCP.local_port(listener), 2000).unwrap!
  _ = TCP.send(socket, "hello\n", 2000)
  puts(TCP.read_line(socket, 2000))
  puts(Task.await(server))
  TCP.close(socket)
  TCP.close_listener(listener)
end
```

```output
ok("echo: hello")
ok()
```

### TCP.send_bytes and TCP.recv_bytes

```signature
TCP.send_bytes(socket: TCP.Socket, bytes: Bytes, timeout_ms: Int) -> Result[Void]
TCP.recv_bytes(socket: TCP.Socket, max_bytes: Int, timeout_ms: Int) -> Result[Bytes]
TCP.recv_bytes(socket: TCP.Socket, max_bytes: Int) -> Result[Bytes]
```

Raw bytes, as [`Bytes`](https://www.agentica-lang.com/agentica/library/data-structures/bytes/index.md). `send_bytes` takes at most 1 MiB per call. `recv_bytes` takes a `max_bytes` from 1 to 1048576 and gives what has arrived, up to `max_bytes`, and empty `Bytes` when the other side has closed.

Without `timeout_ms`, `recv_bytes` waits with no limit, until bytes arrive, the other side closes or the task is cancelled. A server uses it for the next request of an idle client: a timeout would close the socket and so disconnect the client. A cancelled read takes nothing, and the bytes that arrive later go to the next read.

### TCP.write and TCP.flush

```signature
TCP.write(socket: TCP.Socket, text: String, timeout_ms: Int) -> Result[Void]
TCP.write_bytes(socket: TCP.Socket, bytes: Bytes, timeout_ms: Int) -> Result[Void]
TCP.flush(socket: TCP.Socket, timeout_ms: Int) -> Result[Void]
TCP.write_limit(socket: TCP.Socket, bytes: Int) -> Result[Void]
```

`write` takes the bytes and returns without waiting for the other side: what the system does not take at once waits in the socket's write buffer and goes out in the background, in the order of the writes. A task that sends to many sockets uses it so that one slow reader does not hold back the others. `write_bytes` is the same for `Bytes`, at most 1 MiB per call.

- A write waits only when it leaves more bytes in the buffer than the limit, and then until half of the limit has gone out. The limit is 65536 bytes; `write_buffer` sets it for one socket, from 1024 to 16777216.
- `flush` waits until the buffer is empty. `send` after a write goes behind the waiting bytes and returns when they are all out, so `send` is a write and a flush.
- When a buffered write fails, `flush` and every later write on the socket return the error of the failed write. A `timeout_ms` that ends closes the socket, as for `send`.
- `TCP.close`, the end of the task that owns the socket and the end of the run send the bytes that still wait before the connection closes. They wait for them at most the flush limit of the run (`--flush-timeout`, 30 seconds by default), and a closed socket whose peer does not read keeps its buffer and its descriptor for that long. Bytes that are still unsent at the limit are dropped, and so are the bytes of a connection that the peer resets and those that wait when a stop signal ends the run; the run prints a warning with their count on standard error when it ends. A program that must know whether the bytes went out calls `flush`, which returns the error.
- The limit is not the most memory a socket's buffer can take: each task that writes to the socket can leave one call's bytes (up to 1 MiB for `write_bytes`) over it, and the bytes are copied once more while they go out.
- A TLS socket buffers its records the same way.

```agentica
def read_two(listener: TCP.Listener) -> Result[String]
  client = try TCP.accept(listener, 2000)
  first = try TCP.read_line(client, 2000)
  second = try TCP.read_line(client, 2000)
  TCP.close(client)
  ok("#{first} #{second}")
end

def main() -> Void
  listener = TCP.listen("127.0.0.1", 0).unwrap!
  reader = Task.spawn(&read_two, listener)
  socket = TCP.connect("127.0.0.1", TCP.local_port(listener), 2000).unwrap!
  _ = TCP.write(socket, "one\n", 2000)
  _ = TCP.write(socket, "two\n", 2000)
  puts(TCP.flush(socket, 2000))
  puts(Task.await(reader))
  TCP.close(socket)
  TCP.close_listener(listener)
end
```

```output
ok()
ok("one two")
```

### TCP.close and TCP.close_listener

```signature
TCP.close(socket: TCP.Socket) -> Void
TCP.close_listener(listener: TCP.Listener) -> Void
```

Closing twice is fine. Close early only when it must not wait for the task to end. `TCP.close` returns at once; bytes of the write buffer still go out ([TCP.write](https://www.agentica-lang.com/agentica/library/io-and-system/network/index.md#tcpwrite-and-tcpflush)).

## TLS

```signature
TLS.alpn(socket: TCP.Socket) -> String
TLS.client_context(options: TLS.ClientOptions) -> Result[TLS.Context]
TLS.server_context(options: TLS.ServerOptions) -> Result[TLS.Context]
TLS.connect(host: String, port: Int, context: TLS.Context, timeout_ms: Int) -> Result[TCP.Socket]
TLS.listen(host: String, port: Int, context: TLS.Context) -> Result[TCP.Listener]
TLS.upgrade(socket: TCP.Socket, context: TLS.Context, host: String, timeout_ms: Int) -> Result[TCP.Socket]
```

```text
struct TLS.ClientOptions
  ca_file: String = ""
  cert_file: String = ""
  key_file: String = ""
  alpn: List[String] = []
end

struct TLS.ServerOptions
  cert_file: String
  key_file: String
  alpn: List[String] = []
end
```

A `TLS.Context` is the TLS setup of one role, built once and shared by every socket, listener and HTTP client made from it. `HTTP.ClientOptions` holds one, so `JSON.schema`, `JSON.decode` and `JSON.encode` refuse it. TLS sockets and listeners use the same `TCP` functions, with the same limits and timeouts.

- `TLS.client_context` and `TLS.server_context` read and check the PEM files when they run, so a bad file fails there, not at each connect. A file that changes later does not change the context: build a new one.
- `TLS.connect` takes a client context and `TLS.listen` a server context; the other role stops the program with `RUNTIME-TLS-CONTEXT-ROLE`. A context stays valid while a socket or listener made from it is open.
- `TLS.connect` uses TLS 1.2 or later and always checks the certificate and the host name (an IP address host against the certificate's IP addresses).
- An empty `ca_file` uses the system's trusted certificates, read once per process, with the ones the system distrusts rejected. `SSL_CERT_FILE` replaces the store, `SSL_CERT_DIR` adds a directory. A nonempty `ca_file` is a PEM file that replaces them; a missing or empty file fails `TLS.client_context`.

  | System | Store |
  |---|---|
  | Linux | the CA bundle |
  | macOS | the system roots and Keychain trust settings |
  | Windows | the ROOT store (intermediates from its CA store help build a chain but are never roots) |

- A server context needs PEM files for the certificate chain and the private key, and fails when a file is bad or the key does not match.
- `alpn` lists the protocols that ALPN negotiates in the handshake (`["h2", "http/1.1"]`), for a library that speaks HTTP/2 or gRPC on a TLS socket. A client offers them; a server picks the first of its own that the client offers too, and refuses the handshake when none is in common (a client that offers none gets none). `TLS.alpn(socket)` returns the protocol picked, or `""`. Each name is 1 to 255 bytes and the list at most 65535 bytes (each name takes one byte more), checked when the context is built. `HTTP.client`, `HTTP.start` and `HTTP.serve_tls` speak HTTP/1.1 only: a context whose `alpn` is not `[]` or `["http/1.1"]` stops the program with `RUNTIME-TLS-CONTEXT-ALPN`.
- A client context sends a client certificate when `cert_file` and `key_file` name PEM files, checked as for a server. Leave both empty to send none; giving only one is an error.
- A peer that closes without TLS's closing message ends the stream like EOF.

A client that speaks HTTP/2 offers it first and reads which protocol the server picked:

```agentica
def protocol(host: String) -> Result[String]
  context = try TLS.client_context(TLS.ClientOptions(alpn: ["h2", "http/1.1"]))
  socket = try TLS.connect(host, 443, context, 5000)
  ok(TLS.alpn(socket))
end
```

### TLS.upgrade

`TLS.upgrade` starts TLS on an open TCP socket, for protocols that begin in plain text (SMTP and IMAP `STARTTLS`, PostgreSQL's `SSLRequest`). It returns a new TLS socket.

- With a client context it is the client side and checks `host` as `TLS.connect` does. With a server context it is the server side and `host` must be `""`; another host stops the program with `RUNTIME-TLS-CONTEXT-ROLE`.
- Once its arguments pass their checks, the plain socket is closed for the program, whether the handshake works or not: a later call on it returns `network: socket is closed`.
- Bytes that arrived and were not read yet fail the upgrade (`network: data came before the TLS handshake`): STARTTLS forbids them. A send still in progress on the socket fails it too. With several schedulers, an upgrade while another task reads the socket may fail with `network: a read on the socket is in progress`, and the plain socket then stays open: it depends on timing (that read is inside its receive from the kernel). Upgrade in the task that reads the socket.
- The handshake runs within `timeout_ms`; a timeout closes the connection. A TLS socket cannot be upgraded again.

An SMTP client reads each reply to its last line, so no byte is left before the handshake:

```agentica
# An SMTP reply, up to its last line: "250-" goes on, "250 " ends it.
def reply(socket: TCP.Socket) -> Result[String]
  line = try TCP.read_line(socket, 5000)
  while line.slice(3, 1) == "-"
    line = try TCP.read_line(socket, 5000)
  end

  ok(line)
end

def starttls(host: String, context: TLS.Context) -> Result[TCP.Socket]
  plain = try TCP.connect(host, 587, 5000)
  try reply(plain)
  try TCP.send(plain, "EHLO client.example\r\n", 5000)
  try reply(plain)
  try TCP.send(plain, "STARTTLS\r\n", 5000)
  ready = try reply(plain)
  return error(ready) if !ready.start_with?("220")

  TLS.upgrade(plain, context, host, 5000)
end
```

```agentica
def main() -> Void
  context = TLS.client_context(TLS.ClientOptions()).unwrap!
  socket = TLS.connect("example.com", 443, context, 5000).unwrap!
  _ = TCP.send(socket, "HEAD / HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n", 5000)
  puts(TCP.read_line(socket, 5000))
  TCP.close(socket)
end
```

## HTTP client

HTTP is the `std/http` library, written in Agentica: `import HTTP from "std/http"` (without it, `CHECK-UNKNOWN-NAME`). It works the same on Linux, macOS and Windows, over HTTP and HTTPS.

- Every call of the client is whole: it returns after the whole response arrived (for a body read piece by piece, see [`HTTP.start`](https://www.agentica-lang.com/agentica/library/io-and-system/network/index.md#httpstart-httpsend_request-httpread_body-and-httpfinish), and for a body on a channel, [`HTTP.open`](https://www.agentica-lang.com/agentica/library/io-and-system/network/index.md#httpopen-and-httpupload)). The body is `Bytes`, exactly as it came (any content, up to `max_body_bytes`); it is not decompressed. [`HTTP.text`](https://www.agentica-lang.com/agentica/library/io-and-system/network/index.md#httptext) decodes it in its charset.
- Status codes such as 404 or 500 are normal responses. `error` results are a bad URL, a refused connection, a timeout, or a body over the limit. Protocol errors start with `http: `, connection errors keep their TCP or TLS text, and a timeout is `network: operation timed out`.
- `GET`, `HEAD`, `OPTIONS`, `PUT` and `DELETE` are retried once on a new connection, within the same timeout, when the server had closed a reused connection and no response byte arrived. Other methods are never retried.
- Header names must be HTTP tokens, values Latin-1 text without control characters.
- `HTTP.Request`, `HTTP.Response`, `HTTP.Header`, `HTTP.ClientOptions`, `HTTP.ServerOptions`, `HTTP.Client` and `HTTP.Server` are builtin types that `std/http` re-exports, so `import {Request, Response} from "std/http"` binds them by name. A diagnostic, `help` and a printed value show the `HTTP.` names: a response prints as `HTTP.Response(status: ...)` and a client as `<HTTP.Client>`. They reserve no name: a program may declare its own `Header` or `HttpRequest`.

### HTTP.client

```signature
HTTP.client(options: HTTP.ClientOptions = HTTP.ClientOptions()) -> Result[HTTP.Client]
HTTP.close_client(client: HTTP.Client) -> Void
HTTP.proxy_from_env(url: String) -> String
```

A client reuses open connections for the same scheme, host and port. Every field of `HTTP.ClientOptions` has the default below, so `HTTP.ClientOptions(timeout_ms: 5000)` changes one and keeps the others, and `HTTP.client()` uses them all.

| Option | Default | Limit |
|---|---|---|
| `timeout_ms` | 30 s, for each whole call | positive |
| `idle_timeout_ms` | 30 s, for kept connections | positive |
| `max_connections` | 4, per host | positive, at most 65536 |
| `max_body_bytes` | 1 MiB | positive, at most 64 MiB |
| `proxy` | `""`: no proxy | an `http://host:port` origin, see below |
| `tls` | `none`: the system's CA certificates | a client `TLS.Context` |

- Calls wait in FIFO order for a `max_connections` slot. A call in flight when `close_client` runs fails with `http: client is closed` (unless a connection had already started sending it).
- `proxy` is an `http://host:port` origin with no path or query, else the call is an `error`. `http://` requests go to it in absolute form and share its connections; an `https://` request opens a `CONNECT` tunnel (one per target host and port) and speaks TLS to the target inside it, verified as without a proxy. This holds for `HTTP.client` and every call that takes a client or options.
- User info in the URL (`http://user:password@proxy:8080`, percent-decoded) is sent as `Proxy-Authorization: Basic` to the proxy only, unless the call sets that header; in an `https` call your own header goes to the target. No error shows the user info, and a `Connection` from `HTTP.start` prints its proxy without it, but the options you built still hold it, so keep them out of logs.
- A `407` is `http: the proxy HOST:PORT refused the credentials (407)` (or `requires credentials` when the URL has none); another status to a `CONNECT` is `http: the proxy HOST:PORT refused the tunnel to HOST:PORT (STATUS)`. Inside the tunnel, any status of the target is a normal response.
- A client never reads the environment: pass `HTTP.proxy_from_env(url)`, which returns the proxy the environment names for `url`, or `""` for none. It follows curl: `http_proxy` or `https_proxy` by the scheme, the lower-case name winning even when set and empty; `HTTP_PROXY` ignored when `REQUEST_METHOD` is set (httpoxy); `ALL_PROXY` not read; `no_proxy` (or `NO_PROXY`) a comma or space list of `*`, domains, optional `:port`, IP literals and IPv4 CIDR ranges (IPv6 ranges are not read; empty and invalid entries are ignored; a trailing dot of a host or an entry does not count). A value without `://` is read as `http://`; an invalid `url` gives `""`.
- The client runs as Agentica code in its own tasks, so it spends the run's `--max-steps` budget.

```agentica
import HTTP from "std/http"

def main() -> Void
  client = HTTP.client(HTTP.ClientOptions(timeout_ms: 5000, max_connections: 2)).unwrap!
  HTTP.close_client(client)
end
```

Clients that trust the same CA file share one context: build it once and pass it to each.

```agentica
import HTTP from "std/http"

def main() -> Void
  tls = TLS.client_context(TLS.ClientOptions(ca_file: "ca.pem")).unwrap!
  client = HTTP.client(HTTP.ClientOptions(tls: some(tls))).unwrap!
  HTTP.close_client(client)
end
```

### HTTP.get, HTTP.post and HTTP.request

```signature
HTTP.get(client: HTTP.Client, url: String) -> Result[HTTP.Response]
HTTP.post(client: HTTP.Client, url: String, body: Bytes, headers: List[HTTP.Header] = []) -> Result[HTTP.Response]
HTTP.request(client: HTTP.Client, method: String, url: String, body: Bytes, headers: List[HTTP.Header] = []) -> Result[HTTP.Response]
HTTP.get_response(url: String, options: HTTP.ClientOptions = HTTP.ClientOptions()) -> Result[HTTP.Response]
HTTP.post_response(url: String, body: Bytes, headers: List[HTTP.Header] = [], options: HTTP.ClientOptions = HTTP.ClientOptions()) -> Result[HTTP.Response]
```

- `HTTP.Response` has `status`, `headers` (names in lowercase) and `body`, which is `Bytes`. `post` sends a `Bytes` body, as Ruby's `Net::HTTP.post(uri, data, header)` does, and `request` takes any method. Send text as `"text".bytes`, and no body as `"".bytes`. The body is at most `max_body_bytes`, and `headers` default to `[]`.
- For one request use `get_response` and `post_response`, like Ruby's `Net::HTTP.get_response` and `Net::HTTP.post`: each makes a client with `options`, makes the call and closes the client and its connection before it returns, so it needs no `client` and no `close_client`. For many requests use one `HTTP.client()` with `get`, `post` and `request`, which reuses connections; calling `get_response` in a loop opens a connection each time, and over HTTPS also builds a new TLS context and loads the CA bundle each time.
- URLs start with `http://` or `https://`. A bracketed host (`http://[::1]:8080/`) must look like an IPv6 address, else an error result.
- The client adds `Host` and `Content-Length`; a request may not set them, nor `Transfer-Encoding` or `Connection`.

```agentica
import HTTP from "std/http"

def main() -> Void
  client = HTTP.client().unwrap!
  headers = [HTTP.Header(name: "Content-Type", value: "application/json")]
  case HTTP.post(client, "http://localhost:8080/items", "{\"name\":\"tea\"}".bytes, headers)
    ok(created) -> puts("#{created.status} #{HTTP.text(created.body, created.headers).unwrap!}")
    error(e) -> IO.warn(e.message)
  end

  deleted = HTTP.request(client, "DELETE", "http://localhost:8080/items/1", "".bytes)
  puts(deleted.ok?)
  HTTP.close_client(client)
end
```

One request, with no client to open or close:

```agentica
import HTTP from "std/http"

def main() -> Void
  case HTTP.get_response("http://localhost:8080/items", HTTP.ClientOptions(timeout_ms: 5000))
    ok(response) -> puts("#{response.status} #{HTTP.text(response.body, response.headers).unwrap!}")
    error(e) -> IO.warn(e.message)
  end
end
```

### HTTP.text

```signature
HTTP.text(body: Bytes, headers: List[HTTP.Header] = []) -> Result[String]
```

Decodes a body as text. Pass the `headers` of the same message: the body is read in the `charset` of its `Content-Type` (any case, quoted or not), and as UTF-8 when there is none. The charsets are the encodings of [`Bytes.decode`](https://www.agentica-lang.com/agentica/library/data-structures/bytes/index.md#decode): UTF-8, UTF-16, UTF-32, ASCII, Latin-1 (`iso-8859-1`), ISO-8859-15 and Windows-1252, by any of their names. A body that is not valid in its charset is an `error` result (with the byte offset, except for UTF-8), and any other charset (`shift_jis`, `koi8-r`) is an `error` that names it. Other charsets belong to the planned `agentica-lang/charset` package.

```agentica
import HTTP from "std/http"

def main() -> Void
  utf8 = [HTTP.Header(name: "content-type", value: "text/plain; charset=UTF-8")]
  latin1 = [HTTP.Header(name: "content-type", value: "text/plain; charset=iso-8859-1")]
  koi8 = [HTTP.Header(name: "content-type", value: "text/plain; charset=koi8-r")]
  puts(HTTP.text("café".bytes, utf8).unwrap!)
  puts(HTTP.text("caf".bytes + Bytes.from_list([233]).unwrap!, latin1).unwrap!)
  puts(HTTP.text("caf".bytes, koi8).ok?)
  puts(HTTP.text(Bytes.from_list([255, 0, 128]).unwrap!).ok?)
end
```

```output
café
café
false
false
```

### HTTP.header_values

```signature
HTTP.header_values(headers: List[HTTP.Header], name: String) -> List[String]
```

Finds every value of a header, in order. It ignores case.

```agentica
import HTTP from "std/http"

def main() -> Void
  headers = [HTTP.Header(name: "set-cookie", value: "a=1"), HTTP.Header(name: "Set-Cookie", value: "b=2")]
  puts(HTTP.header_values(headers, "Set-Cookie"))
end
```

```output
["a=1", "b=2"]
```

### HTTP.download

```signature
HTTP.download(client: HTTP.Client, url: String, path: String, options: DownloadOptions = DownloadOptions()) -> Result[Download]
```

- `DownloadOptions` has `timeout_ms`, for the whole call, and `max_total_bytes`, for the body, at most 256 MiB. `DownloadOptions()`, the default, gives 30 s and 256 MiB. `Download` has `status`, `headers` and `bytes_written`; the body itself is in the file, never in the record.
- A printed `Download` takes the alias the program imports `std/http` with, while a builtin record keeps its fixed name: with `import H from "std/http"`, it prints as `H.Download(status: 200, headers: [HTTP.Header(...)], ...)`.
- The download sends a `GET` and streams the body to `path`, so bodies may be arbitrary bytes. The file never grows past `max_total_bytes`.
- The file must not exist: it is made private to the user, so an existing path fails untouched, while a failed download keeps the partial file. Status codes such as 404 are normal responses whose body is still written, so check `status` before using the file.
- The connection is not pooled: it closes when the download ends. There is no redirect follow, and `https` keeps certificate verification on.

```agentica
import HTTP from "std/http"

def main() -> Void
  client = HTTP.client().unwrap!
  case HTTP.download(client, "http://localhost:8080/asset", "asset.bin")
    ok(saved) -> puts("#{saved.status} #{saved.bytes_written}")
    error(e) -> IO.warn(e.message)
  end

  HTTP.close_client(client)
end
```

### HTTP.start, HTTP.send_request, HTTP.read_body and HTTP.finish

```signature
HTTP.start(origin: String, options: HTTP.ClientOptions = HTTP.ClientOptions()) -> Result[HTTP.Connection]
HTTP.send_request(conn: HTTP.Connection, method: String, target: String, body: Bytes, headers: List[HTTP.Header] = []) -> Result[HTTP.ResponseHead]
HTTP.read_body(conn: HTTP.Connection, max_bytes: Int = 65536) -> Result[Bytes]
HTTP.finish(conn: HTTP.Connection) -> Void
```

One connection that the program drives itself, outside the pool, as Ruby's `Net::HTTP.start`, `send_request`, `read_body` and `finish` do (and Python's `http.client.HTTPConnection`). Use it to read a body piece by piece, as it arrives (a big file, a log that never ends, lines of a stream), or to control the connection: which requests go on one socket, and when it closes. For whole responses use `get` and the pooled client, which are simpler.

- `start` takes an origin (`http://host`, `https://host:8443`) with no path or query, and connects now. `https` verifies the certificate with `options.tls` (the system trust when `none`, built again for each `start`, so a program that opens many connections passes `tls: some(context)`). Only `timeout_ms`, `max_body_bytes`, `tls` and `proxy` of the options apply: `timeout_ms` is the time of each call (the connect, each `send_request`, each `read_body`), and `max_body_bytes` the largest request body.
- `send_request` sends the request and returns when the head of the response has been read: `HTTP.ResponseHead` has `status` and `headers` (names in lowercase). `target` is the path and query (`/items?page=2`). `Host` and `Content-Length` are added; the rules for headers are those of `HTTP.request`. An interim `1xx` head is read past.
- `read_body` waits for at least one byte and gives at most `max_bytes` (1 to 1 MiB) of the body, decoded (a chunked body has no framing in it). An empty `Bytes` is the end of the body. A `Content-Length` body is held to its length, a chunked one to its framing, and a body that runs to the close of the connection must end with a clean close (over TLS, the peer's `close_notify`). A response body is at most 256 MiB, the limit of `download`, whatever its framing. A response to `HEAD`, a `204`, a `304` and one with `Content-Length: 0` have no body: the connection is ready at once, with no `read_body` needed (a `read_body` gives the empty end piece).
- After a body has been read to its end, the connection is ready for the next `send_request`, unless the server closed it (`Connection: close`, HTTP/1.0 or a body that ran to the close): then `send_request` is `error("http: the connection is closed")`. The end comes with the last byte, so a program that knows the length may stop reading before the empty piece. The connection is also closed when input is left after the body (a server that sent a second response in the same write, or bytes after the last chunk): reading its answer for the next request would be wrong. A request while the last body is still being read is an `error`, and the connection stays as it was.
- A failure of the connection (a cut body, a bad chunk, a timeout, a response body over the limit, a write that fails) is an `error` and ends it. A request that is refused before anything is written (a bad method, header or target, a body over `max_body_bytes`) is an `error` too, and the connection stays as it was. A server that closed an idle connection shows as an `error` of the next `send_request`: `start` a new one; nothing is retried.
- `finish` closes the socket, drops a body not read to its end, and may be called twice. The connection belongs to the task that opened it (as a socket does), and one call at a time uses it: a second call at once is `error("http: the connection is in use by another call")`.
- There is no redirect follow, cookie or decompression: a program that needs them loops over `send_request`.

```agentica
import HTTP from "std/http"

def main() -> Void
  conn = HTTP.start("http://localhost:8080").unwrap!
  head = HTTP.send_request(conn, "GET", "/log", "".bytes).unwrap!
  puts(head.status)
  total = 0
  while true
    piece = HTTP.read_body(conn, 4096).unwrap!
    break if piece.empty?

    total = total + piece.size
  end

  puts(total)
  next_head = HTTP.send_request(conn, "GET", "/other", "".bytes)
  puts(next_head.ok?)
  HTTP.finish(conn)
end
```

### HTTP.open and HTTP.upload

```signature
HTTP.open(method: String, url: String, body: Bytes, headers: List[HTTP.Header] = [], options: HTTP.ClientOptions = HTTP.ClientOptions()) -> Result[HTTP.Stream]
HTTP.upload(method: String, url: String, body: Channel[Bytes], length: Int = -1, headers: List[HTTP.Header] = [], options: HTTP.ClientOptions = HTTP.ClientOptions()) -> Result[HTTP.Response]
```

The two forms for a body that goes through a channel, so that another task can use it as it comes: a download that is too big to hold, an endless one (events, the lines of a log), or an upload that is produced as it goes. Each call uses a connection of its own, outside the pool, built on [`HTTP.start`](https://www.agentica-lang.com/agentica/library/io-and-system/network/index.md#httpstart-httpsend_request-httpread_body-and-httpfinish). A call whose whole body fits in memory is simpler with `get`, `post` and `request`.

- `open` sends the request and returns at the head of the response: `HTTP.Stream` has `status`, `headers`, `body` (a `Channel[Bytes]`) and `done` (a `Task[Result[Void]]`). A task feeds `body` with the pieces of the response (at most 64 KiB, never empty, a chunked body already decoded) and closes it on every path. `url` has a path and a query; `method`, `body` and `headers` are those of `request`.
- The reader runs the usual receive loop until the closed error, then awaits `done`: `ok` means the body ended cleanly, and an `error` says why it did not (a cut body, a timeout, a body over 256 MiB). A channel can only end, so `done` is the only way to tell a complete body from a cut one: always await it.
- To stop early, close `body`: the feeding task's next `send` fails, it closes the connection and `done` is `error("channel: closed")`. That works only while data flows. On a quiet stream (a server that has nothing to say) the task waits in its read until `timeout_ms`, so the prompt stop is `Task.cancel(stream.done)`: it closes the connection at once and `done` is an error.
- `options.timeout_ms` is the time of each wait of `open`: the connect, the head, each read of the body and each `send` to the channel. A reader that takes longer than that to ask for the next piece ends the stream, and so does a server that is silent for that long: raise it for events that come rarely. The channel holds 8 pieces, so a slow reader makes the task wait and the server's data wait in the socket.
- `upload` sends the pieces that another task puts in `body`, until it closes the channel, and returns the whole response (as `request`: up to `max_body_bytes`). `method` is `POST`, `PUT` or `PATCH`. `length` is the exact number of bytes, said as `Content-Length`: the body ends when that many bytes were sent, and the producer need not close the channel. `-1` is a chunked body, whose pieces become chunks (a piece over 512 KiB is several, and pieces that wait in the channel together share one, under 64 KiB plus one piece) and which ends when the channel closes. A body that is longer than `length`, or a channel that closes short of it, is an `error`, and so is a channel that is silent for longer than `timeout_ms`.
- A channel that closes ends the body, also when its producer died: a producer that can fail should set `length`, so that a short body is an `error`. `upload` closes the channel when it returns, so a producer that is still sending finds the closed error and stops.
- A server that answers and closes before the upload ends (a `413`) does not hide its answer: when a write fails, `upload` reads the head of the response that is waiting (for at most `timeout_ms`) and returns that response, as Python's `http.client` and Go do. Only when there is none is the write failure the `error` (`http: ` and the reason): on Windows a reset connection can drop the server's early answer, so `upload` returns the write error there. Nothing is retried, and neither call follows redirects.

```agentica
import HTTP from "std/http"

def produce(into: Channel[Bytes]) -> Void
  _ = into.send("line 1\n".bytes, 1000)
  _ = into.send("line 2\n".bytes, 1000)
  into.close
end

def main() -> Void
  stream = HTTP.open("GET", "http://localhost:8080/log", "".bytes).unwrap!
  total = 0
  while true
    case stream.body.recv(5000)
      ok(piece) -> total = total + piece.size
      error(_) -> break
    end
  end

  puts(total)
  puts(Task.await(stream.done).ok?)
  lines: Channel[Bytes] = Channel.new(2)
  Task.spawn(&produce, lines)
  response = HTTP.upload("PUT", "http://localhost:8080/log", lines).unwrap!
  puts(response.status)
end
```

## HTTP server

The server is in `std/http` too. `serve` serves every kind of route on one port: pages, files sent in pieces, uploads and WebSockets. It runs one task per connection, with keep-alive.

### HTTP.serve

```signature
HTTP.serve(host: String, port: Int, app: HTTP.App, options: HTTP.ServerOptions = HTTP.ServerOptions()) -> Result[HTTP.Server]
HTTP.serve_tls(host: String, port: Int, tls: TLS.Context, app: HTTP.App, options: HTTP.ServerOptions = HTTP.ServerOptions()) -> Result[HTTP.Server]
HTTP.app(handler: HTTP.Handler, max_body_bytes: Int = 1048576) -> HTTP.App
HTTP.local_port(server: HTTP.Server) -> Int
```

- `serve` returns at once and serves in the background; `serve_tls` does the same over TLS with a server `TLS.Context` (`TLS.server_context`). Port 0 picks a free port (`local_port`).
- The app, an `HTTP.App`, decides for each request how to read the body and how to answer. `HTTP.App` is `Fn[HTTP.Request, HTTP.RequestBody, Result[HTTP.Answer]]`: it gets the request with an empty `body` and the body on a channel ([request bodies](https://www.agentica-lang.com/agentica/library/io-and-system/network/index.md#request-bodies)).
- `HTTP.Answer` is an enum. `Answer.Whole(response)` answers with an `HTTP.Response`. `Answer.Stream(response)` sends an `HTTP.StreamResponse`, whose body arrives on a channel ([streamed responses](https://www.agentica-lang.com/agentica/library/io-and-system/network/index.md#streamed-responses-and-server-sent-events)). `Answer.Upgrade(upgrade)` takes what [`accept_websocket`](https://www.agentica-lang.com/agentica/library/io-and-system/network/index.md#websockets) returns: its `Accept` runs the WebSocket on the connection, and its `Reply` is sent as `Whole`.
- `HTTP.app(handler, max_body_bytes)` makes an `App` from a `Handler`, for routes that take the request whole. It reads the body first, at most `max_body_bytes` (1 MiB unless given, whatever the server's cap; a negative limit counts as 0), and calls `handler` with it. A body that is larger, by its `Content-Length` or as it arrives, gets a `413`, a chunk line or trailer section over the head limits a `431`, and a bad chunk a `400`. These answers come with `Connection: close`, and `handler` is not called. A body that is cut or stalls (the client left, a timeout) closes the connection.
- `HTTP.Request` has `method`, `target` (as sent, with the query), `path` (before `?`), `headers` (names in lowercase), `body` (`Bytes`, exactly as the client sent it, whichever the framing; decode text with [`HTTP.text`](https://www.agentica-lang.com/agentica/library/io-and-system/network/index.md#httptext) and `request.headers`) and `remote_addr`, the client's IP address without the port (`"127.0.0.1"`, `"::1"`, as [`TCP.remote_address`](https://www.agentica-lang.com/agentica/library/io-and-system/network/index.md#tcpremote_address) gives it; Rack's `REMOTE_ADDR`). The server fills `remote_addr`; behind a proxy it is the proxy's address. It defaults to `""` in `HTTP.Request(...)`.

A server that fetches its own page:

```agentica
import HTTP from "std/http"

def handle(request: HTTP.Request) -> Result[HTTP.Response]
  if request.method == "GET" and request.path == "/"
    return ok(
      HTTP.Response(
        status: 200,
        headers: [HTTP.Header(name: "Content-Type", value: "text/plain; charset=utf-8")],
        body: "hello".bytes,
      ),
    )
  end

  ok(HTTP.Response(status: 404, headers: [], body: "not found".bytes))
end

def main() -> Void
  server = HTTP.serve("127.0.0.1", 0, HTTP.app(&handle)).unwrap!
  client = HTTP.client().unwrap!
  base = "http://127.0.0.1:#{HTTP.local_port(server)}"
  response = HTTP.get(client, base + "/").unwrap!
  puts("#{response.status} #{HTTP.text(response.body, response.headers).unwrap!}")
  puts(HTTP.get(client, base + "/missing").unwrap!.status)
  HTTP.close_client(client)
  HTTP.close_server(server)
end
```

```output
200 hello
404
```

The server adds `Content-Length` (not on 204 and 304, whose body must be empty), a `Date` header unless the handler set one, and `Connection: close` when the request or response asked for it. `HEAD` gets the headers without the body.

A server with a page, a file sent in pieces, an upload and a WebSocket on one port:

```agentica
import HTTP from "std/http"

def page(request: HTTP.Request) -> Result[HTTP.Response]
  ok(HTTP.Response(status: 200, headers: [], body: "hello".bytes))
end

def produce(pieces: Channel[Bytes]) -> Void
  for n in 1..4
    break if not Result.ok?(pieces.send("part #{n}\n".bytes, 5000))
  end

  pieces.close
end

def file() -> HTTP.Answer
  pieces: Channel[Bytes] = Channel.new(2)
  Task.spawn(&produce, pieces)
  HTTP.Answer.Stream(HTTP.StreamResponse(status: 200, headers: [], body: pieces, length: some(28)))
end

def upload(body: HTTP.RequestBody) -> Result[HTTP.Answer]
  total = 0
  while true
    case body.pieces.recv(5000)
      ok(piece) -> total = total + piece.size
      error(_) -> break
    end
  end

  try Task.await(body.done)
  ok(HTTP.Answer.Whole(HTTP.Response(status: 200, headers: [], body: "#{total} bytes".bytes)))
end

def echo(ws: HTTP.WebSocket) -> Result[Void]
  while true
    case ws.incoming.recv(60000)
      ok(HTTP.Message.Text(text)) -> try ws.outgoing.send(HTTP.Message.Text(text), 5000)
      ok(HTTP.Message.Close(_, _)) -> return ok()
      ok(_) -> next
      error(_) -> return ok()
    end
  end

  ok()
end

def route(request: HTTP.Request, body: HTTP.RequestBody) -> Result[HTTP.Answer]
  return ok(HTTP.Answer.Upgrade(try HTTP.accept_websocket(request, &echo))) if request.path == "/ws"

  return ok(file()) if request.path == "/file"

  return upload(body) if request.path == "/upload"

  HTTP.app(&page).call(request, body)
end

def main() -> Void
  server = HTTP.serve("127.0.0.1", 8080, &route).unwrap!
  HTTP.wait(server).unwrap!
end
```

#### Handler and middleware

`HTTP.Handler` is the type of a route that takes the request whole: `Fn[HTTP.Request, Result[HTTP.Response]]`. `HTTP.App` is the type of the app of `serve`. They are type aliases, so `&handle` is a `Handler` when `handle` has that shape, and a framework can hold, store and return handlers by that name.

A middleware is a function from a `Handler` to a `Handler`: it wraps the next handler, and may change the request before it, or the response after it, or answer without calling it. A [lambda](https://www.agentica-lang.com/agentica/tour/blocks/index.md#lambdas) that captures the next handler is the new one. Middlewares stack by calling one with another's result. A middleware of an `App` is a function from an `App` to an `App` in the same way.

```agentica
import HTTP from "std/http"

def hello(request: HTTP.Request) -> Result[HTTP.Response]
  ok(HTTP.Response(status: 200, headers: [], body: "hello".bytes))
end

def log_answer(next: HTTP.Handler, request: HTTP.Request) -> Result[HTTP.Response]
  response = next.call(request)
  case response
    ok(answer) -> puts("#{request.method} #{request.path} #{answer.status}")
    error(_) -> puts("#{request.method} #{request.path} failed")
  end

  response
end

# Logs the request line and the status of the answer; an error of the next handler passes through unchanged.
def logged(next: HTTP.Handler) -> HTTP.Handler = ->(request) { log_answer(next, request) }

def authorized(next: HTTP.Handler, request: HTTP.Request) -> Result[HTTP.Response]
  if HTTP.header_values(request.headers, "authorization").empty?
    return ok(HTTP.Response(status: 401, headers: [], body: "".bytes))
  end

  next.call(request)
end

# Answers 401 to a request without an Authorization header, and does not call the next handler.
def guarded(next: HTTP.Handler) -> HTTP.Handler = ->(request) { authorized(next, request) }

def main() -> Void
  app = logged(guarded(&hello))
  open = HTTP.Request(method: "GET", target: "/", path: "/", headers: [], body: "".bytes)
  signed = HTTP.Request(
    method: "GET",
    target: "/",
    path: "/",
    headers: [HTTP.Header(name: "authorization", value: "token")],
    body: "".bytes,
  )

  _ = app.call(open)
  _ = app.call(signed)
end
```

```output
GET / 401
GET / 200
```

App and handler errors:

- An app or handler returning `error(message)` gives the client a 500 with an empty body and closes the connection. stderr gets `http: handler error: <message>`.
- A response that cannot be sent gets the same 500 and close, with `http: invalid response: <reason>` on stderr: status outside 200 to 599, a bad header, a `Content-Length` or `Transfer-Encoding` header, or a body with 204 or 304.
- A runtime error in an app or handler ends only its connection. The program goes on but exits with code 1 at the end, as for any unawaited task crash.

Every field of `HTTP.ServerOptions` has the default below, so `HTTP.ServerOptions(max_connections: 16)` changes one, and a call without `options` uses them all. The same checks as the client options apply.

| Option | Default | Bounds |
|---|---|---|
| `request_timeout_ms` | 30 s | the first request on a connection, each whole request from its first byte, and the sending of each response (the app has no time limit) |
| `idle_timeout_ms` | 30 s | the wait between requests on a kept connection |
| `max_connections` | 128 | connections over it wait until one closes |
| `max_body_bytes` | 1 MiB | at most 256 MiB; a body read whole takes about four times this in memory per connection, so lower `max_connections` when you raise it |

Bad requests never reach the app: the server answers and closes the connection.

| Status | Cause |
|---|---|
| 400 | malformed |
| 413 | a body over `max_body_bytes` |
| 417 | an `Expect` other than `100-continue` |
| 431 | headers too long or too many |
| 501 | `CONNECT`, or an `Upgrade` other than a WebSocket handshake |
| 505 | not `HTTP/1.1` |

Before closing, the server drops up to 256 KiB of the peer's remaining input, so the answer is not lost to a reset. A client still sending a large body after a 413 may see a connection reset instead.

### Request bodies

```signature
HTTP.read_all(body: HTTP.RequestBody, max_bytes: Int) -> Result[Bytes]
HTTP.body_refusal(message: String) -> HTTP.Answer
```

The app gets the body on a channel, so an upload too big to hold, or one the app stores as it comes (a file), never has to be in memory whole. It is the server side of [`HTTP.upload`](https://www.agentica-lang.com/agentica/library/io-and-system/network/index.md#httpopen-and-httpupload).

- `HTTP.RequestBody` has `pieces` (a `Channel[Bytes]`) and `done` (a `Task[Result[Void]]`). A task of the server feeds `pieces` with the body as it arrives (up to 64 KiB each, never empty, a chunked body already decoded) and closes it on every path. A request with no body gets a closed channel at once.
- The app runs the usual receive loop until the closed error, then awaits `done`: `ok` means the whole body arrived, and an `error` says why it did not (the client left, a bad chunk, a timeout, a body over the cap). A channel can only end, so `done` is the only way to tell a whole body from a cut one: always await it. When `done` is cancelled, by `close_server` or by the app itself, it is `error("task: cancelled")` and the request gets no answer: the connection closes. To stop an upload early, answer (a `413`, say) without reading the rest and without cancelling `done`: the server sends the answer and closes the connection.
- The channel holds 8 pieces. An app that reads slowly makes the server wait, and the client's data waits in the socket, so memory stays bounded.
- Every body is at most `max_body_bytes` of `options` (1 MiB by default; raise it, up to 256 MiB, for uploads). `HTTP.app` keeps its own limit (1 MiB unless given), so a route under it that takes larger bodies raises both. A request whose `Content-Length` is larger gets a `413` before the app runs, with no `100 Continue` first, so a client that waits for it never sends the body. A chunked body that grows past the cap ends `done` with the error of `read_all`, which `HTTP.app` answers `413`.
- `Expect: 100-continue` within the cap is answered with `100` before the app runs, so an app cannot refuse an upload before the client sends the body.
- `request_timeout_ms` is the wait of each step (each read of the socket, and each piece the app has not taken), not the time of the whole upload.
- The connection serves the next request only when the whole body had arrived by the time the app returned, read or not: a request with no body or an empty chunked body keeps it. Otherwise (an app that answers first, with a `413` or a `401`, or a body that failed) the answer gets `Connection: close` and the connection closes after it, so a client still sending may see the close before it reads the answer.
- `HTTP.read_all(body, max_bytes)` collects the body for a route that wants it whole: it returns the pieces joined as a `Result[Bytes]`, or an `error` when the body is longer than `max_bytes` or the cap, or did not arrive whole (it awaits `done`).
- `HTTP.body_refusal(message)` is the answer for that error: `413` for a body over its limit, `431` for a chunk line or trailer section over the head limits, and `400` for any other (a bad chunk, a body cut or stalled), a whole response with `Connection: close` and no body. `HTTP.app` answers so for a `Handler`; a route that reads the body itself returns `ok(HTTP.body_refusal(message))`, as the stream route below does.

A server that counts an upload, and the client call that streams one to it:

```agentica
import HTTP from "std/http"

def count(request: HTTP.Request, body: HTTP.RequestBody) -> Result[HTTP.Answer]
  total = 0
  while true
    case body.pieces.recv(5000)
      ok(piece) -> total = total + piece.size
      error(_) -> break
    end
  end

  try Task.await(body.done)
  ok(HTTP.Answer.Whole(HTTP.Response(status: 200, headers: [], body: "#{total} bytes".bytes)))
end

def feed(into: Channel[Bytes]) -> Void
  _ = into.send("hello ".bytes, 1000)
  _ = into.send("world".bytes, 1000)
  into.close
end

def main() -> Void
  server = HTTP.serve("127.0.0.1", 0, &count).unwrap!
  into: Channel[Bytes] = Channel.new(2)
  Task.spawn(&feed, into)
  url = "http://127.0.0.1:#{HTTP.local_port(server)}/"
  response = HTTP.upload("PUT", url, into).unwrap!
  puts("#{response.status} #{HTTP.text(response.body, response.headers).unwrap!}")
  HTTP.close_server(server)
end
```

```output
200 11 bytes
```

### Streamed responses and Server-Sent Events

```signature
HTTP.whole(data: Bytes) -> Channel[Bytes]

HTTP.StreamResponse(status: Int, headers: List[HTTP.Header], body: Channel[Bytes], length: Optional[Int] = none)
```

For a body that is not ready when the handler returns: events, tokens as a model makes them, a big file. The app answers `Answer.Stream` with a `StreamResponse` whose `body` is a [channel](https://www.agentica-lang.com/agentica/library/concurrency/task/index.md), and a task it started sends the pieces and closes the channel at the end.

- The server sends the head at once, then each piece as it arrives, as one flushed chunk (`Transfer-Encoding: chunked`), and ends the body when the channel closes. Pieces that wait in the channel together go out as one chunk (under 64 KiB plus one piece), so a client must not take a chunk for a piece. The app sets neither `Content-Length` nor `Transfer-Encoding`. The pieces are `Bytes`, sent as they are with no UTF-8 check, so a stream can carry a file or any binary data (a piece over 512 KiB is split into several chunks). An empty piece is skipped.
- A body whose size is known up front (a big file read in pieces) sets `length: some(n)`. The head then has `Content-Length: n` and the pieces go out raw, with no chunk framing. A body that ends short of `n`, or a piece that would pass `n`, closes the connection, so the client sees an incomplete body and never reads past the length. The body ends as soon as `n` bytes are sent, without waiting for the channel to close, so the connection serves the next request at once: the server closes the channel then, and a producer that goes on gets `error("channel: closed")` and stops. A piece after the body is full is not read; a piece that crosses `n` is the cut above. A closed body whose size is not `n` is the 500 of an invalid response, as is a `length` on a 204 or 304 answer. `HEAD` gets the head with the length and no body.
- A route that answers with one text or file uses `body: HTTP.whole(data)`, a closed channel holding that `Bytes` (`"text".bytes` for a text). The server then sends `Content-Length`, as for a whole response. It does the same for any body that is already closed when the app returns.
- The server reads the connection for the whole stream. When the client's input ends (it left, or it only half-closed its sending side) or a send fails, the server closes the channel, so the producer's next `send` returns `error("channel: closed")` and it stops. A producer that sends rarely can look at `body.closed?` as well. The body is then cut without its last chunk, so the client sees an incomplete body, not a finished one. Only the producer closing the channel ends the body cleanly.
- The producer must close the channel on every path. A producer that never closes it holds the stream until the client leaves: there is no maximum age.
- Bytes the client sends during the stream (a pipelined request) are dropped, and the connection closes when the stream ends; the server keeps watching, so a client that leaves later is still noticed.
- A bounded channel (`Channel.new(8)`) is the backpressure: a client that reads slowly makes the server wait, and so the producer's `send` waits.
- A slow producer is not an error. The wait for the next piece has no time limit, and `idle_timeout_ms` counts only between requests, from the end of a stream. `request_timeout_ms` bounds the send of each piece (and of a whole body sent with `Content-Length`): a client that stops reading for that long is cut off, and the channel closes.
- `HEAD` gets the head and the channel closes at once. A 204 or 304 status with a body that is still open, or any other response that cannot be sent, is the same 500 as for a whole response, and the channel closes.
- A body that is still coming when the app answers closes the connection after the stream, as for every answer. A stream route that takes a body reads it first, and answers a body it cannot read with [`HTTP.body_refusal`](https://www.agentica-lang.com/agentica/library/io-and-system/network/index.md#request-bodies), as `HTTP.app` does:

```agentica
import HTTP from "std/http"

def echoed(data: Bytes) -> HTTP.Answer
  HTTP.Answer.Stream(HTTP.StreamResponse(status: 200, headers: [], body: HTTP.whole(data)))
end

def handle(request: HTTP.Request, body: HTTP.RequestBody) -> Result[HTTP.Answer]
  case HTTP.read_all(body, 65536)
    ok(data) -> ok(echoed(data))
    error(e) -> ok(HTTP.body_refusal(e.message))
  end
end

def main() -> Void
  server = HTTP.serve("127.0.0.1", 8080, &handle).unwrap!
  HTTP.wait(server).unwrap!
end
```

- The server speaks HTTP/1.1 only: an HTTP/1.0 request gets a 505 before the app runs.

Server-Sent Events are a stream with `Content-Type: text/event-stream` whose pieces are `data: ...` lines ended by a blank line:

```agentica
import HTTP from "std/http"

def produce(events: Channel[Bytes]) -> Void
  for n in 1..3
    break if not Result.ok?(events.send("data: tick #{n}\n\n".bytes, 5000))

    Task.sleep(100)
  end

  events.close
end

def handle(request: HTTP.Request, body: HTTP.RequestBody) -> Result[HTTP.Answer]
  if request.method == "GET" and request.path == "/events"
    events: Channel[Bytes] = Channel.new(8)
    Task.spawn(&produce, events)
    headers = [
      HTTP.Header(name: "Content-Type", value: "text/event-stream"),
      HTTP.Header(name: "Cache-Control", value: "no-cache"),
    ]

    return ok(HTTP.Answer.Stream(HTTP.StreamResponse(status: 200, headers: headers, body: events)))
  end

  ok(HTTP.Answer.Whole(HTTP.Response(status: 404, headers: [], body: "not found\n".bytes)))
end

def main() -> Void
  server = HTTP.serve("127.0.0.1", 0, &handle).unwrap!
  client = HTTP.client().unwrap!
  base = "http://127.0.0.1:#{HTTP.local_port(server)}"
  response = HTTP.get(client, base + "/events").unwrap!
  puts(HTTP.header_values(response.headers, "transfer-encoding"))
  puts(HTTP.text(response.body, response.headers).unwrap!)
  puts(HTTP.get(client, base + "/missing").unwrap!.status)
  HTTP.close_client(client)
  HTTP.close_server(server)
end
```

```output
["chunked"]
data: tick 1

data: tick 2

data: tick 3


404
```

`HTTP.get` waits for the whole body, so the client above sees the events together; a browser's `EventSource` or `curl -N` sees each one as it is sent.

### WebSockets

```signature
HTTP.accept_websocket(request: HTTP.Request, session: HTTP.WebSocketSession, options: HTTP.WebSocketOptions = HTTP.WebSocketOptions()) -> Result[HTTP.Upgrade]
HTTP.prepare(message: HTTP.Message) -> HTTP.Message
```

`serve` upgrades a request to a WebSocket (RFC 6455) when the app answers `Answer.Upgrade` with what `accept_websocket` returns. `HTTP.Upgrade` is an enum: `Upgrade.Accept(...)` upgrades the request, and `Upgrade.Reply(response)` answers it as a whole response (and the connection serves the next request); make an `Accept` with `accept_websocket`, never by hand.

- `accept_websocket(request, session, options)` checks the handshake: a `GET` with `Upgrade: websocket`, `Connection: Upgrade`, `Sec-WebSocket-Version: 13` and a `Sec-WebSocket-Key` that is 16 bytes in base64. A request that is not one gets an `Upgrade.Reply`: `426` with `Sec-WebSocket-Version: 13` for another version, `400` for the rest. The head reader lets only a `GET` with one `Upgrade: websocket` through, so any other `Upgrade` (`h2c`, a `POST`) is a `501`. A route that does not call `accept_websocket` ignores the headers and answers as usual.
- A WebSocket handshake reaches every app; a route that does not upgrade answers it as any other request.
- `session` is a `HTTP.WebSocketSession`, `Fn[HTTP.WebSocket, Result[Void]]`. The server writes the `101` answer and runs it in the task of the connection. When it returns, the server sends a close frame (code 1000, or 1011 and a warning for an `error`) unless the session already sent one, waits for the peer's close frame, and closes the connection.
- An upgrade needs the whole body first. An `Accept` while the body is still unread gets a `500` and a close, with `http: invalid response: ...` on stderr.
- `HTTP.WebSocket` has `incoming` and `outgoing`, both `Channel[HTTP.Message]`, `incoming` of 8 messages and `outgoing` of `outgoing_queue` (8 by default), and `protocol`, the subprotocol that was agreed on (`""` for none). A session that does not read makes the server stop reading the socket, and one that sends faster than the peer reads waits in `send`. A session must keep taking messages from `incoming` (or end): while it does not, the server does not read the socket, so pings and the peer's close go unanswered. `incoming` closes after the `Close` message, and `outgoing` closes when the connection is over, so a send then is an `error`.
- `HTTP.Message` is `Text(String)`, `Binary(Bytes)`, `Ping(Bytes)`, `Pong(Bytes)`, `Close(Int, String)`, the code and the reason, and `Prepared(Bytes)`, which only a session sends. A received `Text` or `Binary` is a whole message: the fragments are joined, and a text message is checked as UTF-8. The server answers every received ping with a pong and does not hand it on (the pong goes out behind what the session already queued in `outgoing`, up to `outgoing_queue` messages, and a session that closed its own `outgoing` may get no pongs); a `Pong` is handed on. A `Ping` or `Pong` carries at most 125 bytes (more is cut).
- A `Close` is the last message the session receives, whatever ended the connection: the peer's close frame with its code and reason, a frame that broke the rules (the code of the answer: 1002, 1007 or 1009), or the loss of the connection (code 1006, since no close frame came). When the peer stops reading, the session hears its close only after the write in progress ends (the peer's read, or `request_timeout_ms` of `HTTP.ServerOptions`). Sending `Close(code, reason)` starts the close handshake; a code that cannot be sent (below 1000, 1004 to 1006, 1015 to 2999, past 4999) is sent as 1011, and a reason is cut to 123 bytes.
- The server checks every frame of the peer: it must be masked, with no reserved bit, a known opcode, a control frame whole and of at most 125 bytes, fragments in order, text as UTF-8 and a close code that a peer may send. A broken frame is answered with a close frame (1002 protocol error, 1007 invalid data, 1009 too big) and the connection ends. The server never masks its frames and accepts no extension, so nothing is compressed.
- `HTTP.WebSocketOptions` has `max_message_bytes` (default 1 MiB, 1 to 256 MiB: a message past it, in one frame or joined from fragments, closes with 1009, and a frame that announces it is refused before its payload is read), `idle_ms` (default 0, no limit but a year, since a read that times out closes the socket: the longest the server waits for the peer to send anything, after which the connection is dropped and the session gets `Close` with 1006), `ping_ms` (default 0, none: the server sends a ping after that many milliseconds with nothing to write, so with `ping_ms` below `idle_ms` the pongs keep a live peer), `close_ms` (default 5000: how long the server waits for the peer's answer to its close frame), `protocols` (the subprotocols it speaks, in order of preference: the first one the client offered in `Sec-WebSocket-Protocol` is agreed on) and `outgoing_queue` (default 8, 1 to 1048576: how many messages `outgoing` holds before a `send` waits, or fails after its timeout). The server writes the messages queued in `outgoing` at that moment in one socket write, in order, and stops reading the queue for it once 64 KiB are reached (a bigger message goes whole), so a bigger `outgoing_queue` lets a broadcaster that sends straight to many sockets' `outgoing` channels deliver in fewer writes, at the cost of the memory of the queued messages.
- `HTTP.prepare(message)` frames a `Text` or `Binary` message once and returns it as `Prepared`; any other message comes back as it is. A broadcaster sends the one `Prepared` message on the `outgoing` channel of every subscriber, and each server writes its bytes as they are, so the message is not framed for every socket. The peer receives the same frame as for the message itself. The writer checks only the frame's head, so the payload is trusted as `prepare` made it (a text payload is not checked as UTF-8 again). A `Prepared` message whose bytes are not a frame `prepare` made closes the connection with 1011, with a warning on stderr. A `case` on a received `HTTP.Message` never sees `Prepared`, but still needs an arm for it or `_`.
- `request_timeout_ms` of `HTTP.ServerOptions` bounds the handshake and each write of a frame. A WebSocket counts against `max_connections` for as long as it lives. `idle_timeout_ms` does not apply after the upgrade.
- The server does not check `Origin`. A browser sends it with every handshake, and an app that serves pages of its own should compare it with `HTTP.header_values(request.headers, "origin")` before it accepts, since a page of another site can open a WebSocket to it with the visitor's cookies.
- Known limit: the mask of a frame is taken off in a loop over the bytes, at about 7 MB/s, so a message of a few MiB costs a fraction of a second of its connection's task. Keep `max_message_bytes` at what the application needs.

An echo server that mixes a plain route and a WebSocket route:

```agentica
import HTTP from "std/http"

def relay(ws: HTTP.WebSocket, message: HTTP.Message) -> Result[Bool]
  case message
    HTTP.Message.Text(text) ->
      try ws.outgoing.send(HTTP.Message.Text("echo: #{text}"), 5000)
      ok(true)
    HTTP.Message.Binary(data) ->
      try ws.outgoing.send(HTTP.Message.Binary(data), 5000)
      ok(true)
    HTTP.Message.Close(_, _) -> ok(false)
    _ -> ok(true)
  end
end

def echo(ws: HTTP.WebSocket) -> Result[Void]
  while true
    case ws.incoming.recv(60000)
      ok(message) -> return ok() if not try relay(ws, message)

      error(_) -> return ok()
    end
  end

  ok()
end

def home(request: HTTP.Request) -> Result[HTTP.Response]
  ok(HTTP.Response(status: 200, headers: [], body: "home".bytes))
end

def route(request: HTTP.Request, body: HTTP.RequestBody) -> Result[HTTP.Answer]
  return ok(HTTP.Answer.Upgrade(try HTTP.accept_websocket(request, &echo))) if request.path == "/echo"

  HTTP.app(&home).call(request, body)
end

def main() -> Void
  server = HTTP.serve("127.0.0.1", 8080, &route).unwrap!
  _ = HTTP.wait(server)
end
```

### HTTP.wait, HTTP.close_server and HTTP.shutdown

```signature
HTTP.wait(server: HTTP.Server) -> Result[Void]
HTTP.close_server(server: HTTP.Server) -> Void
HTTP.shutdown(server: HTTP.Server, timeout_ms: Int = 30000) -> Void
```

- `close_server` stops accepting, closes every connection and cancels the running apps and their tasks. Calling it again does nothing.
- `shutdown` is the graceful stop. It stops accepting at once, so a new connection is refused, and closes the connections that wait for a request. The requests in flight go on, and their answers say `Connection: close`. A WebSocket handshake gets a `503`. A stream or an upgraded connection that is already running goes on until the deadline, and so does the close after an answer while the client keeps its side open. When they have all ended, or after `timeout_ms` (30 s unless given), it closes what is left as `close_server` does, cancelling the apps still running, and returns. Calling it on a closed server does nothing; a call made while another drains waits for that one. Do not call it from an app: it would wait for that app's own request until the deadline. An app that must stop the server sends a value on a channel that the task that called `serve` receives, and that task calls `shutdown`. A server that must end cleanly on a container stop subscribes to `Term` and `Int` ([`System.subscribe`](https://www.agentica-lang.com/agentica/library/io-and-system/system/index.md#systemsubscribe)) and calls it, as below.
- `wait` returns `ok()` once the server is closed and its apps and their tasks have ended. A program that only serves waits on it. When `main` returns, the server stops.
- A server belongs to the task that called `HTTP.serve` and closes (freeing its port) when that task ends, so call `serve` in the task that keeps it, such as `main`. Each connection belongs to the task that serves it.

```agentica
import HTTP from "std/http"

def handle(request: HTTP.Request) -> Result[HTTP.Response]
  ok(HTTP.Response(status: 200, headers: [], body: "you asked for #{request.path}".bytes))
end

def main() -> Void
  options = HTTP.ServerOptions(request_timeout_ms: 10000, max_connections: 64, max_body_bytes: 65536)
  server = HTTP.serve("0.0.0.0", 8080, HTTP.app(&handle), options).unwrap!
  puts("listening on #{HTTP.local_port(server)}")
  IO.flush()
  HTTP.wait(server).unwrap!
end
```

```agentica
import HTTP from "std/http"

def handle(request: HTTP.Request) -> Result[HTTP.Response]
  ok(HTTP.Response(status: 200, headers: [], body: "hello".bytes))
end

def main() -> Void
  server = HTTP.serve("0.0.0.0", 8080, HTTP.app(&handle)).unwrap!
  signals = System.subscribe([System.Signal.Term, System.Signal.Int]).unwrap!
  while not Result.ok?(signals.recv(60000))
  end

  HTTP.shutdown(server, 10000)
end
```
