@hops-ops/distributed 0.0.0

package/dist/replica/operation-binding.d.ts

@@ -0,0 +1,14 @@
+import type { GraphqlVariables } from '../types.js';
+import type { ReplicaOperationArtifact, ReplicaSurfaceTrustedPresetDescriptor } from './types.js';
+export type ValidatedReplicaOperationBinding = {
+    readonly version: 1;
+    readonly schemaHash: string;
+    readonly operation: string;
+    readonly surfaceIdentity: string;
+    readonly trustedPresets: readonly ReplicaSurfaceTrustedPresetDescriptor[];
+};
+/**
+ * Validate the exact compiler-owned protocol identity before an operation may
+ * acquire a cache key, register a maintenance plan, or reach a transport.
+ */
+export declare function validateReplicaOperationBinding<TData, TVariables extends GraphqlVariables>(artifact: ReplicaOperationArtifact<TData, TVariables>): ValidatedReplicaOperationBinding;

package/dist/replica/operation-binding.js

@@ -0,0 +1,76 @@
+import { isDistributedTrustedPresetCodec } from '../protocol.js';
+/**
+ * Validate the exact compiler-owned protocol identity before an operation may
+ * acquire a cache key, register a maintenance plan, or reach a transport.
+ */
+export function validateReplicaOperationBinding(artifact) {
+    if (typeof artifact.id !== 'string' || artifact.id.length === 0) {
+        throw new TypeError('replica artifact id must be a non-empty string');
+    }
+    const binding = artifact.protocol;
+    if (binding === undefined ||
+        binding.version !== 1 ||
+        typeof binding.schemaHash !== 'string' ||
+        binding.schemaHash.length === 0 ||
+        typeof binding.operation !== 'string' ||
+        binding.operation.length === 0 ||
+        binding.operation !== artifact.id) {
+        throw new TypeError('replica artifact protocol binding is invalid');
+    }
+    if (artifact.variableCodec === undefined) {
+        throw new TypeError('protocol-v1 replica artifact requires variableCodec');
+    }
+    return Object.freeze({
+        version: binding.version,
+        schemaHash: binding.schemaHash,
+        operation: binding.operation,
+        surfaceIdentity: validateReplicaSurfaceIdentity(binding.surface),
+        trustedPresets: canonicalTrustedPresetDescriptors(binding.trustedPresets)
+    });
+}
+function validateReplicaSurfaceIdentity(value) {
+    if (value === null ||
+        typeof value !== 'object' ||
+        typeof value.name !== 'string' ||
+        value.name.length === 0) {
+        throw new TypeError('replica artifact client surface is invalid');
+    }
+    if (value.kind === 'role') {
+        return JSON.stringify(['role', value.name]);
+    }
+    if (value.kind !== 'application' ||
+        !Array.isArray(value.roles) ||
+        value.roles.length === 0 ||
+        value.roles.some((role) => typeof role !== 'string' || role.length === 0) ||
+        new Set(value.roles).size !== value.roles.length ||
+        [...value.roles].sort().some((role, index) => role !== value.roles[index])) {
+        throw new TypeError('replica artifact client surface is invalid');
+    }
+    return JSON.stringify(['application', value.name, value.roles]);
+}
+function canonicalTrustedPresetDescriptors(value) {
+    if (!Array.isArray(value)) {
+        throw new TypeError('replica artifact trusted preset contract is invalid');
+    }
+    const names = new Set();
+    return Object.freeze(value
+        .map((candidate) => {
+        if (candidate === null ||
+            typeof candidate !== 'object' ||
+            typeof candidate.name !== 'string' ||
+            candidate.name.length === 0 ||
+            candidate.name.length > 128 ||
+            candidate.name.trim() !== candidate.name ||
+            /[\u0000-\u001f\u007f-\u009f]/.test(candidate.name) ||
+            names.has(candidate.name) ||
+            !isDistributedTrustedPresetCodec(candidate.codec)) {
+            throw new TypeError('replica artifact trusted preset contract is invalid');
+        }
+        names.add(candidate.name);
+        return Object.freeze({
+            name: candidate.name,
+            codec: candidate.codec
+        });
+    })
+        .sort(({ name: left }, { name: right }) => left < right ? -1 : left > right ? 1 : 0));
+}

