UDPConnection

The production Connection: a socket-free handle to one multiplexed client of a MultiConnectionUDPServer.

It owns no socket and no thread of its own. push and keepAlive address peer over the server's single shared socket; actuate registers this connection's message handler in the server's registry, while terminate now fully deregisters it - not just unregisters the handler. Every fallible operation returns a Result. A scheduled keepalive (startKeepAlive) runs on the server's shared mcups-keepalive thread - still not one owned here - and is cancelled by terminate. An opt-in link-quality probe (startProbe) likewise runs on the server's shared mcups-probe thread and is cancelled by terminate.

Instances are minted only by MultiConnectionUDPServer's internal factory - the constructor is internal. Standalone bidirectional-socket users take UDPSendReceiveServer directly.

Properties

Link copied to clipboard
open override val name: String

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

Link copied to clipboard
open override val peer: InetSocketAddress

the client's post-NAT endpoint, learned from its Iam datagram; every datagram to this client is addressed here

Functions

Link copied to clipboard
open override 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 override fun actuateBytes(onMessage: (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
open override fun channel(mode: DeliveryMode): UdpChannel

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
open override fun keepAlive(): Result<Unit>

Sends a bare 0x80 keepalive datagram to peer.

Link copied to clipboard
open override fun linkQuality(): LinkQuality?

The latest link-quality snapshot for this connection, delegated to ClientChannel.

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

Frames bytes as an 0x90 unreliable datagram ([0x90][channel][payload]) and sends it to peer. Any payload bytes are delivered to the peer intact - there is no reserved first byte.

open override 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 override fun startKeepAlive(intervalMillis: Long): Result<Unit>

Unlike the Connection default, this production implementation does support a scheduled keepalive: it delegates to the server's shared mcups-keepalive executor via ClientChannel, which sends an idle-aware 0x80 keepalive to peer on the given cadence. A non-positive intervalMillis surfaces as the ClientChannel's IllegalArgumentException failure. The schedule is cancelled by stopKeepAlive and by terminate.

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

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

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

Unlike the Connection default, this production implementation does support a link-quality probe: it delegates to the server's shared mcups-probe executor via ClientChannel, which sends a periodic 0x81 probe to peer and folds each 0x82 reply into a per-connection estimator. A non-positive intervalMillis or an unregistered peer surfaces as the ClientChannel's failure. The schedule is cancelled by stopProbe and by terminate.

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

Unlike the Connection default no-op, this production implementation cancels the keepalive armed by startKeepAlive on the server's shared mcups-keepalive executor via ClientChannel. Idempotent; terminate also does this.

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

Unlike the Connection default no-op, this production implementation cancels the probe armed by startProbe on the server's shared mcups-probe executor via ClientChannel. Idempotent; terminate also does this.

Link copied to clipboard
open override 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.