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 withdenied: --deny-net, before any DNS query. With--deny-fs, a TLS call that names a file (a CA file, a certificate or a key) returnsdenied: --deny-fs. - Sockets, listeners, clients and servers are handles:
IO.inspectprints<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:0or a negative one returnsnetwork: 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 withnetwork: 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(""))
endok(["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) -> IntPort 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)
endtrueTCP.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) -> StringThe 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)
end127.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_lineerrors 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
sendcan arrive in several reads and oneread_linecan 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)
endok("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_buffersets it for one socket, from 1024 to 16777216. flushwaits until the buffer is empty.sendafter a write goes behind the waiting bytes and returns when they are all out, sosendis a write and a flush.- When a buffered write fails,
flushand every later write on the socket return the error of the failed write. Atimeout_msthat ends closes the socket, as forsend. 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 callsflush, 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)
endok()
ok("one two")TCP.close and TCP.close_listener #
TCP.close(socket: TCP.Socket) -> Void
TCP.close_listener(listener: TCP.Listener) -> VoidClosing 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] = []
endA 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_contextandTLS.server_contextread 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.connecttakes a client context andTLS.listena server context; the other role stops the program withRUNTIME-TLS-CONTEXT-ROLE. A context stays valid while a socket or listener made from it is open.TLS.connectuses 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_fileuses the system’s trusted certificates, read once per process, with the ones the system distrusts rejected.SSL_CERT_FILEreplaces the store,SSL_CERT_DIRadds a directory. A nonemptyca_fileis a PEM file that replaces them; a missing or empty file failsTLS.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.
alpnlists 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.startandHTTP.serve_tlsspeak HTTP/1.1 only: a context whosealpnis not[]or["http/1.1"]stops the program withRUNTIME-TLS-CONTEXT-ALPN.A client context sends a client certificate when
cert_fileandkey_filename 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))
endTLS.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
hostasTLS.connectdoes. With a server context it is the server side andhostmust be""; another host stops the program withRUNTIME-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 withnetwork: 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)
enddef 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)
endHTTP 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 isBytes, exactly as it came (any content, up tomax_body_bytes); it is not decompressed.HTTP.textdecodes it in its charset. - Status codes such as 404 or 500 are normal responses.
errorresults are a bad URL, a refused connection, a timeout, or a body over the limit. Protocol errors start withhttp:, connection errors keep their TCP or TLS text, and a timeout isnetwork: operation timed out. GET,HEAD,OPTIONS,PUTandDELETEare 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.ClientandHTTP.Serverare builtin types thatstd/httpre-exports, soimport {Request, Response} from "std/http"binds them by name. A diagnostic,helpand a printed value show theHTTP.names: a response prints asHTTP.Response(status: ...)and a client as<HTTP.Client>. They reserve no name: a program may declare its ownHeaderorHttpRequest.
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) -> StringA 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_connectionsslot. A call in flight whenclose_clientruns fails withhttp: client is closed(unless a connection had already started sending it). proxyis anhttp://host:portorigin with no path or query, else the call is anerror.http://requests go to it in absolute form and share its connections; anhttps://request opens aCONNECTtunnel (one per target host and port) and speaks TLS to the target inside it, verified as without a proxy. This holds forHTTP.clientand every call that takes a client or options.- User info in the URL (
http://user:password@proxy:8080, percent-decoded) is sent asProxy-Authorization: Basicto the proxy only, unless the call sets that header; in anhttpscall your own header goes to the target. No error shows the user info, and aConnectionfromHTTP.startprints its proxy without it, but the options you built still hold it, so keep them out of logs. - A
407ishttp: the proxy HOST:PORT refused the credentials (407)(orrequires credentialswhen the URL has none); another status to aCONNECTishttp: 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 forurl, or""for none. It follows curl:http_proxyorhttps_proxyby the scheme, the lower-case name winning even when set and empty;HTTP_PROXYignored whenREQUEST_METHODis set (httpoxy);ALL_PROXYnot read;no_proxy(orNO_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 ashttp://; an invalidurlgives"". - The client runs as Agentica code in its own tasks, so it spends the run’s
--max-stepsbudget.
import HTTP from "std/http"
def main() -> Void
client = HTTP.client(HTTP.ClientOptions(timeout_ms: 5000, max_connections: 2)).unwrap!
HTTP.close_client(client)
endClients 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)
endHTTP.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.Responsehasstatus,headers(names in lowercase) andbody, which isBytes.postsends aBytesbody, as Ruby’sNet::HTTP.post(uri, data, header)does, andrequesttakes any method. Send text as"text".bytes, and no body as"".bytes. The body is at mostmax_body_bytes, andheadersdefault to[].- For one request use
get_responseandpost_response, like Ruby’sNet::HTTP.get_responseandNet::HTTP.post: each makes a client withoptions, makes the call and closes the client and its connection before it returns, so it needs noclientand noclose_client. For many requests use oneHTTP.client()withget,postandrequest, which reuses connections; callingget_responsein 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://orhttps://. A bracketed host (http://[::1]:8080/) must look like an IPv6 address, else an error result. - The client adds
HostandContent-Length; a request may not set them, norTransfer-EncodingorConnection.
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)
endOne 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
endHTTP.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?)
endcafé
café
false
falseHTTP.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["a=1", "b=2"]HTTP.download #
HTTP.download(client: HTTP.Client, url: String, path: String, options: DownloadOptions = DownloadOptions()) -> Result[Download]DownloadOptionshastimeout_ms, for the whole call, andmax_total_bytes, for the body, at most 256 MiB.DownloadOptions(), the default, gives 30 s and 256 MiB.Downloadhasstatus,headersandbytes_written; the body itself is in the file, never in the record.- A printed
Downloadtakes the alias the program importsstd/httpwith, while a builtin record keeps its fixed name: withimport H from "std/http", it prints asH.Download(status: 200, headers: [HTTP.Header(...)], ...). - The download sends a
GETand streams the body topath, so bodies may be arbitrary bytes. The file never grows pastmax_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
statusbefore using the file. - The connection is not pooled: it closes when the download ends. There is no redirect follow, and
httpskeeps 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)
endHTTP.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) -> VoidOne 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.
starttakes an origin (http://host,https://host:8443) with no path or query, and connects now.httpsverifies the certificate withoptions.tls(the system trust whennone, built again for eachstart, so a program that opens many connections passestls: some(context)). Onlytimeout_ms,max_body_bytes,tlsandproxyof the options apply:timeout_msis the time of each call (the connect, eachsend_request, eachread_body), andmax_body_bytesthe largest request body.send_requestsends the request and returns when the head of the response has been read:HTTP.ResponseHeadhasstatusandheaders(names in lowercase).targetis the path and query (/items?page=2).HostandContent-Lengthare added; the rules for headers are those ofHTTP.request. An interim1xxhead is read past.read_bodywaits for at least one byte and gives at mostmax_bytes(1 to 1 MiB) of the body, decoded (a chunked body has no framing in it). An emptyBytesis the end of the body. AContent-Lengthbody 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’sclose_notify). A response body is at most 256 MiB, the limit ofdownload, whatever its framing. A response toHEAD, a204, a304and one withContent-Length: 0have no body: the connection is ready at once, with noread_bodyneeded (aread_bodygives 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): thensend_requestiserror("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 anerror, 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
errorand ends it. A request that is refused before anything is written (a bad method, header or target, a body overmax_body_bytes) is anerrortoo, and the connection stays as it was. A server that closed an idle connection shows as anerrorof the nextsend_request:starta new one; nothing is retried. finishcloses 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 iserror("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)
endHTTP.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.
opensends the request and returns at the head of the response:HTTP.Streamhasstatus,headers,body(aChannel[Bytes]) anddone(aTask[Result[Void]]). A task feedsbodywith the pieces of the response (at most 64 KiB, never empty, a chunked body already decoded) and closes it on every path.urlhas a path and a query;method,bodyandheadersare those ofrequest.- The reader runs the usual receive loop until the closed error, then awaits
done:okmeans the body ended cleanly, and anerrorsays why it did not (a cut body, a timeout, a body over 256 MiB). A channel can only end, sodoneis the only way to tell a complete body from a cut one: always await it. - To stop early, close
body: the feeding task’s nextsendfails, it closes the connection anddoneiserror("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 untiltimeout_ms, so the prompt stop isTask.cancel(stream.done): it closes the connection at once anddoneis an error. options.timeout_msis the time of each wait ofopen: the connect, the head, each read of the body and eachsendto 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.uploadsends the pieces that another task puts inbody, until it closes the channel, and returns the whole response (asrequest: up tomax_body_bytes).methodisPOST,PUTorPATCH.lengthis the exact number of bytes, said asContent-Length: the body ends when that many bytes were sent, and the producer need not close the channel.-1is 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 thanlength, or a channel that closes short of it, is anerror, and so is a channel that is silent for longer thantimeout_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 anerror.uploadcloses 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,uploadreads the head of the response that is waiting (for at mosttimeout_ms) and returns that response, as Python’shttp.clientand Go do. Only when there is none is the write failure theerror(http:and the reason): on Windows a reset connection can drop the server’s early answer, souploadreturns 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)
endHTTP 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) -> Intservereturns at once and serves in the background;serve_tlsdoes the same over TLS with a serverTLS.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.AppisFn[HTTP.Request, HTTP.RequestBody, Result[HTTP.Answer]]: it gets the request with an emptybodyand the body on a channel (request bodies). HTTP.Answeris an enum.Answer.Whole(response)answers with anHTTP.Response.Answer.Stream(response)sends anHTTP.StreamResponse, whose body arrives on a channel (streamed responses).Answer.Upgrade(upgrade)takes whataccept_websocketreturns: itsAcceptruns the WebSocket on the connection, and itsReplyis sent asWhole.HTTP.app(handler, max_body_bytes)makes anAppfrom aHandler, for routes that take the request whole. It reads the body first, at mostmax_body_bytes(1 MiB unless given, whatever the server’s cap; a negative limit counts as 0), and callshandlerwith it. A body that is larger, by itsContent-Lengthor as it arrives, gets a413, a chunk line or trailer section over the head limits a431, and a bad chunk a400. These answers come withConnection: close, andhandleris not called. A body that is cut or stalls (the client left, a timeout) closes the connection.HTTP.Requesthasmethod,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 withHTTP.textandrequest.headers) andremote_addr, the client’s IP address without the port ("127.0.0.1","::1", asTCP.remote_addressgives it; Rack’sREMOTE_ADDR). The server fillsremote_addr; behind a proxy it is the proxy’s address. It defaults to""inHTTP.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)
end200 hello
404The 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!
endHandler 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)
endGET / 401
GET / 200App and handler errors:
- An app or handler returning
error(message)gives the client a 500 with an empty body and closes the connection. stderr getshttp: 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, aContent-LengthorTransfer-Encodingheader, 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 #
HTTP.read_all(body: HTTP.RequestBody, max_bytes: Int) -> Result[Bytes]
HTTP.body_refusal(message: String) -> HTTP.AnswerThe 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.RequestBodyhaspieces(aChannel[Bytes]) anddone(aTask[Result[Void]]). A task of the server feedspieceswith 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:okmeans the whole body arrived, and anerrorsays why it did not (the client left, a bad chunk, a timeout, a body over the cap). A channel can only end, sodoneis the only way to tell a whole body from a cut one: always await it. Whendoneis cancelled, byclose_serveror by the app itself, it iserror("task: cancelled")and the request gets no answer: the connection closes. To stop an upload early, answer (a413, say) without reading the rest and without cancellingdone: 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_bytesofoptions(1 MiB by default; raise it, up to 256 MiB, for uploads).HTTP.appkeeps its own limit (1 MiB unless given), so a route under it that takes larger bodies raises both. A request whoseContent-Lengthis larger gets a413before the app runs, with no100 Continuefirst, so a client that waits for it never sends the body. A chunked body that grows past the cap endsdonewith the error ofread_all, whichHTTP.appanswers413. Expect: 100-continuewithin the cap is answered with100before the app runs, so an app cannot refuse an upload before the client sends the body.request_timeout_msis 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
413or a401, or a body that failed) the answer getsConnection: closeand 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 aResult[Bytes], or anerrorwhen the body is longer thanmax_bytesor the cap, or did not arrive whole (it awaitsdone).HTTP.body_refusal(message)is the answer for that error:413for a body over its limit,431for a chunk line or trailer section over the head limits, and400for any other (a bad chunk, a body cut or stalled), a whole response withConnection: closeand no body.HTTP.appanswers so for aHandler; a route that reads the body itself returnsok(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)
end200 11 bytesStreamed 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 neitherContent-LengthnorTransfer-Encoding. The pieces areBytes, 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 hasContent-Length: nand the pieces go out raw, with no chunk framing. A body that ends short ofn, or a piece that would passn, closes the connection, so the client sees an incomplete body and never reads past the length. The body ends as soon asnbytes 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 getserror("channel: closed")and stops. A piece after the body is full is not read; a piece that crossesnis the cut above. A closed body whose size is notnis the 500 of an invalid response, as is alengthon a 204 or 304 answer.HEADgets 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 thatBytes("text".bytesfor a text). The server then sendsContent-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
sendreturnserror("channel: closed")and it stops. A producer that sends rarely can look atbody.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’ssendwaits. - A slow producer is not an error. The wait for the next piece has no time limit, and
idle_timeout_mscounts only between requests, from the end of a stream.request_timeout_msbounds the send of each piece (and of a whole body sent withContent-Length): a client that stops reading for that long is cut off, and the channel closes. HEADgets 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, asHTTP.appdoes:
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["chunked"]
data: tick 1
data: tick 2
data: tick 3
404HTTP.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.Messageserve 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: aGETwithUpgrade: websocket,Connection: Upgrade,Sec-WebSocket-Version: 13and aSec-WebSocket-Keythat is 16 bytes in base64. A request that is not one gets anUpgrade.Reply:426withSec-WebSocket-Version: 13for another version,400for the rest. The head reader lets only aGETwith oneUpgrade: websocketthrough, so any otherUpgrade(h2c, aPOST) is a501. A route that does not callaccept_websocketignores the headers and answers as usual.- A WebSocket handshake reaches every app; a route that does not upgrade answers it as any other request.
sessionis aHTTP.WebSocketSession,Fn[HTTP.WebSocket, Result[Void]]. The server writes the101answer 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 anerror) 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
Acceptwhile the body is still unread gets a500and a close, withhttp: invalid response: ...on stderr. HTTP.WebSockethasincomingandoutgoing, bothChannel[HTTP.Message],incomingof 8 messages andoutgoingofoutgoing_queue(8 by default), andprotocol, 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 insend. A session must keep taking messages fromincoming(or end): while it does not, the server does not read the socket, so pings and the peer’s close go unanswered.incomingcloses after theClosemessage, andoutgoingcloses when the connection is over, so a send then is anerror.HTTP.MessageisText(String),Binary(Bytes),Ping(Bytes),Pong(Bytes),Close(Int, String), the code and the reason, andPrepared(Bytes), which only a session sends. A receivedTextorBinaryis 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 inoutgoing, up tooutgoing_queuemessages, and a session that closed its ownoutgoingmay get no pongs); aPongis handed on. APingorPongcarries at most 125 bytes (more is cut).- A
Closeis 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, orrequest_timeout_msofHTTP.ServerOptions). SendingClose(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.WebSocketOptionshasmax_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 getsClosewith 1006),ping_ms(default 0, none: the server sends a ping after that many milliseconds with nothing to write, so withping_msbelowidle_msthe 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 inSec-WebSocket-Protocolis agreed on) andoutgoing_queue(default 8, 1 to 1048576: how many messagesoutgoingholds before asendwaits, or fails after its timeout). The server writes the messages queued inoutgoingat 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 biggeroutgoing_queuelets a broadcaster that sends straight to many sockets’outgoingchannels deliver in fewer writes, at the cost of the memory of the queued messages.HTTP.prepare(message)frames aTextorBinarymessage once and returns it asPrepared; any other message comes back as it is. A broadcaster sends the onePreparedmessage on theoutgoingchannel 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 aspreparemade it (a text payload is not checked as UTF-8 again). APreparedmessage whose bytes are not a framepreparemade closes the connection with 1011, with a warning on stderr. Acaseon a receivedHTTP.Messagenever seesPrepared, but still needs an arm for it or_.request_timeout_msofHTTP.ServerOptionsbounds the handshake and each write of a frame. A WebSocket counts againstmax_connectionsfor as long as it lives.idle_timeout_msdoes 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 withHTTP.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_bytesat 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)
endHTTP.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) -> Voidclose_serverstops accepting, closes every connection and cancels the running apps and their tasks. Calling it again does nothing.shutdownis 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 sayConnection: close. A WebSocket handshake gets a503. 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 aftertimeout_ms(30 s unless given), it closes what is left asclose_serverdoes, 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 calledservereceives, and that task callsshutdown. A server that must end cleanly on a container stop subscribes toTermandInt(System.subscribe) and calls it, as below.waitreturnsok()once the server is closed and its apps and their tasks have ended. A program that only serves waits on it. Whenmainreturns, the server stops.- A server belongs to the task that called
HTTP.serveand closes (freeing its port) when that task ends, so callservein the task that keeps it, such asmain. 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!
endimport 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