package/dist/replica/persistence/idb.d.ts

@@ -0,0 +1,20 @@
+import type { ReplicaAuthoritativeScope, ReplicaDehydratedState } from '../types.js';
+import type { ReplicaIndexedDbFactory, ReplicaIndexedDbPersistence, ReplicaIndexedDbPersistenceOptions } from './types.js';
+import { type NormalizedPolicy } from './state.js';
+export declare class IndexedDbConfirmedStatePersistence implements ReplicaIndexedDbPersistence {
+    #private;
+    readonly supportsOfflineCommandOutbox: false;
+    constructor(factory: ReplicaIndexedDbFactory, databaseName: string, policy: NormalizedPolicy);
+    save(state: ReplicaDehydratedState): Promise<boolean>;
+    restore(authoritativeScope: ReplicaAuthoritativeScope): Promise<ReplicaDehydratedState | undefined>;
+    discard(authoritativeScope: ReplicaAuthoritativeScope): Promise<void>;
+    close(): void;
+}
+/**
+ * Create opt-in confirmed-state persistence. Merely creating a replica never
+ * opens IndexedDB; applications must explicitly create and call this adapter.
+ */
+export declare function createReplicaIndexedDbPersistence(options?: ReplicaIndexedDbPersistenceOptions): ReplicaIndexedDbPersistence;
+export declare function openDatabase(factory: ReplicaIndexedDbFactory, name: string): Promise<IDBDatabase>;
+export declare function requestResult<T>(request: IDBRequest<T>): Promise<T>;
+export declare function transactionResult(transaction: IDBTransaction): Promise<void>;

package/dist/replica/persistence/idb.js

