kuilt-gossip/us.tractat.kuilt.gossip

Package-level declarations

Types

Flood every other peer: the active view is the whole roster minus self. The server-hub (star) policy — the hub re-floods each spoke's broadcast to all the others. A node under this policy keeps no spares: the active view already covers everyone.

GossipSeam

class GossipSeam(base: Seam, random: Random, clock: () -> Instant, config: HeartbeatConfig = HeartbeatConfig(), spareCount: Int = GossipView.DEFAULT_SPARE_COUNT, jitter: ClosedRange<Duration> = GossipView.DEFAULT_JITTER, initialTtl: Int = DEFAULT_TTL, topology: TopologyPolicy = RandomKRegular(random), policy: DeliveryPolicy = DeliveryPolicy.Reliable, reorderGrace: Duration = DEFAULT_REORDER_GRACE) : Seam, PrincipalRoster

A partial-mesh Seam over a base full-membership seam, exposing two views of the endpoints (docs/gossip-mesh-design.md):

GossipView

class GossipView(selfId: PeerId, seam: Seam, roster: StateFlow<Set<PeerId>>, rawIncoming: SharedFlow<Swatch>, random: Random, clock: () -> Instant, config: HeartbeatConfig = HeartbeatConfig(), spareCount: Int = DEFAULT_SPARE_COUNT, jitter: ClosedRange<Duration> = DEFAULT_JITTER, topology: TopologyPolicy = RandomKRegular(random))

The live, self-healing partial view of the gossip overlay for one peer.

PartialView

data class PartialView(val active: Set<PeerId>, val spares: List<PeerId>)

A peer's partial view of the gossip overlay.

RandomKRegular

class RandomKRegular(random: Random) : TopologyPolicy

The k-regular partial mesh: a seeded random k-out sample of the roster (k = recommendedActiveViewSize(N), via partialView), re-drawn on roster churn. The union of every peer's independent draw is connected with high probability — see recommendedActiveViewSize.

TopologyPolicy

interface TopologyPolicy

The shape of the gossip overlay for one node: given the live roster, which peers this node eager-floods broadcasts to (and GCs against), and which peers it may sample as anti-entropy partners.

TwoTier

class TwoTier(core: Set<PeerId>, attachment: (PeerId) -> PeerId?) : TopologyPolicy

The federated two-tier shape: a small core of servers fully meshed among themselves, each fronting a periphery of clients that attach to exactly one of them. Unlike FullFanout/RandomKRegular, this policy is anisotropic — the view a node gets depends on where it sits, not just how many peers there are:

Functions

hostedMesh

suspend fun CoroutineScope.hostedMesh(selfId: PeerId, source: ConnectionSource, dispatcher: CoroutineContext, admission: LinkAdmission = LinkAdmission.AcceptAll, handshakeTimeout: Duration = 10.seconds): Seam

Compose the raw accept-pumped hub mesh from a ConnectionSource: an initially-empty hubMesh plus the accept-pump that addLinks each accepted us.tractat.kuilt.core.fabric.Connection as clients connect. This is hostedOverlay without the star-relay flood — the seam whose sendTo reaches each spoke directly and whose broadcast is not re-flooded.

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.

partialView

fun partialView(self: PeerId, roster: Set<PeerId>, k: Int, spareCount: Int, random: Random): PartialView

Derives this peer's PartialView from the full roster as a seeded random k-out sample (excluding self): shuffle the other peers and take the first k as PartialView.active, then up to spareCount more as disjoint PartialView.spares. Both are capped by the number of available peers.

policyOverlay

fun CoroutineScope.policyOverlay(base: Seam, topology: TopologyPolicy, random: Random = Random.Default, clock: () -> Instant): Seam

Wrap base in a gossip-relay layer under an explicit topology policy, with zero recompute jitter, started on the receiver scope. The generalization of starOverlay (which is just policyOverlay(base, FullFanout, …)): the same started-GossipSeam relay interior, but the dissemination shape is whatever TopologyPolicy the caller passes — FullFanout (the hub star), RandomKRegular (the k-regular partial mesh), or TwoTier (a federated server core + client periphery). Broadcasts flood along the policy's active view; Seam.sendTo passes through unwrapped — the tested unicast invariant that keeps per-recipient traffic off the flood path is independent of the shape.

recommendedActiveViewSize

fun recommendedActiveViewSize(membershipSize: Int): Int

Recommended active-view size k for a membership of membershipSize peers: k = max(4, ⌈ln N⌉ + 2).

starOverlay

fun CoroutineScope.starOverlay(base: Seam, random: Random = Random.Default, clock: () -> Instant): Seam

Wrap base in the star-relay policy layer: a GossipSeam with FullFanout and zero recompute jitter, started on the receiver scope. A thin alias for policyOverlay(base, FullFanout, …) — the star is the full-fanout special case; the general form (policyOverlay) drives any TopologyPolicy with the same started-seam interior and the same zero-jitter determinism.