/// A small HTTP/1.1 server (native programs only). /// /// pub fn main() -> () / { /// match http.listen("0.0.0.0", 8080) { /// Ok(server) -> http.serve(server, fn(req) { /// http.html(

{"Hello from " <> req.path}

) /// }), /// Error(e) -> io.eprintln(e), /// } /// } /// /// Each connection is handled by an actor of its own, which serves its /// requests one after another (keep-alive; ADR 0012): /// - an HTTP/1.1 connection stays open unless the request or the response /// has `Connection: close`; an HTTP/1.0 one only if the request has /// `Connection: keep-alive`; /// - a connection that waits longer than the idle timeout for a request /// to start, or for more of a body, is closed; so is one whose request /// head, once begun, takes longer than the head timeout to arrive whole /// (a client that trickles it), and one whose response takes longer /// than the write timeout to send (a client that stops reading); the /// handler is not timed; /// - at most `max_open` connections are open at once. At the limit, the /// next client is accepted and held while the oldest connection is /// asked to close: at once if it waits for a request, else after its /// current response (`Connection: close`). So kept-alive clients cannot /// starve waiting ones (issue #304), and the next client gets in within /// about one response time. A streamed response is not cut: its /// connection closes when the stream ends; /// - a connection serves at most `max_requests` requests: the last one is /// answered with `Connection: close`, and the client reconnects; /// - request bodies are read whole, sized by `Content-Length` or chunked /// (`Transfer-Encoding: chunked`), up to a size limit (413 beyond it), /// which can be larger under some path prefixes (`large_bodies`); a /// malformed request gets an error response, and the connection is /// closed; /// - the server sets `Content-Length` and `Connection` on responses, except /// that final 204 and 304 responses have no content length or body; /// - a response can be **streamed** (ADR 0053): the head goes out with /// `Transfer-Encoding: chunked`, the handler's stream fn writes chunks /// (each flushed, each write timed per chunk; the stream between chunks /// is not timed), and keep-alive continues after the final chunk. /// Server-Sent Events are a streamed response that stays open. A response /// with final status 204 or 304 sends no framing, chunks or final chunk, and /// does not call the stream fn. /// /// Request heads and chunk sizes are parsed by httparse (picohttpparser's /// design) in the runtime. import std/bytes.{type Builder} import std/dict.{type Dict} import std/ffi.{type Resource} import std/html.{type Html} import std/int import std/io import std/list import std/net. {type SocketAddress, type TcpListener, type TcpStream, SocketAddress} import std/option import std/process. {type ExitReason, type Pid, type Subject, type proc, Crashed, Down} import std/random.{type random} import std/result import std/string import std/time.{type clock} pub type Request { Request( method: String , path: String , headers: List<(String, String)> , body: Bytes ) } pub type Response { Response(status: Int, headers: List<(String, String)>, body: Body) } /// What a response's body is (ADR 0053). pub type Body { /// The whole body, in hand. Whole(Bytes) /// Written chunk by chunk: the server sends the head with /// `Transfer-Encoding: chunked`, then calls `write` with a `Writer` /// and sends the final chunk when it returns. Between chunks the /// connection is not timed; each chunk's write is, per chunk, by the /// write timeout. A 204 or 304 response skips `write` and sends neither /// framing nor a final chunk. A HEAD request for any other status /// sends the head only: `write` runs with a writer whose every write fails, /// so it stops, and whatever cleanup it does on a failed write runs (#363). /// If `write` unwinds, the connection dies without the final /// chunk: the client sees a truncated stream, the only honest end /// once the status line is sent. , Streamed(write: fn(Writer) -> () / ) } /// What a streamed response writes with (ADR 0053): the connection, /// memory when the body is read in hand (`collect_body`), or nothing, for /// a HEAD request, whose writes all fail. pub opaque type Writer { Socket(conn: Resource, activity: Subject) , Memory(chunks: Subject) , Headless } /// Write one chunk, flushed (one frame, one socket write). `Error` says /// the client is gone: stop writing. An empty chunk writes nothing: its /// frame would be the chunked encoding's last one, ending the body. pub fn write_chunk :: w: Writer chunk: Bytes -> Result<(), String> / { match w { _ if bytes.length chunk == 0 -> Ok(()) , Socket(conn, activity) -> { process.send activity Writing match net.write conn (frame chunk) { Ok(()) -> { process.send activity Streaming Ok(()) } , Error(e) -> Error(e) } } , Memory(chunks) -> { process.send chunks chunk Ok(()) } , Headless -> Error("a HEAD request has no body") } } /// Write one chunk of text, flushed. pub fn write_string :: w: Writer text: String -> Result<(), String> / { write_chunk w (bytes.from_string text) } /// A chunk's frame: its length in hex, CRLF, the data, CRLF. fn frame :: chunk: Bytes -> Bytes { let head = to_hex (bytes.length chunk) <> "\r\n" bytes.concat_all [bytes.from_string head, chunk, bytes.from_string "\r\n"] } fn to_hex :: n: Int -> String { if n <= 0 { "0" } else { hex_up n "" } } fn hex_up :: n: Int acc: String -> String { if n == 0 { acc } else { hex_up (int.shift_right n 4) (hex_digit (int.and n 15) <> acc) } } fn hex_digit :: d: Int -> String { match d { 0 -> "0" , 1 -> "1" , 2 -> "2" , 3 -> "3" , 4 -> "4" , 5 -> "5" , 6 -> "6" , 7 -> "7" , 8 -> "8" , 9 -> "9" , 10 -> "a" , 11 -> "b" , 12 -> "c" , 13 -> "d" , 14 -> "e" , _ -> "f" } } /// Change the defaults with a record update: /// `Settings(..http.defaults(), idle_timeout: 1000)`. pub type Settings { /// - `connections`: serve this many connections, then return (all of /// them if negative); /// - `idle_timeout`: close a connection that waits this many /// milliseconds for a request to start, or for more of a body (never /// if negative); /// - `write_timeout`: close a connection whose response takes longer /// than this many milliseconds to send (never if negative); /// - `max_body`: answer 413 to a request whose body is larger than this /// many bytes, and close the connection (no limit if negative); /// - `large_bodies`: other body limits for some paths, as `(prefix, /// limit)`: the first prefix that matches the request's path on whole /// segments (`/uploads` matches `/uploads` and `/uploads/a`, not /// `/uploadsx`) sets its limit instead of `max_body` (see /// `body_limit`). The 413 still comes before any byte of the body is /// read; /// - `max_open`: keep at most this many connections open at once (no /// limit if negative). At the limit, the next client is held (one /// more open socket) and the oldest connection asked to close, at once /// if it waits for a request, else after its current response; /// - `max_requests`: answer this many requests on one connection, the /// last with `Connection: close` (no limit if negative); /// - `head_timeout`: close a connection whose request head, once begun, /// takes longer than this many milliseconds to arrive whole (never if /// negative); /// - `drain_timeout`: once `serve_until` is told to stop, give the /// requests in flight this many milliseconds to finish, then close /// their connections (no limit if negative). Settings( connections: Int , idle_timeout: Int , write_timeout: Int , max_body: Int , large_bodies: List<(String, Int)> , max_open: Int , head_timeout: Int , max_requests: Int , drain_timeout: Int ) } /// Every connection, at most 512 at once (under the usual limit of 1024 /// open files, so the limit is reached before `accept` fails); closed /// after 5 idle seconds, when a request head takes over 10 seconds to /// arrive, when a response takes over 30 seconds to send, or after 1,000 /// requests (nginx's `keepalive_requests`); bodies up to 1 MiB on every /// path; 10 seconds to drain when stopped. pub fn defaults :: -> Settings { Settings( connections: -1 , idle_timeout: 5000 , write_timeout: 30000 , max_body: 1048576 , large_bodies: [] , max_open: 512 , head_timeout: 10000 , max_requests: 1000 , drain_timeout: 10000 ) } /// The client's address (issue #308): the other end of the connection the /// request came on, as the server accepted it. Behind a proxy, that is /// the proxy: see `client_address`. `None` for a request built by hand /// (in tests). /// /// The server puts it among the request's headers as the pseudo-header /// `:peer` (`"127.0.0.1:52144"`, `"[::1]:52144"`), which no client can /// send: a header name cannot contain `:`. It is found anywhere in the /// list (issue #313); a server-built request always has it first. /// `wire_headers` leaves it out. pub fn peer :: req: Request -> Option { option.then (find_header req.headers ":peer") parse_address } /// `req` as if it arrived from `address` (for tests): the `:peer` /// pseudo-header first, where the server puts it. pub fn with_peer :: req: Request address: SocketAddress -> Request { Request(..req, headers: [(":peer", address_text address), ..req.headers]) } /// `host:port`, or `[host]:port` for an IPv6 host. fn parse_address :: value: String -> Option { let ( host , port ) = if string.starts_with value "[" { match string.split (string.slice value 1 (string.length value)) "]:" { [host, port] -> (host, port), _ -> ("", "") } } else { match string.split value ":" { [host, port] -> (host, port), _ -> ("", "") } } match string.to_int port { Ok(port) -> if host == "" { None } else { Some(SocketAddress(host, port)) } , Error(_) -> None } } /// How the server writes a peer in `:peer`. fn address_text :: address: SocketAddress -> String { let host = if string.contains address.host ":" { "[" <> address.host <> "]" } else { address.host } host <> ":" <> show address.port } /// The headers the client sent, without the server's pseudo-headers /// (`:peer`): what to forward or log. pub fn wire_headers :: req: Request -> List<(String, String)> { use h <- list.filter req.headers !string.starts_with h.0 ":" } /// The client's IP address, through the proxies in `trusted` (exact /// addresses, as text). When the peer is not trusted, it is the client: /// its `X-Forwarded-For`, which anyone can send, is ignored. When it is, /// the client is the right-most `X-Forwarded-For` entry that is not /// trusted (each proxy appends the address it got the request from), or /// the left-most one if all are; with no entries, the peer itself. /// `None` without a peer (a request built by hand). /// /// // Behind one nginx on 10.0.0.2: /// http.client_address(req, ["10.0.0.2"]) pub fn client_address :: req: Request trusted: List -> Option { match peer req { None -> None , Some(p) -> if !is_trusted trusted p.host { Some(p.host) } else { Some(untrusted_hop (list.reverse (forwarded_for req)) trusted p.host) } } } /// Every `X-Forwarded-For` entry, in order, across repeated headers. fn forwarded_for :: req: Request -> List { use h <- list.flat_map req.headers if string.eq_ignore_ascii_case h.0 "x-forwarded-for" { string.split h.1 "," |> list.map string.trim |> list.filter fn entry { entry != "" } } else { [] } } /// The first of `hops` (right-most first) not in `trusted`, else the /// last one seen (`seen`: the peer, before any). fn untrusted_hop :: hops: List trusted: List seen: String -> String { match hops { [] -> seen , [ hop , ..rest ] -> if is_trusted trusted hop { untrusted_hop rest trusted hop } else { hop } } } fn is_trusted :: trusted: List address: String -> Bool { list.any trusted fn t { t == address } } /// The value of header `name` (case-insensitive), if present. pub fn header :: req: Request name: String -> Option { find_header req.headers name } fn find_header :: headers name { match headers { [] -> None , [(k, v), ..rest] -> if string.eq_ignore_ascii_case k name { Some(v) } else { find_header rest name } } } /// The request body as text, if it is valid UTF-8. pub fn body_text :: req: Request -> Result { bytes.to_string req.body } /// The fields of a form-encoded request body (see `form`). pub fn form_body :: req: Request -> List<(String, String)> { form (bytes.to_string_lossy req.body) } /// A response with `body` of type `content_type`. pub fn response :: status: Int content_type: String body: Bytes -> Response { Response(status, [("Content-Type", content_type)], Whole(body)) } /// A 200 response written chunk by chunk (ADR 0053): the head goes out /// first (`Transfer-Encoding: chunked`), then `write` runs with a /// `Writer`; each `write_chunk`/`write_string` flushes. Between chunks /// the connection is not timed; each write is, per chunk. Keep-alive /// continues after the final chunk. /// /// http.stream("text/html; charset=utf-8", fn(w) { /// let _ = http.write_string(w, html.render(shell_top)) /// // each component, as it finishes /// let _ = http.write_string(w, "") /// }) pub fn stream :: content_type: String write: fn(Writer) -> () / -> Response { Response(200, [("Content-Type", content_type)], Streamed(write)) } /// The body a response holds, if it is a whole one (a streamed response's /// body is written, not held). pub fn whole_body :: resp: Response -> Option { match resp.body { Whole(body) -> Some(body), Streamed(_) -> None } } /// A response's body in hand: a streamed one is written into memory, /// chunk by chunk, as the server would send it. For tests and tools: the /// whole body is held at once. pub fn collect_body :: resp: Response -> Bytes / { match resp.body { Whole(body) -> body , Streamed(write) -> { let chunks = process.subject () write Memory(chunks) bytes.concat_all (written chunks []) } } } /// The chunks a memory writer was given, in order. fn written :: chunks: Subject held: List -> List / { match process.receive chunks 0 { Some(chunk) -> written chunks [chunk, ..held], None -> list.reverse held } } /// A 200 response with a rendered page. pub fn html :: page: Html -> Response { response 200 "text/html; charset=utf-8" (bytes.from_string (html.render page)) } /// A plain-text response. pub fn text :: status: Int body: String -> Response { response status "text/plain; charset=utf-8" (bytes.from_string body) } pub fn not_found :: -> Response { text 404 "not found" } /// `resp` with the header `name: value` added, after the ones it has /// (headers can repeat: each `Set-Cookie` is its own header). pub fn with_header :: resp: Response name: String value: String -> Response { Response(..resp, headers: list.append resp.headers [(name, value)]) } /// Listen for HTTP connections. pub fn listen :: host: String port: Int -> Result, String> / { net.listen host port } /// Serve forever with the default settings. pub fn serve :: server: Resource handler: send fn(Request) -> Response / -> () / { serve_with server (defaults ()) handler } /// Serve with `settings`: one actor per connection. When this returns, /// the last connections' actors may still be running. pub fn serve_with :: server: Resource settings: Settings handler: send fn(Request) -> Response / -> () / { accept_all server settings handler (process.subject ()) Open(0, dict.empty (), 0, False) 10 } /// Serve with `settings` until a message arrives on `stop`, then stop /// gracefully (ADR 0060): new clients are refused at once; idle /// connections are closed, and busy ones after their current response /// (with `Connection: close`); after `settings.drain_timeout`, the /// connections still open are closed. Returns once every connection is. /// /// `stop` is one of the calling actor's subjects, and any message on it /// stops the server: `os.signals([Term])` for a program that stops on /// SIGTERM, `process.exits()` for a `main` that traps exits under /// `[application]` (ADR 0060), or a `process.subject()` another actor /// sends on. pub fn serve_until :: server: Resource settings: Settings handler: send fn(Request) -> Response / stop: Subject -> () / { let ready = process.subject () let (_, done) = process.spawn_monitor fn { let events = process.subject () process.send ready events accept_all server settings handler events Open(0, dict.empty (), 0, False) 10 } let events = process.receive_forever ready let stopped = process.new_selector () |> process.selecting stop fn _ { True } |> process.selecting done fn _ { False } if process.select_forever stopped { // Wakes the acceptor, parked in `accept`, which then drains. process.send events Stop net.close_listener server let Down(_, reason) = process.receive_forever done stopped_with reason } else { // `settings.connections` were served. () } } /// The acceptor's end: a crash is `serve_until`'s. fn stopped_with :: reason: ExitReason -> () { match reason { Crashed(message) -> panic ("http: the acceptor crashed: " <> message) , _ -> () } } /// Accept connections while `settings.connections` lasts. Their /// watchdogs report on `events` when they open and end. After a failed /// `accept` (out of file descriptors, say), wait `pause` milliseconds, /// doubling up to a second while it keeps failing (ADR 0012, Revision 2). fn accept_all :: server settings: Settings handler events: Subject open: Open pause: Int -> () / { if settings.connections != 0 { let next = Settings(..settings, connections: settings.connections - 1) match net.accept server { Ok(conn) -> { // At `max_open`, this client is held until there is room (or the // server stops: it is served, then drained). let open = make_room events (take_events events open False) settings.max_open False let id = open.next let _ = process.spawn fn { handle_connection conn id settings handler events } accept_all server next handler events Open(..open, count: open.count + 1, next: id + 1) 10 } , Error(e) -> { let open = take_events events open False if open.stopping { drain events open settings.drain_timeout } else { io.eprintln ("http: accept failed: " <> e) process.sleep pause accept_all server next handler events open if pause >= 500 { 1000 } else { pause * 2 } } } } } else { () } } /// Stop serving (`serve_until`): ask every open connection to close /// (idle ones at once, busy ones after their response), and wait until /// they have, for `timeout` milliseconds at most; then close the rest. fn drain :: events: Subject open: Open timeout: Int -> () / { let asked = list.map (dict.to_list open.closable) fn entry { ask_to_close entry.1 } let timer = if timeout >= 0 { Some( process.spawn fn { process.sleep timeout process.send events DrainOver } ) } else { None } wait_drained events open.count asked match timer { Some(pid) -> process.kill pid, None -> () } } /// Ask a connection to close: its actor and its watchdog (see `Opened`). /// Returns its actor's subject. fn ask_to_close :: subjects: (Subject<()>, Subject<()>) -> Subject<()> / { let (actor, watchdog) = subjects process.send actor () process.send watchdog () actor } /// Wait until `count` connections have ended, asking those that open /// meanwhile (accepted just before the stop) to close too; at /// `DrainOver`, stop the actors of those asked. fn wait_drained :: events: Subject count: Int asked: List> -> () / { if count > 0 { match process.receive_forever events { Ended(_) -> wait_drained events (count - 1) asked , Opened(_, actor, watchdog) -> wait_drained events count [ask_to_close (actor, watchdog), ..asked] , DrainOver -> list.each asked fn actor { process.kill (process.owner actor) } , Stop -> wait_drained events count asked } } else { () } } /// What a connection's watchdog tells the acceptor. type Event { /// Connection `id` is open: a `()` on both subjects (its actor's, its /// watchdog's) asks it to close. Opened(id: Int, actor: Subject<()>, watchdog: Subject<()>) /// Connection `id` ended. , Ended(id: Int) /// `serve_until` was told to stop: drain once `accept` fails. , Stop /// The drain timeout passed. , DrainOver } /// The acceptor's view: `count` connections open, those it may still ask /// to close by id (ids grow, so the least is the oldest), the next id, /// and whether `serve_until` was told to stop. type Open { Open( count: Int , closable: Dict, Subject<()>)> , next: Int , stopping: Bool ) } /// `open` after the events received so far; with `wait`, after waiting /// for one first. fn take_events :: events: Subject open: Open wait: Bool -> Open / { match process.receive events if wait { -1 } else { 0 } { Some(Opened(id, actor, watchdog)) -> take_events events Open(..open, closable: dict.insert open.closable id (actor, watchdog)) False , Some(Ended(id)) -> take_events events Open( ..open , count: open.count - 1 , closable: dict.remove open.closable id ) False , Some(Stop) -> take_events events Open(..open, stopping: True) False , Some(DrainOver) -> take_events events open False , None -> open } } /// `open` once a connection more fits under `max_open`. While full, the /// oldest connection not asked yet is asked to close (once per held /// client, `asked`), and the acceptor waits for one to end: that one, or /// any other. fn make_room :: events: Subject open: Open max_open: Int asked: Bool -> Open / { if max_open < 0 || open.count < max_open || open.stopping { open } else { let (open, asked) = match (asked, dict.first open.closable) { (False, Some((id, (actor, watchdog)))) -> { process.send actor () process.send watchdog () (Open(..open, closable: dict.remove open.closable id), True) } , _ -> (open, asked) } make_room events (take_events events open True) max_open asked } } /// What a connection's watchdog learns. type Activity { /// The connection's actor waits for a request to start: timed by /// `idle_timeout`. Asked to close now, the connection closes at once. Idle /// It waits for more of a body: timed by `idle_timeout` from each read. , Reading /// A request head has begun and is not whole yet: timed by /// `head_timeout` from here, once, since nothing else is sent until the /// head is read. , HeadStarted /// It runs the handler: not timed. , Handling /// It sends a response: timed. , Writing /// A streamed response, between chunks: not timed (a stream may be /// quiet arbitrarily long); each chunk's write is `Writing`. , Streaming /// It stopped (also by crashing). , Stopped /// The acceptor asks the connection to close (at `max_open`, for a /// waiting client): the watchdog closes it if it is `Idle`; otherwise /// its actor answers the current request with `Connection: close`. , Drain } fn handle_connection :: conn: Resource id: Int settings: Settings handler: fn(Request) -> Response / events: Subject -> () / { let me = process.self () let ready = process.subject () let drain = process.subject () let _ = process.spawn fn { watchdog conn me id drain settings ready events } let activity = process.receive_forever ready let peer = match net.peer conn { Ok(address) -> [(":peer", address_text address)], Error(_) -> [] } let serving = Serving(conn, peer, activity, drain, settings, handler) serve_requests serving (bytes.empty ()) 0 0 net.close conn } /// Close the connection when it waits too long for a request, takes too /// long to send its head, or takes too long to send a response: its actor /// then reads the end of the stream, or fails to write, and stops. The /// watchdog monitors that actor, and stops with it, releasing its /// reference to the socket. It tells the acceptor that the connection /// opened, with how to ask it to close (`drain`, its actor's subject, and /// one of its own), and, once, that it ended (for `max_open`). fn watchdog :: conn: Resource owner: Pid id: Int drain: Subject<()> settings: Settings ready: Subject> acceptor: Subject -> () / { let activity = process.subject () let asked = process.subject () let down = process.monitor owner process.send ready activity process.send acceptor Opened(id, drain, asked) let events = process.new_selector () |> process.selecting activity fn a { a } |> process.selecting down fn _ { Stopped } |> process.selecting asked fn _ { Drain } watch conn settings events settings.idle_timeout True process.send acceptor Ended(id) } /// `idle`: the actor waits for a request to start. (A `Drain` otherwise /// restarts the current timeout; it comes at most once.) Closing an idle /// connection races with a request just sent, as the idle timeout does: /// a client retries it on a new connection (RFC 9112, section 9.3.1). fn watch :: conn settings: Settings events timeout idle: Bool { match process.select events timeout { None -> net.close conn , Some(Idle) -> watch conn settings events settings.idle_timeout True , Some(Reading) -> watch conn settings events settings.idle_timeout False , Some(HeadStarted) -> watch conn settings events settings.head_timeout False , Some(Handling) -> watch conn settings events (-1) False , Some(Writing) -> watch conn settings events settings.write_timeout False , Some(Streaming) -> watch conn settings events (-1) False , Some ( Drain ) -> if idle { net.close conn } else { watch conn settings events timeout False } , Some(Stopped) -> () } } /// Why no request was read. type Failure { /// The connection closed or failed: nothing to answer. Closed /// A malformed request, answered with `status` before closing. , Bad(status: Int, message: String) } /// A request, whether the client keeps the connection open after it, and /// where the next request starts (offset `at` of `buffer`). type Incoming { Incoming(request: Request, keep_alive: Bool, buffer: Bytes, at: Int) } /// Serve the requests in `buffer` (from offset `at`), then those that /// arrive, until either side closes the connection. /// A connection's actor: the socket, its watchdog's subject, its own /// subject on which the acceptor asks it to close, and how to serve. type Serving { Serving( conn: Resource // `[(":peer", address)]`, or none if it is not known: put first among // every request's headers (`peer`). , peer: List<(String, String)> , activity: Subject , drain: Subject<()> , settings: Settings , handler: fn(Request) -> Response / ) } /// Serve requests from `buffer` at `at`, `served` of them so far. The /// connection is kept unless the request, the response, the acceptor /// (`drain`) or `max_requests` says otherwise. fn serve_requests :: serving: Serving buffer: Bytes at: Int served: Int -> () / { let conn = serving.conn let activity = serving.activity match read_request conn activity serving.settings buffer at { Ok(Incoming(req, keep_alive, buffer, at)) -> { process.send activity Handling let req = Request(..req, headers: list.append serving.peer req.headers) // HEAD is GET without the body (RFC 9110 §9.3.2): the handler sees // a GET, and the body is not sent (a stream fn is not called). let with_body = req.method != "HEAD" let req = if with_body { req } else { Request(..req, method: "GET") } let handler = serving.handler let resp = handler req let served = served + 1 let closes = find_header resp.headers "connection" |> option.unwrap_or "" |> has_token "close" let max = serving.settings.max_requests let drained = option.is_some (process.receive serving.drain 0) let keep = keep_alive && !closes && !drained && (max < 0 || served < max) let sent = if final_status_without_body resp.status { send_response conn activity (bytes.from_string (head_bytes resp.status resp.headers keep "")) } else { match resp.body { Whole(_) -> send_response conn activity (serialize resp keep with_body) , Streamed ( write ) -> if with_body { serve_streamed conn activity resp keep write } else { // HEAD: the head only. The stream fn still runs, and its first // write fails, so what it started is stopped (#363). let head = send_response conn activity (serialize_stream_head resp keep) write Headless head } } } match sent { Ok(_) -> if keep { serve_requests serving buffer at served } else { () } , Error(_) -> () } } , Error(Closed) -> () , Error(Bad(status, message)) -> { let _ = send_response conn activity (serialize (text status message) False True) () } } } /// A streamed response (ADR 0053): the head (chunked, no length), the /// stream fn, the final chunk. Between chunks the connection is untimed; /// each write is timed per chunk by the watchdog. fn serve_streamed :: conn: Resource activity: Subject resp: Response keep: Bool write: fn(Writer) -> () / -> Result<(), String> / { use () <- result.try (send_response conn activity (serialize_stream_head resp keep)) process.send activity Streaming write Socket(conn, activity) process.send activity Writing net.write conn (bytes.from_string "0\r\n\r\n") } /// Write a response (timed by the watchdog). fn send_response :: conn: Resource activity: Subject data: Bytes -> Result<(), String> / { process.send activity Writing net.write conn data } /// The largest request head, in bytes (431 beyond it). fn head_limit :: -> Int { 65536 } fn read_request :: conn activity settings: Settings buffer: Bytes at: Int -> Result / { match parse_head buffer at { Partial -> if bytes.length buffer > at { // A head has begun: it must arrive whole within `head_timeout`. process.send activity HeadStarted let begun = bytes.slice buffer at (bytes.length buffer) read_head conn activity settings (bytes.append (bytes.builder ()) begun) (bytes.length begun) (last_bytes begun) } else { // Waiting for a request to start: `idle_timeout`, and the acceptor // may close the connection now (`Idle`). process.send activity Idle match read_raw conn { Ok(more) -> read_request conn activity settings more 0 , Error(e) -> Error(e) } } , head -> request_of conn activity settings head buffer at } } /// The request whose head, from offset `at` of `buffer`, is `head`. fn request_of :: conn activity settings: Settings head: Head buffer: Bytes at: Int -> Result / { match head { Complete ( method , path , version , headers , end , length ) -> if end - at > head_limit () { Error(Bad(431, "request head too large")) } else { let max_body = body_limit settings path match read_body conn activity max_body headers length buffer end { Ok((body, buffer, at)) -> Ok( Incoming( Request(method, path, headers, body) , keeps_alive version headers , buffer , at ) ) , Error(e) -> Error(e) } } , Invalid(reason) -> Error(Bad(400, "bad request: " <> reason)) // Its end was found, yet it is incomplete: blank lines before the // request line, which would otherwise restart `head_timeout`. , Partial -> Error(Bad(400, "bad request: an empty head")) } } /// Read the rest of a head begun in `received` (`size` bytes, ending in /// `tail`), not reported to the watchdog, which times it by /// `head_timeout`. Each read is scanned once for the head's end, with /// the 3 bytes before it; then the head is built and parsed once (ADR /// 0012, Revision 2). fn read_head :: conn activity settings: Settings received: Builder size: Int tail: Bytes -> Result / { if size > head_limit () { Error(Bad(431, "request head too large")) } else { match read_raw conn { Ok(more) -> { let window = bytes.concat tail more let received = bytes.append received more if parse_head_end window 0 >= 0 { let buffer = bytes.build received request_of conn activity settings (parse_head buffer 0) buffer 0 } else { read_head conn activity settings received (size + bytes.length more) (last_bytes window) } } , Error(e) -> Error(e) } } } /// The last 3 bytes of `b` (all of them if fewer): an end of head may /// straddle two reads. fn last_bytes :: b: Bytes -> Bytes { let n = bytes.length b bytes.slice b if n > 3 { n - 3 } else { 0 } n } /// Whether the client wants the connection kept open after its request. fn keeps_alive :: version: Int headers: List<(String, String)> -> Bool { let connection = option.unwrap_or (find_header headers "connection") "" if version == 0 { has_token connection "keep-alive" } else { !has_token connection "close" } } /// Whether the comma-separated `value` lists `token` (lowercase). fn has_token :: value: String token: String -> Bool { list.any (string.split (string.to_lower value) ",") fn t { string.trim t == token } } /// The body that starts at offset `at` of `buffer`, then where the next /// request starts. A body over `max_body` bytes (if not negative) is not /// read: it gets a 413, and the connection is closed. fn read_body :: conn activity max_body: Int headers length: Int buffer: Bytes at: Int -> Result<(Bytes, Bytes, Int), Failure> / { match find_header headers "transfer-encoding" { Some ( coding ) -> if length >= 0 { // Two framings: reading the wrong one would desynchronize the // connection (request smuggling). Error(Bad(400, "bad request: both Content-Length and Transfer-Encoding")) } else if string.to_lower (string.trim coding) == "chunked" { continue_if_expected conn headers buffer at read_chunks conn activity max_body buffer at (bytes.builder ()) 0 } else { Error(Bad(501, "unsupported Transfer-Encoding: " <> coding)) } , None -> if too_large length max_body { // Before `100 Continue`: a waiting client does not send the body. Error(too_large_error ()) } else if length > 0 { continue_if_expected conn headers buffer at take conn activity buffer at length } else { Ok((bytes.empty (), buffer, at)) } } } /// The body limit for a request to `target` (a path, with or without its /// query): the limit of the first of `settings.large_bodies` whose /// prefix matches the path on whole segments, else `settings.max_body`. /// The path is matched as the client wrote it, not decoded: a request /// that spells a prefix another way (`/upl%6Fads`) gets `max_body`. pub fn body_limit :: settings: Settings target: String -> Int { let path = (target_split target).0 match list.find settings.large_bodies fn entry { under path entry.0 } { Some((_, limit)) -> limit, None -> settings.max_body } } /// Whether `path` is `prefix` or below it, on whole segments. fn under :: path: String prefix: String -> Bool { string.starts_with path prefix && ( string.ends_with prefix "/" || string.byte_length path == string.byte_length prefix || string.starts_with (string.slice path (string.length prefix) (string.length path)) "/" ) } fn too_large :: size: Int max_body: Int -> Bool { max_body >= 0 && size > max_body } fn too_large_error :: -> Failure { Bad(413, "request body too large") } /// Tell a client that waits for it (`Expect: 100-continue`) to send the /// body. fn continue_if_expected :: conn headers buffer: Bytes at: Int -> () / { let expect = option.map (find_header headers "expect") string.to_lower if expect == Some("100-continue") && bytes.length buffer == at { let _ = net.write_string conn "HTTP/1.1 100 Continue\r\n\r\n" () } else { () } } /// The data of the chunks from offset `at` of `buffer` on, appended to /// `body` (`size` bytes so far); then where the next request starts. fn read_chunks :: conn activity max_body: Int buffer: Bytes at: Int body: Builder size: Int -> Result<(Bytes, Bytes, Int), Failure> / { match parse_chunk buffer at { ChunkData(start, chunk) -> if too_large (size + chunk) max_body { Error(too_large_error ()) } else { match take conn activity buffer start (chunk + 2) { Ok((data, buffer, at)) -> if bytes.slice data chunk (chunk + 2) == bytes.from_string "\r\n" { read_chunks conn activity max_body buffer at (bytes.append body (bytes.slice data 0 chunk)) (size + chunk) } else { Error(Bad(400, "bad request: no CRLF after a chunk")) } , Error(e) -> Error(e) } } , ChunkEnd(end) -> Ok((bytes.build body, buffer, end)) , ChunkInvalid(reason) -> Error(Bad(400, "bad request: " <> reason)) , ChunkPartial -> if bytes.length buffer - at > 65536 { Error(Bad(400, "bad request: chunk header too large")) } else { match receive_more conn activity buffer at { Ok(buffer) -> read_chunks conn activity max_body buffer 0 body size , Error(e) -> Error(e) } } } } /// `length` bytes from offset `at` of `buffer`, reading more as needed; /// then where what follows them starts. Reads go into a builder, so a /// large body is copied a bounded number of times. fn take :: conn activity buffer: Bytes at: Int length: Int -> Result<(Bytes, Bytes, Int), Failure> / { let available = bytes.length buffer - at if available >= length { Ok((bytes.slice buffer at (at + length), buffer, at + length)) } else { let rest = bytes.slice buffer at (bytes.length buffer) take_more conn activity (bytes.append (bytes.builder ()) rest) available length } } fn take_more :: conn activity received: Builder size: Int length: Int -> Result<(Bytes, Bytes, Int), Failure> / { if size >= length { let all = bytes.build received Ok((bytes.slice all 0 length, all, length)) } else { match read_some conn activity { Ok(more) -> take_more conn activity (bytes.append received more) (size + bytes.length more) length , Error(e) -> Error(e) } } } /// The unread part of `buffer` (from offset `at`), then what arrives next. fn receive_more :: conn activity buffer: Bytes at: Int -> Result / { match read_some conn activity { Ok(more) -> Ok(bytes.concat (bytes.slice buffer at (bytes.length buffer)) more) , Error(e) -> Error(e) } } /// The next bytes from the connection, timed by `idle_timeout` from now. fn read_some :: conn: Resource activity: Subject -> Result / { process.send activity Reading read_raw conn } /// The next bytes from the connection, under whatever timeout runs. fn read_raw :: conn: Resource -> Result / { match net.read conn 65536 { Ok(more) -> if bytes.length more == 0 { Error(Closed) } else { Ok(more) } , Error(_) -> Error(Closed) } } type Head { Partial , Invalid(reason: String) /// The head ends at offset `end`; `content_length` is -1 when absent. , Complete( method: String , path: String , version: Int , headers: List<(String, String)> , end: Int , content_length: Int ) } @extern c "tl_http_parse_request" fn parse_head :: buffer: Bytes at: Int -> Head /// Where the head in `buffer` ends (just past its empty line), if it ends /// at or after `from`; else -1. @extern c "tl_http_parse_head_end" fn parse_head_end :: buffer: Bytes from: Int -> Int type Chunk { ChunkPartial , ChunkInvalid(reason: String) /// `size` bytes of data from offset `start`, then CRLF. , ChunkData(start: Int, size: Int) /// The last chunk and its trailers end at offset `end`. , ChunkEnd(end: Int) } @extern c "tl_http_parse_chunk" fn parse_chunk :: buffer: Bytes at: Int -> Chunk /// Whether `status` is a final status this server sends without framing or a /// message body: 204 No Content or 304 Not Modified. fn final_status_without_body :: status: Int -> Bool { status == 204 || status == 304 } /// The head and (unless `with_body` is false, for HEAD requests) the body, /// in one buffer so they leave in one write. The whole-body case. fn serialize :: resp: Response keep_alive: Bool with_body: Bool -> Bytes { let body = option.unwrap_or (whole_body resp) (bytes.empty ()) let head = head_bytes resp.status resp.headers keep_alive ("Content-Length: " <> show (bytes.length body)) let out = bytes.append_string (bytes.builder ()) head bytes.build if with_body { bytes.append out body } else { out } } /// A streamed response's head: `Transfer-Encoding: chunked`, no length. fn serialize_stream_head :: resp: Response keep_alive: Bool -> Bytes { bytes.from_string ( head_bytes resp.status resp.headers keep_alive "Transfer-Encoding: chunked" ) } /// The status line, the caller's headers (framing filtered), the framing /// header, and the keep-alive line. fn head_bytes :: status: Int headers: List<(String, String)> keep_alive: Bool framing: String -> String { let own = list.filter headers fn h { !is_framing (string.to_lower h.0) } string.concat [ "HTTP/1.1 " , show status , " " , reason status , "\r\n" , string.concat (list.map own fn h { h.0 <> ": " <> h.1 <> "\r\n" }) , if framing == "" { "" } else { framing <> "\r\n" } , if keep_alive { "Connection: keep-alive\r\n\r\n" } else { "Connection: close\r\n\r\n" } ] } /// Headers the server sets itself. fn is_framing :: name: String -> Bool { match name { "content-length" | "connection" | "transfer-encoding" -> True, _ -> False } } /// The status line's reason phrase (RFC 9110 §15 and the registered /// extensions); `"Status"` for one not in the set. pub fn reason :: status: Int -> String { match status { 100 -> "Continue" , 101 -> "Switching Protocols" , 200 -> "OK" , 201 -> "Created" , 202 -> "Accepted" , 203 -> "Non-Authoritative Information" , 204 -> "No Content" , 205 -> "Reset Content" , 206 -> "Partial Content" , 226 -> "IM Used" , 300 -> "Multiple Choices" , 301 -> "Moved Permanently" , 302 -> "Found" , 303 -> "See Other" , 304 -> "Not Modified" , 305 -> "Use Proxy" , 307 -> "Temporary Redirect" , 308 -> "Permanent Redirect" , 400 -> "Bad Request" , 401 -> "Unauthorized" , 402 -> "Payment Required" , 403 -> "Forbidden" , 404 -> "Not Found" , 405 -> "Method Not Allowed" , 406 -> "Not Acceptable" , 407 -> "Proxy Authentication Required" , 408 -> "Request Timeout" , 409 -> "Conflict" , 410 -> "Gone" , 411 -> "Length Required" , 412 -> "Precondition Failed" , 413 -> "Content Too Large" , 414 -> "URI Too Long" , 415 -> "Unsupported Media Type" , 416 -> "Range Not Satisfiable" , 417 -> "Expectation Failed" , 418 -> "I'm a Teapot" , 421 -> "Misdirected Request" , 422 -> "Unprocessable Content" , 423 -> "Locked" , 424 -> "Failed Dependency" , 425 -> "Too Early" , 426 -> "Upgrade Required" , 428 -> "Precondition Required" , 429 -> "Too Many Requests" , 431 -> "Request Header Fields Too Large" , 451 -> "Unavailable For Legal Reasons" , 500 -> "Internal Server Error" , 501 -> "Not Implemented" , 502 -> "Bad Gateway" , 503 -> "Service Unavailable" , 504 -> "Gateway Timeout" , 505 -> "HTTP Version Not Supported" , 507 -> "Insufficient Storage" , 508 -> "Loop Detected" , 510 -> "Not Extended" , 511 -> "Network Authentication Required" , _ -> "Status" } } /// The fields of an `application/x-www-form-urlencoded` body (or query /// string): `a=1&b=two+words` gives `[("a", "1"), ("b", "two words")]`. /// Pairs split on `&`, each on its first `=`, both sides percent-decoded /// with `+` a space — in the query (`query_params`) as in a form body, /// as browsers send both; empty pairs are dropped, a bare `k` is /// `("k", "")`. @extern c "tl_http_parse_query" pub fn form :: body: String -> List<(String, String)> /// The request target split at its first `?`: `(path, query)`, the query /// without the `?` ("" when there is none). Later `?`s stay in the query: /// `target_split("/a?b?c")` is `("/a", "b?c")`. pub fn target_split :: target: String -> (String, String) { match string.split target "?" { [path] -> (path, "") , [path, ..rest] -> (path, string.join rest "?") , [] -> ("", "") } } /// The path of the request's target (before any `?`). pub fn path :: req: Request -> String { (target_split req.path).0 } /// The query of the request's target (after the first `?`), "" when it /// has none. pub fn query :: req: Request -> String { (target_split req.path).1 } /// The path's segments: split on `/` with empty segments dropped, each /// percent-decoded. Decoding happens after splitting, so an encoded slash /// (`%2F`) stays inside its segment. pub fn segments :: req: Request -> List { list.map (list.filter (string.split (path req) "/") fn s { s != "" }) url_decode } /// The query's parameters: split on `&`, each `k=v` on its first `=`, /// both sides percent-decoded; a bare `k` is `("k", "")`. pub fn query_params :: req: Request -> List<(String, String)> { form (query req) } /// The value of field `name` in a form, if present. pub fn field :: fields: List<(String, String)> name: String -> Option { match fields { [] -> None , [(k, v), ..rest] -> if k == name { Some(v) } else { field rest name } } } /// Decode `%XX` escapes and `+` (a space); invalid escapes stay as they /// are. A string without `%` or `+` is returned as is. @extern c "tl_url_decode" owned pub fn url_decode :: s: String -> String /// Percent-encode `s` for a URL path or query (RFC 3986): every byte /// outside the unreserved set (`A-Z a-z 0-9 - _ . ~`) becomes `%XX` /// (uppercase hex). A space is `%20`, not `+`: `url_decode` maps both /// back to a space, and a `+` in a path segment decodes as a space only /// in a query or form, so `%20` is the safe spelling everywhere. /// `url_decode(url_encode(s))` is `s`. A string without a byte to encode /// is returned as is. @extern c "tl_url_encode" owned pub fn url_encode :: s: String -> String