@@ -0,0 +1,193 @@
+import { DATABASE_VERSION, DEFAULT_DATABASE_NAME, STORE_NAME, filterReplicaState, normalizePolicy, parseAuthoritativeScope, parseReplicaState, parseStoredEntry, persistenceIdentity, sameScope } from './state.js';
+export class IndexedDbConfirmedStatePersistence {
+    supportsOfflineCommandOutbox = false;
+    #factory;
+    #databaseName;
+    #policy;
+    #databasePromise;
+    #closed = false;
+    constructor(factory, databaseName, policy) {
+        this.#factory = factory;
+        this.#databaseName = databaseName;
+        this.#policy = policy;
+    }
+    async save(state) {
+        this.#assertOpen();
+        const parsed = parseReplicaState(state);
+        const filtered = filterReplicaState(parsed, this.#policy);
+        const identity = persistenceIdentity(parsed.scope);
+        if (filtered === undefined) {
+            // A newly restrictive policy must not leave a previously durable copy.
+            await this.#delete(identity);
+            return false;
+        }
+        const entry = Object.freeze({
+            formatVersion: 1,
+            identity,
+            storedAt: Date.now(),
+            state: filtered
+        });
+        await this.#write(entry);
+        return true;
+    }
+    async restore(authoritativeScope) {
+        this.#assertOpen();
+        const scope = parseAuthoritativeScope(authoritativeScope);
+        const identity = persistenceIdentity(scope);
+        const raw = await this.#read(identity);
+        if (raw === undefined)
+            return undefined;
+        try {
+            const entry = parseStoredEntry(raw);
+            const parsed = parseReplicaState(entry.state);
+            if (entry.identity !== identity ||
+                !sameScope(parsed.scope, scope)) {
+                throw new TypeError('persisted replica scope does not match its key');
+            }
+            const filtered = filterReplicaState(parsed, this.#policy);
+            if (filtered === undefined) {
+                await this.#delete(identity);
+                return undefined;
+            }
+            // Reapply the current policy to the durable copy as well as the value
+            // returned to memory. This removes data made memory-only by a newer
+            // manifest instead of leaving it at rest under an older policy.
+            await this.#write(Object.freeze({
+                formatVersion: 1,
+                identity,
+                storedAt: entry.storedAt,
+                state: filtered
+            }));
+            return filtered;
+        }
+        catch {
+            // Never consume a questionable snapshot. Deletion is best-effort so an
+            // IndexedDB failure cannot turn corrupt data into accepted state.
+            try {
+                await this.#delete(identity);
+            }
+            catch {
+                // A later restore will reject the same entry again.
+            }
+            return undefined;
+        }
+    }
+    async discard(authoritativeScope) {
+        this.#assertOpen();
+        await this.#delete(persistenceIdentity(parseAuthoritativeScope(authoritativeScope)));
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        const pending = this.#databasePromise;
+        if (pending !== undefined) {
+            void pending.then((database) => database.close(), () => undefined);
+        }
+    }
+    async #read(identity) {
+        return this.#transaction('readonly', (store) => requestResult(store.get(identity)));
+    }
+    async #write(entry) {
+        await this.#transaction('readwrite', async (store) => {
+            await requestResult(store.put(entry));
+        });
+    }
+    async #delete(identity) {
+        await this.#transaction('readwrite', async (store) => {
+            await requestResult(store.delete(identity));
+        });
+    }
+    async #transaction(mode, operation) {
+        const database = await this.#database();
+        this.#assertOpen();
+        const transaction = database.transaction(STORE_NAME, mode);
+        const completion = transactionResult(transaction);
+        try {
+            const result = await operation(transaction.objectStore(STORE_NAME));
+            await completion;
+            return result;
+        }
+        catch (error) {
+            try {
+                transaction.abort();
+            }
+            catch {
+                // It may already have completed or aborted.
+            }
+            await completion.catch(() => undefined);
+            throw error;
+        }
+    }
+    #database() {
+        this.#assertOpen();
+        this.#databasePromise ??= openDatabase(this.#factory, this.#databaseName);
+        return this.#databasePromise;
+    }
+    #assertOpen() {
+        if (this.#closed) {
+            throw new Error('replica IndexedDB persistence is closed');
+        }
+    }
+}
+/**
+ * Create opt-in confirmed-state persistence. Merely creating a replica never
+ * opens IndexedDB; applications must explicitly create and call this adapter.
+ */
+export function createReplicaIndexedDbPersistence(options = {}) {
+    const factory = options.indexedDB ??
+        globalThis.indexedDB;
+    if (factory === undefined || typeof factory.open !== 'function') {
+        throw new TypeError('IndexedDB is unavailable in this runtime');
+    }
+    const databaseName = options.databaseName ?? DEFAULT_DATABASE_NAME;
+    if (typeof databaseName !== 'string' || databaseName.length === 0) {
+        throw new TypeError('replica persistence databaseName must be non-empty');
+    }
+    return new IndexedDbConfirmedStatePersistence(factory, databaseName, normalizePolicy(options.policy));
+}
+export function openDatabase(factory, name) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const request = factory.open(name, DATABASE_VERSION);
+        request.onupgradeneeded = () => {
+            const database = request.result;
+            if (!database.objectStoreNames.contains(STORE_NAME)) {
+                database.createObjectStore(STORE_NAME, { keyPath: 'identity' });
+            }
+        };
+        request.onsuccess = () => {
+            if (settled) {
+                request.result.close();
+                return;
+            }
+            settled = true;
+            resolve(request.result);
+        };
+        request.onerror = () => {
+            if (settled)
+                return;
+            settled = true;
+            reject(request.error ?? new Error('failed to open replica IndexedDB'));
+        };
+        request.onblocked = () => {
+            if (settled)
+                return;
+            settled = true;
+            reject(new Error('replica IndexedDB upgrade is blocked'));
+        };
+    });
+}
+export function requestResult(request) {
+    return new Promise((resolve, reject) => {
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error ?? new Error('replica IndexedDB request failed'));
+    });
+}
+export function transactionResult(transaction) {
+    return new Promise((resolve, reject) => {
+        transaction.oncomplete = () => resolve();
+        transaction.onabort = () => reject(transaction.error ?? new Error('replica IndexedDB transaction aborted'));
+        transaction.onerror = () => reject(transaction.error ?? new Error('replica IndexedDB transaction failed'));
+    });
+}

