API reference

suberrorClosed

A message sent on a connection that has already closed (HTTP and WebSocket spec 2.4): the client went away, or the response or the WebSocket was already finished. A server raises it from send. An application that keeps sending after a disconnect catches it and stops; a server need not log it as a failure. The text says which connection, for whoever reads the log.

pub(all) suberror Closed {
  Closed(String)
} derive(Eq, @debug.Debug)

enumAsgiApplication

An application in either calling convention — the current 3.0 single-callable form or the legacy 2.0 double-callable form. A server holds one of these and normalizes it with guarantee_single_callable; the enum is the typed, reflection-free way to name which convention an application is written in.

pub(all) enum AsgiApplication {
  Single(async (Scope, async () -> Event, async (Event) -> Unit) -> Unit)
  Legacy((Scope) -> async (async () -> Event, async (Event) -> Unit) -> Unit)
}

structAsgiVersion

The asgi sub-dict every scope carries: the ASGI protocol version ("3.0") and the spec_version of the concrete http / websocket / lifespan sub-spec the server implements. Applications negotiate optional behaviour against spec_version with at_least.

pub(all) struct AsgiVersion {
  version : String
  spec_version : String
} derive(Eq)

pub fn AsgiVersion::at_least(Self, major~ : Int32, minor~ : Int32) -> Bool

pub fn AsgiVersion::http() -> Self

pub fn AsgiVersion::lifespan() -> Self

pub fn AsgiVersion::websocket() -> Self

enumEvent

A protocol event flowing between server and application. Replaces ASGI's stringly-typed message dicts with a typed sum covering the http / websocket / lifespan message sets in both directions, including the standard extension messages (server push, path-send, zero-copy send, response trailers, early hints, debug, and WebSocket denial with a full HTTP response).

pub(all) enum Event {
  HttpRequest(body~ : Bytes, more_body~ : Bool)
  HttpDisconnect
  HttpResponseStart(status~ : Int32, headers~ : Array[(String, String)], trailers~ : Bool)
  HttpResponseBody(body~ : Bytes, more_body~ : Bool)
  HttpResponseTrailers(headers~ : Array[(String, String)], more_trailers~ : Bool)
  HttpResponsePush(path~ : String, headers~ : Array[(String, String)])
  HttpResponsePathSend(path~ : String)
  HttpResponseZeroCopySend(fd~ : Int32, offset~ : Int32?, count~ : Int32?, more_body~ : Bool)
  HttpResponseDebug(info~ : Json)
  HttpResponseEarlyHint(links~ : Array[String])
  WebSocketConnect
  WebSocketReceive(text~ : String?, bytes~ : Bytes?)
  WebSocketDisconnect(code~ : Int32, reason~ : String?)
  WebSocketAccept(subprotocol~ : String?, headers~ : Array[(String, String)])
  WebSocketSendText(String)
  WebSocketSendBytes(Bytes)
  WebSocketClose(code~ : Int32, reason~ : String)
  WebSocketHttpResponseStart(status~ : Int32, headers~ : Array[(String, String)], trailers~ : Bool)
  WebSocketHttpResponseBody(body~ : Bytes, more_body~ : Bool)
  LifespanStartup
  LifespanShutdown
  LifespanStartupComplete
  LifespanStartupFailed(message~ : String)
  LifespanShutdownComplete
  LifespanShutdownFailed(message~ : String)
  Other(type_~ : String, payload~ : Json)
} derive(Eq, @debug.Debug)

structExtensions

The scope's extensions map, modelled as typed capability flags plus the one extension that carries data (tls). A server sets a flag to advertise that it will honour the matching outbound event — an application checks the flag before emitting HttpResponsePush / HttpResponsePathSend / HttpResponseEarlyHint / HttpResponseTrailers / WebSocketHttpResponseStart, exactly as an ASGI app tests "http.response.push" in scope["extensions"].

pub(all) struct Extensions {
  tls : TlsExtension?
  http_response_push : Bool
  http_response_trailers : Bool
  http_response_pathsend : Bool
  http_response_zerocopysend : Bool
  http_response_early_hint : Bool
  http_response_debug : Bool
  websocket_http_response : Bool
  custom : Map[String, Json]
} derive(Eq)

pub fn Extensions::enable(Self, String, value? : Json) -> Self

pub fn Extensions::enable_debug(Self) -> Self

