@honua/react 0.1.2-beta.0 → 0.1.4-beta.0

package/realtime/checkpoint-store.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Durable {@link RealtimeCheckpointStore} implementations for
+ * `@honua/sdk-js/realtime` (issue #937).
+ *
+ * `resumable.ts` already owns the resume state machine: it loads a checkpoint,
+ * validates it with {@link evaluateRealtimeCheckpoint}, and requires an explicit
+ * replacement snapshot whenever the checkpoint no longer applies. What it never
+ * had was a shipped store, so a reload always resnapshotted even when a valid
+ * cursor was in hand a second earlier. This module supplies that durability
+ * without redefining any cursor semantics:
+ *
+ * - {@link createIndexedDbRealtimeCheckpointStore} persists one record per
+ *   resume scope in the browser, keyed by the authorization-scope digest,
+ *   source identity, and query identity that already define checkpoint scope.
+ * - {@link createMemoryRealtimeCheckpointStore} runs the identical
+ *   normalization, screening, expiry, and eviction logic without IndexedDB, for
+ *   tests and non-persistent hosts.
+ * - {@link createRealtimeCheckpointStore} binds that same logic to any
+ *   {@link RealtimeCheckpointRecordStorage}, for hosts this module ships no
+ *   adapter for.
+ *
+ * Four properties are deliberate:
+ *
+ * 1. **Cursors only.** A record carries the resume position (sequence, cursor,
+ *    watermark, timestamp, delta token), the scope identity it belongs to, and
+ *    two observation times. It never carries features, snapshots, request URLs,
+ *    headers, or credentials. The authorization scope is reduced to a SHA-256
+ *    digest before it reaches storage, and every remaining persisted string is
+ *    screened with the shared persisted-string screen in
+ *    `src/connect-url-safety.ts` — the same discipline the offline region store
+ *    applies through `assertCredentialFreeManifest`.
+ * 2. **Fail-closed resume.** Load revalidates through
+ *    {@link evaluateRealtimeCheckpoint} and discards the record outright when
+ *    the source, query, source version, schema version, or authorization scope
+ *    changed, when the record is corrupt, or when the checkpoint is older than
+ *    the configured maximum age. A discarded checkpoint means the subscription
+ *    resnapshots; it never means a partial delta stream is delivered as though
+ *    it were complete.
+ * 3. **Bounded and atomic.** Each scope holds exactly one record (last write
+ *    wins), the store holds at most `maxRecords` scope records, and the
+ *    IndexedDB write plus its eviction sweep share a single readwrite
+ *    transaction.
+ * 4. **Never throws into a subscription.** A storage failure, a refused
+ *    credential-shaped value, or a corrupt record resolves and reports a
+ *    {@link RealtimeCheckpointStoreDiagnosticV1} carrying a
+ *    `HonuaRealtimeResumeError`, so the subscription degrades to a resnapshot
+ *    instead of entering the gate's terminal `error` phase.
+ *
+ * The store stays opt-in: nothing here is wired into a subscription unless a
+ * caller passes it as `checkpointStore`, so no existing subscription changes
+ * behaviour by default.
+ *
+ * @module
+ */
+import { HonuaRealtimeResumeError, type RealtimeCheckpointCompatibilityCode, type RealtimeCheckpointStore, type RealtimeResumeContextV1 } from "./resumable.js";
+/**
+ * Versioned format string stamped on every persisted record. A record whose
+ * format string differs is treated as corrupt and discarded on load, the same
+ * posture the offline stores take, so a future format can never be
+ * misinterpreted as this one.
+ */
+export declare const HONUA_REALTIME_CHECKPOINT_STORE_FORMAT: "honua.realtime-checkpoint-store/1.0";
+/**
+ * Default maximum checkpoint age. A cursor older than this forces a resnapshot
+ * even when its scope still matches, because a server may retire a cursor
+ * window without telling the client; a silent gap is worse than an honest
+ * resnapshot.
+ */
+export declare const DEFAULT_REALTIME_CHECKPOINT_MAX_AGE_MS: number;
+/** Absolute ceiling on `maxAgeMs`. Callers may tighten it, never raise it. */
+export declare const MAX_REALTIME_CHECKPOINT_MAX_AGE_MS: number;
+/**
+ * Default cap on distinct resume scopes retained per store. Each scope holds at
+ * most one record, so this is also the record cap; the least recently written
+ * record is evicted first.
+ */
+export declare const DEFAULT_REALTIME_CHECKPOINT_MAX_RECORDS = 64;
+/** Absolute ceiling on `maxRecords`. Callers may tighten it, never raise it. */
+export declare const MAX_REALTIME_CHECKPOINT_RECORDS = 512;
+/** Resume position persisted with a checkpoint record. Never a payload. */
+export interface RealtimeStoredResumePosition {
+    readonly sequence: number;
+    readonly cursor?: string;
+    readonly watermark?: string;
+    readonly timestamp?: string;
+    readonly deltaToken?: string;
+}
+/**
+ * One persisted checkpoint record.
+ *
+ * `savedAt` is the checkpoint's own observation time and drives expiry;
+ * `observedAt` is when this store wrote the record and drives eviction order.
+ * Recent event ids are deliberately absent: they are bounded delivery history,
+ * not resume state, so a restored checkpoint starts with an empty id window
+ * while its ordering guarantees are unchanged.
+ */
+export interface RealtimeCheckpointRecordV1 {
+    readonly key: `sha256:${string}`;
+    readonly format: typeof HONUA_REALTIME_CHECKPOINT_STORE_FORMAT;
+    readonly sourceId: string;
+    readonly queryFingerprint: string;
+    readonly sourceVersion: string;
+    readonly schemaVersion: string;
+    /** Digest of the resume context's authorization-scope fingerprint, never the fingerprint itself. */
+    readonly authorizationScopeDigest: `sha256:${string}`;
+    readonly resume: RealtimeStoredResumePosition;
+    readonly savedAt: string;
+    readonly observedAt: string;
+}
+/**
+ * Why a checkpoint was not returned or not persisted. The first six values are
+ * exactly the incompatible {@link RealtimeCheckpointCompatibilityCode} results,
+ * so a discard reason reads in the same vocabulary the delivery gate uses.
+ *
+ * `unsupported-format` is deliberately distinct from `invalid-checkpoint`
+ * (issue #1046): a record written in another store format is not damage, it is
+ * a layout this build declines to interpret, and a host that sees a run of them
+ * is looking at a version rollback rather than a corrupt database. Realtime
+ * cursors are cheap to discard, so the posture stays discard-and-resnapshot;
+ * only the reporting distinguishes the two.
+ */
+export type RealtimeCheckpointStoreReason = Exclude<RealtimeCheckpointCompatibilityCode, "compatible"> | "checkpoint-expired" | "credential-screened" | "storage-failed" | "unsupported-format";
+/**
+ * Structured report of a load or save that did not produce a durable resume.
+ *
+ * `error` is a `HonuaRealtimeResumeError`, so a host routes it through the same
+ * envelope as every other realtime failure. Messages never echo a stored cursor,
+ * scope fingerprint, or offending value.
+ */
+export interface RealtimeCheckpointStoreDiagnosticV1 {
+    readonly kind: "honua.realtime-checkpoint-store-diagnostic";
+    readonly version: 1;
+    readonly operation: "load" | "save";
+    readonly reason: RealtimeCheckpointStoreReason;
+    /** Scope key the operation addressed; a digest, never a raw identity. */
+    readonly scopeKey: `sha256:${string}`;
+    readonly error: HonuaRealtimeResumeError;
+}
+export interface RealtimeCheckpointStoreOptions {
+    /** Maximum checkpoint age before a resnapshot is forced. @default 900000 */
+    readonly maxAgeMs?: number;
+    /** Maximum distinct resume scopes retained; least recently written is evicted. @default 64 */
+    readonly maxRecords?: number;
+    readonly now?: () => number;
+    /** Receives every discard, refusal, and storage failure. Must not throw. */
+    readonly onDiagnostic?: (diagnostic: RealtimeCheckpointStoreDiagnosticV1) => void;
+}
+export interface IndexedDbRealtimeCheckpointStoreOptions extends RealtimeCheckpointStoreOptions {
+    /** Defaults to `honua-realtime-checkpoints`. Names are origin-scoped by IndexedDB. */
+    readonly name?: string;
+    /** Injectable for browser tests and hosts with an alternate IndexedDB factory. */
+    readonly indexedDB?: IDBFactory;
+}
+/**
+ * Storage primitives the scope, screening, expiry, and eviction logic is built
+ * on. Implement it to persist checkpoints somewhere this module does not ship an
+ * adapter for (a Node filesystem, SQLite, an extension store). Reads may return
+ * anything at all — every value is revalidated before it can resume a
+ * subscription — and every method may reject, which degrades to a resnapshot.
+ */
+export interface RealtimeCheckpointRecordStorage {
+    read(key: string): Promise<unknown>;
+    /** Atomically write `record` and evict the oldest records beyond `maxRecords`. */
+    write(record: RealtimeCheckpointRecordV1, maxRecords: number): Promise<void>;
+    remove(key: string): Promise<void>;
+    list(): Promise<readonly unknown[]>;
+    clear(): Promise<void>;
+}
+/** A checkpoint store plus the record administration a host needs to audit or reset it. */
+export interface RealtimeCheckpointStoreHandle extends RealtimeCheckpointStore {
+    /** Every valid persisted record, for enumeration in tests and diagnostics. */
+    records(): Promise<readonly RealtimeCheckpointRecordV1[]>;
+    /** Drop every stored checkpoint, for sign-out and scope teardown. */
+    clear(): Promise<void>;
+}
+/**
+ * Deterministic scope key for a resume context: a digest over the
+ * authorization-scope digest, source identity, and query identity — exactly the
+ * identities checkpoint scope validation is defined against. Source and schema
+ * versions are intentionally excluded so a version bump replaces the record in
+ * place and is discarded explicitly on load, instead of orphaning it under a
+ * key nothing will read again.
+ */
+export declare function realtimeCheckpointScopeKey(context: RealtimeResumeContextV1): `sha256:${string}`;
+/**
+ * Opaque digest of an authorization-scope fingerprint. The fingerprint is
+ * already documented as a non-secret opaque identity; persisting only its
+ * digest keeps that promise enforceable rather than assumed.
+ */
+export declare function realtimeAuthorizationScopeDigest(fingerprint: string): `sha256:${string}`;
+/**
+ * Bind the shared scope, screening, expiry, and eviction logic to any
+ * {@link RealtimeCheckpointRecordStorage}. The returned store never throws into
+ * a subscription: a rejected storage call, a refused value, or a corrupt record
+ * resolves and reports a diagnostic, so the subscription resnapshots.
+ */
+export declare function createRealtimeCheckpointStore(storage: RealtimeCheckpointRecordStorage, options?: RealtimeCheckpointStoreOptions): RealtimeCheckpointStoreHandle;
+/** In-memory store with the persistent store's exact semantics, for tests and non-persistent hosts. */
+export declare function createMemoryRealtimeCheckpointStore(options?: RealtimeCheckpointStoreOptions): RealtimeCheckpointStoreHandle;
+/** Map-backed storage with the same one-record-per-scope, oldest-first eviction contract. */
+export declare function createMemoryCheckpointStorage(): RealtimeCheckpointRecordStorage;
+/** Persistent browser store: one bounded, atomically written record per resume scope. */
+export declare function createIndexedDbRealtimeCheckpointStore(options?: IndexedDbRealtimeCheckpointStoreOptions): RealtimeCheckpointStoreHandle;
+/** IndexedDB storage; each method runs in exactly one transaction. */
+export declare function createIndexedDbCheckpointStorage(options?: IndexedDbRealtimeCheckpointStoreOptions): RealtimeCheckpointRecordStorage;
+//# sourceMappingURL=checkpoint-store.d.ts.map

package/realtime/checkpoint-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-store.d.ts","sourceRoot":"","sources":["../../../src/realtime/checkpoint-store.ts"],"names":[],"mappings":"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"}