@hops-ops/distributed 0.0.0

package/dist/replica/distributed-replica/impl-fetch-live.js

@@ -0,0 +1,395 @@
+import { CacheRevisionConflictError } from '../../internal/cache-engine.js';
+import { parseGraphqlResponseExtensions } from '../../protocol.js';
+import { graphqlError, replicaClientRequestExtensions, stableErrors } from './helpers.js';
+export function emitWatchState(host, key, allowFetch) {
+    for (const watch of host.watches.get(key) ?? [])
+        watch._stateChanged(allowFetch);
+}
+export function closeActiveTransports(host) {
+    for (const controller of host.inFlightAborts.values())
+        controller.abort();
+    host.inFlightAborts.clear();
+    for (const entry of host.lives.values()) {
+        entry.active = false;
+        try {
+            entry.unsubscribe();
+        }
+        catch {
+            // The generation fence is already closed; transport cleanup is best effort.
+        }
+    }
+    host.lives.clear();
+    host.inFlight.clear();
+}
+export function fetchWatch(host, watch, force) {
+    if (!host.transport)
+        return Promise.resolve();
+    if (!force && watch.materialized.complete && !watch.materialized.stale) {
+        if (host.diagnostics.enabled) {
+            host.diagnosticEvent(Object.freeze({
+                kind: 'revalidation',
+                operation: watch.artifact.id,
+                action: 'skipped-complete',
+                reason: 'watch'
+            }));
+        }
+        return Promise.resolve();
+    }
+    const existing = host.inFlight.get(watch.key);
+    if (existing) {
+        if (host.diagnostics.enabled) {
+            host.diagnosticEvent(Object.freeze({
+                kind: 'revalidation',
+                operation: watch.artifact.id,
+                action: 'deduplicated',
+                reason: force
+                    ? 'refresh'
+                    : watch.materialized.stale
+                        ? 'stale'
+                        : 'watch'
+            }));
+        }
+        return existing;
+    }
+    const state = host.queryState(watch.key);
+    if (host.diagnostics.enabled) {
+        host.diagnosticEvent(Object.freeze({
+            kind: 'revalidation',
+            operation: watch.artifact.id,
+            action: 'requested',
+            reason: force
+                ? 'refresh'
+                : watch.materialized.stale
+                    ? 'stale'
+                    : 'watch'
+        }));
+    }
+    state.fetching = true;
+    host.emitState(watch.key, false);
+    const operationGeneration = host.operationGeneration(watch.key);
+    const authorizationGeneration = host.protocolGenerationSequence();
+    const projectionGeneration = host.projectionGeneration();
+    /*
+     * Reserve local index ordering and the projection-fence generation when
+     * the request starts, not when it finishes. Distinct operation artifacts
+     * may share the same semantic index key; a slower earlier request must
+     * not replace a later-started result merely because its response arrived
+     * last, nor may it supersede a direct projection installed in between.
+     */
+    const requestRevision = host.allocateIndexRevision();
+    const controller = new AbortController();
+    const request = Object.freeze({
+        operation: 'query',
+        operationId: watch.artifact.id,
+        document: watch.artifact.document,
+        variables: watch.variables,
+        artifact: watch.artifact,
+        ...replicaClientRequestExtensions(watch.artifact),
+        signal: controller.signal
+    });
+    let flight;
+    flight = Promise.resolve()
+        .then(() => host.transport.fetch(request))
+        .then((result) => {
+        if (host.protocolGenerationSequence() !== authorizationGeneration) {
+            if (host.diagnostics.enabled) {
+                host.diagnosticEvent(Object.freeze({
+                    kind: 'response-fenced',
+                    operation: watch.artifact.id,
+                    transport: 'http',
+                    reason: 'authorization-generation'
+                }));
+            }
+            return;
+        }
+        if (host.inFlight.get(watch.key) !== flight) {
+            if (host.diagnostics.enabled) {
+                host.diagnosticEvent(Object.freeze({
+                    kind: 'response-fenced',
+                    operation: watch.artifact.id,
+                    transport: 'http',
+                    reason: 'superseded'
+                }));
+            }
+            return;
+        }
+        if (host.operationGeneration(watch.key) !== operationGeneration) {
+            if (host.diagnostics.enabled) {
+                host.diagnosticEvent(Object.freeze({
+                    kind: 'response-fenced',
+                    operation: watch.artifact.id,
+                    transport: 'http',
+                    reason: 'operation-generation'
+                }));
+            }
+            return;
+        }
+        host.writeCanonicalResult(watch.artifact, watch.variables, result, 'network', requestRevision, projectionGeneration);
+    })
+        .catch((error) => {
+        if (host.inFlight.get(watch.key) !== flight)
+            return;
+        if (controller.signal.aborted)
+            return;
+        state.errors = stableErrors(state.errors, [graphqlError(error)]);
+    })
+        .finally(() => {
+        if (host.inFlight.get(watch.key) !== flight)
+            return;
+        host.inFlight.delete(watch.key);
+        host.inFlightAborts.delete(watch.key);
+        state.fetching = false;
+        host.emitState(watch.key, false);
+    });
+    host.inFlight.set(watch.key, flight);
+    host.inFlightAborts.set(watch.key, controller);
+    return flight;
+}
+export function retainLive(host, watch) {
+    if (!watch.artifact.live || !host.transport?.subscribe)
+        return;
+    const existing = host.lives.get(watch.key);
+    if (existing) {
+        existing.count += 1;
+        return;
+    }
+    const state = host.queryState(watch.key);
+    state.live = 'connecting';
+    const entry = {
+        count: 1,
+        unsubscribe: () => undefined,
+        active: true,
+        protocolGeneration: host.protocolGenerationSequence()
+    };
+    host.lives.set(watch.key, entry);
+    const resume = host.resumeCursors(watch.key);
+    try {
+        const unsubscribe = host.transport.subscribe(Object.freeze({
+            operation: 'live',
+            operationId: watch.artifact.live.id,
+            document: watch.artifact.live.document,
+            variables: watch.variables,
+            artifact: watch.artifact,
+            ...replicaClientRequestExtensions(watch.artifact),
+            ...(resume === undefined || resume.length === 0
+                ? {}
+                : { resume })
+        }), {
+            next: (result) => {
+                // A live frame begins at this synchronous ingress boundary.
+                const projectionGeneration = host.projectionGeneration();
+                if (entry.protocolGeneration !== host.protocolGenerationSequence()) {
+                    if (host.diagnostics.enabled) {
+                        host.diagnosticEvent(Object.freeze({
+                            kind: 'response-fenced',
+                            operation: watch.artifact.live.id,
+                            transport: 'live',
+                            reason: 'authorization-generation'
+                        }));
+                    }
+                    return;
+                }
+                if (entry.operationGeneration !== undefined &&
+                    entry.operationGeneration !==
+                        host.operationGeneration(watch.key)) {
+                    if (host.diagnostics.enabled) {
+                        host.diagnosticEvent(Object.freeze({
+                            kind: 'response-fenced',
+                            operation: watch.artifact.live.id,
+                            transport: 'live',
+                            reason: 'operation-generation'
+                        }));
+                    }
+                    return;
+                }
+                if (!entry.active ||
+                    host.lives.get(watch.key) !== entry) {
+                    if (host.diagnostics.enabled) {
+                        host.diagnosticEvent(Object.freeze({
+                            kind: 'response-fenced',
+                            operation: watch.artifact.live.id,
+                            transport: 'live',
+                            reason: 'superseded'
+                        }));
+                    }
+                    return;
+                }
+                let unsupportedLive = false;
+                try {
+                    unsupportedLive =
+                        parseGraphqlResponseExtensions(result.extensions)
+                            ?.distributed?.live?.supported === false;
+                    if (unsupportedLive)
+                        state.live = 'off';
+                    const distributed = host.writeCanonicalResult(watch.artifact, watch.variables, result, 'live', undefined, projectionGeneration);
+                    if (distributed.live?.supported === false) {
+                        fallbackFromLive(host, watch, entry);
+                        return;
+                    }
+                    state.live = 'active';
+                    entry.operationGeneration =
+                        host.operationGeneration(watch.key);
+                }
+                catch (error) {
+                    if (unsupportedLive &&
+                        error instanceof CacheRevisionConflictError) {
+                        /*
+                         * Revision zero is shared by provisional fallbacks.
+                         * Another operation may already have filled the same
+                         * semantic index differently; HTTP remains authoritative.
+                         */
+                        fallbackFromLive(host, watch, entry);
+                        return;
+                    }
+                    state.live = 'error';
+                    state.errors = stableErrors(state.errors, [graphqlError(error)]);
+                    host.emitState(watch.key, false);
+                }
+            },
+            error: (error) => {
+                if (!entry.active || host.lives.get(watch.key) !== entry)
+                    return;
+                entry.active = false;
+                host.lives.delete(watch.key);
+                const unsub = entry.unsubscribe;
+                entry.unsubscribe = () => undefined;
+                try {
+                    unsub();
+                }
+                catch {
+                    // The terminal stream is fenced; cleanup is best effort.
+                }
+                state.live = 'error';
+                state.errors = stableErrors(state.errors, [graphqlError(error)]);
+                host.emitState(watch.key, false);
+            },
+            complete: () => {
+                if (!entry.active || host.lives.get(watch.key) !== entry)
+                    return;
+                fallbackFromLive(host, watch, entry);
+            }
+        });
+        entry.unsubscribe = unsubscribe;
+        if (!entry.active || host.lives.get(watch.key) !== entry) {
+            entry.unsubscribe = () => undefined;
+            try {
+                unsubscribe();
+            }
+            catch {
+                // A closed/superseded subscription is already fenced.
+            }
+            return;
+        }
+        state.live = 'active';
+    }
+    catch (error) {
+        entry.active = false;
+        host.lives.delete(watch.key);
+        state.live = 'error';
+        state.errors = stableErrors(state.errors, [graphqlError(error)]);
+    }
+    host.emitState(watch.key, false);
+}
+export function fallbackFromLive(host, watch, entry) {
+    if (host.lives.get(watch.key) !== entry) {
+        void fetchWatch(host, watch, true);
+        return;
+    }
+    const protocol = host.operationProtocols.get(watch.key);
+    if (protocol?.active === 'live')
+        protocol.active = undefined;
+    entry.active = false;
+    const unsubscribe = entry.unsubscribe;
+    entry.unsubscribe = () => undefined;
+    try {
+        unsubscribe();
+    }
+    catch {
+        // The inactive stream is fenced; transport cleanup is best effort.
+    }
+    const state = host.queryState(watch.key);
+    state.live = 'off';
+    host.emitState(watch.key, false);
+    const authorizationGeneration = host.protocolGenerationSequence();
+    const supersededFlight = entry.operationGeneration === undefined
+        ? undefined
+        : host.inFlight.get(watch.key);
+    const refresh = () => {
+        if (host.protocolGenerationSequence() !== authorizationGeneration ||
+            host.lives.get(watch.key) !== entry ||
+            entry.active) {
+            return;
+        }
+        void fetchWatch(host, watch, true);
+    };
+    /*
+     * Keep the inactive entry as an authorization-generation-scoped
+     * sentinel. Query ingestion calls resumeLiveWatches(); deleting this
+     * entry would otherwise reopen an unsupported or completed stream
+     * immediately. Authorization invalidation clears it and may retry.
+     *
+     * A supported live frame advances the operation generation. Any HTTP
+     * request that was already running is therefore doomed by its response
+     * fence; drain it before starting the authoritative fallback. A first
+     * unsupported frame never advances the generation, so its overlapping
+     * HTTP request remains valid and can be reused directly.
+     */
+    if (supersededFlight === undefined) {
+        refresh();
+    }
+    else {
+        void supersededFlight.then(refresh, refresh);
+    }
+}
+export function restartLive(host, key) {
+    const previous = host.lives.get(key);
+    if (previous === undefined)
+        return;
+    const count = previous.count;
+    previous.active = false;
+    host.lives.delete(key);
+    try {
+        previous.unsubscribe();
+    }
+    catch {
+        // The old generation is already fenced; cleanup is best effort.
+    }
+    const watch = [...(host.watches.get(key) ?? [])].find((candidate) => candidate.liveRequested);
+    if (watch === undefined) {
+        host.queryState(key).live = 'off';
+        return;
+    }
+    retainLive(host, watch);
+    const replacement = host.lives.get(key);
+    if (replacement !== undefined)
+        replacement.count = count;
+}
+export function resumeLiveWatches(host) {
+    if (host.protocolGeneration() === undefined)
+        return;
+    for (const [key, watches] of host.watches) {
+        if (host.lives.has(key))
+            continue;
+        const liveWatches = [...watches].filter((watch) => watch.liveRequested);
+        const first = liveWatches[0];
+        if (first === undefined)
+            continue;
+        retainLive(host, first);
+        const entry = host.lives.get(key);
+        if (entry !== undefined)
+            entry.count = liveWatches.length;
+    }
+}
+export function releaseLive(host, key) {
+    const entry = host.lives.get(key);
+    if (!entry)
+        return;
+    entry.count -= 1;
+    if (entry.count > 0)
+        return;
+    entry.active = false;
+    host.lives.delete(key);
+    entry.unsubscribe();
+    host.queryState(key).live = 'off';
+    host.emitState(key, false);
+}

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

