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;
}
| Status | Meaning |
|---|---|
loading | A request is outstanding; no current snapshot has been accepted |
ready | The watched publication exists; value contains its copied, immutable value |
missing | The owner reported no publication or withdrew it |
unavailable | Discovery retired the watched running instance; the value is removed |
stopped | The 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.