Skip to content

TCPConnection

[Source] 

class ref TCPConnection

Constructors

client

[Source]

new ref client(
  auth: TCPConnectAuth val,
  host: String val,
  port: String val,
  from: String val,
  enclosing: TCPConnectionActor ref,
  ler: ClientLifecycleEventReceiver ref,
  read_buffer_size: Constrained[USize val, ReadBufferSizeValidator val] val = call,
  ip_version: (IP4 val | IP6 val | DualStack val) = reference)
: TCPConnection ref^

Parameters

Returns

server

[Source]

new ref server(
  auth: TCPServerAuth val,
  fd': U32 val,
  enclosing: TCPConnectionActor ref,
  ler: ServerLifecycleEventReceiver ref,
  read_buffer_size: Constrained[USize val, ReadBufferSizeValidator val] val = call)
: TCPConnection ref^

Parameters

Returns

ssl_client

[Source]

Create a client-side SSL connection. The SSL session is created from the provided SSLContext. If session creation fails, the connection reports failure asynchronously via _on_connection_failure(ConnectionFailedSSL).

new ref ssl_client(
  auth: TCPConnectAuth val,
  ssl_ctx: SSLContext val,
  host: String val,
  port: String val,
  from: String val,
  enclosing: TCPConnectionActor ref,
  ler: ClientLifecycleEventReceiver ref,
  read_buffer_size: Constrained[USize val, ReadBufferSizeValidator val] val = call,
  ip_version: (IP4 val | IP6 val | DualStack val) = reference)
: TCPConnection ref^

Parameters

Returns

ssl_server

[Source]

Create a server-side SSL connection. The SSL session is created from the provided SSLContext. If session creation fails, the connection reports failure asynchronously via _on_start_failure(StartFailedSSL) and closes the fd.

new ref ssl_server(
  auth: TCPServerAuth val,
  ssl_ctx: SSLContext val,
  fd': U32 val,
  enclosing: TCPConnectionActor ref,
  ler: ServerLifecycleEventReceiver ref,
  read_buffer_size: Constrained[USize val, ReadBufferSizeValidator val] val = call)
: TCPConnection ref^

Parameters

Returns

none

[Source]

new ref none()
: TCPConnection ref^

Returns

Public Functions

keepalive

[Source]

Sets the TCP keepalive timeout to approximately secs seconds. Exact timing is OS dependent. If secs is zero, TCP keepalive is disabled. TCP keepalive is disabled by default. This can only be set on a connected socket.

fun box keepalive(
  secs: U32 val)
: None val

Parameters

  • secs: U32 val

Returns

set_nodelay

[Source]

Turn Nagle on/off. Defaults to on (Nagle enabled, nodelay off). When enabled (state = true), small writes are sent immediately without waiting to coalesce — useful for latency-sensitive protocols. When disabled (state = false), the OS may buffer small writes.

Returns 0 on success, or a non-zero errno on failure. Only meaningful on a connected socket — returns non-zero if the connection is not open.

fun box set_nodelay(
  state: Bool val)
: U32 val

Parameters

Returns

get_so_rcvbuf

[Source]

Get the OS receive buffer size for this socket.

Returns a 2-tuple: (errno, value). On success, errno is 0 and value is the buffer size in bytes. On failure, errno is non-zero and value should be ignored. Only meaningful on a connected socket — returns (1, 0) if the connection is not open.

fun box get_so_rcvbuf()
: (U32 val , U32 val)

Returns

set_so_rcvbuf

[Source]

Set the OS receive buffer size for this socket. The OS may round the requested size up to a minimum or clamp it to a maximum.

Returns 0 on success, or a non-zero errno on failure. Only meaningful on a connected socket — returns non-zero if the connection is not open.

fun box set_so_rcvbuf(
  bufsize: U32 val)
: U32 val

Parameters

  • bufsize: U32 val

Returns

get_so_sndbuf

[Source]

Get the OS send buffer size for this socket.

Returns a 2-tuple: (errno, value). On success, errno is 0 and value is the buffer size in bytes. On failure, errno is non-zero and value should be ignored. Only meaningful on a connected socket — returns (1, 0) if the connection is not open.

fun box get_so_sndbuf()
: (U32 val , U32 val)

Returns

set_so_sndbuf

[Source]

Set the OS send buffer size for this socket. The OS may round the requested size up to a minimum or clamp it to a maximum.

Returns 0 on success, or a non-zero errno on failure. Only meaningful on a connected socket — returns non-zero if the connection is not open.

fun box set_so_sndbuf(
  bufsize: U32 val)
: U32 val

