Skip to content

HTTPClientConnection

[Source]

HTTP protocol handler that manages request serialization, response parsing, and connection lifecycle for a single HTTP client connection.

Stored as a field inside an HTTPClientConnectionActor. Handles all HTTP-level concerns — serializing outgoing requests, parsing incoming responses, idle timeout scheduling, and backpressure — and delivers HTTP events to the actor via HTTPClientLifecycleEventReceiver callbacks.

The protocol class implements lori's ClientLifecycleEventReceiver to receive TCP-level events from the connection, and _ResponseParserNotify to receive parser callbacks. It forwards HTTP-level events to the owning actor.

Use none() as the field default so that this is ref in the actor constructor body, then replace with create() or ssl():

actor MyClient is HTTPClientConnectionActor
  var _http: HTTPClientConnection = HTTPClientConnection.none()

  new create(auth: lori.TCPConnectAuth, host: String, port: String,
    config: ClientConnectionConfig)
  =>
    _http = HTTPClientConnection(auth, host, port, this, config)

class ref HTTPClientConnection is
  ClientLifecycleEventReceiver ref,
  _ResponseParserNotify ref

Implements

Constructors

none

[Source]

Create a placeholder protocol instance.

Used as the default value for the _http field in HTTPClientConnectionActor implementations, allowing this to be ref in the actor constructor body. The placeholder is immediately replaced by create() or ssl() — its methods must never be called.

new ref none()
: HTTPClientConnection ref^

Returns

create

[Source]

Create the protocol handler for a plain HTTP connection.

Called inside the HTTPClientConnectionActor constructor. The client_actor parameter must be the actor's this — it provides the HTTPClientLifecycleEventReceiver ref for synchronous HTTP callbacks.

new ref create(
  auth: TCPConnectAuth val,
  host: String val,
  port: String val,
  client_actor: HTTPClientConnectionActor ref,
  config: ClientConnectionConfig val)
: HTTPClientConnection ref^

Parameters

Returns

ssl

[Source]

Create the protocol handler for an HTTPS connection.

Like create, but wraps the TCP connection in SSL using the provided SSLContext. Called inside the HTTPClientConnectionActor constructor for HTTPS connections.

new ref ssl(
  auth: TCPConnectAuth val,
  ssl_ctx: SSLContext val,
  host: String val,
  port: String val,
  client_actor: HTTPClientConnectionActor ref,
  config: ClientConnectionConfig val)
: HTTPClientConnection ref^

Parameters

Returns

Public Functions

send_request

[Source]

Serialize and send an HTTP request.

Returns SendRequestOK on success, ConnectionClosed if the connection is not open, or ResponsePending if a response to a previous request is still in progress.

Auto-sets Host and Content-Length headers during serialization if they are not already present in the request.

fun ref send_request(
  request: HTTPRequest val)
: SendRequestResult

Parameters

Returns

close

[Source]

Close the connection.

Safe to call at any time; idempotent due to the _Active state guard in _close_connection().

fun ref close()
: None val

Returns

yield_read

[Source]

Exit the read loop after the current callback, giving other actors a chance to run. Reading resumes automatically on the next scheduler turn.

Intended for use inside on_body_chunk() to prevent a single large response from starving other actors. Granularity is per-TCP-read, not per-HTTP-chunk — one TCP read may contain multiple chunks, and they will all be parsed before yielding. This is a one-shot flag; there is no corresponding "unmute" needed.

No state guard is needed — if the connection is closed, the read loop is not running and the flag is harmless.

fun ref yield_read()
: None val

Returns

set_timer

[Source]

Create a one-shot timer that fires on_timer() after the configured duration. Returns a TimerToken on success, or a SetTimerError on failure.

Unlike idle timeout, this timer has no I/O-reset behavior — it fires unconditionally after the duration elapses, regardless of send/receive activity. There is no automatic re-arming; call set_timer() again from on_timer() for repetition.

Only one timer can be active at a time. Setting a timer while one is already active returns SetTimerAlreadyActive — call cancel_timer() first. Requires the connection to be open; returns SetTimerNotOpen if not.

Use lori.MakeTimerDuration(milliseconds) to create the duration value. MakeTimerDuration returns (TimerDuration | ValidationFailure), so match on the result before passing it here.

fun ref set_timer(
  duration: TimerDuration)
: (TimerToken val | SetTimerError)

Parameters

Returns

cancel_timer

[Source]

Cancel an active timer. No-op if the token doesn't match the active timer (already fired, already cancelled, wrong token). Safe to call with stale tokens.

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

Parameters

Returns

response_received

[Source]

fun ref response_received(
  status: U16 val,
  reason: String val,
  version: Version,
  headers: Headers val)
: None val

Parameters

Returns

body_chunk

[Source]

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

Parameters

Returns

response_complete

[Source]

fun ref response_complete()
: None val

Returns

parse_error

[Source]

fun ref parse_error(
  err: ParseError)
: None val

Parameters

Returns