pub fn Extensions::enable_early_hint(Self) -> Self

pub fn Extensions::enable_pathsend(Self) -> Self

pub fn Extensions::enable_push(Self) -> Self

pub fn Extensions::enable_trailers(Self) -> Self

pub fn Extensions::enable_websocket_http_response(Self) -> Self

pub fn Extensions::enable_zerocopysend(Self) -> Self

pub fn Extensions::get(Self, String) -> Json?

pub fn Extensions::none() -> Self

pub fn Extensions::with_tls(Self, TlsExtension) -> Self

enumHttp2HeaderError

Why a HEADERS frame does not map onto an HttpScope field-by-field: an HTTP/2 (RFC 7540 §8.1.2.3) or HTTP/3 request carries its request line as four *pseudo-headers* — :method, :scheme, :authority, :path — interleaved with the ordinary fields, and ASGI reserves no slot for them in scope["headers"]. A conforming server must consume the pseudo-headers into the scope's typed fields and hand the application only the ordinary headers, with host synthesised from :authority. moonasgi owns that lowering so every h2/h2c/h3 transport produces the same scope from the same frame, and an app never sees a :-prefixed header.

A malformed pseudo-header set — a missing required one, a duplicate, an unknown :foo, or a pseudo-header after an ordinary field — is rejected with the exact Http2HeaderError, matching RFC 7540's "malformed request" treatment, so the transport can answer RST_STREAM(PROTOCOL_ERROR) instead of forwarding a bad scope.

pub(all) enum Http2HeaderError {
  MissingMethod
  MissingScheme
  MissingPath
  EmptyPath
  DuplicatePseudoHeader(String)
  UnknownPseudoHeader(String)
  PseudoHeaderAfterRegular(String)
} derive(Eq)

structHttpScope

HTTP connection scope (ASGI type == "http"). raw_path / query_string stay Bytes because they are not guaranteed valid UTF-8; header names follow ASGI's lowercased-latin1 convention. asgi carries the version handshake, extensions the advertised server capabilities, and state is per-connection scratch copied from the lifespan state.

pub(all) struct HttpScope {
  http_version : String
  http_method : String
  scheme : String
  path : String
  raw_path : Bytes
  query_string : Bytes
  root_path : String
  headers : Array[(String, String)]
  client : (String, Int32)?
  server : (String, Int32?)?
  asgi : AsgiVersion
  extensions : Extensions
  state : Map[String, Json]
}

pub fn HttpScope::from_h2_headers(Array[(String, String)], http_version? : String, root_path? : String, client? : (String, Int32), server? : (String, Int32?), extensions? : Extensions, asgi? : AsgiVersion, state? : Map[String, Json]) -> Result[Self, Http2HeaderError]

pub fn HttpScope::new(http_method~ : String, path~ : String, http_version? : String, scheme? : String, raw_path? : Bytes, query_string? : Bytes, root_path? : String, headers? : Array[(String, String)], client? : (String, Int32), server? : (String, Int32?), asgi? : AsgiVersion, extensions? : Extensions, state? : Map[String, Json]) -> Self

structLifespanScope

Lifespan scope (ASGI type == "lifespan"): a single run spanning process startup and shutdown, whose state seeds every request scope. Carries its own asgi handshake — lifespan versions independently (sub-spec 2.0), so it does not borrow the http/websocket spec_version.

pub(all) struct LifespanScope {
  asgi : AsgiVersion
  state : Map[String, Json]
}

pub fn LifespanScope::new(asgi? : AsgiVersion, state? : Map[String, Json]) -> Self

enumScope

The connection scope: one value per HTTP request, WebSocket connection, or lifespan run. It carries the immutable connection metadata a server hands to an application, mirroring ASGI 3.0's scope dict as a typed sum.

pub(all) enum Scope {
  Http(HttpScope)
  WebSocket(WebSocketScope)
  Lifespan(LifespanScope)
}

structTlsExtension

The tls extension's per-connection data (ASGI TLS extension). Present in a scope's extensions only when the connection is TLS-terminated by the server. Certificates are PEM text; tls_version / cipher_suite are the numeric IANA identifiers, None when the server does not expose them.

pub(all) struct TlsExtension {
  server_cert : String?
  client_cert_chain : Array[String]
  client_cert_name : String?
  client_cert_error : String?
  tls_version : Int32?
  cipher_suite : Int32?
} derive(Eq)

