@hops-ops/distributed 0.0.0

package/dist/replica/distributed-replica/helpers.js

@@ -0,0 +1,445 @@
+import {} from '../../internal/cache-engine.js';
+import { isDistributedTrustedPresetCodec } from '../../protocol.js';
+import { canonicalVariables, cloneJsonValue, replicaIndexKey, replicaRecordKey, resolveArguments } from '../identity.js';
+import {} from '../index-maintenance.js';
+import { validateReplicaOperationBinding as validatedArtifactBinding } from '../operation-binding.js';
+import { embeddedRecordKey, runtimeRoot } from '../selection.js';
+import { deepEqual, modelFromRecordKey, protocolInvalid, responsePathKey } from './clocks.js';
+import { EMPTY_ERRORS, SHA256 } from './constants.js';
+import { reportSafely, reportUnhandledError } from '../../lib/report.js';
+export { deepEqual } from './clocks.js';
+export function prepareRecordEvidence(snapshot, commandRecords) {
+    const byPath = new Map();
+    const tombstones = [];
+    const pathless = [];
+    const livePaths = new Set();
+    for (const evidence of snapshot.records) {
+        if (evidence.path === undefined) {
+            if (evidence.tombstone)
+                tombstones.push(evidence);
+            else
+                pathless.push(evidence);
+            continue;
+        }
+        const key = responsePathKey(evidence.path);
+        if (byPath.has(key)) {
+            protocolInvalid('extensions.distributed.snapshot.records.path');
+        }
+        byPath.set(key, evidence);
+        if (evidence.tombstone)
+            tombstones.push(evidence);
+        else
+            livePaths.add(key);
+    }
+    for (const evidence of commandRecords) {
+        if (evidence.tombstone)
+            tombstones.push(evidence);
+        else
+            pathless.push(evidence);
+    }
+    return {
+        byPath,
+        tombstones: Object.freeze(tombstones),
+        pathless: Object.freeze(pathless),
+        livePaths
+    };
+}
+export function replicaResultIndexKeys(artifact, variables, envelope, snapshot) {
+    const keys = new Set();
+    if (envelope.data === undefined ||
+        envelope.data === null ||
+        !isReplicaResultObject(envelope.data) ||
+        (envelope.errors ?? []).some((error) => !Array.isArray(error.path) || error.path.length === 0)) {
+        return keys;
+    }
+    const errorPaths = (envelope.errors ?? []).flatMap((error) => Array.isArray(error.path) && error.path.length > 0
+        ? [error.path]
+        : []);
+    const evidencePaths = new Set(snapshot.records.flatMap((record) => record.path === undefined || record.tombstone
+        ? []
+        : [responsePathKey(record.path)]));
+    for (const artifactRoot of artifact.roots) {
+        const root = runtimeRoot(artifactRoot);
+        const rootPath = [root.responseKey];
+        const rootKey = replicaIndexKey({
+            field: root.field,
+            arguments: resolveArguments(root.arguments, variables, root.coverage)
+        });
+        keys.add(rootKey);
+        if (resultPathBlocked(errorPaths, rootPath) ||
+            !Object.prototype.hasOwnProperty.call(envelope.data, root.responseKey)) {
+            continue;
+        }
+        const value = envelope.data[root.responseKey];
+        if (value === null &&
+            resultPathHasErrors(errorPaths, rootPath)) {
+            continue;
+        }
+        collectResultBranchIndexKeys(artifact.id, root, value, rootPath, rootKey, variables, errorPaths, evidencePaths, keys);
+    }
+    return keys;
+}
+export function collectResultBranchIndexKeys(artifactId, selection, value, path, enclosingIndexKey, variables, errorPaths, evidencePaths, keys) {
+    if (value === null || value === undefined)
+        return;
+    if (selection.cardinality === 'one') {
+        collectResultObjectIndexKeys(artifactId, selection.selection, value, path, enclosingIndexKey, undefined, variables, errorPaths, evidencePaths, keys);
+        return;
+    }
+    if (!Array.isArray(value))
+        return;
+    for (const [ordinal, entry] of value.entries()) {
+        if (entry === null || entry === undefined)
+            continue;
+        collectResultObjectIndexKeys(artifactId, selection.selection, entry, [...path, ordinal], enclosingIndexKey, ordinal, variables, errorPaths, evidencePaths, keys);
+    }
+}
+export function collectResultObjectIndexKeys(artifactId, selection, value, path, enclosingIndexKey, ordinal, variables, errorPaths, evidencePaths, keys) {
+    if (resultPathBlocked(errorPaths, path) || !isReplicaResultObject(value)) {
+        return;
+    }
+    const fields = new Map();
+    for (const member of selection.members) {
+        if (member.kind !== 'scalar')
+            continue;
+        const fieldPath = [...path, member.responseKey];
+        if (resultPathBlocked(errorPaths, fieldPath) ||
+            !Object.prototype.hasOwnProperty.call(value, member.responseKey)) {
+            continue;
+        }
+        const rawValue = value[member.responseKey];
+        if (rawValue === null && !member.nullable)
+            continue;
+        if (!fields.has(member.field)) {
+            fields.set(member.field, cloneJsonValue(rawValue));
+        }
+    }
+    let parentKey;
+    if (selection.storage.kind === 'normalized' &&
+        evidencePaths.has(responsePathKey(path.map(String)))) {
+        const identity = selection.storage.identityFields.flatMap((field) => {
+            const value = fields.get(field);
+            return value === undefined || value === null ? [] : [value];
+        });
+        if (identity.length !== selection.storage.identityFields.length)
+            return;
+        parentKey = replicaRecordKey({
+            id: selection.storage.model,
+            identityFields: selection.storage.identityFields
+        }, identity);
+    }
+    else {
+        parentKey = embeddedRecordKey(artifactId, enclosingIndexKey, ordinal);
+    }
+    for (const member of selection.members) {
+        if (member.kind !== 'branch')
+            continue;
+        const branchPath = [...path, member.responseKey];
+        const branchKey = replicaIndexKey({
+            parent: parentKey,
+            field: member.field,
+            arguments: resolveArguments(member.arguments, variables, member.coverage)
+        });
+        keys.add(branchKey);
+        if (resultPathBlocked(errorPaths, branchPath) ||
+            !Object.prototype.hasOwnProperty.call(value, member.responseKey)) {
+            continue;
+        }
+        const branchValue = value[member.responseKey];
+        if (branchValue === null &&
+            resultPathHasErrors(errorPaths, branchPath)) {
+            continue;
+        }
+        collectResultBranchIndexKeys(artifactId, member, branchValue, branchPath, branchKey, variables, errorPaths, evidencePaths, keys);
+    }
+}
+export function resultPathBlocked(errorPaths, path) {
+    return errorPaths.some((errorPath) => resultPathPrefix(errorPath, path));
+}
+export function resultPathHasErrors(errorPaths, path) {
+    return errorPaths.some((errorPath) => resultPathPrefix(path, errorPath) ||
+        resultPathPrefix(errorPath, path));
+}
+export function resultPathPrefix(prefix, value) {
+    return (prefix.length <= value.length &&
+        prefix.every((entry, index) => entry === value[index]));
+}
+export function isReplicaResultObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function indexMaintenanceSnapshot(confirmed) {
+    return Object.freeze({
+        records: Object.freeze(confirmed.records.flatMap((record) => {
+            if (record.tombstoneRevision !== undefined)
+                return [];
+            const model = modelFromRecordKey(record.key);
+            if (model === undefined)
+                return [];
+            return [
+                Object.freeze({
+                    key: record.key,
+                    model,
+                    fields: Object.freeze(Object.fromEntries(Object.entries(record.fields).map(([name, field]) => [
+                        name,
+                        field.value
+                    ])))
+                })
+            ];
+        })),
+        indexes: Object.freeze(confirmed.indexes.flatMap((index) => {
+            if (index.deleted || index.metadata === undefined)
+                return [];
+            return [
+                Object.freeze({
+                    key: index.key,
+                    records: index.records,
+                    complete: index.complete,
+                    metadata: index.metadata
+                })
+            ];
+        }))
+    });
+}
+export function indexSemanticLayer(layer) {
+    const context = layer.context;
+    if (context === null ||
+        Array.isArray(context) ||
+        typeof context !== 'object') {
+        throw new TypeError(`optimistic layer ${layer.id} has invalid index-maintenance context`);
+    }
+    const record = context;
+    if (record.id !== layer.id || !Array.isArray(record.changes)) {
+        throw new TypeError(`optimistic layer ${layer.id} has invalid index-maintenance context`);
+    }
+    return Object.freeze({
+        id: layer.id,
+        changes: record.changes
+    });
+}
+export function baseWriter(writer) {
+    return Object.freeze({
+        writeRecord(model, identity, revision, patch) {
+            return writer.writeRecord({
+                key: replicaRecordKey(model, identity),
+                revision,
+                ...patch
+            });
+        },
+        tombstoneRecord(model, identity, revision) {
+            return writer.tombstoneRecord(replicaRecordKey(model, identity), revision);
+        },
+        writeIndex(target, records, revision) {
+            return writer.writeIndex({
+                key: indexKeyFromTarget(target),
+                revision,
+                records,
+                complete: target.complete ?? false,
+                metadata: metadataFromTarget(target)
+            });
+        },
+        deleteIndex(target, revision) {
+            return writer.deleteIndex(indexKeyFromTarget(target), revision);
+        }
+    });
+}
+export function metadataFromTarget(target) {
+    const dependencies = [...new Set(target.dependencies ?? [])].sort();
+    return Object.freeze({
+        ...(target.parent === undefined ? {} : { parent: target.parent }),
+        field: target.field,
+        arguments: target.arguments ?? Object.freeze({}),
+        coverage: target.coverage ?? { kind: 'unknown' },
+        dependencies: Object.freeze(dependencies),
+        ...(target.staleReason === undefined ? {} : { staleReason: target.staleReason }),
+        ...(target.nullValue === undefined ? {} : { nullValue: target.nullValue })
+    });
+}
+export function indexKeyFromTarget(target) {
+    return replicaIndexKey({
+        ...(target.parent === undefined ? {} : { parent: target.parent }),
+        field: target.field,
+        arguments: target.arguments ?? {}
+    });
+}
+export function replicaClientRequestExtensions(artifact) {
+    validatedArtifactBinding(artifact);
+    const protocol = artifact.protocol;
+    const surface = protocol.surface.kind === 'role'
+        ? Object.freeze({
+            kind: 'role',
+            name: protocol.surface.name
+        })
+        : Object.freeze({
+            kind: 'application',
+            name: protocol.surface.name,
+            roles: Object.freeze([...protocol.surface.roles])
+        });
+    return Object.freeze({
+        extensions: Object.freeze({
+            distributed: Object.freeze({
+                client: Object.freeze({
+                    surface,
+                    schemaHash: protocol.schemaHash
+                })
+            })
+        })
+    });
+}
+export function validatedCommandAuthorityContract(value) {
+    if (value === null ||
+        typeof value !== 'object' ||
+        value.protocolVersion !== 1 ||
+        typeof value.schemaHash !== 'string' ||
+        !SHA256.test(value.schemaHash) ||
+        typeof value.protocolHash !== 'string' ||
+        !SHA256.test(value.protocolHash) ||
+        !Array.isArray(value.trustedPresets)) {
+        throw new TypeError('replica command authority contract is invalid');
+    }
+    const surfaceIdentity = validatedSurfaceIdentity(value.surface);
+    const names = new Set();
+    const trustedPresets = Object.freeze(value.trustedPresets
+        .map((descriptor) => {
+        if (descriptor === null ||
+            typeof descriptor !== 'object' ||
+            typeof descriptor.name !== 'string' ||
+            descriptor.name.length === 0 ||
+            descriptor.name.length > 128 ||
+            descriptor.name.trim() !== descriptor.name ||
+            /[\u0000-\u001f\u007f-\u009f]/.test(descriptor.name) ||
+            names.has(descriptor.name) ||
+            !isDistributedTrustedPresetCodec(descriptor.codec)) {
+            throw new TypeError('replica command trusted preset contract is invalid');
+        }
+        names.add(descriptor.name);
+        return Object.freeze({
+            name: descriptor.name,
+            codec: descriptor.codec
+        });
+    })
+        .sort(({ name: left }, { name: right }) => left < right ? -1 : left > right ? 1 : 0));
+    const fingerprint = JSON.stringify([
+        2,
+        value.schemaHash,
+        value.protocolHash,
+        surfaceIdentity,
+        trustedPresets
+    ]);
+    return Object.freeze({
+        schemaHash: value.schemaHash,
+        protocolHash: value.protocolHash,
+        surfaceIdentity,
+        trustedPresets,
+        fingerprint
+    });
+}
+export function canonicalTrustedPresets(value) {
+    return Object.freeze([...value].sort(({ name: left }, { name: right }) => left < right ? -1 : left > right ? 1 : 0));
+}
+export function trustedPresetInventoryFingerprint(value) {
+    return JSON.stringify(canonicalTrustedPresets(value));
+}
+export function trustedPresetDescriptorFingerprint(value) {
+    return JSON.stringify(value);
+}
+export function operationKey(artifact, variables) {
+    const binding = validatedArtifactBinding(artifact);
+    const artifactIdentity = JSON.stringify([
+        binding.version,
+        binding.schemaHash,
+        binding.surfaceIdentity,
+        binding.operation,
+        artifact.id
+    ]);
+    return `protocol:${artifactIdentity}:${canonicalVariables(variables)}`;
+}
+export function validatedSurfaceIdentity(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]);
+}
+export function snapshotFrom(materialized, state) {
+    const status = state.errors.length > 0
+        ? 'error'
+        : materialized.stale
+            ? 'stale'
+            : materialized.complete
+                ? 'ready'
+                : 'loading';
+    const snapshot = Object.freeze({
+        data: materialized.data,
+        status,
+        fetching: state.fetching,
+        stale: materialized.stale,
+        complete: materialized.complete,
+        errors: state.errors,
+        live: state.live
+    });
+    // `materializeReplicaOperation` only reports complete after every generated
+    // selection is present; that runtime invariant is what promotes sparse data
+    // to the generated result type in ReplicaSnapshot's discriminated union.
+    return snapshot;
+}
+export function snapshotEqual(left, right) {
+    return (left.data === right.data &&
+        left.status === right.status &&
+        left.fetching === right.fetching &&
+        left.stale === right.stale &&
+        left.complete === right.complete &&
+        left.errors === right.errors &&
+        left.live === right.live);
+}
+export function freezeErrors(errors) {
+    if (errors.length === 0)
+        return EMPTY_ERRORS;
+    return Object.freeze(errors.map((error) => Object.freeze({
+        message: error.message,
+        ...(error.locations === undefined
+            ? {}
+            : {
+                locations: Object.freeze(error.locations.map((location) => Object.freeze({ ...location })))
+            }),
+        ...(error.path === undefined ? {} : { path: Object.freeze([...error.path]) }),
+        ...(error.extensions === undefined
+            ? {}
+            : {
+                extensions: cloneJsonValue(error.extensions)
+            })
+    })));
+}
+export function stableErrors(current, next) {
+    if (next.length === 0)
+        return EMPTY_ERRORS;
+    return deepEqual(current, next) ? current : freezeErrors(next);
+}
+export function graphqlError(error) {
+    return Object.freeze({
+        message: error instanceof Error ? error.message : String(error),
+        extensions: Object.freeze({ code: 'REPLICA_TRANSPORT' })
+    });
+}
+export function assertWriteSource(source) {
+    if (!['network', 'live', 'ssr', 'restore', 'projected'].includes(source)) {
+        throw new TypeError(`unsupported replica write source: ${source}`);
+    }
+}
+export function protocolOperationSource(source) {
+    return source === 'live' ? 'live' : 'query';
+}
+export { reportSafely };
+export const reportUnhandledObserverError = reportUnhandledError;