@@ -0,0 +1,56 @@
+import { type CacheEngine, type CacheEngineSnapshot } from '../../internal/cache-engine.js';
+import type { DistributedOpaqueString, DistributedTrustedPreset } from '../../protocol.js';
+import type { ReplicaDiagnosticEventInput } from '../diagnostics.js';
+import type { ReplicaIndexPlanRegistration } from '../index-maintenance.js';
+import type { ReplicaAuthoritativeScope, ReplicaDehydratedState } from '../types.js';
+import type { AnonymousRecordProtocolClock, OperationProtocolGroup, OptimisticReceiptState, ProtocolGeneration, QueryState, RecordProtocolClock, RegisteredCommandAuthorityContract, RenderedOperation, ReplicaArtifactBinding } from './types.js';
+import type { ReplicaDiagnosticLayerInput } from '../diagnostics.js';
+/**
+ * Host for dehydrate / hydrate orchestration.
+ */
+export type HydrationHost = {
+    readonly engine: CacheEngine;
+    readonly operationProtocols: Map<string, OperationProtocolGroup>;
+    readonly operationGenerations: Map<string, number>;
+    readonly recordClocks: Map<string, RecordProtocolClock>;
+    readonly recordKeysByScope: Map<DistributedOpaqueString, string>;
+    readonly anonymousRecordClocks: Map<DistributedOpaqueString, AnonymousRecordProtocolClock>;
+    readonly optimisticReceipts: Map<string, OptimisticReceiptState>;
+    readonly diagnosticLayers: Map<string, ReplicaDiagnosticLayerInput> | undefined;
+    readonly renderedOperations: Map<string, RenderedOperation>;
+    readonly readOperationKeys: Set<string>;
+    readonly watchRenderCounts: Map<string, number>;
+    readonly indexPlanRegistrations: Map<string, ReplicaIndexPlanRegistration>;
+    readonly queryStates: Map<string, QueryState>;
+    readonly diagnostics: {
+        readonly enabled: boolean;
+    };
+    getProtocolGeneration(): ProtocolGeneration | undefined;
+    setProtocolGeneration(value: ProtocolGeneration | undefined): void;
+    getProtocolGenerationSequence(): number;
+    getTrustedPresets(): readonly DistributedTrustedPreset[];
+    setTrustedPresets(value: readonly DistributedTrustedPreset[]): void;
+    getNextIndexRevision(): string;
+    setNextIndexRevision(value: string): void;
+    getArtifactBinding(): ReplicaArtifactBinding | undefined;
+    setArtifactBinding(value: ReplicaArtifactBinding | undefined): void;
+    getCommandAuthorityContract(): RegisteredCommandAuthorityContract | undefined;
+    setDiagnosticLayerSequence(value: number): void;
+    operationGeneration(key: string): number;
+    closeActiveTransports(): void;
+    closeAuthorizationGeneration(): void;
+    resumeLiveWatches(): void;
+    syncDiagnostics(): void;
+    diagnosticEvent(event: ReplicaDiagnosticEventInput): void;
+    refreshIndexMaintenance(): void;
+    finishDehydration(): void;
+};
+export declare function reachableConfirmedState(host: HydrationHost): {
+    readonly cache: CacheEngineSnapshot;
+    readonly recordKeys: ReadonlySet<string>;
+    readonly clockRecordKeys: ReadonlySet<string>;
+    readonly models: ReadonlySet<string>;
+};
+export declare function finishDehydration(host: HydrationHost): void;
+export declare function dehydrateReplica(host: HydrationHost): ReplicaDehydratedState;
+export declare function hydrateReplica(host: HydrationHost, state: ReplicaDehydratedState, authoritativeScope: ReplicaAuthoritativeScope): boolean;