structWebSocketScope

WebSocket connection scope (ASGI type == "websocket"). scheme is "ws"/"wss"; subprotocols are the client-offered values. Carries the same asgi handshake and extensions capabilities as an http scope.

pub(all) struct WebSocketScope {
  http_version : String
  scheme : String
  path : String
  raw_path : Bytes
  query_string : Bytes
  root_path : String
  headers : Array[(String, String)]
  client : (String, Int32)?
  server : (String, Int32?)?
  subprotocols : Array[String]
  asgi : AsgiVersion
  extensions : Extensions
  state : Map[String, Json]
}

pub fn WebSocketScope::new(path~ : String, http_version? : String, scheme? : String, raw_path? : Bytes, query_string? : Bytes, root_path? : String, headers? : Array[(String, String)], client? : (String, Int32), server? : (String, Int32?), subprotocols? : Array[String], asgi? : AsgiVersion, extensions? : Extensions, state? : Map[String, Json]) -> Self

pub fn WebSocketScope::select_subprotocol(Self, Array[String]) -> String?

typeAsgiApp

The load-bearing ASGI callable: (scope, receive, send). Every server binds to this shape and every framework in the suite ultimately compiles down to it.

pub type AsgiApp = async (Scope, async () -> Event, async (Event) -> Unit) -> Unit

typeAsgiAppInstance

The asynchronous instance a legacy app's first callable returns: already bound to the scope, it drives the connection with receive / send.

pub type AsgiAppInstance = async (async () -> Event, async (Event) -> Unit) -> Unit

typeLegacyAsgiApp

A legacy ASGI 2.0 double-callable application: a synchronous application(scope) that returns the AsgiAppInstance.

pub type LegacyAsgiApp = (Scope) -> async (async () -> Event, async (Event) -> Unit) -> Unit

typeReceive

Pull the next inbound event. The async awaitable an application calls to read request body chunks, websocket frames, or lifespan signals.

pub type Receive = async () -> Event

typeSend

Push an outbound event. The async awaitable an application calls to emit response start/body, websocket frames, or lifespan completion.

pub type Send = async (Event) -> Unit

enumDrain

Why a body drain stopped: the request body finished, the client went away mid-request, or the stream ran out without either. A long-polling or streaming handler cares about the difference — Disconnected means nothing it sends will arrive, so cleanup is all that is left to do.

pub(all) enum Drain {
  Complete
  Disconnected
  Truncated
} derive(Eq, @debug.Debug)

structRequest

An inbound HTTP request in ergonomic form: the request line, headers, and the fully-read body. The sugar over @spec.HttpScope plus a drained Receive, so a Handler never touches the async transport directly.

pub(all) struct Request {
  http_method : String
  path : String
  query_string : Bytes
  headers : Array[(String, String)]
  body : Bytes
} derive(Eq)

pub fn Request::header(Self, String) -> String?

structResponse

An outbound HTTP response: status, headers, and the full body. Mutable so middleware can decorate it before the server serialises it into HttpResponseStart + HttpResponseBody.

pub(all) struct Response {
  status : Int32
  headers : Array[(String, String)]
  body : Bytes
} derive(Eq)

pub fn Response::events(Self) -> Array[@spec.Event]

pub fn Response::header(Self, String) -> String?

pub fn Response::json(status? : Int32, Json) -> Self

pub fn Response::new(Int32, Array[(String, String)], Bytes) -> Self

pub fn Response::text(status? : Int32, String) -> Self

structStreamingResponse

A streamed outbound response: the status line, headers, an ordered list of body chunks each emitted as its own HttpResponseBody, and optional trailing trailers. Models ASGI response streaming (multiple body messages with more_body: true) and the http.response.trailers extension without an async transport. events lowers it to the exact event sequence a server would send. early_hints (the http.response.early_hint extension) are the 103 Early Hints messages emitted ahead of the final response, each element a list of Link header values.

pub(all) struct StreamingResponse {
  status : Int32
  headers : Array[(String, String)]
  chunks : Array[Bytes]
  trailers : Array[(String, String)]
  early_hints : Array[Array[String]]
} derive(Eq)

pub fn StreamingResponse::events(Self) -> Array[@spec.Event]

pub fn StreamingResponse::new(chunks~ : Array[Bytes], status? : Int32, headers? : Array[(String, String)], trailers? : Array[(String, String)], early_hints? : Array[Array[String]]) -> Self