package/dist/replica/distributed-replica/hydration.d.ts

@@ -0,0 +1,19 @@
+import { type DistributedDecimalString, type DistributedOpaqueString } from '../../protocol.js';
+import type { OperationProtocolGroup, OperationProtocolSource, OperationProtocolState, ParsedReplicaHydration, ProtocolGeneration, RecordProtocolClock, SerializedOperationProtocolGroup, SerializedOperationProtocolState } from './types.js';
+export declare function serializeOperationProtocolGroup(key: string, group: OperationProtocolGroup, generation: number): SerializedOperationProtocolGroup;
+export declare function serializeOperationProtocolState(state: OperationProtocolState): SerializedOperationProtocolState;
+export declare function parseAuthoritativeScope(value: unknown): ProtocolGeneration | undefined;
+export declare function hydrationMetadataConsistent(parsed: ParsedReplicaHydration): boolean;
+export declare function parseReplicaHydration(value: unknown): ParsedReplicaHydration | undefined;
+export declare function parseOperationProtocolState(value: unknown, path: string): OperationProtocolState;
+export declare function parseRecordClock(value: unknown, path: string): RecordProtocolClock;
+export declare function hydrationRecord(value: unknown, path: string, allowed: readonly string[], required?: readonly string[]): Record<string, unknown>;
+export declare function isHydrationRecord(value: unknown): value is Record<string, unknown>;
+export declare function hydrationArray(value: unknown, path: string): unknown[];
+export declare function hydrationPair(value: unknown, path: string): readonly [unknown, unknown];
+export declare function hydrationString(value: unknown, path: string): string;
+export declare function hydrationOpaque(value: unknown, path: string): DistributedOpaqueString;
+export declare function hydrationDecimal(value: unknown, path: string): DistributedDecimalString;
+export declare function hydrationGeneration(value: unknown, path: string): number;
+export declare function hydrationOperationSource(value: unknown, path: string): OperationProtocolSource;
+export declare function hydrationInvalid(path: string): never;