Parameters

  • bufsize: U32 val

Returns

getsockopt

[Source]

General interface to getsockopt(2) for accessing any socket option.

The option_max_size argument is the maximum number of bytes the caller expects the kernel to return. This method allocates a buffer of that size before calling getsockopt(2).

Returns a 2-tuple: on success, (0, data) where data is the bytes returned by the kernel, sized to the actual length the kernel wrote. On failure, (errno, undefined) — the second element must be ignored. Only meaningful on a connected socket — returns (1, empty) if the connection is not open.

For commonly-tuned options, prefer the dedicated convenience methods (set_nodelay, get_so_rcvbuf, etc.). Do not change the socket's non-blocking mode — lori's event-driven I/O requires non-blocking sockets.

fun box getsockopt(
  level: I32 val,
  option_name: I32 val,
  option_max_size: USize val = 4)
: (U32 val , Array[U8 val] iso^)

Parameters

  • level: I32 val
  • option_name: I32 val
  • option_max_size: USize val = 4

Returns

getsockopt_u32

[Source]

Wrapper for getsockopt(2) where the kernel returns a C uint32_t.

Returns a 2-tuple: on success, (0, value). On failure, (errno, undefined) — the second element must be ignored. Only meaningful on a connected socket — returns (1, 0) if the connection is not open.

For commonly-tuned options, prefer the dedicated convenience methods (get_so_rcvbuf, get_so_sndbuf, etc.). Do not change the socket's non-blocking mode — lori's event-driven I/O requires non-blocking sockets.

fun box getsockopt_u32(
  level: I32 val,
  option_name: I32 val)
: (U32 val , U32 val)

Parameters

  • level: I32 val
  • option_name: I32 val

Returns

setsockopt

[Source]

General interface to setsockopt(2) for setting any socket option.

The caller is responsible for the correct size, byte contents, and byte order of the option array for the requested level and option_name.

Returns 0 on success, or the value of errno on failure. Only meaningful on a connected socket — returns non-zero if the connection is not open.

For commonly-tuned options, prefer the dedicated convenience methods (set_nodelay, set_so_rcvbuf, etc.). Do not change the socket's non-blocking mode — lori's event-driven I/O requires non-blocking sockets.

fun box setsockopt(
  level: I32 val,
  option_name: I32 val,
  option: Array[U8 val] ref)
: U32 val

Parameters

Returns

setsockopt_u32

[Source]

Wrapper for setsockopt(2) where the kernel expects a C uint32_t.

Returns 0 on success, or the value of errno on failure. Only meaningful on a connected socket — returns non-zero if the connection is not open.

For commonly-tuned options, prefer the dedicated convenience methods (set_nodelay, set_so_rcvbuf, etc.). Do not change the socket's non-blocking mode — lori's event-driven I/O requires non-blocking sockets.

fun box setsockopt_u32(
  level: I32 val,
  option_name: I32 val,
  option: U32 val)
: U32 val

Parameters

  • level: I32 val
  • option_name: I32 val
  • option: U32 val

Returns

idle_timeout

[Source]

Set or disable the idle timeout. Idle timeout is disabled by default.

When duration is an IdleTimeout, the timer fires when no successful send or receive occurs for that duration, delivering _on_idle_timeout() to the lifecycle event receiver. When duration is None, the idle timeout is disabled.

The timer automatically re-arms after each firing until disabled or the connection closes.

Can be called before the connection is established — the value is stored and the timer starts when the connection is ready.

This is independent of TCP keepalive (keepalive()). TCP keepalive is a transport-level probe that detects dead peers. Idle timeout is application-level inactivity detection — it fires whether or not the peer is alive.

fun ref idle_timeout(
  duration: (Constrained[U64 val, IdleTimeoutValidator val] val | None val))
: None val

Parameters

Returns

set_read_buffer_minimum

[Source]

Set the shrink-back floor for the read buffer to exactly new_min bytes. When the read buffer is empty and larger than the minimum, it shrinks back to this size automatically. If the current buffer allocation is smaller than new_min, the buffer is grown to match.

Returns ReadBufferResizeBelowExpect if new_min is less than the current expect value.

fun ref set_read_buffer_minimum(
  new_min: Constrained[USize val, ReadBufferSizeValidator val] val)
: (ReadBufferResized val | ReadBufferResizeBelowExpect val)

Parameters

Returns

resize_read_buffer

[Source]

Force the read buffer to exactly size' bytes, reallocating if different. If size' is below the current minimum, the minimum is lowered to match.

Returns ReadBufferResizeBelowExpect if size' is less than the current expect value, or ReadBufferResizeBelowUsed if size' is less than the amount of unprocessed data currently in the buffer.

