Federation

DSM federation connects collections across independent DSM runtimes. It is useful when two clusters need selected coordination state to converge without pretending they are one membership domain.

What Federation Provides

Type	Role
FederationBridge	Binds a local collection to a remote FederationTarget and routes by collection consistency tier.
FederationTarget	Remote (clusterId, serviceId, locator) destination.
FederationRelay	Transport SPI used by the bridge. Custom production transports implement this boundary.
FederationDigest	Register digest used to detect divergence without transferring every visible entry.
InMemoryFederationRelay	In-process baseline relay for tests and embedded examples. It is not a production network transport.
InMemoryFederationBridge	Baseline bridge implementation for register, lease, and CRDT federation semantics.

Scope And Limitations

Federation is not multi-region clustering by another name. It does not merge membership domains, transfer lease ownership across clusters, or provide a production gRPC/HTTP relay out of the box.

Collection tier	Federation behavior	Repair behavior
Register	Bootstrap visible local state, then forward live puts and removes.	Periodic digest-based anti-entropy repairs dropped mutations.
Lease	Forward LeaseSnapshot changes for read-only remote observation.	No cross-cluster acquire, renew, transfer, bootstrap repair, or ownership transfer.
CRDT	Forward committed StateDelta values.	Relies on CRDT convergence and idempotency; no federation anti-entropy sweep.

The current relay baseline is in-memory and in-process. A production deployment must implement FederationRelay over a real transport and carry the same semantics explicitly.

Register Repair Loop

Register federation uses bootstrap-then-forward semantics, then closes relay gaps with a sweeper.

Dropped puts and same-key updates are repaired by digest divergence. Dropped removes are repaired by re-bootstrap when the remote digest still contains stale entries after merge.

Relay Health

Federation status is driven by relay health:

Relay state	Binding status	Runtime behavior
HEALTHY	HEALTHY	Live forwarding and repair continue.
DEGRADED	DEGRADED	Status exposes risk; transport may still succeed.
FAILED	DISCONNECTED	Forwarding is suspended; disconnected bindings are skipped by repair.
recovered	SYNCING then HEALTHY	Register bindings trigger immediate catch-up bootstrap.

Use RelayHealthMonitor.noop() only for tests or deployments that deliberately do not track relay health.

Minimal Shape

DsmRuntime runtimeA = /* cluster-a runtime */;
DsmRuntime runtimeB = /* cluster-b runtime */;

CollectionSpec<MyEntry> spec = CollectionSpecBuilder.<MyEntry>register(
        "shared", "gateway", "entries")
    .schemaId("entries/v1")
    .codec(new MyEntryCodec())
    .build();

runtimeA.register(spec);
runtimeB.register(spec);
runtimeA.start();
runtimeB.start();

InMemoryFederationRelay relay = new InMemoryFederationRelay();
relay.registerRuntime(runtimeA);
relay.registerRuntime(runtimeB);

InMemoryFederationBridge bridge = new InMemoryFederationBridge(
    runtimeA,
    relay,
    RelayHealthMonitor.noop());

bridge.federateCollection(
    spec.locator(),
    new FederationBridge.FederationTarget("cluster-b", "gateway-service", spec.locator()));

Production Checklist

• Implement FederationRelay over a real transport before using federation across processes or regions.
• Preserve tier-specific semantics. Do not let a remote cluster acquire or renew federated leases.
• Emit DsmMetrics.recordFederationRepair(locator, target, outcome) and alert on sustained failed or bootstrap_fallback outcomes.
• Treat register anti-entropy as state repair, not historical event replay.
• Test slow relay behavior; bridge flushing must not block local change-stream enqueueing.

Test Evidence

• InMemoryFederationBridgeTest covers bootstrap, live put/remove forwarding, relay failure/recovery, register repair outcomes, non-blocking flush behavior, lease observation, and CRDT delta convergence.
• FederationIntegrationTest covers bidirectional register convergence across two independent runtimes using the in-memory relay baseline.

Related Pages

• Repair And Anti-Entropy
• Collection Types
• Observability