Connection

interface Connection(source)

A single named, logical connection to one remote client of a MultiConnectionUDPServer.

UDPConnection is the production implementation: a socket-free handle over the server's single shared UDP socket. The interface exists so the server's registration and handshake logic can be exercised against a socket-free fake.

UDPConnection is still socket-free and owns no thread of its own; an opt-in scheduled keepalive (startKeepAlive) borrows the server's shared mcups-keepalive thread rather than starting one per connection, and an opt-in link-quality probe (startProbe) likewise borrows the server's shared mcups-probe thread and updates a per-connection estimator.

Inheritors

Properties

Link copied to clipboard
abstract val name: String

a human-readable identifier for this connection, typically supplied by the client during the handshake

Link copied to clipboard
abstract val peer: InetSocketAddress

the client's post-NAT endpoint, learned from its Iam datagram; every datagram to this client is addressed here so it rides the NAT mapping the handshake opened

Functions

Link copied to clipboard
abstract fun actuate(onMessage: (message: String) -> Unit): Result<Unit>

Registers onMessage as the handler for datagrams from this client. No socket is bound - the server already owns the one shared socket; this only routes inbound datagrams whose source matches peer to onMessage. Calling this on a connection that has been terminated is a silent no-op (see terminate). The handler receives the trimmed UTF-8 text of each datagram; for a binary protocol use actuateBytes instead.

Link copied to clipboard
open fun actuateBytes(onMessage: (bytes: ByteArray) -> Unit): Result<Unit>

Registers onMessage as the raw-bytes handler for datagrams from this client: it is handed an exact-length copy of each inbound datagram body - no UTF-8 decode, no .trim().

Link copied to clipboard

The delivery-mode-scoped handle for this connection. Each DeliveryMode has its own sequence space and its own inbound handler - binding a handler on one mode's UdpChannel never disturbs the other's.

Link copied to clipboard
abstract fun keepAlive(): Result<Unit>

Sends one minimal keepalive datagram to peer to keep its NAT mapping warm. A one-shot: the caller schedules it (recommended ~20 s idle cadence). Owns no timer or thread. For a library-managed cadence use startKeepAlive.

Link copied to clipboard

The latest link-quality snapshot for this connection, or null if no probe is running or none has resolved yet.

Link copied to clipboard
open fun push(bytes: ByteArray): Result<Unit>

Sends bytes as one raw datagram to peer over the server's shared socket: the payload is placed on the wire verbatim - no encoding, no trim.

abstract fun push(message: String): Result<Unit>

Sends message as the body of one datagram to peer over the server's shared socket. This is the abstract send primitive; the default push(ByteArray) delegates to it via a UTF-8 decode unless an implementor overrides that overload to send raw bytes.

Link copied to clipboard

Starts the scheduled keepalive at the recommended interval (TransportWireFormat.DEFAULT_KEEPALIVE_INTERVAL_MILLIS, 20 s).

open fun startKeepAlive(intervalMillis: Long): Result<Unit>

Starts an opt-in, idle-aware background keepalive for this connection: every ~intervalMillis of output silence toward peer the server sends one 0x80 keepalive datagram, until stopKeepAlive, terminate, or server stop().

Link copied to clipboard
open fun startProbe(): Result<Unit>

Starts the probe at the default interval (TransportWireFormat.DEFAULT_PROBE_INTERVAL_MILLIS, 1 s).

open fun startProbe(intervalMillis: Long): Result<Unit>

Starts an opt-in link-quality probe toward peer: every intervalMillis the server sends one 0x81 probe datagram, and each 0x82 reply updates a smoothed RTT / jitter / loss estimate readable via linkQuality. Runs until stopProbe, terminate, or server stop(). Server -> client 0x81 reaches the client whenever the session is live (the client is actively holding its own mapping open); the same cone-NAT caveat as keepAlive applies if the client has gone silent.

Link copied to clipboard

Stops the background keepalive started by startKeepAlive. Idempotent; a no-op if none is running or the implementation does not support one. terminate and server stop() also do this.

Link copied to clipboard
open fun stopProbe(): Result<Unit>

Stops the probe started by startProbe. Idempotent; terminate and server stop() also do this. The last linkQuality snapshot remains readable. A probe still unanswered when the probe stopped is counted as lost once it passes the loss horizon, so packetLossRatio can still settle for up to three probe intervals after this call.

Link copied to clipboard
abstract fun terminate(): Result<Unit>

Fully deregisters this connection: its message handler is cleared and its registration is removed from the server entirely, so it is no longer addressed by MultiConnectionUDPServer.pushToAll and any subsequent datagram from peer is dropped as unregistered. This is final - calling actuate again afterward is a silent no-op, since there is no longer a registration to bind against; the client must complete a fresh Iam handshake to be registered again.