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 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 #

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.

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 #

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.

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 #

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 #

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.

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 #

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:

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 #

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. 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 #

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.
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 #

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).

TLS #

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]
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.

    SystemStore
    Linuxthe CA bundle
    macOSthe system roots and Keychain trust settings
    Windowsthe 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:

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:

# 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
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, and for a body on a channel, HTTP.open). The body is Bytes, exactly as it came (any content, up to max_body_bytes); it is not decompressed. HTTP.text 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 #

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.

OptionDefaultLimit
timeout_ms30 s, for each whole callpositive
idle_timeout_ms30 s, for kept connectionspositive
max_connections4, per hostpositive, at most 65536
max_body_bytes1 MiBpositive, at most 64 MiB
proxy"": no proxyan http://host:port origin, see below
tlsnone: the system’s CA certificatesa 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.
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.

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 #

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.
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:

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 #

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: 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.

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 #

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

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

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 #

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.
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 #

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.
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 #

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. 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.
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 #

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).
  • 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). Answer.Upgrade(upgrade) takes what accept_websocket 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 and request.headers) and remote_addr, the client’s IP address without the port ("127.0.0.1", "::1", as TCP.remote_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:

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:

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 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.

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.

OptionDefaultBounds
request_timeout_ms30 sthe 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_ms30 sthe wait between requests on a kept connection
max_connections128connections over it wait until one closes
max_body_bytes1 MiBat 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.

StatusCause
400malformed
413a body over max_body_bytes
417an Expect other than 100-continue
431headers too long or too many
501CONNECT, or an Upgrade other than a WebSocket handshake
505not 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 #

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.

  • 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:

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 #

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, 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, as HTTP.app does:
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:

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 #

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:

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 #

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) 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.
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
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