typeHandler

The ergonomic request→response function most handlers are written as. The synchronous sugar the suite lifts onto @spec.AsgiApp at the server boundary.

pub type Handler = (Request) -> Response

typeMiddleware

A handler transformer that wraps a downstream Handler to add cross-cutting behaviour. Composed as an onion where the first registered is outermost.

pub type Middleware = ((Request) -> Response) -> (Request) -> Response

typeStreamHandler

A streaming handler: produces a StreamingResponse (multi-chunk body, optional trailers) instead of a single buffered Response. Driven by run_http_stream and the TestClient.

pub type StreamHandler = (Request) -> StreamingResponse

structWebSocketHandler

A synchronous WebSocket application in the connect / receive / disconnect shape, the WebSocket analog of the http Handler. on_connect decides the handshake from the scope; on_receive maps each inbound WsMessage to the frames to send back (it may Close); on_disconnect runs when the client goes away, carrying the close code and the optional close reason (ASGI 2.5). Driven in-process by ws_run and the TestClient, so accept/subprotocol/echo/close logic is testable on every backend without an async socket — the faithful synchronous core the async server lifts onto AsgiApp.

pub(all) struct WebSocketHandler {
  on_connect : (@spec.WebSocketScope) -> WsAccept
  on_receive : (WsMessage) -> Array[WsSend]
  on_disconnect : (Int32, String?) -> Array[WsSend]
}

pub fn WebSocketHandler::echo(subprotocol? : String) -> Self

pub fn WebSocketHandler::new(on_connect? : (@spec.WebSocketScope) -> WsAccept, on_receive? : (WsMessage) -> Array[WsSend], on_disconnect? : (Int32, String?) -> Array[WsSend]) -> Self

enumWsAccept

The application's answer to a WebSocketConnect, mirroring the three replies ASGI allows to an opening handshake: Accept it (optionally choosing a subprotocol and adding response headers), Reject it with a bare close code (ASGI closes the handshake with websocket.close), or DenyHttp it with a full HTTP response (the websocket.http.response extension — a real status + headers + body instead of a bare close).

pub(all) enum WsAccept {
  Accept(subprotocol~ : String?, headers~ : Array[(String, String)])
  Reject(code~ : Int32, reason~ : String)
  DenyHttp(status~ : Int32, headers~ : Array[(String, String)], body~ : Bytes)
} derive(Eq)

enumWsMessage

A message crossing a WebSocket in either direction: a UTF-8 Text frame or a Binary frame. The ergonomic form of WebSocketReceive / WebSocketSendText / WebSocketSendBytes, so a WebSocketHandler reasons over messages instead of raw events.

pub(all) enum WsMessage {
  Text(String)
  Binary(Bytes)
} derive(Eq, @debug.Debug)

enumWsSend

An outbound action a WebSocketHandler takes while the connection is open: send a SendText / SendBinary frame, or Close the connection with a code and reason. A Close ends the handler's send stream — the driver stops pulling further inbound messages, mirroring a server that has closed the socket.

pub(all) enum WsSend {
  SendText(String)
  SendBinary(Bytes)
  Close(code~ : Int32, reason~ : String)
} derive(Eq)

structLifespanHandler

A synchronous lifespan application in the startup / shutdown shape, the lifespan analog of the http Handler and the WebSocket WebSocketHandler. on_startup runs once at boot: it seeds the scope's state in place (the map the server then copies onto every request scope — a DB pool handle, a loaded config) and returns Complete or Failed. on_shutdown runs once at teardown to release those resources. Driven in-process by run_lifespan, so boot/teardown logic is testable on every backend without an async runtime — the synchronous core a server lifts onto the lifespan protocol.

pub(all) struct LifespanHandler {
  on_startup : (@spec.LifespanScope) -> LifespanReply
  on_shutdown : (@spec.LifespanScope) -> LifespanReply
}

pub fn LifespanHandler::new(on_startup? : (@spec.LifespanScope) -> LifespanReply, on_shutdown? : (@spec.LifespanScope) -> LifespanReply) -> Self

enumLifespanReply

An application's answer to a lifespan phase: Complete when startup or shutdown succeeded, or Failed with a message the server logs and (for startup) aborts the boot on. Mirrors the two replies ASGI allows to each lifespan message — lifespan.startup.complete / .failed and lifespan.shutdown.complete / .failed.

