@weaveprotocol/core 0.1.2 → 0.2.1

package/dist/sync/sync-engine.d.ts

@@ -2,17 +2,29 @@
  * @module sync-engine
  * Keeps one store in step with its peers.
  *
- * Reconciliation is a pull, and both sides do it:
+ * 1. A peer says hello with a fingerprint of each collection it keeps. Equal
+ *    fingerprints mean the same versions: nothing to do for that collection.
+ * 2. For each collection that differs, one side — the initiator — reconciles
+ *    it with the other (`negentropy.ts`). A few rounds of fingerprints of
+ *    ever smaller ranges end with the initiator knowing which versions each
+ *    side lacks.
+ * 3. The initiator asks for what it lacks, and sends what the other lacks.
+ *    Everything that arrives passes the gatekeeper before it is stored.
  *
- * 1. A tells B its root. Equal roots mean identical data — one round trip, done.
- * 2. Otherwise each walks the other's tree from the root, asking for nodes in
- *    batches and skipping any subtree that is already part of its own tree.
- * 3. The keys found in the nodes it fetched, less the records it already
- *    holds, are what it is missing. It asks for those, and every one of them
- *    passes the gatekeeper before it is stored.
+ * Cost follows the difference, not the size: two stores differing by one
+ * version exchange a few hundred bytes.
  *
- * Cost follows the difference, not the size: two trees differing by one entry
- * exchange the few nodes on the path to it.
+ * The initiator is the peer whose id sorts first, so two peers that hear each
+ * other's hello at once don't both do the work. A peer that isn't the
+ * initiator answers a hello with its own, which starts the other.
+ *
+ * **Holding part of a space.** A node may hold every collection, or only
+ * some (plus the space's own `sys.*`, which every node holds). Each hello
+ * says which. Two peers reconcile only the collections both hold, and a
+ * version for a collection this node doesn't hold is not taken in. Whatever
+ * a node does take in from a peer, it tells that peer it has (`stored`): a
+ * node holding part of a space keeps its own writes until enough keepers have
+ * said so.
  */
 import type { Expression } from '../types.js';
 import type { StorageProvider } from '../storage/storage-provider.js';
@@ -29,9 +41,19 @@ export interface IncomingValidation {
      */
     readonly later?: boolean;
 }
+/** What a node holds of a space: every collection, or these (besides `sys.*`, which every node holds) */
+export type Holds = 'all' | ReadonlySet<string>;
+/** Whether a collection is held, given what a node holds */
+export declare const holdsCollection: (holds: Holds, collection: string) => boolean;
 export interface SyncEngineConfig {
     readonly storageProvider: StorageProvider;
     readonly sendToPeer: (peerId: string, message: SyncMessage) => void;
+    /**
+     * This node's id among its peers. The one of two peers whose id sorts first
+     * starts reconciling. Without it, this node starts whenever it hears of a
+     * difference — harmless, just sometimes twice the work.
+     */
+    readonly self?: string;
     readonly heartbeatInterval?: number;
     /**
      * Gatekeeper for expressions arriving from peers — typically a
@@ -42,14 +64,24 @@ export interface SyncEngineConfig {
      * for a trusted transport or a test.
      */
     readonly validate?: (expression: Expression) => Promise<IncomingValidation>;
+    /** What this node holds, asked afresh for every hello. Default: everything. */
+    readonly holds?: () => Holds;
 }
-export type SyncEvent = 'synced' | 'expression-received' | 'rejected' | 'error';
+/**
+ * - `synced` (peer, full): nothing left in flight with the peer; `full` when the peer holds every collection
+ * - `level` (peer, collection, full): this node holds what the peer holds of a
+ *   collection, as far as it could take it in; `full` when the peer holds every collection
+ * - `stored` (peer, ids): the peer says it now has these versions
+ * - `expression-received` (version), `rejected` (peer, version, reason), `error` (error)
+ */
+export type SyncEvent = 'synced' | 'level' | 'stored' | 'expression-received' | 'rejected' | 'error';
 type EventHandler = (...args: any[]) => void;
 export interface SyncEngine {
     start(): void;
     stop(): void;
     /** Handles whatever a peer sent; anything that is not a sync message this peer speaks is ignored. */
     handleMessage(peerId: string, message: unknown): Promise<void>;
+    /** Says hello to these peers now, rather than at the next heartbeat. */
     notifyPeers(peers: ReadonlyArray<string>): void;
     onLocalChange(expression: Expression): void;
     addPeer(peerId: string): void;
@@ -57,10 +89,10 @@ export interface SyncEngine {
     on(event: SyncEvent, callback: EventHandler): void;
     off(event: SyncEvent, callback: EventHandler): void;
 }
-/** Nodes asked for in one message. Nodes are small; this keeps round trips few. */
-export declare const MAX_CIDS_PER_REQUEST = 64;
-/** Records asked for in one message. */
+/** Records asked for, or sent, in one message. */
 export declare const MAX_IDS_PER_REQUEST = 200;
+/** Largest Negentropy message, in bytes before base64. Stays well inside a data channel's limit. */
+export declare const FRAME_SIZE_LIMIT = 32000;
 /**
  * Creates a sync engine orchestrator.
  * @param config Sync engine configuration.

package/dist/sync/sync-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync-engine.d.ts","sourceRoot":"","sources":["../../src/sync/sync-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAItE,OAAO,EAA2C,KAAK,WAAW,EAAwB,MAAM,oBAAoB,CAAC;AAGrH,wDAAwD;AACxD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAQD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC;IACpE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC7E;AAED,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,qBAAqB,GAAG,UAAU,GAAG,OAAO,CAAC;AAChF,KAAK,YAAY,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;AAE7C,MAAM,WAAW,UAAU;IACzB,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,IAAI,CAAC;IACb,qGAAqG;IACrG,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAChD,aAAa,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IAC5C,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IACnD,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;CACrD;AAED,mFAAmF;AACnF,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,wCAAwC;AACxC,eAAO,MAAM,mBAAmB,MAAM,CAAC;AA0BvC;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,CA6RrE"}
+{"version":3,"file":"sync-engine.d.ts","sourceRoot":"","sources":["../../src/sync/sync-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAKtE,OAAO,EAA2C,KAAK,WAAW,EAAwB,MAAM,oBAAoB,CAAC;AAErH,wDAAwD;AACxD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAOD,yGAAyG;AACzG,MAAM,MAAM,KAAK,GAAG,KAAK,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;AAEhD,4DAA4D;AAC5D,eAAO,MAAM,eAAe,GAAI,OAAO,KAAK,EAAE,YAAY,MAAM,KAAG,OACQ,CAAC;AAK5E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC;IACpE;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC5E,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,qBAAqB,GAAG,UAAU,GAAG,OAAO,CAAC;AACrG,KAAK,YAAY,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;AAE7C,MAAM,WAAW,UAAU;IACzB,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,IAAI,CAAC;IACb,qGAAqG;IACrG,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,wEAAwE;IACxE,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAChD,aAAa,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IAC5C,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IACnD,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;CACrD;AAED,kDAAkD;AAClD,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,oGAAoG;AACpG,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAiCvC;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,CA2WrE"}