Module http/server

http/server
Stability: unstable — may still change; see below.

Minimal HTTP/1.1 server on TcpListener (plans/archive/STD_API_AUDIT.md §7 P1).

One connection at a time, one request per connection (Connection: close is added to every response) — the shape a CLI, a test fixture or a local tool needs; it shares its wire code (std/http/wire.yo) with the client, so request bodies may be Content-Length or chunked.

{ HttpServer, HttpResponse } :: import("std/http");
server := io.await(HttpServer.bind(SocketAddr.loopback(u16(8080)), io), e);
io.await(server.serve(req -> HttpResponse.with_status(StatusCode.OK()).with_body(`hi ${req.path}`), io), e);

serve runs until stop() is called (checked after each connection) — from another task, or from the handler itself. serve_once handles exactly one connection, which is what a test wants. Both consume the server, so the future owns it; keep a server.clone() (a second handle to the same listener and stop flag) for stop, local_addr and close.

A client's mistake never takes the server down: a request that does not parse gets 400, one that exceeds max_request_bytes gets 413, one with broken framing (Content-Length that is not a number, malformed chunking) gets 400 — and serve goes on to the next connection. An I/O failure on the accepted socket itself still propagates out of serve.

Stability

unstable — the SHAPE (one connection at a time, one request per connection, Connection: close on every response) is expected to change when a connection loop / keep-alive lands; bind, local_addr, with_max_request_bytes, serve, serve_once, stop and close are intended to keep their names and meanings.

Types

HttpServer struct
HttpServer

An HTTP/1.1 server bound to a TcpListener.

Semantically shared (plans/VALUES_BY_DEFAULT.md V5 part B, class S): a handler calls stop() on the server whose serve future is running it, so two owners outlive each other's calls. A clone is a second handle: the listener sits behind an Rc (it is move-only, and close's future borrows it across a suspension) and the stop flag behind an Rc(RefCell(bool)), so every clone sees one listener and one flag.

Fields

NameTypeDescription
listenerRc(TcpListener)
max_request_bytesusize

Requests larger than this are answered with 413 Payload Too Large and the connection closed; serve keeps going (0 lifts the ceiling).

stoppedRc(RefCell(bool))

Trait Implementations

impl(generic(T : Type), where(T <: Clone), T : (Clone))
impl(generic(T : Type), where(T <: Clone), T : (Clone), CloneInto)
clone_into : fn(self : &Self, dst : *(Self)) -> unit

Write a clone of self into the uninitialized slot dst, which has room for size_of_val(self) bytes at align_of_val(self).

Parameters

NameTypeNotes
selfSelf
dst*(Self)

Returns: unit

impl(HttpServer, ...)
bind : (HttpServer) fn(addr : SocketAddr, io : Io) -> Impl(Future(HttpServer, IoExn))

Bind a listening socket on addr (port 0 picks a free port — read it back with local_addr()).

Parameters

NameTypeNotes
addrSocketAddr
ioIo

Returns: Impl(Future(HttpServer, IoExn))

local_addr : (HttpServer) fn(self : &HttpServer) -> SocketAddr

The address the server is listening on.

Parameters

NameTypeNotes
selfHttpServer

Returns: SocketAddr

with_max_request_bytes : (HttpServer) fn(self : HttpServer, n : usize) -> HttpServer

Set the request-size ceiling (builder pattern, before serve; 0 = unlimited). A clone taken earlier keeps the old ceiling, which only serve reads.

Parameters

NameTypeNotes
selfHttpServer
nusize

Returns: HttpServer

_accept_request : (HttpServer) fn(self : &HttpServer, io : Io) -> Impl(Future(Tuple(0 : TcpStream, 1 : Result(HttpRequest, HttpResponse)), IoExn))

Accept ONE connection and read one request from it. Returns the connection and either the request or the response it gets without reaching the handler: a request that does not parse gets a 400 Bad Request whose body names the defect, and a framing defect (oversize, unreadable Content-Length, malformed chunking) is answered the same way (413 for oversize) instead of being thrown out of the server (issues/fixed/one-malformed-request-killed-http-server-serve.md).

Parameters

NameTypeNotes
selfHttpServer
ioIo

Returns: Impl(Future(Tuple(0 : TcpStream, 1 : Result(HttpRequest, HttpResponse)), IoExn))

serve_once : (HttpServer) fn(self : HttpServer, handler : Impl(Fn(&HttpRequest) -> HttpResponse), io : Io) -> Impl(Future(unit, IoExn))

Accept ONE connection, read one request, run handler, write the response and close. A request that does not parse, or whose framing is broken, is answered without calling handler (_accept_request).

The returned future owns the server and handler (sink), so it can be spawned: a closure argument moves its captures into it (plans/VALUES_BY_DEFAULT.md decision 22). A future that only borrowed the handler would be second-class, and an io.spawn of it is E0909 (issues/fixed/2026-10-15-http-server-captures-its-borrowed-handler-into-the-connection-future.md).

Parameters

NameTypeNotes
selfHttpServer
handlerImpl(Fn(&HttpRequest) -> HttpResponse)
ioIo

Returns: Impl(Future(unit, IoExn))

serve : (HttpServer) fn(self : HttpServer, handler : Impl(Fn(&HttpRequest) -> HttpResponse), io : Io) -> Impl(Future(unit, IoExn))

Serve connections one after another until stop() has been called (checked after each connection completes). The future owns the server and handler, as serve_once's does.

Parameters

NameTypeNotes
selfHttpServer
handlerImpl(Fn(&HttpRequest) -> HttpResponse)
ioIo

Returns: Impl(Future(unit, IoExn))

stop : (HttpServer) fn(self : &HttpServer) -> unit

Ask serve to return after the connection it is currently handling. Writes the flag every clone shares, so a handle kept beside a running serve (or the handler's own capture) stops it.

Parameters

NameTypeNotes
selfHttpServer

Returns: unit

close : (HttpServer) fn(self : &HttpServer, io : Io) -> Impl(Future(unit, IoExn))

Close the listening socket.

Parameters

NameTypeNotes
selfHttpServer
ioIo

Returns: Impl(Future(unit, IoExn))

Methods
clone : (HttpServer) fn(self : &HttpServer) -> HttpServer

Parameters

NameTypeNotes
selfHttpServer

Returns: HttpServer

Constants

DEFAULT_MAX_REQUEST_BYTES constant usize

Default ceiling on a request (headers + body): 16 MiB.

Value: 16777216