pub(all) enum LifespanReply {
  Complete
  Failed(message~ : String)
} derive(Eq)

structPushPromise

A server-side push promise captured by the TestClient: the pushed path and the request headers the server would send for it (http.response.push).

pub(all) struct PushPromise {
  path : String
  headers : Array[(String, String)]
} derive(Eq, @debug.Debug)

pub fn PushPromise::header(Self, String) -> String?

structTestClient

An in-process application driver — the ASGI TestClient — built on the synchronous @http.run_http_app core, so it needs no socket and runs on every backend. It builds a synthetic http scope, feeds the request body in as HttpRequest events, runs the application, and reassembles the outbound stream into a TestResponse. app is the event-emitting application; the new / from_stream constructors adapt a @http.Handler / @http.StreamHandler.

pub(all) struct TestClient {
  app : (@http.Request) -> Array[@spec.Event]
  root_path : String
  base_headers : Array[(String, String)]
  client : (String, Int32)?
  server : (String, Int32?)?
  extensions : @spec.Extensions
}

pub fn TestClient::delete(Self, String, headers? : Array[(String, String)]) -> TestResponse

pub fn TestClient::from_app((@http.Request) -> Array[@spec.Event], root_path? : String, base_headers? : Array[(String, String)], client? : (String, Int32)?, server? : (String, Int32?)?, extensions? : @spec.Extensions) -> Self

pub fn TestClient::from_stream((@http.Request) -> @http.StreamingResponse, root_path? : String, base_headers? : Array[(String, String)], client? : (String, Int32)?, server? : (String, Int32?)?, extensions? : @spec.Extensions) -> Self

pub fn TestClient::get(Self, String, headers? : Array[(String, String)]) -> TestResponse

pub fn TestClient::head(Self, String, headers? : Array[(String, String)]) -> TestResponse

pub fn TestClient::new((@http.Request) -> @http.Response, root_path? : String, base_headers? : Array[(String, String)], client? : (String, Int32)?, server? : (String, Int32?)?, extensions? : @spec.Extensions) -> Self

pub fn TestClient::patch(Self, String, body? : Bytes, headers? : Array[(String, String)]) -> TestResponse

pub fn TestClient::post(Self, String, body? : Bytes, headers? : Array[(String, String)]) -> TestResponse

pub fn TestClient::put(Self, String, body? : Bytes, headers? : Array[(String, String)]) -> TestResponse

pub fn TestClient::request(Self, http_method~ : String, path~ : String, headers? : Array[(String, String)], body? : Bytes, http_version? : String, chunks? : Array[Bytes]) -> TestResponse

pub fn TestClient::websocket(Self, path~ : String, handler~ : @ws.WebSocketHandler, send? : Array[@ws.WsMessage], headers? : Array[(String, String)], subprotocols? : Array[String], disconnect? : Int32?) -> WsTestSession

pub fn TestClient::websocket_app(Self, path~ : String, app~ : (@spec.WebSocketScope, Array[@spec.Event]) -> Array[@spec.Event], send? : Array[@ws.WsMessage], headers? : Array[(String, String)], subprotocols? : Array[String], disconnect? : Int32?) -> WsTestSession

structTestResponse

