@hops-ops/distributed 4.8.0 → 4.10.0

package/dist/sveltekit/boundary-lifecycle.js

@@ -0,0 +1,355 @@
+import { boundaryOperationIdentity } from './operation-identity.js';
+const MAX_BOUNDARY_INSTANCES = 4_096;
+const MAX_INSTANCE_ID_BYTES = 512;
+const MAX_LOCATION_PATHNAME_BYTES = 8_192;
+const MAX_LOCATION_SEGMENTS = 256;
+export class DistributedSvelteKitBoundaryController {
+    #replica;
+    #operations;
+    #diagnostic;
+    #instances = new Map();
+    #identityOwners = new Map();
+    #destroyed = false;
+    constructor(replica, operations, diagnostic) {
+        this.#replica = replica;
+        this.#operations = operations;
+        this.#diagnostic = diagnostic;
+    }
+    retain(instance, context) {
+        if (this.#destroyed) {
+            throw new Error('Distributed SvelteKit boundary controller is destroyed');
+        }
+        const validated = validateInstance(instance);
+        const resolved = this.#resolve(validated, context);
+        const signature = JSON.stringify(resolved.map(({ identity }) => identity));
+        const existing = this.#instances.get(validated.id);
+        if (existing !== undefined) {
+            if (existing.signature !== signature ||
+                existing.boundary !== validated.boundary) {
+                throw new Error('Distributed SvelteKit boundary instance changed ownership while retained');
+            }
+            existing.owners += 1;
+            this.#emit({
+                action: 'retain',
+                boundary: existing.boundary,
+                owners: existing.owners
+            });
+            return this.#lease(validated.id, existing);
+        }
+        if (this.#instances.size >= MAX_BOUNDARY_INSTANCES) {
+            throw new Error(`Distributed SvelteKit cannot retain more than ${MAX_BOUNDARY_INSTANCES} boundary instances`);
+        }
+        const watches = [];
+        try {
+            for (const item of resolved) {
+                const watch = this.#replica.watch(item.operation.artifact, item.variables, { live: item.live });
+                watches.push(Object.freeze({
+                    watch,
+                    identity: item.identity,
+                    operation: item.operation.plan.operation,
+                    live: item.live
+                }));
+            }
+        }
+        catch (error) {
+            for (const { watch } of watches)
+                watch.destroy();
+            throw error;
+        }
+        const retained = {
+            signature,
+            boundary: validated.boundary,
+            owners: 1,
+            watches: Object.freeze(watches)
+        };
+        this.#instances.set(validated.id, retained);
+        for (const item of watches) {
+            const owners = (this.#identityOwners.get(item.identity) ?? 0) + 1;
+            this.#identityOwners.set(item.identity, owners);
+            this.#emit({
+                action: 'acquire',
+                boundary: retained.boundary,
+                operation: item.operation,
+                live: item.live,
+                owners
+            });
+        }
+        return this.#lease(validated.id, retained);
+    }
+    /** Retain the nearest generated page/layout boundary at a browser location. */
+    retainLocation(location, context) {
+        const matched = matchNearestBoundary(this.#operations, location.pathname, location.kind);
+        if (matched === undefined) {
+            return Object.freeze({ release: () => undefined });
+        }
+        return this.retain({
+            id: location.id,
+            route: matched.route,
+            kind: location.kind
+        }, Object.freeze({ ...context, params: matched.params }));
+    }
+    /** Warm every generated page and owning layout selection for one target URL. */
+    async prefetchLocation(pathname, context) {
+        if (this.#destroyed) {
+            throw new Error('Distributed SvelteKit boundary controller is destroyed');
+        }
+        const matches = matchLocationBoundaries(this.#operations, pathname);
+        const scheduled = new Map();
+        for (const matched of matches) {
+            for (const item of this.#resolve({
+                id: 'prefetch',
+                route: matched.route,
+                kind: matched.kind,
+                boundary: `${matched.kind}:${matched.route}`
+            }, Object.freeze({ ...context, params: matched.params }))) {
+                scheduled.set(item.identity, item);
+            }
+        }
+        await Promise.all([...scheduled.values()].map(async (item) => {
+            const snapshot = this.#replica.read(item.operation.artifact, item.variables);
+            if (snapshot.complete && !snapshot.stale)
+                return;
+            const watch = this.#replica.watch(item.operation.artifact, item.variables, { live: false });
+            try {
+                await watch.refresh();
+            }
+            finally {
+                watch.destroy();
+            }
+        }));
+    }
+    /** Close every old-scope owner while keeping the controller reusable. */
+    disposeScope() {
+        if (this.#destroyed)
+            return;
+        this.#disposeInstances(true);
+    }
+    destroy() {
+        if (this.#destroyed)
+            return;
+        this.#destroyed = true;
+        this.#disposeInstances(false);
+    }
+    #resolve(instance, context) {
+        const selected = this.#operations.filter(({ plan }) => plan.kind === instance.kind && normalizeRoute(plan.route) === instance.route);
+        if (selected.length === 0) {
+            throw new Error(`Distributed SvelteKit boundary plan has no ${instance.boundary} selection`);
+        }
+        return Object.freeze(selected.map((operation) => {
+            const variables = operation.binding.resolve(context);
+            return Object.freeze({
+                operation,
+                variables,
+                identity: boundaryOperationIdentity(operation.artifact, variables),
+                live: operation.artifact.live !== undefined
+            });
+        }));
+    }
+    #lease(instanceId, retained) {
+        let released = false;
+        return Object.freeze({
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                if (this.#instances.get(instanceId) !== retained)
+                    return;
+                retained.owners -= 1;
+                this.#emit({
+                    action: 'release',
+                    boundary: retained.boundary,
+                    owners: retained.owners
+                });
+                if (retained.owners > 0)
+                    return;
+                this.#instances.delete(instanceId);
+                this.#releaseWatches(retained);
+            }
+        });
+    }
+    #disposeInstances(scope) {
+        for (const [instanceId, retained] of [...this.#instances]) {
+            this.#instances.delete(instanceId);
+            if (scope) {
+                this.#emit({
+                    action: 'scope-dispose',
+                    boundary: retained.boundary,
+                    owners: 0
+                });
+            }
+            this.#releaseWatches(retained);
+        }
+    }
+    #releaseWatches(retained) {
+        for (const item of retained.watches) {
+            item.watch.destroy();
+            const owners = (this.#identityOwners.get(item.identity) ?? 1) - 1;
+            if (owners > 0) {
+                this.#identityOwners.set(item.identity, owners);
+                continue;
+            }
+            this.#identityOwners.delete(item.identity);
+            if (item.live) {
+                this.#emit({
+                    action: 'final-unsubscribe',
+                    boundary: retained.boundary,
+                    operation: item.operation,
+                    live: true,
+                    owners: 0
+                });
+            }
+        }
+    }
+    #emit(event) {
+        try {
+            this.#diagnostic?.(Object.freeze(event));
+        }
+        catch {
+            // Diagnostics are observational and cannot alter lifecycle ownership.
+        }
+    }
+}
+function validateInstance(instance) {
+    if (instance === null || typeof instance !== 'object') {
+        throw new TypeError('Distributed SvelteKit boundary instance is required');
+    }
+    const id = typeof instance.id === 'string' ? instance.id.trim() : undefined;
+    if (typeof id !== 'string' ||
+        id.length === 0 ||
+        new TextEncoder().encode(id).byteLength > MAX_INSTANCE_ID_BYTES) {
+        throw new TypeError('Distributed SvelteKit boundary instance id is invalid');
+    }
+    if (instance.kind !== 'layout' && instance.kind !== 'page') {
+        throw new TypeError('Distributed SvelteKit boundary instance kind is invalid');
+    }
+    const route = normalizeRoute(instance.route);
+    return Object.freeze({
+        id,
+        route,
+        kind: instance.kind,
+        boundary: `${instance.kind}:${route}`
+    });
+}
+function normalizeRoute(value) {
+    if (typeof value !== 'string' || !value.startsWith('/')) {
+        throw new TypeError('Distributed SvelteKit boundary route must start with /');
+    }
+    const normalized = value.length === 1 ? value : value.replace(/\/+$/, '');
+    return normalized.length === 0 ? '/' : normalized;
+}
+function matchNearestBoundary(operations, pathname, kind) {
+    const matches = matchLocationBoundaries(operations, pathname).filter((candidate) => candidate.kind === kind);
+    if (matches.length === 0)
+        return undefined;
+    const mostSpecific = matches[0];
+    if (matches[1] !== undefined &&
+        matches[1].specificity === mostSpecific.specificity) {
+        throw new Error(`Distributed SvelteKit boundary plan is ambiguous for this ${kind} location`);
+    }
+    return mostSpecific;
+}
+function matchLocationBoundaries(operations, pathname) {
+    const routes = new Map();
+    for (const { plan } of operations) {
+        routes.set(`${plan.kind}\u0000${plan.route}`, {
+            route: plan.route,
+            kind: plan.kind
+        });
+    }
+    const matches = [];
+    for (const candidate of routes.values()) {
+        const matched = matchRoutePattern(candidate.route, pathname, candidate.kind === 'layout');
+        if (matched !== undefined) {
+            matches.push(Object.freeze({ ...candidate, ...matched }));
+        }
+    }
+    return Object.freeze(matches.sort((left, right) => right.specificity - left.specificity ||
+        left.kind.localeCompare(right.kind) ||
+        left.route.localeCompare(right.route)));
+}
+function matchRoutePattern(pattern, pathname, prefix) {
+    const route = normalizeRoute(pattern);
+    const path = normalizePathname(pathname);
+    const routeSegments = route
+        .split('/')
+        .filter((segment) => segment.length > 0 && !/^\(.+\)$/.test(segment));
+    const pathSegments = path.split('/').filter((segment) => segment.length > 0);
+    const params = Object.create(null);
+    let pathIndex = 0;
+    let specificity = 0;
+    for (let routeIndex = 0; routeIndex < routeSegments.length; routeIndex += 1) {
+        const segment = routeSegments[routeIndex];
+        // SvelteKit matcher functions are application code. The browser adapter
+        // cannot execute or guess them from a generated route pattern.
+        if (segment.startsWith('[') && segment.includes('='))
+            return undefined;
+        const rest = /^\[\[?\.\.\.([^\]=]+)(?:=[^\]]+)?\]?\]$/.exec(segment);
+        if (rest !== null) {
+            const values = pathSegments.slice(pathIndex).map(decodePathSegment);
+            if (values.some((value) => value === undefined))
+                return undefined;
+            params[rest[1]] =
+                values.length === 0 ? undefined : values.join('/');
+            pathIndex = pathSegments.length;
+            break;
+        }
+        const optional = /^\[\[([^\]=]+)(?:=[^\]]+)?\]\]$/.exec(segment);
+        if (optional !== null) {
+            const remainingRequired = routeSegments
+                .slice(routeIndex + 1)
+                .filter((part) => !/^\[\[/.test(part)).length;
+            if (pathSegments.length - pathIndex > remainingRequired) {
+                const value = decodePathSegment(pathSegments[pathIndex++]);
+                if (value === undefined)
+                    return undefined;
+                params[optional[1]] = value;
+            }
+            else {
+                params[optional[1]] = undefined;
+            }
+            continue;
+        }
+        const dynamic = /^\[([^\]=]+)(?:=[^\]]+)?\]$/.exec(segment);
+        if (dynamic !== null) {
+            if (pathSegments[pathIndex] === undefined)
+                return undefined;
+            const value = decodePathSegment(pathSegments[pathIndex++]);
+            if (value === undefined)
+                return undefined;
+            params[dynamic[1]] = value;
+            continue;
+        }
+        if (pathSegments[pathIndex] === undefined)
+            return undefined;
+        const actual = decodePathSegment(pathSegments[pathIndex++]);
+        if (actual === undefined || actual !== segment)
+            return undefined;
+        specificity += 1;
+    }
+    if (!prefix && pathIndex !== pathSegments.length)
+        return undefined;
+    return Object.freeze({
+        params: Object.freeze(params),
+        specificity: specificity * 1_000 + routeSegments.length
+    });
+}
+function normalizePathname(value) {
+    if (typeof value !== 'string' ||
+        !value.startsWith('/') ||
+        new TextEncoder().encode(value).byteLength > MAX_LOCATION_PATHNAME_BYTES ||
+        value.split('/').length - 1 > MAX_LOCATION_SEGMENTS) {
+        throw new TypeError('Distributed SvelteKit location pathname is invalid or exceeds adapter limits');
+    }
+    const withoutQuery = value.split(/[?#]/u, 1)[0];
+    return withoutQuery.length === 1
+        ? withoutQuery
+        : withoutQuery.replace(/\/+$/, '');
+}
+function decodePathSegment(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/sveltekit/boundary-variables.d.ts

@@ -0,0 +1,57 @@
+import { type ReplicaOperationArtifact } from '../replica/index.js';
+import type { GraphqlVariables } from '../types.js';
+export type DistributedBoundaryVariableSource<TValue = unknown> = Readonly<{
+    kind: 'route_param';
+    name: string;
+}> | Readonly<{
+    kind: 'search_param';
+    name: string;
+    mode?: 'first' | 'all';
+}> | Readonly<{
+    kind: 'trusted_session';
+    path: readonly string[];
+}> | Readonly<{
+    kind: 'constant';
+    value: TValue;
+}> | Readonly<{
+    kind: 'forwarded_prop';
+    path: readonly string[];
+}> | Readonly<{
+    kind: 'omit';
+}>;
+export type DistributedBoundaryVariableSources<TVariables extends GraphqlVariables> = Readonly<{
+    [K in keyof TVariables]?: DistributedBoundaryVariableSource<TVariables[K]>;
+}>;
+export type DistributedBoundaryVariableContext<TSession = unknown, TProps = Readonly<Record<string, unknown>>> = Readonly<{
+    params: Readonly<Record<string, string | undefined>>;
+    search: URLSearchParams | Readonly<Record<string, string | readonly string[] | undefined>>;
+    session: TSession | null;
+    props: TProps;
+}>;
+export type DistributedBoundaryBinding<TVariables extends GraphqlVariables, TSession = unknown, TProps = Readonly<Record<string, unknown>>> = Readonly<{
+    version: 1;
+    id: string;
+    artifactId: string;
+    sources: DistributedBoundaryVariableSources<TVariables>;
+    resolve(context: DistributedBoundaryVariableContext<TSession, TProps>): TVariables;
+    canonicalBytes(context: DistributedBoundaryVariableContext<TSession, TProps>): string;
+}>;
+export type DistributedBoundaryPlan = Readonly<{
+    operation: string;
+    route: string;
+    kind: 'layout' | 'page';
+    sourcePath?: string;
+    discovery: 'component' | 'route_document' | 'explicit';
+}>;
+export type DistributedBoundaryOperation<TData = unknown, TVariables extends GraphqlVariables = GraphqlVariables, TSession = unknown, TProps = Readonly<Record<string, unknown>>> = Readonly<{
+    plan: DistributedBoundaryPlan;
+    artifact: ReplicaOperationArtifact<TData, TVariables>;
+    binding: DistributedBoundaryBinding<TVariables, TSession, TProps>;
+}>;
+/**
+ * Define one closed, inspectable variable binding for every boundary lifecycle.
+ * The operation artifact remains the sole owner of coercion and cache identity.
+ */
+export declare function defineDistributedBoundaryBinding<TData, TVariables extends GraphqlVariables, TSession = unknown, TProps = Readonly<Record<string, unknown>>>(artifact: ReplicaOperationArtifact<TData, TVariables>, sources: DistributedBoundaryVariableSources<TVariables>): DistributedBoundaryBinding<TVariables, TSession, TProps>;
+export declare function defineDistributedBoundaryOperation<TData, TVariables extends GraphqlVariables, TSession = unknown, TProps = Readonly<Record<string, unknown>>>(plan: DistributedBoundaryPlan, artifact: ReplicaOperationArtifact<TData, TVariables>, binding: DistributedBoundaryBinding<TVariables, TSession, TProps>): DistributedBoundaryOperation<TData, TVariables, TSession, TProps>;
+export declare function resolveDistributedBoundaryVariables<TData, TVariables extends GraphqlVariables, TSession, TProps>(artifact: ReplicaOperationArtifact<TData, TVariables>, sources: DistributedBoundaryVariableSources<TVariables>, context: DistributedBoundaryVariableContext<TSession, TProps>): TVariables;