@openlfcp/client 0.1.0-rc.1

package/dist/sync-client.d.ts

@@ -0,0 +1,203 @@
+import { type ControlRecordId, type DataEpoch, type DataUnitId, type Hash32, type ResourceId } from "@openlfcp/core";
+import { type AgreementKeyPair } from "@openlfcp/crypto";
+import { type LfcpStorage, type SecretStore } from "@openlfcp/storage";
+import { type ClientConnectionState, type DataProfileCodec, type HaveVector, type Signer } from "@openlfcp/wire";
+import type { ApplyOutcome, DataUnitApplier, EpochReconciliation } from "./apply.js";
+import type { ProfileCheckpointer } from "./checkpoint.js";
+import { type WebSocketFactory } from "./connection.js";
+import type { AckOutcome, NackOutcome, OutboundQueue, StaleOutboundUnit } from "./outbound.js";
+import { type ResourcePhase } from "./resource-state.js";
+/**
+ * The client sync session (LFCP-039a): one LFCP connection to a server and
+ * the §65 machine of every Resource opened on it, orchestrating the parts
+ * built before it. It adds no protocol rule of its own:
+ *
+ * - connection, handshake, heartbeat, size limits: LfcpConnection;
+ * - Control catch-up: planControlSync, then validateControlChain over the
+ *   stored records and the fetched ones; a fork is stored and surfaced
+ *   (CONTROL_CONFLICT), never resolved;
+ * - keys: KEY_PACKAGE_GET for epochs without a DEK, receiveKeyPackage, the
+ *   DEK into the SecretStore before its reference into storage;
+ * - data: Have Vectors (missingFrom, ≤256 ranges per DATA_GET), every unit
+ *   through the DataUnitApplier; periodic DATA_HAVE (§69: anti-entropy);
+ * - outbound: OutboundQueue, flushed once keys are in place (§88 step 6),
+ *   ACK and NACK routed back to it;
+ * - on every newly validated Control state: DataUnitApplier.reconcileEpochs
+ *   AND OutboundQueue.reconcileEpochs (G-EP7, §88 step 7).
+ *
+ * Time and timers belong to the caller: tick(now) does the periodic work
+ * (heartbeat, anti-entropy, retries, checkpoints, reconnect), and a thin
+ * driver may call it from a timer (startSyncDriver). Events tell the
+ * application what happened; nothing is logged, plaintext never.
+ */
+/** A Resource to synchronize: its Data Profile applier (and optional checkpoints). */
+/**
+ * How a Data Profile reads and writes Snapshots (§29, §66 step 3): its §13
+ * codec, loading a received Snapshot's state, and the state to publish
+ * (for Shared Objects: snapshotCodec(), loadSnapshot(), snapshotState()).
+ */
+export interface SnapshotBinding<T> {
+    readonly codec: DataProfileCodec<T>;
+    load(value: T): void;
+    current(): T;
+}
+/** A Resource to synchronize: its Data Profile applier (and optional checkpoints and Snapshots). */
+export interface ResourceBinding {
+    readonly resourceId: ResourceId;
+    readonly applier: DataUnitApplier;
+    readonly checkpointer?: ProfileCheckpointer;
+    /** Load an offered Snapshot instead of replaying every unit, and allow publishing. */
+    readonly snapshot?: SnapshotBinding<unknown>;
+}
+/** When to try connecting again after the `attempt`-th failure (1, 2, …): a delay in ms, or null to stop. */
+export type ReconnectPolicy = (attempt: number) => number | null;
+/** 1 s, doubling, at most 60 s, forever. */
+export declare const defaultReconnect: ReconnectPolicy;
+export interface SyncClientOptions {
+    readonly url: string;
+    /** The session and writing Principal. */
+    readonly signer: Signer;
+    /** Its X25519 key pair, to open Key Packages addressed to it. */
+    readonly agreement: AgreementKeyPair;
+    readonly storage: LfcpStorage;
+    readonly secrets: SecretStore;
+    readonly outbound: OutboundQueue;
+    /** The caller's clock, in milliseconds. */
+    readonly now: () => number;
+    readonly webSocket?: WebSocketFactory;
+    readonly reconnect?: ReconnectPolicy;
+    /** How often a LIVE Resource exchanges DATA_HAVE (§69); default 30 s. */
+    readonly antiEntropyMs?: number;
+    /**
+     * How long a request waits for its answer on a live connection before
+     * the step it belongs to is issued again (a lost request or reply, §70
+     * at-least-once): RESOURCE_OPEN, the Control round, KEY_PACKAGE_GET, the
+     * data round. A lost SNAPSHOT_GET falls back to the data round. Default 15 s.
+     */
+    readonly requestTimeoutMs?: number;
+    /** An opaque hosting credential for AUTH (§36): server policy only. */
+    readonly credential?: Uint8Array;
+    readonly dataProfiles?: readonly string[];
+    /**
+     * Whether to publish a Snapshot of a LIVE Resource now, asked on every
+     * tick with the number of units merged since the last one; no automatic
+     * schedule otherwise (publishSnapshot can also be called directly).
+     */
+    readonly snapshotPolicy?: (resourceId: ResourceId, unitsSinceLast: number) => boolean;
+}
+/** What the session reports to the application. */
+export type SyncEvent = {
+    readonly type: "connection";
+    readonly state: ClientConnectionState;
+    readonly reason?: string;
+} | {
+    readonly type: "resource-state";
+    readonly resourceId: ResourceId;
+    readonly state: ResourcePhase;
+}
+/** A received unit's outcome (merged, held, quarantined, equivocation, …). */
+ | {
+    readonly type: "unit";
+    readonly resourceId: ResourceId;
+    readonly outcome: ApplyOutcome;
+}
+/** Merged units a new Key Epoch excluded, and the objects that changed (G-EP7). */
+ | {
+    readonly type: "epoch-reconciled";
+    readonly resourceId: ResourceId;
+    readonly applied: EpochReconciliation;
+    readonly outbound: readonly StaleOutboundUnit[];
+} | {
+    readonly type: "control-conflict";
+    readonly resourceId: ResourceId;
+    readonly heads: readonly ControlRecordId[];
+} | {
+    readonly type: "key-blocked";
+    readonly resourceId: ResourceId;
+    readonly epochs: readonly DataEpoch[];
+}
+/** A Snapshot was loaded (§66 step 3); only units beyond its frontier are fetched. */
+ | {
+    readonly type: "snapshot-loaded";
+    readonly resourceId: ResourceId;
+    readonly snapshotId: Hash32;
+    readonly frontier: HaveVector;
+} | {
+    readonly type: "snapshot-published";
+    readonly resourceId: ResourceId;
+    readonly snapshotId: Hash32;
+}
+/** Stored accepted units applied again to a profile state that lacked them (restart). */
+ | {
+    readonly type: "replayed";
+    readonly resourceId: ResourceId;
+    readonly replayed: readonly DataUnitId[];
+    readonly skipped: readonly {
+        readonly unitId: DataUnitId;
+        readonly reason: string;
+    }[];
+    /** Units quarantined because they crashed the profile engine twice by themselves. */
+    readonly crashed: readonly DataUnitId[];
+} | {
+    readonly type: "ack";
+    readonly outcome: AckOutcome;
+}
+/** A NACK of an outbound object: stale, equivocation alarm, rejected, repropose, … */
+ | {
+    readonly type: "nack";
+    readonly outcome: NackOutcome;
+}
+/** A refusal or failure that concerns a Resource or the session (codes and reasons, never payloads). */
+ | {
+    readonly type: "error";
+    readonly resourceId?: ResourceId;
+    readonly code: string;
+    readonly message: string;
+};
+export declare class SyncClient {
+    #private;
+    constructor(options: SyncClientOptions);
+    /** Subscribes to session events; returns the unsubscribe function. */
+    on(listener: (event: SyncEvent) => void): () => void;
+    /** Resolves once every message received so far has been handled (tests and shutdown). */
+    idle(): Promise<void>;
+    get connectionState(): ClientConnectionState;
+    resourceState(resource: ResourceId): ResourcePhase;
+    /** Connects, and reconnects after losses (per the ReconnectPolicy) until stop(). */
+    start(): void;
+    /** Closes the connection and stops reconnecting. Local state stays usable. */
+    stop(): Promise<void>;
+    /** Registers a Resource and opens it now (or when the session is READY). */
+    open(binding: ResourceBinding): void;
+    /** RESOURCE_CLOSE (§43): no more pushes; local state stays usable. */
+    close(resource: ResourceId): void;
+    /** RESOURCE_HOST (§39): asks the server to host a Resource from its exact Genesis bytes; resolves with the durability applied. */
+    host(genesis: Uint8Array, credential?: Uint8Array): Promise<bigint>;
+    /** Sends what the outbound queue has due for every Resource past KEY_SYNC (e.g. after a local write). */
+    flush(): void;
+    /**
+     * The periodic work, on the caller's clock: heartbeat (§38), reconnect,
+     * anti-entropy DATA_HAVE for LIVE Resources (§69), Key Package retries,
+     * due outbound retries and debounced checkpoints.
+     */
+    tick(now: number): void;
+    /**
+     * Publishes a Snapshot of the Resource's current state (§29): its frontier
+     * is every merged unit and every stored Snapshot's frontier, so a client
+     * that loads it never skips content the state does not hold. Queued and
+     * sent like any object; returns its ID.
+     */
+    publishSnapshot(resource: ResourceId): Promise<Hash32>;
+}
+/**
+ * A thin timer driver for SyncClient: calls tick(now) every `intervalMs`
+ * with the given clock and timer functions (setInterval/clearInterval in
+ * production). Returns the stop function. The core never sets timers
+ * itself; this is the one explicit place that does.
+ */
+export declare function startSyncDriver(client: SyncClient, timers: {
+    readonly setInterval: (fn: () => void, ms: number) => unknown;
+    readonly clearInterval: (handle: unknown) => void;
+    readonly now: () => number;
+}, intervalMs?: number): () => void;
+//# sourceMappingURL=sync-client.d.ts.map