kuilt-gossip/us.tractat.kuilt.gossip/hostedOverlay

hostedOverlay

suspend fun CoroutineScope.hostedOverlay(selfId: PeerId, source: ConnectionSource, dispatcher: CoroutineContext, random: Random = Random.Default, clock: () -> Instant = { Clock.System.now() }, admission: LinkAdmission = LinkAdmission.AcceptAll, handshakeTimeout: Duration = 10.seconds): Seam

Compose a started hub Seam from a ConnectionSource: an initially-empty hubMesh wrapped in a GossipSeam with FullFanout (the hub floods every broadcast to all spokes), plus an accept-pump that addLinks each accepted us.tractat.kuilt.core.fabric.Connection so clients join the running hub as they connect. The pump coroutine lives on the receiver scope and is torn down with it.

A failed admit (torn or garbled spoke — client drops before or during the MeshHello preamble, or a link the admission policy rejects) is best-effort: the bad connection is dropped and the pump continues accepting the next one. This mirrors us.tractat.kuilt.core.fabric.Mesh's own per-link tolerance in its read loop. Cancellation still propagates so the pump exits cleanly when the receiver scope is torn down.

The returned hub seam is a us.tractat.kuilt.core.PrincipalRoster: principals attached to accepted connections (a KtorConnectionSource principalExtractor, or us.tractat.kuilt.core.withPrincipal in tests) are observable per admitted peer.

This is the production form of the in-memory star the test harness composes by hand; the harness is re-expressed on top of it so there is one composition path.

Parameters

admission

Per-link admission policy, enforced at the hub mesh between each spoke's MeshHello handshake and its publication. Defaults to LinkAdmission.AcceptAll (today's open behaviour); once supplied, the policy is authoritative for every spoke, including unattested ones. A rejected spoke surfaces as one debug-logged drop and the hub keeps serving.