Skip to main content

Replication

sync.replication publishes named snapshots. Publications broadcast complete replacements and withdrawals; only explicit watches retain a foreign value. A watch opened after publication requests the current snapshot.

Use this for datasets published occasionally and read by selected consumers. State mirrors owner-written keys on every node. Core builds its library registries on Replication and owns the schemas and provider-selection policy.

Import​

import type {
ReplicaPublication, ReplicaSnapshot, ReplicaSubscription, PeerInfo,
} from '@bedrock-core/sync';

SyncNode creates the Replication service and starts it with the other subsystems.

Publish​

const items = sync.replication.publish('items', {
entries: ['diamond', 'emerald'],
});

items.set({ entries: ['diamond', 'emerald', 'gold_ingot'] });
items.stop();

publish(key, value) returns a ReplicaPublication. The key belongs to this running node; another node may publish the same key. Publishing a duplicate local key throws.

The initial value and every set() value are copied and frozen. set(value) broadcasts the complete replacement and increments its revision. It sends even when the supplied contents are equal. Unsupported values throw during copying or encoding.

stop() withdraws the publication and broadcasts its absence. It is idempotent. A stopped publication's set() throws; publishing that key again creates a new generation.

Watch​

function watchItems(peer: PeerInfo): () => void {
const watch = sync.replication.watch(peer.id, peer.instanceId, 'items');
const showStatus = (): void => {
console.warn(`Items: ${watch.snapshot.get().status}`);
};

showStatus();
const unsubscribe = watch.snapshot.subscribe(showStatus);

return () => {
unsubscribe();
watch.stop();
};
}

watch(id, instance, key) returns a ReplicaSubscription with a standard read-only observable at snapshot. Use the current PeerInfo.instanceId from Discovery. The watch is pinned to that running instance; a replacement requires a new watch.

The first local watch for a peer/instance/key sends one current-snapshot request. Additional watches share its observable and retained value without sending that request again. Each handle owns one interest. stop() is idempotent; the final handle removes the retained watch and sets its shared snapshot to stopped. Observable listeners have their own unsubscribe functions.

No watch retains data for unrelated keys or publishers. Broadcasts still travel over the bus; opt-in retention does not remove their transport cost.

Snapshot states​

interface ReplicaSnapshot {
readonly status: 'loading' | 'ready' | 'missing' | 'unavailable' | 'stopped';
readonly generation: number;
readonly revision: number;
readonly value?: unknown;
}
StatusMeaning
loadingA request is outstanding; no current snapshot has been accepted
readyThe watched publication exists; value contains its copied, immutable value
missingThe owner reported no publication or withdrew it
unavailableDiscovery retired the watched running instance; the value is removed
stoppedThe final watch handle or the Replication service stopped

ready may contain a value of undefined; inspect status rather than using value !== undefined as a presence test. loading and stopped use generation/revision -1. unavailable keeps the last counters while removing the value.

Generation distinguishes successive publications and withdrawals. Revision orders replacements within one generation. Older, duplicate and mismatched-instance snapshots are ignored. Directed replies must also match the reader's running instance and request token.

Validation and availability​

Values are unknown: the consumer owns schema validation and compatibility checks. A discovered peer is not proof that a key exists or that it implements the publication contract. A watch has no built-in response timeout; callers own any deadline while it remains loading.

Payloads follow the data value and protocol contract. Protocol negotiation alone does not describe an application's publication schema.

Lifecycle​

SyncNode starts Replication before discovery advertises. Peer departure, incompatible replacement or running-instance replacement invalidates that instance's retained snapshots. Stopping the node clears publications and watches; existing watch observables become stopped.

Use a publication's stop() for an explicit withdrawal while the node is live. Node shutdown sends no graceful peer-departure announcement, so remote availability can remain unchanged until discovery retires the peer.