The materialised result of driving an application in-process: the response status and headers, the body reassembled from every HttpResponseBody chunk, the trailing headers gathered from HttpResponseTrailers, any push promises, the pathsend path if the app used the path-send extension, the last zerocopysend handoff, every debug info payload, and the early_hints (each a 103 message's Link values). The captured, sans-transport analog of what a real client would observe.

pub(all) struct TestResponse {
  status : Int32
  headers : Array[(String, String)]
  body : Bytes
  trailers : Array[(String, String)]
  pushes : Array[PushPromise]
  pathsend : String?
  zerocopysend : ZeroCopySend?
  debug : Array[Json]
  early_hints : Array[Array[String]]
} derive(Eq, @debug.Debug)

pub fn TestResponse::header(Self, String) -> String?

pub fn TestResponse::json(Self) -> Json raise

pub fn TestResponse::text(Self) -> String

pub fn TestResponse::trailer(Self, String) -> String?

structWsTestSession

The materialised result of driving a WebSocket connection in-process: whether the handshake was accepted, the negotiated subprotocol and accept_headers, every server→client message (messages), whether the server closed and with what close_code / close_reason, and — when the handshake was denied with the websocket.http.response extension — the captured HTTP denial response. The WebSocket analog of TestResponse.

pub(all) struct WsTestSession {
  accepted : Bool
  subprotocol : String?
  accept_headers : Array[(String, String)]
  messages : Array[@ws.WsMessage]
  closed : Bool
  close_code : Int32?
  close_reason : String?
  denial : TestResponse?
} derive(Eq, @debug.Debug)

pub fn WsTestSession::header(Self, String) -> String?

pub fn WsTestSession::texts(Self) -> Array[String]

structZeroCopySend

A http.response.zerocopysend message captured by the TestClient: the open file descriptor the app handed off, and the optional byte offset / count. The sans-transport analog of the server performing the zero-copy send.

pub(all) struct ZeroCopySend {
  fd : Int32
  offset : Int32?
  count : Int32?
} derive(Eq, @debug.Debug)

structBodyLimit

A ceiling on a request body. A Content-Length above it is answered 413 at once, without calling the application. A body that grows past it while the application reads it is answered 413 too, when no response has started; the application then reads a disconnect, and what it sends afterwards is dropped, since the client already has its answer.

pub(all) struct BodyLimit {
  limit : Int32
} derive(Eq, @debug.Debug)

pub impl Layer for BodyLimit

pub fn BodyLimit::new(limit? : Int32) -> Self

pub fn BodyLimit::wrap(Self, async (@spec.Scope, async () -> @spec.Event, async (@spec.Event) -> Unit) -> Unit) -> async (@spec.Scope, async () -> @spec.Event, async (@spec.Event) -> Unit) -> Unit

structCors

Cross-origin resource sharing, per the Fetch standard §3.2.

origins, methods and headers are allow-lists, and "*" in one allows anything. A preflight is answered here: 200 with the negotiated headers, or 400 naming what was refused. Other cross-origin responses get access-control-allow-origin when the origin is allowed. With credentials the origin is echoed rather than *, as the standard requires.

pub(all) struct Cors {
  origins : Array[String]
  methods : Array[String]
  headers : Array[String]
  credentials : Bool
  expose : Array[String]
  max_age : Int32
} derive(Eq, @debug.Debug)

pub impl Layer for Cors

pub fn Cors::new(origins? : Array[String], methods? : Array[String], headers? : Array[String], credentials? : Bool, expose? : Array[String], max_age? : Int32) -> Self

pub fn Cors::wrap(Self, async (@spec.Scope, async () -> @spec.Event, async (@spec.Event) -> Unit) -> Unit) -> async (@spec.Scope, async () -> @spec.Event, async (@spec.Event) -> Unit) -> Unit

structGzip

Gzip for responses a client accepts it for: a body of at least minimum octets, sent in one message, not already content-encoded. level is the zlib effort, 0 to 9.

A body sent in several messages is passed through as it comes: compressing it would hold it back until the end, and a stream is sent in pieces so that it is not held back. An event stream is never compressed, for the same reason.

pub(all) struct Gzip {
  minimum : Int32
  level : Int32
} derive(Eq, @debug.Debug)

pub impl Layer for Gzip

pub fn Gzip::new(minimum? : Int32, level? : Int32) -> Self

pub fn Gzip::wrap(Self, async (@spec.Scope, async () -> @spec.Event, async (@spec.Event) -> Unit) -> Unit) -> async (@spec.Scope, async () -> @spec.Event, async (@spec.Event) -> Unit) -> Unit

structHttpsRedirect

Send every plain request to its secure equivalent: http to https and ws to wss, with a 307 so the method and body are kept. Port 80 or 443 in the host is dropped; any other port stays.

pub(all) struct HttpsRedirect {
} derive(Eq, @debug.Debug)

pub impl Layer for HttpsRedirect

pub fn HttpsRedirect::new() -> Self

pub fn HttpsRedirect::wrap(Self, async (@spec.Scope, async () -> @spec.Event, async (@spec.Event) -> Unit) -> Unit) -> async (@spec.Scope, async () -> @spec.Event, async (@spec.Event) -> Unit) -> Unit

structProxyHeaders

The client and scheme a reverse proxy saw, put back in the scope, by X-Forwarded-For / X-Forwarded-Proto or by RFC 7239's Forwarded. Only a request from an address in trusted is rewritten, since anyone else could claim any address; "*" trusts every peer.

X-Forwarded-For gives the client: the rightmost address that is not trusted, every proxy before it having appended its own; when all are trusted, the leftmost. X-Forwarded-Proto gives the scheme, http or https (ws or wss for a WebSocket). Without either header, the Forwarded header is read the same way through its for and proto.

pub(all) struct ProxyHeaders {
  trusted : Array[String]
} derive(Eq, @debug.Debug)

pub impl Layer for ProxyHeaders

pub fn ProxyHeaders::new(trusted? : Array[String]) -> Self

pub fn ProxyHeaders::wrap(Self, async (@spec.Scope, async () -> @spec.Event, async (@spec.Event) -> Unit) -> Unit) -> async (@spec.Scope, async () -> @spec.Event, async (@spec.Event) -> Unit) -> Unit

structServerErrors

What an application's failure becomes: a 500 when the response has not started, then the error raised on to the server, which logs it. debug puts the error in the body. handler writes the answer instead: (status, headers, body) for the error.

pub(all) struct ServerErrors {
  debug : Bool
  handler : ((Error) -> (Int32, Array[(String, String)], String))?
}

pub impl Layer for ServerErrors

pub fn ServerErrors::new(debug? : Bool, handler? : (Error) -> (Int32, Array[(String, String)], String)) -> Self

pub fn ServerErrors::wrap(Self, async (@spec.Scope, async () -> @spec.Event, async (@spec.Event) -> Unit) -> Unit) -> async (@spec.Scope, async () -> @spec.Event, async (@spec.Event) -> Unit) -> Unit

structTrustedHosts

Only the hosts listed may be asked for: a host header naming another answers 400. *.example.com allows any subdomain, * alone allows any host. With www_redirect, a request for example.com where only www.example.com is listed is sent there.

pub(all) struct TrustedHosts {
  hosts : Array[String]
  www_redirect : Bool
} derive(Eq, @debug.Debug)

pub impl Layer for TrustedHosts

pub fn TrustedHosts::new(hosts? : Array[String], www_redirect? : Bool) -> Self

pub fn TrustedHosts::wrap(Self, async (@spec.Scope, async () -> @spec.Event, async (@spec.Event) -> Unit) -> Unit) -> async (@spec.Scope, async () -> @spec.Event, async (@spec.Event) -> Unit) -> Unit

structWrap

A middleware written as a plain function from application to application.

pub(all) struct Wrap((async (@spec.Scope, async () -> @spec.Event, async (@spec.Event) -> Unit) -> Unit) -> async (@spec.Scope, async () -> @spec.Event, async (@spec.Event) -> Unit) -> Unit)

pub impl Layer for Wrap

pub fn Wrap::wrap(Self, async (@spec.Scope, async () -> @spec.Event, async (@spec.Event) -> Unit) -> Unit) -> async (@spec.Scope, async () -> @spec.Event, async (@spec.Event) -> Unit) -> Unit

traitLayer

Something that wraps one ASGI application in another: CORS, compression, a host check, or the caller's own. Every middleware here is a record that implements it, so a caller's middleware stacks with them on equal terms.

pub(open) trait Layer {
  fn wrap(Self, async (@spec.Scope, async () -> @spec.Event, async (@spec.Event) -> Unit) -> Unit) -> async (@spec.Scope, async () -> @spec.Event, async (@spec.Event) -> Unit) -> Unit
}

structEnviron

What a synchronous application is told about a request (← WSGI's environ, PEP 3333): the CGI variables as fields, the request headers, the body read in full, and the URL scheme. to_map gives the same under the CGI names, for code that reads them by key.

pub(all) struct Environ {
  request_method : String
  script_name : String
  path_info : String
  query_string : String
  content_type : String
  content_length : String
  server_name : String
  server_port : String
  server_protocol : String
  remote_addr : String
  remote_port : String
  headers : Array[(String, String)]
  url_scheme : String
  input : Bytes
} derive(Eq, @debug.Debug)

pub fn Environ::header(Self, String) -> String?

pub fn Environ::of(@spec.HttpScope, Bytes) -> Self

pub fn Environ::to_map(Self) -> Map[String, String]

typeStartResponse

How a synchronous application starts its response (← WSGI's start_response): the status line, such as "200 OK", and the headers. It gives back a function that writes part of the body at once, for code written against that older style; returning the body is the usual way.

pub type StartResponse = (String, Array[(String, String)]) -> (Bytes) -> Unit

typeWsgiApp

A synchronous application (← a WSGI application): the environment and start_response in, the body out, chunk by chunk. A chunk is sent as soon as the iterator yields it, so a long body streams.

pub type WsgiApp = (Environ, (String, Array[(String, String)]) -> (Bytes) -> Unit) -> Iter[Bytes] raise

suberrorRefused

What a test driver could not get from the application under test.

pub(all) suberror Refused {
  Timeout(limit~ : Int32)
  Finished
  Unexpected(@spec.Event)
  Closed(status~ : Int32, reason~ : String)
  Denied(@client.TestResponse)
  Startup(String)
  Shutdown(String)
} derive(Eq)

Timeout

Nothing arrived within `limit` milliseconds.

Finished

The application returned with nothing more to send.

Unexpected

The application sent an event the protocol does not allow at that point.

Closed

The application closed the WebSocket, before accepting it or after.

Denied

The application declined the WebSocket handshake with an HTTP response (`websocket.http.response`).

Startup

The application reported `lifespan.startup.failed` with this message.

Shutdown

The application reported `lifespan.shutdown.failed` with this message.

structClient

An in-process client for a real AsgiApp. Each request runs the application on a fresh scope, feeds it the body, sends http.disconnect once the response is complete, and waits for the application to return, so an error it raises fails the test. @client.TestClient is the synchronous counterpart for event-folding handlers.

state is the lifespan state: lifespan hands it to the application's startup, and every request and WebSocket scope gets a shallow copy, as the lifespan sub-specification asks.

pub(all) struct Client {
  app : async (@spec.Scope, async () -> @spec.Event, async (@spec.Event) -> Unit) -> Unit
  root_path : String
  base_headers : Array[(String, String)]
  client : (String, Int32)?
  server : (String, Int32?)?
  extensions : @spec.Extensions
  state : Map[String, Json]
  timeout : Int32
}

pub fn Client::new(async (@spec.Scope, async () -> @spec.Event, async (@spec.Event) -> Unit) -> Unit, root_path? : String, base_headers? : Array[(String, String)], client? : (String, Int32)?, server? : (String, Int32?)?, extensions? : @spec.Extensions, state? : Map[String, Json], timeout? : Int32) -> Self

structCommunicator

A running application under test: events go in with send, come out with receive, and wait waits for the application to return. An error the application raises comes out of the next send, receive or wait, after the events it sent before failing. Made by communicate, which owns the application's task.

pub struct Communicator {
  // private fields
}

structSession

An accepted WebSocket under test: the negotiated subprotocol and accept headers, plus methods that talk to the application.

pub struct Session {
  subprotocol : String?
  headers : Array[(String, String)]
  // private fields
}

structConformanceReport

The outcome of the ASGI 3.0 conformance harness: how many round-trip checks ran, how many passed, and the names of any that failures. A clean run has an empty failures. Reusable beyond the test suite — a server or framework built on the seam can call run_conformance to self-verify the wiring.

pub(all) struct ConformanceReport {
  total : Int32
  passed : Int32
  failures : Array[String]
} derive(Eq)

pub fn ConformanceReport::ok(Self) -> Bool

enumEventOrderError

Why an outbound event stream is malformed. ASGI pins the order an application may emit messages in — a body before the response starts, a second start, a websocket frame before the handshake is accepted, and so on are all protocol violations. validate_events walks a stream and names the first violation it finds; a well-formed stream returns None. A server can run this over its own emissions to catch a buggy app early, and the conformance harness drives a negative table through it.

pub(all) enum EventOrderError {
  BodyBeforeStart
  DuplicateResponseStart
  EarlyHintAfterStart
  BodyAfterComplete
  UnexpectedTrailers
  TrailersBeforeBody
  MissingResponseStart
  IncompleteBody
  MissingTrailers
  EventAfterComplete
  DebugAfterStart
  DuplicateDebug
  PushBeforeStart
  PathSendMixedWithBody
  IllegalResponseHeader
  FrameBeforeAccept
  DuplicateAccept
  EventAfterClose
  DenialBodyBeforeStart
  DenialAfterAccept
  AcceptAfterDenial
  IncompleteDenial
  MissingHandshakeReply
  DuplicateLifespanReply
  ShutdownBeforeStartup
  NonResponseEvent
} derive(Eq)

pub fn EventOrderError::describe(Self) -> String