@hops-ops/distributed 0.0.0

package/dist/sveltekit/replica.js

@@ -0,0 +1,491 @@
+import { sameAuthCredential, snapshotAuthCredential } from '../identity.js';
+import { createDistributedReplica, createReplicaGraphqlTransport } from '../replica/index.js';
+import { replicaCommandProjectedLifecycleOf } from '../replica/command-runtime.js';
+import { authFromPageData } from './auth.js';
+/**
+ * Bind the framework-neutral replica to Svelte's readable-store lifecycle.
+ *
+ * Generated `$distributed` modules call this once, then export
+ * `client.operation(Operation_Todos)` and `client.commands`.
+ */
+export function createDistributedSvelteKit(options) {
+    if (options.session === null ||
+        typeof options.session !== 'object' ||
+        typeof options.session.getAuth !== 'function') {
+        throw new TypeError('Distributed SvelteKit requires one session source');
+    }
+    if ((options.hydration === undefined) !==
+        (options.authority === undefined)) {
+        throw new TypeError('Distributed SvelteKit hydration requires separate trusted SSR authority');
+    }
+    let replica;
+    const auth = createAuthorizationFence(options.session, () => replica?.invalidateAuthorization(), options.onAuthError);
+    const configuredUrl = options.url;
+    const transport = createReplicaGraphqlTransport({
+        getUrl: typeof configuredUrl === 'function'
+            ? configuredUrl
+            : () => configuredUrl ?? '/graphql',
+        getAuth: auth.read,
+        ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+        ...(options.webSocket === undefined
+            ? {}
+            : { webSocket: options.webSocket })
+    });
+    replica = createDistributedReplica({
+        transport,
+        ...(options.replica ?? {})
+    });
+    const stores = new Set();
+    const pending = new PendingReceiptStore();
+    let destroyed = false;
+    const hydrate = (hydration, authority) => {
+        let accepted = false;
+        try {
+            const expected = validatedHydrationAuthority(authority);
+            const active = replica.scope;
+            if (active !== undefined && !sameReplicaScope(active, expected)) {
+                throw new TypeError('Distributed SvelteKit hydration authority changed before session invalidation');
+            }
+            accepted =
+                hydration?.version === 1 &&
+                    replica.hydrate(hydration.state, expected);
+        }
+        catch {
+            accepted = false;
+        }
+        if (!accepted)
+            replica.invalidateAuthorization();
+        return accepted;
+    };
+    if (options.hydration !== undefined && options.authority !== undefined) {
+        hydrate(options.hydration, options.authority);
+    }
+    // Hydration must precede command authority registration: trusted presets are
+    // server-derived and restored only as part of an exact authoritative seed.
+    const commandRuntime = options.createCommands?.(replica, transport, Object.freeze({
+        ...(options.replica?.diagnostics === undefined
+            ? {}
+            : { diagnostics: options.replica.diagnostics })
+    }));
+    const commands = commandRuntime === undefined
+        ? Object.freeze({})
+        : wrapCommandTree(commandRuntime.commands, pending);
+    const operation = (artifact) => bindOperation(replica, artifact, pending, {
+        isAlive: () => !destroyed,
+        activateWatches: () => options.browser ?? true,
+        active: (store) => {
+            stores.add(store);
+        },
+        idle: (store) => {
+            stores.delete(store);
+        }
+    });
+    return Object.freeze({
+        replica,
+        transport,
+        commands,
+        operation,
+        hydrate,
+        invalidateAuthorization() {
+            if (!destroyed)
+                replica.invalidateAuthorization();
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            auth.dispose();
+            for (const store of [...stores])
+                store.destroy();
+            stores.clear();
+            pending.clear();
+            commandRuntime?.dispose();
+        }
+    });
+}
+/**
+ * Low-level composition seam for applications that already own a replica.
+ *
+ * Most SvelteKit applications use `createDistributedSvelteKit().operation()`;
+ * this form exists for custom composition and framework adapter conformance.
+ */
+export function bindSveltekitOperation(replica, artifact) {
+    return bindOperation(replica, artifact, new PendingReceiptStore(), {
+        isAlive: () => true,
+        activateWatches: () => true,
+        active: () => undefined,
+        idle: () => undefined
+    });
+}
+/** Map SvelteKit page data into the one shared transport/session source. */
+export function sessionSourceFromPageData(source) {
+    if (source === null ||
+        typeof source !== 'object' ||
+        typeof source.get !== 'function') {
+        throw new TypeError('page-data session source requires get');
+    }
+    return Object.freeze({
+        getAuth: () => authFromPageData(source.get()),
+        ...(source.subscribe === undefined
+            ? {}
+            : { subscribe: source.subscribe.bind(source) })
+    });
+}
+/**
+ * Create the single mutable page-data/session source owned by one layout.
+ *
+ * HTTP, WebSocket reconnects, commands, and authorization invalidation all
+ * observe `session`; navigation updates the same source through `set`.
+ */
+export function createPageDataSessionSource(initial) {
+    let current = initial;
+    const listeners = new Set();
+    const source = Object.freeze({
+        get() {
+            return current;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        }
+    });
+    return Object.freeze({
+        session: sessionSourceFromPageData(source),
+        get: source.get,
+        set(next) {
+            current = next;
+            for (const listener of [...listeners])
+                listener();
+        }
+    });
+}
+function bindOperation(replica, artifact, pending, lifecycle) {
+    const use = (...args) => {
+        const variables = (args[0] ?? {});
+        const useOptions = args[1];
+        const store = new SveltekitQueryStoreImpl(replica, artifact, variables, Object.freeze({
+            live: useOptions?.live ?? artifact.live !== undefined
+        }), pending, lifecycle);
+        return store;
+    };
+    return Object.freeze({
+        artifact,
+        use,
+        read: (variables) => replica.read(artifact, variables)
+    });
+}
+class SveltekitQueryStoreImpl {
+    #replica;
+    #artifact;
+    #variables;
+    #options;
+    #pending;
+    #lifecycle;
+    #listeners = new Set();
+    #watch;
+    #unsubscribeWatch;
+    #unsubscribePending;
+    #snapshot;
+    #destroyed = false;
+    constructor(replica, artifact, variables, options, pending, lifecycle) {
+        this.#replica = replica;
+        this.#artifact = artifact;
+        this.#variables = variables;
+        this.#options = options;
+        this.#pending = pending;
+        this.#lifecycle = lifecycle;
+        this.#snapshot = querySnapshot(replica.read(artifact, variables), pending.get(), () => this.refetch());
+    }
+    get() {
+        if (!this.#destroyed && this.#watch === undefined) {
+            this.#snapshot = querySnapshot(this.#replica.read(this.#artifact, this.#variables), this.#pending.get(), () => this.refetch());
+        }
+        return this.#snapshot;
+    }
+    subscribe(listener) {
+        if (this.#destroyed) {
+            throw new Error('Distributed SvelteKit query is destroyed');
+        }
+        if (typeof listener !== 'function') {
+            throw new TypeError('Distributed SvelteKit query listener must be a function');
+        }
+        if (!this.#lifecycle.isAlive()) {
+            throw new Error('Distributed SvelteKit client is destroyed');
+        }
+        if (this.#listeners.size === 0 &&
+            this.#lifecycle.activateWatches()) {
+            this.#activate();
+        }
+        this.#listeners.add(listener);
+        listener(this.#snapshot);
+        let active = true;
+        return () => {
+            if (!active)
+                return;
+            active = false;
+            this.#listeners.delete(listener);
+            if (this.#listeners.size === 0)
+                this.#deactivate();
+        };
+    }
+    async refetch() {
+        if (this.#destroyed) {
+            throw new Error('Distributed SvelteKit query is destroyed');
+        }
+        if (!this.#lifecycle.isAlive()) {
+            throw new Error('Distributed SvelteKit client is destroyed');
+        }
+        if (this.#watch !== undefined) {
+            await this.#watch.refresh();
+            return;
+        }
+        const temporary = this.#replica.watch(this.#artifact, this.#variables, { ...this.#options, live: false });
+        try {
+            await temporary.refresh();
+            this.#snapshot = querySnapshot(temporary.get(), this.#pending.get(), () => this.refetch());
+        }
+        finally {
+            temporary.destroy();
+        }
+    }
+    destroy() {
+        if (this.#destroyed)
+            return;
+        this.#destroyed = true;
+        this.#deactivate();
+        this.#listeners.clear();
+    }
+    get data() {
+        return this.#snapshot.data;
+    }
+    get status() {
+        return this.#snapshot.status;
+    }
+    get complete() {
+        return this.#snapshot.complete;
+    }
+    get loading() {
+        return this.#snapshot.loading;
+    }
+    get fetching() {
+        return this.#snapshot.fetching;
+    }
+    get stale() {
+        return this.#snapshot.stale;
+    }
+    get live() {
+        return this.#snapshot.live;
+    }
+    get errors() {
+        return this.#snapshot.errors;
+    }
+    get error() {
+        return this.#snapshot.error;
+    }
+    get pending() {
+        return this.#snapshot.pending;
+    }
+    #activate() {
+        let watch;
+        try {
+            watch = this.#replica.watch(this.#artifact, this.#variables, this.#options);
+            this.#watch = watch;
+            this.#snapshot = querySnapshot(watch.get(), this.#pending.get(), () => this.refetch());
+            this.#unsubscribeWatch = watch.subscribe((snapshot) => {
+                this.#publish(snapshot, this.#pending.get());
+            });
+            this.#unsubscribePending = this.#pending.subscribe((receipts) => {
+                const current = this.#watch;
+                if (current !== undefined)
+                    this.#publish(current.get(), receipts);
+            });
+            this.#lifecycle.active(this);
+        }
+        catch (error) {
+            this.#unsubscribeWatch?.();
+            this.#unsubscribePending?.();
+            watch?.destroy();
+            this.#watch = undefined;
+            this.#unsubscribeWatch = undefined;
+            this.#unsubscribePending = undefined;
+            throw error;
+        }
+    }
+    #deactivate() {
+        if (this.#watch === undefined)
+            return;
+        this.#unsubscribeWatch?.();
+        this.#unsubscribePending?.();
+        this.#watch.destroy();
+        this.#watch = undefined;
+        this.#unsubscribeWatch = undefined;
+        this.#unsubscribePending = undefined;
+        this.#lifecycle.idle(this);
+    }
+    #publish(replicaSnapshot, receipts) {
+        if (this.#destroyed)
+            return;
+        const next = querySnapshot(replicaSnapshot, receipts, () => this.refetch());
+        if (sameQuerySnapshot(this.#snapshot, next))
+            return;
+        this.#snapshot = next;
+        for (const listener of [...this.#listeners])
+            listener(next);
+    }
+}
+class PendingReceiptStore {
+    #receipts = new Map();
+    #listeners = new Set();
+    #snapshot = Object.freeze([]);
+    get() {
+        return this.#snapshot;
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    track(receipt) {
+        const lifecycle = replicaCommandProjectedLifecycleOf(receipt) ?? receipt.projected;
+        if (lifecycle === undefined || this.#receipts.has(receipt.commandId)) {
+            return;
+        }
+        this.#receipts.set(receipt.commandId, receipt);
+        this.#publish();
+        void lifecycle.then(() => this.#remove(receipt.commandId), () => this.#remove(receipt.commandId));
+    }
+    clear() {
+        if (this.#receipts.size === 0)
+            return;
+        this.#receipts.clear();
+        this.#publish();
+        this.#listeners.clear();
+    }
+    #remove(commandId) {
+        if (!this.#receipts.delete(commandId))
+            return;
+        this.#publish();
+    }
+    #publish() {
+        this.#snapshot = Object.freeze([...this.#receipts.values()]);
+        for (const listener of [...this.#listeners])
+            listener(this.#snapshot);
+    }
+}
+function wrapCommandTree(value, pending) {
+    if (typeof value === 'function') {
+        const command = value;
+        return ((...args) => {
+            const result = command(...args);
+            if (isPromiseLike(result)) {
+                return result.then((receipt) => {
+                    if (isCommandReceipt(receipt))
+                        pending.track(receipt);
+                    return receipt;
+                });
+            }
+            return result;
+        });
+    }
+    if (value === null || typeof value !== 'object')
+        return value;
+    const output = Object.create(null);
+    for (const key of Object.keys(value)) {
+        output[key] = wrapCommandTree(value[key], pending);
+    }
+    return Object.freeze(output);
+}
+function isCommandReceipt(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        typeof value.commandId === 'string' &&
+        typeof value.status === 'function');
+}
+function isPromiseLike(value) {
+    return (value !== null &&
+        (typeof value === 'object' || typeof value === 'function') &&
+        typeof value.then === 'function');
+}
+function querySnapshot(snapshot, pending, refetch) {
+    return Object.freeze({
+        ...snapshot,
+        loading: snapshot.fetching || snapshot.status === 'loading',
+        ...(snapshot.errors[0] === undefined
+            ? {}
+            : { error: snapshot.errors[0] }),
+        pending,
+        refetch
+    });
+}
+function sameQuerySnapshot(left, right) {
+    return (left.data === right.data &&
+        left.status === right.status &&
+        left.complete === right.complete &&
+        left.loading === right.loading &&
+        left.fetching === right.fetching &&
+        left.stale === right.stale &&
+        left.live === right.live &&
+        left.errors === right.errors &&
+        left.pending === right.pending);
+}
+function createAuthorizationFence(source, invalidate, onError) {
+    let current;
+    let queue = Promise.resolve();
+    let disposed = false;
+    const read = () => {
+        const candidate = Promise.resolve().then(() => source.getAuth());
+        const transition = queue.then(async () => {
+            try {
+                const next = snapshotAuthCredential(await candidate);
+                if (current !== undefined &&
+                    !sameAuthCredential(current, next)) {
+                    invalidate();
+                }
+                current = next;
+                return next;
+            }
+            catch (error) {
+                current = undefined;
+                invalidate();
+                throw error;
+            }
+        });
+        queue = transition.then(() => undefined, () => undefined);
+        return transition;
+    };
+    const unsubscribe = source.subscribe?.(() => {
+        if (disposed)
+            return;
+        void read().catch((error) => onError?.(error));
+    });
+    // Snapshot the bind-time credential so a later first request can fence a
+    // token refresh that retained the same unverified JWT subject.
+    void read().catch((error) => onError?.(error));
+    return Object.freeze({
+        read,
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            unsubscribe?.();
+        }
+    });
+}
+function validatedHydrationAuthority(value) {
+    const scope = value?.scope;
+    if (value?.version !== 1 ||
+        scope === null ||
+        typeof scope !== 'object' ||
+        scope.protocolVersion !== 1 ||
+        typeof scope.schemaHash !== 'string' ||
+        scope.schemaHash.length === 0 ||
+        typeof scope.cacheScope !== 'string' ||
+        scope.cacheScope.length === 0) {
+        throw new TypeError('Distributed SvelteKit hydration authority is invalid');
+    }
+    return scope;
+}
+function sameReplicaScope(left, right) {
+    return (left.protocolVersion === right.protocolVersion &&
+        left.schemaHash === right.schemaHash &&
+        left.cacheScope === right.cacheScope);
+}

package/dist/sveltekit/server-replica.d.ts

@@ -0,0 +1,52 @@
+import { type ReplicaOperationArtifact } from '../replica/index.js';
+import type { FetchLike } from '../request.js';
+import type { GqlAuth, GraphqlVariables } from '../types.js';
+import { type PageGraphqlData } from './auth.js';
+import type { SveltekitDistributedPageData } from './replica.js';
+export type DistributedRoutePlan = Readonly<{
+    operation: string;
+    route: string;
+    source_path?: string;
+    discovery: 'convention' | 'explicit';
+}>;
+export type DistributedRouteOperation = Readonly<{
+    plan: DistributedRoutePlan;
+    artifact: ReplicaOperationArtifact<unknown, GraphqlVariables>;
+}>;
+export type SveltekitServerLoadEventLike<TLocals = unknown> = Readonly<{
+    locals: TLocals;
+    route?: Readonly<{
+        id?: string | null;
+    }>;
+    url?: URL;
+    fetch?: FetchLike;
+}>;
+export type DistributedRouteVariables<TEvent extends SveltekitServerLoadEventLike> = Readonly<Record<string, (event: TEvent) => GraphqlVariables | Promise<GraphqlVariables>>>;
+export type CreateDistributedSvelteKitServerOptions<TSession extends NonNullable<PageGraphqlData['session']>, TEvent extends SveltekitServerLoadEventLike = SveltekitServerLoadEventLike> = Readonly<{
+    routes: readonly DistributedRouteOperation[];
+    getSession(event: TEvent): Promise<TSession | null>;
+    getRole(session: TSession | null, event: TEvent): string | null | undefined;
+    getAuth?(pageData: PageGraphqlData, event: TEvent): GqlAuth;
+    /** Private API origin or same-origin `/graphql`; defaults to `/graphql`. */
+    getUrl?(event: TEvent): string;
+    /** Variables for routed operations that do not accept `{}`. */
+    variables?: DistributedRouteVariables<TEvent>;
+}>;
+export type DistributedSvelteKitServer<TEvent> = Readonly<{
+    load(event: TEvent): Promise<SveltekitDistributedPageData & {
+        gqlError: string | null;
+    }>;
+}>;
+/**
+ * One app-level root layout loader for every compiler-discovered `@load`
+ * operation. Each invocation creates a fresh replica and never shares SSR data
+ * across requests.
+ */
+export declare function createDistributedSvelteKitServer<TSession extends NonNullable<PageGraphqlData['session']>, TEvent extends SveltekitServerLoadEventLike = SveltekitServerLoadEventLike>(options: CreateDistributedSvelteKitServerOptions<TSession, TEvent>): DistributedSvelteKitServer<TEvent>;
+/**
+ * Explicit one-line fallback when the compiler cannot discover route ownership.
+ *
+ * Prefer co-locating `+page.graphql`; the compiler diagnostic includes the
+ * equivalent `--route Operation=/route-id` registration.
+ */
+export declare function registerDistributedRoute<TData, TVariables extends GraphqlVariables>(route: string, operation: string, artifact: ReplicaOperationArtifact<TData, TVariables>): DistributedRouteOperation;