kuilt-core/us.tractat.kuilt.core.fabric/Connection

Connection

A point-to-point, message-oriented duplex link between exactly two peers.

The minimal SPI a message transport (WebSocket, gRPC bidi stream, Multipeer, Nearby) implements to become a kuilt fabric. Stream transports (TCP) do not implement this directly — they provide a kotlinx-io Source/Sink and use :kuilt-stream's framed() to obtain a Connection.

Each frame is a whole message; the link preserves frame boundaries and FIFO order.

Neither send nor close may report a failure as a cancellation — the obligation us.tractat.kuilt.core.Seam.close states in full, for the same reason and with the same withTimeout trap. MeshSeam closes a whole roster of connections under a best-effort guard, so one callee-minted CancellationException here cancels that loop and leaks every remaining link (#1826).

Properties

incoming

abstract val incoming: Flow<ByteArray>

Whole messages received from the peer, in order. Single-collection.

maxFrameBytes

open val maxFrameBytes: Int?

The largest frame send accepts, or null when this link cannot name a ceiling.

Functions

abstract suspend fun close()

Close the link. Idempotent. Completes incoming.

send

abstract suspend fun send(frame: ByteArray)

Send one whole message. Suspends until the transport accepts it (backpressure).

withPrincipal

fun Connection.withPrincipal(principal: Principal?): Connection

Returns a Connection that reports principal via PrincipalAttested. When principal is null the receiver is returned unchanged — an unauthenticated connection carries no attestation and is never wrapped.