Skip to content

HTTPServerLifecycleEventReceiver

[Source]

HTTP request lifecycle callbacks delivered to the server actor.

All callbacks have default no-op implementations. Override only the callbacks your actor needs. For most servers, on_request_complete() is the only required callback — it delivers the Responder for sending the response after the full request has been received. Override on_request() when you need to respond before the body arrives (e.g., rejecting with 413) — it delivers the same Responder earlier.

Callbacks are invoked synchronously inside the actor that owns the HTTPServer. The protocol class handles HTTP parsing and connection management internally, delivering only HTTP-level events through this interface.

trait ref HTTPServerLifecycleEventReceiver

Public Functions

on_request

[Source]

Called when the request line and all headers have been parsed.

The Request bundles method, URI, version, and headers into a single immutable value. The URI is a pre-parsed RFC 3986 structure — invalid URIs are rejected with 400 Bad Request before reaching this callback.

The responder is specific to this request. Use respond() with a ResponseBuilder-constructed response, or use start_chunked_response(), send_chunk(), and finish_response() for streaming responses. The responder may be used immediately or stored for later use (e.g., after accumulating body chunks).

fun ref on_request(
  request': Request val,
  responder: Responder ref)
: None val

Parameters

Returns

on_body_chunk

[Source]

Called for each chunk of request body data as it arrives.

Body data is delivered incrementally. Accumulate chunks manually if you need the complete body before responding.

fun ref on_body_chunk(
  data: Array[U8 val] val)
: None val

Parameters

Returns

on_request_complete

[Source]

Called when the entire request (including any body) has been received.

The request' is the same instance delivered in on_request(). The responder is also the same instance. For most servers, this is the only callback needed — it delivers both the complete request metadata and the Responder for sending the response.

fun ref on_request_complete(
  request': Request val,
  responder: Responder ref)
: None val

Parameters

Returns

on_closed

[Source]

Called when the connection closes.

Fires on client disconnect, server-initiated close, or any other reason. Not called if the connection fails before starting — see on_start_failure() for that case.

fun ref on_closed()
: None val

Returns

on_start_failure

[Source]

Called when a connection fails before starting.

Fires when the TCP connection was accepted but never reached the HTTP-ready state — for example, when an SSL handshake fails. The reason identifies the cause (currently lori.StartFailedSSL).

Neither on_request() nor on_closed() will fire for this connection. This is the only notification the actor receives.

Override this to log or take action on connection failures. The default is a no-op.

fun ref on_start_failure(
  reason: StartFailedSSL val)
: None val

Parameters

Returns

on_throttled

[Source]

Called when backpressure is applied on the connection.

The TCP send buffer is full — stop generating response data until on_unthrottled() is called.

fun ref on_throttled()
: None val

Returns

on_chunk_sent

[Source]

Called when a chunk from send_chunk() has been handed to the OS.

The token matches the ChunkSendToken returned by the send_chunk() call that produced the data. Fires asynchronously in a subsequent behavior turn — never during the send_chunk() call itself. Only user chunks trigger this callback; internal sends (headers, terminal chunk, error responses) do not.

Use this for flow-controlled streaming: send a chunk, wait for the callback, then send the next chunk. Multiple chunks can be in flight simultaneously (windowed); use the tokens to track which have been delivered.

fun ref on_chunk_sent(
  token: ChunkSendToken val)
: None val

Parameters

Returns

on_unthrottled

[Source]

Called when backpressure is released on the connection.

The TCP send buffer has drained — response generation may resume.

fun ref on_unthrottled()
: None val

Returns

on_timer

[Source]

Called when a one-shot timer created by HTTPServer.set_timer() fires.

The token matches the one returned by set_timer(). Fires once per set_timer() call. The timer is consumed before the callback, so it is safe to call set_timer() from within on_timer() to re-arm. No automatic re-arming occurs.

Unlike idle timeout, this timer has no I/O-reset behavior — it fires unconditionally after the configured duration, regardless of send/receive activity.

fun ref on_timer(
  token: TimerToken val)
: None val

Parameters

Returns