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)
: TCPConnection ref^

new ref server(
  auth: TCPServerAuth val,
  fd': U32 val,
  enclosing: TCPConnectionActor ref,
  ler: ServerLifecycleEventReceiver ref)
: TCPConnection ref^

Parameters¶

auth: TCPServerAuth val
fd': U32 val
enclosing: TCPConnectionActor ref
ler: ServerLifecycleEventReceiver ref

Returns¶

TCPConnection ref^

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().

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)
: TCPConnection ref^

Parameters¶

auth: TCPConnectAuth val
ssl_ctx: SSLContext val
host: String val
port: String val
from: String val
enclosing: TCPConnectionActor ref
ler: ClientLifecycleEventReceiver ref

Returns¶

TCPConnection ref^

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() 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¶

auth: TCPServerAuth val
ssl_ctx: SSLContext val
fd': U32 val
enclosing: TCPConnectionActor ref
ler: ServerLifecycleEventReceiver ref

Returns¶

TCPConnection ref^

none¶

[Source]

new ref none()
: TCPConnection ref^

Returns¶

TCPConnection ref^

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¶

None val

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¶

NetAddress val

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¶

NetAddress val

mute¶

[Source]

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

fun ref mute()
: None val

Returns¶

None val

unmute¶

[Source]

Start reading off this TCPConnection again after having been muted.

fun ref unmute()
: None val

Returns¶

None val

expect¶

[Source]

fun ref expect(
  qty: USize val)
: None val ?

Parameters¶

qty: USize val

Returns¶

None val ?

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¶

None val

hard_close¶

[Source]

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

fun ref hard_close()
: None val

Returns¶

None val

is_open¶

[Source]

fun box is_open()
: Bool val

Returns¶

Bool val

is_closed¶

[Source]

fun box is_closed()
: Bool val

Returns¶

Bool val

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¶

Bool val

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¶

ssl_ctx: SSLContext val
host: String val = ""

Returns¶

(None val | StartTLSNotConnected val | StartTLSAlreadyTLS val | StartTLSNotReady val | StartTLSSessionFailed val)

send¶

[Source]

Send data on this connection. 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))
: (SendToken val | SendErrorNotConnected val | SendErrorNotWriteable val)

Parameters¶

data: (String val | Array[U8 val] val)

Returns¶

(SendToken val | SendErrorNotConnected val | SendErrorNotWriteable val)