fun ref resize_read_buffer(
  size': Constrained[USize val, ReadBufferSizeValidator val] val)
: (ReadBufferResized val | ReadBufferResizeBelowExpect val | ReadBufferResizeBelowUsed val)

Parameters

Returns

local_address

[Source]

Return the local IP address. If this TCPConnection is closed then the address returned is invalid.

fun box local_address()
: NetAddress val

Returns

remote_address

[Source]

Return the remote IP address. If this TCPConnection is closed then the address returned is invalid.

fun box remote_address()
: NetAddress val

Returns

mute

[Source]

Temporarily suspend reading off this TCPConnection until such time as unmute is called.

fun ref mute()
: None val

Returns

unmute

[Source]

Start reading off this TCPConnection again after having been muted.

fun ref unmute()
: None val

Returns

yield_read

[Source]

Request the read loop to exit after the current _on_received callback returns, giving other actors a chance to run. Reading resumes automatically in the next scheduler turn — no explicit unmute() is needed.

Call this from within _on_received() to implement application-level yield policies (e.g. yield after N messages, after N bytes, or after a time threshold). Unlike mute()/unmute(), which persistently stop reading until reversed, yield_read() is a one-shot pause: the read loop resumes on its own.

For SSL connections, yield_read() operates at TCP-read granularity. All SSL-decrypted messages from a single TCP read are delivered before the yield takes effect, because the inner dispatch loop runs exactly once per TCP read when SSL is active.

fun ref yield_read()
: None val

Returns

expect

[Source]

Set the number of bytes to read before delivering data via _on_received. When qty is None, all available data is delivered.

Returns ExpectAboveBufferMinimum if qty exceeds the current read buffer minimum. Raise the buffer minimum first, then set expect.

fun ref expect(
  qty: (Constrained[USize val, ExpectValidator val] val | None val))
: (ExpectSet val | ExpectAboveBufferMinimum val)

Parameters

Returns

close

[Source]

Attempt to perform a graceful shutdown. Don't accept new writes.

During the connecting phase (Happy Eyeballs in progress), marks the connection as closed so straggler events clean up instead of establishing a connection. Once all in-flight connections have drained, _on_connection_failure fires.

If the connection is established and not muted, we won't finish closing until we get a zero length read. If the connection is muted, perform a hard close and shut down immediately.

fun ref close()
: None val

Returns

hard_close

[Source]

When an error happens, do a non-graceful close.

fun ref hard_close()
: None val

Returns

is_open

[Source]

fun box is_open()
: Bool val

Returns

is_closed

[Source]

fun box is_closed()
: Bool val

Returns

is_writeable

[Source]

Returns whether the connection can currently accept a send() call. Checks that the connection is open, the socket is writeable, and any SSL layer has completed its handshake.

fun box is_writeable()
: Bool val

Returns

start_tls

[Source]

Initiate a TLS handshake on an established plaintext connection. Returns None when the handshake has been started, or a StartTLSError if the upgrade cannot proceed (the connection is unchanged in that case).

Preconditions: the connection must be open, not already TLS, not muted, have no unprocessed data in the read buffer, and have no pending writes. The read buffer check prevents a man-in-the-middle from injecting pre-TLS data that the application would process as post-TLS (CVE-2021-23222).

On success, _on_tls_ready() fires when the handshake completes. During the handshake, send() returns SendErrorNotConnected. If the handshake fails, _on_tls_failure fires followed by _on_closed().

The host parameter is used for SNI (Server Name Indication) on client connections. Pass an empty string for server connections or when SNI is not needed.

fun ref start_tls(
  ssl_ctx: SSLContext val,
  host: String val = "")
: (None val | StartTLSNotConnected val | StartTLSAlreadyTLS val | 
    StartTLSNotReady val | StartTLSSessionFailed val)

Parameters

Returns

send

[Source]

Send data on this connection. Accepts a single buffer (ByteSeq) or multiple buffers (ByteSeqIter). When multiple buffers are provided, they are sent in a single writev syscall — avoiding both per-buffer syscall overhead and the cost of copying into a contiguous buffer.

Returns a SendToken on success, or a SendError explaining the failure. When successful, _on_sent(token) will fire in a subsequent behavior turn once the data has been fully handed to the OS.

fun ref send(
  data: (String val | Array[U8 val] val | ByteSeqIter val))
: (SendToken val | SendErrorNotConnected val | SendErrorNotWriteable val)

Parameters

Returns

read_again

[Source]

fun ref read_again()
: None val

Returns