package/dist/replica/persistence/implementation.d.ts

@@ -0,0 +1,4 @@
+/** Re-export surface for persistence modules (body-split). */
+export * from './types.js';
+export * from './state.js';
+export * from './idb.js';

package/dist/replica/persistence/implementation.js

@@ -0,0 +1,4 @@
+/** Re-export surface for persistence modules (body-split). */
+export * from './types.js';
+export * from './state.js';
+export * from './idb.js';

package/dist/replica/persistence/index.d.ts

@@ -0,0 +1,2 @@
+export { createReplicaIndexedDbPersistence, REPLICA_OFFLINE_COMMAND_OUTBOX_SUPPORTED } from './implementation.js';
+export type { ReplicaIndexedDbFactory, ReplicaIndexedDbPersistence, ReplicaIndexedDbPersistenceOptions, ReplicaPersistenceModelPolicy, ReplicaPersistencePolicy } from './implementation.js';

package/dist/replica/persistence/index.js

@@ -0,0 +1 @@
+export { createReplicaIndexedDbPersistence, REPLICA_OFFLINE_COMMAND_OUTBOX_SUPPORTED } from './implementation.js';

package/dist/replica/persistence/state.d.ts

@@ -0,0 +1,104 @@
+import { type CacheEngineSnapshot, type RecordLink } from '../../internal/cache-engine.js';
+import { type DistributedTrustedPreset } from '../../protocol.js';
+import type { ReplicaAuthoritativeScope, ReplicaDehydratedState } from '../types.js';
+import type { ReplicaPersistenceModelPolicy, ReplicaPersistencePolicy } from './types.js';
+export declare const DATABASE_VERSION = 1;
+export declare const ENTRY_FORMAT_VERSION = 1;
+export declare const STORE_NAME = "confirmed-replicas";
+export declare const DEFAULT_DATABASE_NAME = "@hops-ops/distributed:replica";
+export declare const GRAPHQL_NAME: RegExp;
+export declare const DECIMAL: RegExp;
+export type RecordClockV1 = {
+    readonly scopeToken: string;
+    readonly incarnation: string;
+    readonly revision: string;
+    readonly tombstone: boolean;
+};
+export type AnonymousRecordClockV1 = {
+    readonly model: string;
+    readonly clock: RecordClockV1;
+};
+export type OperationProtocolStateV1 = {
+    readonly operation: string;
+    readonly snapshotScope?: string;
+    readonly indexClocks: readonly (readonly [
+        string,
+        Readonly<{
+            scopeToken: string;
+            position: string;
+        }>
+    ])[];
+    readonly indexRevision?: string;
+    readonly indexKeys: readonly string[];
+    readonly pathRecords: readonly (readonly [string, string])[];
+    readonly cursors: readonly Readonly<{
+        projection: string;
+        position: string;
+        token: string;
+    }>[];
+};
+export type OperationProtocolGroupV1 = {
+    readonly key: string;
+    readonly query?: OperationProtocolStateV1;
+    readonly live?: OperationProtocolStateV1;
+    readonly active?: 'query' | 'live';
+    readonly generation: number;
+};
+export type ReplicaPersistencePayloadV1 = {
+    readonly cache: CacheEngineSnapshot;
+    readonly operations: readonly OperationProtocolGroupV1[];
+    readonly recordClocks: readonly (readonly [string, RecordClockV1])[];
+    readonly anonymousRecordClocks: readonly (readonly [
+        string,
+        AnonymousRecordClockV1
+    ])[];
+    readonly trustedPresets: readonly DistributedTrustedPreset[];
+    readonly nextIndexRevision: string;
+};
+export type ParsedReplicaState = {
+    readonly state: ReplicaDehydratedState;
+    readonly scope: ReplicaAuthoritativeScope;
+    readonly payload: ReplicaPersistencePayloadV1;
+};
+export type StoredReplicaEntry = {
+    readonly formatVersion: 1;
+    readonly identity: string;
+    readonly storedAt: number;
+    readonly state: ReplicaDehydratedState;
+};
+export type NormalizedPolicy = ReadonlyMap<string, ReplicaPersistenceModelPolicy>;
+export declare function normalizePolicy(policy: ReplicaPersistencePolicy | undefined): NormalizedPolicy;
+export declare function filterReplicaState(parsed: ParsedReplicaState, policy: NormalizedPolicy): ReplicaDehydratedState | undefined;
+export declare function operationStateAllowed(state: OperationProtocolStateV1, indexes: ReadonlyMap<string, CacheEngineSnapshot['indexes'][number]>, recordClockKeys: ReadonlySet<string>, allowedRecord: (key: string) => boolean): boolean;
+export declare function indexesProvenByOperations(candidates: ReadonlyMap<string, CacheEngineSnapshot['indexes'][number]>, states: Iterable<OperationProtocolStateV1>): Set<string>;
+export declare function linkReferencesOnly(link: RecordLink, allowedLiveRecordKeys: ReadonlySet<string>): boolean;
+export declare function parseReplicaState(value: unknown): ParsedReplicaState;
+export declare function parseAuthoritativeScope(value: unknown): ReplicaAuthoritativeScope;
+export declare function parseCacheSnapshot(value: unknown): CacheEngineSnapshot;
+export declare function canonicalCacheSnapshot(value: CacheEngineSnapshot): CacheEngineSnapshot;
+export declare function assertIndexMetadata(value: unknown, path: string): void;
+export declare function assertCoverage(value: unknown, path: string): void;
+export declare function parseOperations(value: unknown): readonly OperationProtocolGroupV1[];
+export declare function parseOperationState(value: unknown, path: string): OperationProtocolStateV1;
+export declare function parseRecordClocks(value: unknown): readonly (readonly [string, RecordClockV1])[];
+export declare function parseAnonymousRecordClocks(value: unknown, recordClocks: readonly (readonly [string, RecordClockV1])[]): readonly (readonly [string, AnonymousRecordClockV1])[];
+export declare function parseRecordClock(value: unknown, path: string): RecordClockV1;
+export declare function assertMetadataConsistent(payload: ReplicaPersistencePayloadV1): void;
+export declare function parseStoredEntry(value: unknown): StoredReplicaEntry;
+export declare function persistenceIdentity(scope: ReplicaAuthoritativeScope): string;
+export declare function sameScope(left: ReplicaAuthoritativeScope, right: ReplicaAuthoritativeScope): boolean;
+export declare function modelFromRecordKey(key: string): string | undefined;
+export declare function parseUniquePairs<T>(value: unknown, path: string, parseValue: (value: unknown, path: string) => T): readonly (readonly [string, T])[];
+export declare function uniqueStrings(value: unknown, path: string): readonly string[];
+export declare function assertRecordLink(value: unknown, path: string): void;
+export declare function assertJsonValue(value: unknown, path: string, ancestors?: Set<object>): void;
+export declare function exactRecord(value: unknown, path: string, allowed: readonly string[], required?: readonly string[]): Record<string, unknown>;
+export declare function exactKeys(record: Record<string, unknown>, path: string, allowed: readonly string[], required?: readonly string[]): void;
+export declare function plainRecord(value: unknown, path: string): Record<string, unknown>;
+export declare function arrayValue(value: unknown, path: string): unknown[];
+export declare function nonEmptyString(value: unknown, path: string): string;
+export declare function decimalString(value: unknown, path: string): string;
+export declare function booleanValue(value: unknown, path: string): boolean;
+export declare function operationSource(value: unknown, path: string): 'query' | 'live';
+export declare function nonNegativeInteger(value: unknown, path: string): number;
+export declare function compareDecimal(left: string, right: string): -1 | 0 | 1;