Context

[Source]

Request context passed to middleware and handlers.

Provides access to the HTTP request, route parameters, accumulated request body, and a key-value data map for inter-middleware communication. Call respond() or respond_with_headers() to send a complete HTTP response, or start_streaming() to begin a chunked streaming response.

For HEAD requests, the framework automatically suppresses response bodies while preserving headers (including Content-Length). Handlers do not need special HEAD logic — respond() and respond_with_headers() send headers only, and start_streaming() returns BodyNotNeeded instead of starting a stream.

Mutation methods (respond, respond_with_headers, start_streaming, set) require ref access. Read-only methods (param, body, get, is_handled, is_streaming) require only box access. This split supports the typed accessor convention: middleware authors provide accessor primitives that take Context box, letting them read context data without requiring write access.

class ref Context

Constructors

create

[Source]

new ref create(
  request': Request val,
  responder': Responder ref,
  params': HashMap[String val, String val, HashEq[String val] val] val,
  body': Array[U8 val] val,
  conn': _Connection tag)
: Context ref^

Parameters

• request': Request val
• responder': Responder ref
• params': HashMap[String val, String val, HashEq[String val] val] val
• body': Array[U8 val] val
• conn': _Connection tag

Returns

• Context ref^

---

Public fields

let request: Request val

[Source]

---

Public Functions

respond

[Source]

Send a complete response with the given status and body.

Sets Content-Length automatically. If a response has already been sent, this call is silently ignored (the first response wins). For HEAD requests, the body is suppressed but Content-Length is preserved.

fun ref respond(
  status: Status val,
  body': (String val | Array[U8 val] val))
: None val

Parameters

• status: Status val
• body': (String val | Array[U8 val] val)

Returns

• None val

---

respond_with_headers

[Source]

Send a complete response with explicit headers and body.

The caller is responsible for including Content-Length or any other required headers in headers. If a response has already been sent, this call is silently ignored. For HEAD requests, the body is suppressed but all headers are preserved.

fun ref respond_with_headers(
  status: Status val,
  headers: Headers val,
  body': (String val | Array[U8 val] val))
: None val

Parameters

• status: Status val
• headers: Headers val
• body': (String val | Array[U8 val] val)

Returns

• None val

---

is_handled

[Source]

Returns true if a response has already been sent.

fun box is_handled()
: Bool val

Returns

• Bool val

---

start_streaming

[Source]

Begin a streaming response using chunked transfer encoding.

Returns StreamSender tag on success, ChunkedNotSupported if the client does not support chunked encoding (e.g., HTTP/1.0), or BodyNotNeeded for HEAD requests (the framework has already sent a headers-only response). Errors if a response has already been sent (programmer error).

When ChunkedNotSupported is returned, is_handled() remains false and the handler can fall back to ctx.respond() for a non-streaming response.

When BodyNotNeeded is returned, is_handled() is true — the handler should not start a producer. Existing handlers that don't match on BodyNotNeeded work correctly: in a statement-position match, unmatched cases silently fall through, so the handler does nothing (which is correct for HEAD).

On success, sets is_handled() to true — no further respond() calls will take effect. Pass the returned sender to a producer actor. The producer calls send_chunk() to send data and finish() to terminate the stream.

If the handler errors after a successful start_streaming(), the framework automatically sends the terminal chunk to prevent a hung connection.

fun ref start_streaming(
  status: Status val,
  headers: (Headers val | None val) = reference)
: (StreamSender tag | ChunkedNotSupported val | BodyNotNeeded val) ?

Parameters

• status: Status val
• headers: (Headers val | None val) = reference

Returns

• (StreamSender tag | ChunkedNotSupported val | BodyNotNeeded val) ?

---

is_streaming

[Source]

Returns true if a streaming response has been started.

fun box is_streaming()
: Bool val

Returns

• Bool val

---

param

[Source]

Get a route parameter by name.

Errors if the parameter does not exist. Parameter names come from route definitions — :id in /users/:id is accessed as param("id").

fun box param(
  key: String val)
: String val ?

Parameters

• key: String val

Returns

• String val ?

---

body

[Source]

Return the accumulated request body bytes.

fun box body()
: Array[U8 val] val

Returns

• Array[U8 val] val

---

set

[Source]

Store a value in the context data map.

Middleware uses this to communicate with downstream middleware and handlers. Keys should be namespaced to the middleware (e.g., "basic_auth") to avoid collisions.

fun ref set(
  key: String val,
  value: Any val)
: None val

Parameters

• key: String val
• value: Any val

Returns

• None val

---

get

[Source]

Retrieve a value from the context data map.

Errors if the key does not exist. Middleware authors should provide typed accessor primitives that wrap this method with match to recover domain types.

fun box get(
  key: String val)
: Any val ?

Parameters

• key: String val

Returns

• Any val ?

---