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,
  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)
: 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,
  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)
: 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

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

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]

fun ref expect(
  qty: USize val)
: None 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