@hops-ops/distributed 0.0.0

package/dist/sveltekit/server-replica.js

@@ -0,0 +1,176 @@
+import { createDistributedReplica, createReplicaGraphqlTransport } from '../replica/index.js';
+import { authFromPageData } from './auth.js';
+/**
+ * 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 function createDistributedSvelteKitServer(options) {
+    const routes = validateRoutes(options.routes);
+    return Object.freeze({
+        async load(event) {
+            const session = await options.getSession(event);
+            const accessToken = session?.accessToken ?? null;
+            const engineRole = options.getRole(session, event) ?? null;
+            const pageData = {
+                session,
+                accessToken,
+                engineRole
+            };
+            const auth = options.getAuth?.(pageData, event) ?? authFromPageData(pageData);
+            const routeId = routeIdentity(event);
+            const selected = routes.filter(({ plan }) => plan.route === routeId);
+            if (selected.length === 0) {
+                return {
+                    ...pageData,
+                    gqlError: null
+                };
+            }
+            const fetchImpl = event.fetch;
+            const transport = createReplicaGraphqlTransport({
+                getUrl: () => options.getUrl?.(event) ?? '/graphql',
+                getAuth: () => auth,
+                ...(fetchImpl === undefined ? {} : { fetch: fetchImpl })
+            });
+            const replica = createDistributedReplica({ transport });
+            const watches = [];
+            try {
+                for (const binding of selected) {
+                    let variables;
+                    try {
+                        variables =
+                            (await options.variables?.[binding.plan.operation]?.(event)) ??
+                                {};
+                        const watch = replica.watch(binding.artifact, variables, { live: false });
+                        watches.push({
+                            operation: binding.plan.operation,
+                            artifact: binding.artifact,
+                            variables,
+                            watch
+                        });
+                    }
+                    catch (error) {
+                        if (options.variables?.[binding.plan.operation] === undefined) {
+                            throw new Error(`Distributed @load operation \`${binding.plan.operation}\` needs route variables; configure variables.${binding.plan.operation}(event) in createDistributedSvelteKitServer`, { cause: error });
+                        }
+                        throw error;
+                    }
+                }
+                await Promise.all(watches.map(({ watch }) => watch.refresh()));
+                const errors = watches.flatMap(({ watch }) => watch.get().errors);
+                for (const { artifact, variables, watch } of watches) {
+                    // Preserve exact rendered-operation reachability after the
+                    // temporary watch is released.
+                    replica.read(artifact, variables);
+                    watch.destroy();
+                }
+                const transfer = replica.scope === undefined
+                    ? undefined
+                    : hydrationTransfer(replica.dehydrate(), selected.map(({ plan }) => plan.operation));
+                return {
+                    ...pageData,
+                    ...(transfer === undefined
+                        ? {}
+                        : {
+                            distributed: transfer.hydration,
+                            distributedAuthority: transfer.authority
+                        }),
+                    gqlError: errors[0]?.message ??
+                        (transfer === undefined
+                            ? 'Distributed GraphQL response did not establish an authoritative cache scope'
+                            : null)
+                };
+            }
+            finally {
+                for (const { watch } of watches)
+                    watch.destroy();
+            }
+        }
+    });
+}
+/**
+ * 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 function registerDistributedRoute(route, operation, artifact) {
+    return Object.freeze({
+        plan: Object.freeze({
+            operation: nonEmpty(operation, 'operation'),
+            route: normalizeRoute(route),
+            discovery: 'explicit'
+        }),
+        artifact: artifact
+    });
+}
+function hydrationTransfer(state, operations) {
+    return Object.freeze({
+        hydration: Object.freeze({
+            version: 1,
+            state,
+            operations: Object.freeze([...operations])
+        }),
+        authority: Object.freeze({
+            version: 1,
+            scope: state.scope
+        })
+    });
+}
+function validateRoutes(value) {
+    if (!Array.isArray(value)) {
+        throw new TypeError('createDistributedSvelteKitServer requires generated DISTRIBUTED_ROUTE_OPERATIONS');
+    }
+    const identities = new Set();
+    return Object.freeze(value.map((binding, index) => {
+        if (binding === null ||
+            typeof binding !== 'object' ||
+            binding.plan === null ||
+            typeof binding.plan !== 'object' ||
+            binding.artifact === null ||
+            typeof binding.artifact !== 'object') {
+            throw new TypeError(`invalid Distributed route binding at index ${index}`);
+        }
+        const operation = nonEmpty(binding.plan.operation, 'route operation');
+        const route = normalizeRoute(binding.plan.route);
+        if (binding.artifact.id.length === 0) {
+            throw new TypeError(`invalid Distributed route artifact for ${operation}`);
+        }
+        const identity = `${route}\u0000${operation}`;
+        if (identities.has(identity)) {
+            throw new TypeError(`duplicate Distributed route operation ${operation} at ${route}`);
+        }
+        identities.add(identity);
+        return Object.freeze({
+            plan: Object.freeze({
+                ...binding.plan,
+                operation,
+                route
+            }),
+            artifact: binding.artifact
+        });
+    }));
+}
+function routeIdentity(event) {
+    const route = event.route?.id;
+    if (typeof route === 'string' && route.length > 0)
+        return normalizeRoute(route);
+    if (event.url !== undefined)
+        return normalizeRoute(event.url.pathname);
+    throw new Error('Distributed SvelteKit route loading requires event.route.id or event.url.pathname');
+}
+function normalizeRoute(value) {
+    const route = nonEmpty(value, 'route');
+    if (!route.startsWith('/')) {
+        throw new TypeError('Distributed route must start with /');
+    }
+    if (route.length === 1)
+        return route;
+    return route.replace(/\/+$/, '');
+}
+function nonEmpty(value, label) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new TypeError(`Distributed ${label} must be a non-empty string`);
+    }
+    return value.trim();
+}

package/dist/sveltekit/vite.d.ts

@@ -0,0 +1,103 @@
+export type DistributedGraphqlProxyOptions = {
+    /** Absolute Distributed API origin, for example `http://127.0.0.1:8791`. */
+    target: string;
+    /** Proxy key. Defaults to `/graphql` and includes its `/ws` child. */
+    path?: string;
+};
+/** Vite proxy config for GraphQL HTTP and WebSocket traffic. */
+export declare function distributedGraphqlProxy(options: DistributedGraphqlProxyOptions | string): Record<string, {
+    target: string;
+    changeOrigin: true;
+    ws: true;
+}>;
+export type DistributedSvelteKitManifestSource = string | Readonly<{
+    /**
+     * Arguments passed to the configured dctl command. The first value
+     * must be `client-manifest`; stdout becomes ephemeral compiler input.
+     */
+    args: readonly string[];
+}>;
+export type DistributedSvelteKitClientCompiler = Readonly<{
+    /** `$distributed` or an explicit elevated entrypoint such as `$distributed/admin`. */
+    module: string;
+    /** Existing manifest path, or canonical `dctl client-manifest` argv. */
+    manifest: DistributedSvelteKitManifestSource;
+    /** Verify exactly one concrete role. Mutually exclusive with `surface`. */
+    role?: string;
+    /** Verify exactly one Rust-declared application surface. */
+    surface?: string;
+    /** GraphQL globs passed verbatim as repeated `dctl client --documents`. */
+    documents: readonly string[];
+    /** Explicit `OPERATION=/route` fallbacks. */
+    routes?: readonly string[];
+    /** Compiler-owned artifact directory, relative to `cwd` by default. */
+    out: string;
+}>;
+export type DistributedSvelteKitViteOptions = Readonly<{
+    /** Project root used for dctl cwd, document globs, and output containment. */
+    cwd?: string;
+    /** Executable invoked without a shell. Defaults to `dctl`. */
+    command?: string;
+    /** Prefix argv, e.g. `cargo run ... --`; never interpreted by a shell. */
+    commandArgs?: readonly string[];
+    clients: readonly DistributedSvelteKitClientCompiler[];
+}>;
+type ViteWebSocketLike = Readonly<{
+    send(payload: unknown): void;
+}>;
+type ViteModuleGraphLike = Readonly<{
+    getModuleById(id: string): unknown;
+    invalidateModule(module: unknown): void;
+}>;
+type ViteServerLike = Readonly<{
+    watcher: Readonly<{
+        add(paths: string | readonly string[]): void;
+    }>;
+    ws: ViteWebSocketLike;
+    moduleGraph: ViteModuleGraphLike;
+    httpServer?: Readonly<{
+        once(event: 'close', listener: () => void): void;
+    }> | null;
+}>;
+type ViteHotContextLike = Readonly<{
+    file: string;
+    server: ViteServerLike;
+}>;
+type RollupWatchContextLike = Readonly<{
+    addWatchFile(path: string): void;
+}>;
+/** Minimal structural Vite plugin type; avoids making Vite a runtime dependency. */
+export type DistributedSvelteKitVitePlugin = Readonly<{
+    name: string;
+    enforce: 'pre';
+    configResolved(config: Readonly<{
+        root: string;
+    }>): Promise<void>;
+    configureServer(server: ViteServerLike): void;
+    buildStart(this: RollupWatchContextLike): void;
+    resolveId(source: string): string | undefined;
+    load(id: string): string | undefined;
+    handleHotUpdate(context: ViteHotContextLike): Promise<never[] | undefined>;
+    watchChange(id: string): Promise<void>;
+    closeBundle(): Promise<void>;
+}>;
+/** Generate every configured surface through the same transaction used by Vite. */
+export declare function generateDistributedSvelteKit(options: DistributedSvelteKitViteOptions): Promise<void>;
+/** Check every configured surface through canonical `dctl client --check`; never write. */
+export declare function checkDistributedSvelteKit(options: DistributedSvelteKitViteOptions): Promise<void>;
+/**
+ * Compiler-watching Vite integration for one or more authorization surfaces.
+ *
+ * Every run stages every surface first, then swaps the complete generated
+ * trees as one rollback-capable transaction. Child processes are serialized,
+ * coalesced, abortable, and always invoked without a shell.
+ */
+export declare function distributedSvelteKit(options: DistributedSvelteKitViteOptions): DistributedSvelteKitVitePlugin;
+/**
+ * SvelteKit language-tool aliases for the exact files used by Vite resolution.
+ *
+ * Keep this alongside the Vite plugin in the Node-only export. It performs no
+ * generation and is safe to call from `svelte.config.js`.
+ */
+export declare function distributedSvelteKitAliases(options: Pick<DistributedSvelteKitViteOptions, 'cwd' | 'clients'>): Readonly<Record<string, string>>;
+export {};