@lensmcp/cluster 1.11.0 → 1.13.0

package/executors/gateway/runtime/scope.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.baseDomainOf = baseDomainOf;
+exports.readLensScope = readLensScope;
+exports.lensKeyFrom = lensKeyFrom;
+exports.lensSlug = lensSlug;
+const tslib_1 = require("tslib");
+/**
+ * Per-workspace lens scope + dashboard-host derivation. Pure (fs reads only),
+ * mirrors the `lensmcp` CLI's `workspace-scope` (kept in lock-step).
+ */
+const fs = tslib_1.__importStar(require("node:fs"));
+const path = tslib_1.__importStar(require("node:path"));
+/** The base domain for the lens dashboard host — the longest common dotted
+ *  suffix of the declared cluster hosts (e.g. ['api.tetros.ai.local',
+ *  'tetros.ai.local'] → 'tetros.ai.local'). Falls back to the first host, then
+ *  to 'lens.local' if no host is declared. */
+function baseDomainOf(hosts) {
+    const clean = hosts.filter((h) => !!h && !h.startsWith('*.'));
+    if (clean.length === 0)
+        return 'local';
+    // Use the SHORTEST host as the candidate base (most likely the apex), then
+    // require every other host to end with it.
+    const shortest = clean.reduce((a, b) => (b.length < a.length ? b : a));
+    if (clean.every((h) => h === shortest || h.endsWith('.' + shortest)))
+        return shortest;
+    // No clean common apex — derive the trailing 2-3 labels of the shortest host.
+    const parts = shortest.split('.');
+    return parts.slice(-Math.min(parts.length, 3)).join('.');
+}
+/** Per-workspace lens scope (key + dashboard port + mount path). Prefers the
+ *  CLI-written `.lensmcp/config.json` (so the gateway agrees with `lensmcp gateway`
+ *  / `lensmcp dashboard`); falls back to deriving from the workspace. */
+function readLensScope(root) {
+    try {
+        const cfg = JSON.parse(fs.readFileSync(path.join(root, '.lensmcp', 'config.json'), 'utf8'));
+        if (cfg && typeof cfg.key === 'string') {
+            return {
+                key: cfg.key,
+                dashboardPort: cfg.ports?.dashboard ?? 4321,
+                basePath: cfg.dashboardBasePath ?? '/' + cfg.key,
+            };
+        }
+    }
+    catch {
+        /* no config yet — derive below */
+    }
+    const key = lensKeyFrom(root);
+    return { key, dashboardPort: 4321, basePath: '/' + key };
+}
+function lensKeyFrom(root) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+        if (pkg?.name)
+            return lensSlug(pkg.name);
+    }
+    catch {
+        /* fall through to dir name */
+    }
+    return lensSlug(path.basename(root));
+}
+function lensSlug(input) {
+    return (input
+        .toLowerCase()
+        .replace(/^@[^/]+\//, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/(^-|-$)/g, '') || 'workspace');
+}

package/executors/gateway/runtime/server.d.ts

@@ -0,0 +1,3 @@
+import type { GatewayContext, GatewayHandle, GatewayRuntimeOptions } from './types';
+export declare function startGateway(options: GatewayRuntimeOptions, context: GatewayContext): Promise<GatewayHandle>;
+//# sourceMappingURL=server.d.ts.map

package/executors/gateway/runtime/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/server.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAkB,qBAAqB,EAAe,MAAM,SAAS,CAAC;AAEjH,wBAAsB,YAAY,CAChC,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC,CAmJxB"}

package/executors/gateway/runtime/server.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startGateway = startGateway;
+const tslib_1 = require("tslib");
+/**
+ * The composition root. `startGateway` resolves options, discovers routes, wires
+ * every layer (observability → service lifecycle → lens children → proxy → auth →
+ * hooks → handler/upgrade), boots TLS + listeners, and returns a `GatewayHandle`.
+ *
+ * The TOP-TO-BOTTOM ORDER here is itself a contract: service keys load before the
+ * runtime is built; lens children boot (pushing the dashboard route) BEFORE the
+ * cert SANs are derived from `routes`; eager services boot before listeners; the
+ * `gateway-up` event fires only after the ports are bound.
+ */
+const http = tslib_1.__importStar(require("node:http"));
+const path = tslib_1.__importStar(require("node:path"));
+const discovery_1 = require("./discovery");
+const service_keys_1 = require("./service-keys");
+const observability_1 = require("./observability");
+const lifecycle_1 = require("./lifecycle");
+const lens_children_1 = require("./lens-children");
+const proxy_1 = require("./proxy");
+const auth_1 = require("./auth");
+const hooks_1 = require("./hooks");
+const handler_1 = require("./handler");
+const upgrade_1 = require("./upgrade");
+async function startGateway(options, context) {
+    // NB: this local `https` (TLS-on flag) deliberately SHADOWS the `node:https`
+    // module — which is why TLS/agents are reached via `require('node:https')`.
+    const https = options.https !== false;
+    const ports = options.ports?.length ? options.ports : [443];
+    const scanTtlMs = options.scanTtlMs ?? 1500;
+    const startupTimeoutMs = options.startupTimeoutMs ?? 120_000;
+    const sweepMs = options.sweepMs ?? 10_000;
+    const trafficFlushMs = options.trafficFlushMs ?? 5000;
+    // Set by stop(); read via rt.stopped() so an in-flight cold start neither
+    // spawns a process nor logs after the gateway is torn down.
+    let stopped = false;
+    // The gateway is a first-class lens source — the shared event file the MCP tails.
+    const eventFile = process.env['LENSMCP_EVENT_FILE'] ?? path.join(context.root, '.lensmcp', 'events.jsonl');
+    // --- discover ---------------------------------------------------------------
+    const { routes, services } = (0, discovery_1.discoverRoutes)(context.root, context.projectsConfigurations?.projects ?? {});
+    if (routes.length === 0) {
+        throw new Error('[gateway] no project declares a `cluster` field — nothing to route.');
+    }
+    // --- per-service api keys (the gateway is the trust boundary) ---------------
+    const { serviceKeys, keyToProject } = (0, service_keys_1.loadServiceKeys)(context.root, services);
+    // --- the shared runtime (state + knobs; stopped() is a live getter) ---------
+    const rt = {
+        root: context.root,
+        eventFile,
+        routes,
+        services,
+        serviceKeys,
+        keyToProject,
+        scanTtlMs,
+        startupTimeoutMs,
+        sweepMs,
+        trafficFlushMs,
+        https,
+        stopped: () => stopped,
+    };
+    // --- layers -----------------------------------------------------------------
+    const obs = (0, observability_1.createObservability)(eventFile, { trafficFlushMs });
+    const svcLayer = (0, lifecycle_1.createServiceLayer)(rt, obs);
+    const lens = (0, lens_children_1.createLensChildren)(rt, obs, options);
+    const proxyLayer = (0, proxy_1.createProxy)(rt, obs, svcLayer);
+    const edgeAuth = (0, auth_1.createEdgeAuth)(rt, obs);
+    // Custom user middleware (the JWT seam; internal.* routes skip it) is wired as
+    // the BUILT-IN FIRST `afterAuth` hook — so "custom middleware runs AFTER core
+    // auth" and the `{ mode:'middleware' }` trace step are preserved.
+    let middleware;
+    if (options.middleware) {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const mod = require(path.resolve(context.root, options.middleware));
+        middleware = (mod.default ?? mod);
+    }
+    const builtinMiddleware = (ctx) => {
+        if (!middleware)
+            return;
+        try {
+            middleware(ctx.req);
+        }
+        catch (e) {
+            obs.traceStep(ctx.trace, 'auth', { mode: 'middleware', ok: false, reason: e.message });
+            if (ctx.route)
+                obs.finishTrace(ctx.trace, ctx.route.project, 401);
+            ctx.sendError(401, 'unauthorized', `Gateway middleware rejected the request: ${e.message}`);
+        }
+    };
+    const userHooks = options.hooks ?? {};
+    const hooks = (0, hooks_1.createHooks)({
+        ...userHooks,
+        afterAuth: [builtinMiddleware, ...(userHooks.afterAuth ?? [])],
+    });
+    const handler = (0, handler_1.createHandler)({ rt, obs, auth: edgeAuth, proxy: proxyLayer, hooks });
+    const upgrade = (0, upgrade_1.createUpgrade)({ rt, auth: edgeAuth, proxy: proxyLayer, hooks });
+    // Background timers (both `.unref()`'d): traffic-edge flush + idle sweeper.
+    const edgeFlusher = obs.startEdgeFlusher();
+    const sweeper = svcLayer.startSweeper();
+    // --- lens-mode children: dashboard + MCP singletons + `lens:true` apps ------
+    // MUST run before TLS — it pushes the dashboard route, which joins the cert SANs.
+    lens.bootSingletonsAndApps();
+    // Eager services boot with the gateway.
+    for (const svc of services) {
+        if (svc.decl.eager)
+            void svcLayer.ensureUp(svc);
+    }
+    // --- TLS + listeners --------------------------------------------------------
+    let pem;
+    let caPath;
+    if (https) {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const basicSsl = require('../../../basic-ssl');
+        const cacheDir = (0, service_keys_1.gatewayCacheDir)(context.root);
+        const hosts = routes.map((r) => r.host).filter((h) => !!h);
+        pem = basicSsl.getCertificateSync(cacheDir, 'gateway', hosts);
+        caPath = basicSsl.caCertPath(cacheDir);
+    }
+    const servers = [];
+    const boundPorts = [];
+    for (const port of ports) {
+        const server = pem
+            ? // eslint-disable-next-line @typescript-eslint/no-require-imports
+                require('node:https').createServer({ key: pem, cert: pem }, handler)
+            : http.createServer(handler);
+        server.on('upgrade', upgrade);
+        server.on('error', (err) => console.error(`[gateway] port ${port}: ${err.code}`));
+        await new Promise((resolve) => {
+            server.listen(port, () => {
+                const actual = server.address()?.port ?? port;
+                boundPorts.push(actual);
+                console.log(`[gateway] Listening on ${pem ? 'https' : 'http'}://localhost:${actual}`);
+                resolve();
+            });
+        });
+        servers.push(server);
+    }
+    console.log('[gateway] Routes:');
+    for (const r of routes) {
+        const dest = r.pool ? `pods@${r.pool.dir}` : r.target;
+        console.log(`[gateway]   ${r.host ?? '(default)'} → ${dest}${r.prependPrefix ? `  (+${r.prependPrefix})` : ''}${r.internal ? '  [internal: no middleware]' : ''}  [${r.project}]`);
+    }
+    if (caPath)
+        console.log(`[gateway] CA: ${caPath} — one-time setup via the trust executor.`);
+    obs.emit('info', `gateway up: ${routes.length} routes on ${boundPorts.join('/')}`, 'cluster-gateway', {
+        kind: 'gateway-up',
+        ports: boundPorts,
+        routes: routes.map((r) => ({ host: r.host ?? '(default)', project: r.project, mode: r.pool ? 'pods' : 'tcp', internal: !!r.internal, prependPrefix: r.prependPrefix })),
+    });
+    const stop = async () => {
+        if (stopped)
+            return;
+        stopped = true;
+        clearInterval(edgeFlusher);
+        clearInterval(sweeper);
+        obs.emit('info', 'gateway down', 'cluster-gateway', { kind: 'gateway-down' });
+        for (const svc of services)
+            svcLayer.killSpawned(svc, 'gateway shutdown');
+        // Reap the lens-mode managed children (dashboard + MCP singletons + each
+        // `lens:true` app's Vite/capture) — same teardown as the pod services.
+        lens.reapAll();
+        await Promise.all(servers.map((s) => new Promise((r) => s.close(() => r()))));
+        proxyLayer.closeProxy();
+        proxyLayer.destroyAgents(); // release pooled upstream sockets
+    };
+    return { ports: boundPorts, routes, services, stop };
+}

package/executors/gateway/runtime/service-keys.d.ts

@@ -0,0 +1,11 @@
+import type { ServiceCtl } from './types';
+/** The gateway's on-disk cache root — shared by service keys AND the TLS cert cache. */
+export declare function gatewayCacheDir(root: string): string;
+/** Load (or generate + persist) a stable key per pod service, plus the inverse
+ *  key→project map used to authenticate internal callers. Tolerant of a
+ *  read-only fs (keys then live only for this process). */
+export declare function loadServiceKeys(root: string, services: ServiceCtl[]): {
+    serviceKeys: Record<string, string>;
+    keyToProject: Map<string, string>;
+};
+//# sourceMappingURL=service-keys.d.ts.map

package/executors/gateway/runtime/service-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-keys.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/service-keys.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;2DAE2D;AAC3D,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,UAAU,EAAE,GACrB;IAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAc5E"}

package/executors/gateway/runtime/service-keys.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gatewayCacheDir = gatewayCacheDir;
+exports.loadServiceKeys = loadServiceKeys;
+const tslib_1 = require("tslib");
+/**
+ * Per-service api keys (be-security: the gateway is the trust boundary).
+ * Every pod service gets a stable key in `{cacheDir}/service-keys.json`.
+ * - Public routes: the gateway injects the TARGET's key as `x-internal-token` —
+ *   pods are only reachable through it (unix sockets aren't on the network).
+ * - `internal.<host>` routes: the CALLER must present its own key as `x-api-key`;
+ *   the gateway validates it, stamps `x-api-key-id` (caller identity) and
+ *   forwards with the target's `x-internal-token`.
+ */
+const node_crypto_1 = require("node:crypto");
+const fs = tslib_1.__importStar(require("node:fs"));
+const path = tslib_1.__importStar(require("node:path"));
+/** The gateway's on-disk cache root — shared by service keys AND the TLS cert cache. */
+function gatewayCacheDir(root) {
+    return path.join(root, 'node_modules', '.cache', 'davnx-webpack');
+}
+/** Load (or generate + persist) a stable key per pod service, plus the inverse
+ *  key→project map used to authenticate internal callers. Tolerant of a
+ *  read-only fs (keys then live only for this process). */
+function loadServiceKeys(root, services) {
+    const keysDir = gatewayCacheDir(root);
+    const keysPath = path.join(keysDir, 'service-keys.json');
+    let serviceKeys = {};
+    try {
+        serviceKeys = JSON.parse(fs.readFileSync(keysPath, 'utf8'));
+    }
+    catch { /* first run */ }
+    let dirty = false;
+    for (const svc of services) {
+        if (!serviceKeys[svc.project]) {
+            serviceKeys[svc.project] = (0, node_crypto_1.randomBytes)(16).toString('hex');
+            dirty = true;
+        }
+    }
+    if (dirty) {
+        try {
+            fs.mkdirSync(keysDir, { recursive: true });
+            fs.writeFileSync(keysPath, JSON.stringify(serviceKeys, null, 2));
+        }
+        catch { /* ro fs */ }
+    }
+    const keyToProject = new Map(Object.entries(serviceKeys).map(([p, k]) => [k, p]));
+    return { serviceKeys, keyToProject };
+}

package/executors/gateway/runtime/types.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Shared types for the layered gateway runtime. This file is TYPES-ONLY and
+ * imports nothing from a runtime layer (only `node:*`, `../manifest`,
+ * `../schema`, `../gateway-errors` types) — so every layer can import it
+ * without creating an import cycle. The composition root (`server.ts`) is the
+ * only place that wires concrete layers together.
+ */
+import type { ChildProcess } from 'node:child_process';
+import type * as http from 'node:http';
+import type * as stream from 'node:stream';
+import type { GatewayExecutorSchema } from '../schema';
+import type { AuthPolicy, Attrs } from '../manifest';
+import type { GatewayErrorReason } from '../gateway-errors';
+export type { Attrs };
+export interface GatewayContext {
+    root: string;
+    projectName?: string;
+    projectsConfigurations?: {
+        projects: Record<string, {
+            root: string;
+        }>;
+    };
+}
+/** Per-project declaration: top-level `cluster` field in project.json (`davnx` legacy). */
+export interface ClusterProjectDecl {
+    /** Public dev hostname (e.g. `api.tetros.ai.local`). */
+    host?: string;
+    /** Mount PATH under the host — backend services share api.<domain> path-routed (e.g. `/channels`). */
+    path?: string;
+    /**
+     * Socket-pool mode (the "pods" model): the cluster devserver's service
+     * name. The gateway round-robins DIRECTLY over its children's unix
+     * sockets (`$TMPDIR/<service>-devserver/child-*.sock`) — one load
+     * balancer in front of N pods, like production. Also auto-exposes
+     * `internal.<host>` for east-west calls that SKIP the middleware (JWT).
+     */
+    service?: string;
+    /** TCP mode (vite apps etc.): where the dev server listens. */
+    upstream?: string;
+    /** Shorthand for upstream. */
+    port?: number;
+    /** Prepend to forwarded URLs (e.g. `/api` for an app mounted under a prefix). */
+    prependPrefix?: string;
+    /** This project also serves unmatched hostnames (the catch-all). */
+    default?: boolean;
+    /** Override the auto `internal.<host>` name, or `false` to disable it. */
+    internalHost?: string | false;
+    /** Edge auth policy (default + per-path overrides) — generated from controller decorators
+     *  by @tetros-server/gateway-sync; the gateway verifies + injects identity + enforces it.
+     *  Absent ⇒ the service is unguarded at the edge (current behavior — opt-in enforcement). */
+    auth?: AuthPolicy;
+    /** Start at gateway boot (true) or on first request — scale from zero (false, default). */
+    eager?: boolean;
+    /** Pod range: spawn with min, autoscale up to max while requests overlap. */
+    minPods?: number;
+    maxPods?: number;
+    /** Kill a gateway-spawned (non-eager) service after this many idle seconds. */
+    idleKillSec?: number;
+    /** Nx target that runs the service. Default serve-hmr. */
+    serveTarget?: string;
+    /** Devserver admin endpoint for scaling (default from port: http(s)://localhost:<port>). */
+    adminUrl?: string;
+    /**
+     * FRONTEND apps only: run this app UNDER the lens. When true, the gateway
+     * SPAWNS the app's own Vite dev server with `@lensmcp/vite-plugin`
+     * instrumentation + a browser-capture sidecar (via the shared
+     * `spawnLensFrontend` helper) and routes THAT as the upstream — instead of
+     * assuming an external Vite already runs on `port`/`upstream`. The
+     * cluster-wide singletons (dashboard + MCP) are owned by the gateway, so a
+     * `lens:true` app never spawns its own. Absent/false ⇒ today's behavior
+     * (plain TCP upstream; bring-your-own Vite). Ignored for pod (`service`) decls.
+     */
+    lens?: boolean;
+}
+export interface SockPool {
+    dir: string;
+    socks: string[];
+    idx: number;
+    scannedAt: number;
+}
+export interface Route {
+    host?: string;
+    prefix?: string;
+    project: string;
+    prependPrefix?: string;
+    target?: string;
+    pool?: SockPool;
+    svc?: ServiceCtl;
+    internal?: boolean;
+    auth?: AuthPolicy;
+    /** Frontend `lens:true` route: the gateway spawns this app's Vite + lens
+     *  instrumentation as the upstream (see `LensFrontend`). */
+    lens?: LensFrontend;
+}
+/** A frontend app the gateway runs UNDER the lens (`cluster.lens: true`). The
+ *  gateway spawns its Vite + browser capture as the upstream, deterministically
+ *  on `port`, and never spawns the per-app dashboard/MCP (those are singletons
+ *  the gateway owns). */
+export interface LensFrontend {
+    project: string;
+    /** Absolute project root (holds vite.config.*). */
+    projectRoot: string;
+    /** The pinned Vite dev port (also the upstream target's port). */
+    port: number;
+    /** Set once the Vite child has been spawned (idempotency guard). */
+    started?: boolean;
+}
+export interface ServiceCtl {
+    project: string;
+    decl: ClusterProjectDecl;
+    pool: SockPool;
+    proc?: ChildProcess;
+    state: 'down' | 'starting' | 'up';
+    lastUsed: number;
+    inflight: number;
+    lastScaleAt: number;
+    spawnAt?: number;
+    lastErrors?: string[];
+    buildFailed?: boolean;
+}
+/** Test-tunable knobs on top of the user-facing schema. */
+export interface GatewayRuntimeOptions extends GatewayExecutorSchema {
+    /** Traffic-edge flush period (ms). Default 5000. */
+    trafficFlushMs?: number;
+    /** Idle sweeper period (ms). Default 10000. */
+    sweepMs?: number;
+    /** Sock-dir rescan TTL (ms). Default 1500. */
+    scanTtlMs?: number;
+    /** Cold-start wait budget (ms). Default 120000. */
+    startupTimeoutMs?: number;
+    /** Customer-supplied lifecycle hooks layered on top of the built-in pipeline. */
+    hooks?: GatewayHooks;
+}
+export interface GatewayHandle {
+    /** Ports actually bound (resolves `0` to the assigned ephemeral port). */
+    ports: number[];
+    routes: Route[];
+    services: ServiceCtl[];
+    stop: () => Promise<void>;
+}
+export interface GwTrace {
+    startedAt: number;
+    method: string;
+    host: string;
+    url: string;
+    steps: Array<Record<string, unknown>>;
+    flowId?: string;
+    requestId?: string;
+    originNodeId?: string;
+    done?: boolean;
+}
+/**
+ * STATE + KNOBS shared across layers — deliberately holds NO layer-produced
+ * functions (so `types.ts` stays acyclic). Each layer factory receives this
+ * plus the specific sibling layers it needs. Arrays/maps are passed BY
+ * REFERENCE and mutated in place (e.g. the dashboard route is pushed onto
+ * `routes`, dead pods are filtered out of a pool).
+ */
+export interface GatewayRuntime {
+    readonly root: string;
+    readonly eventFile: string;
+    readonly routes: Route[];
+    readonly services: ServiceCtl[];
+    readonly serviceKeys: Record<string, string>;
+    readonly keyToProject: ReadonlyMap<string, string>;
+    readonly scanTtlMs: number;
+    readonly startupTimeoutMs: number;
+    readonly sweepMs: number;
+    readonly trafficFlushMs: number;
+    readonly https: boolean;
+    /** Teardown flag — a GETTER, never a captured boolean, so every layer reads
+     *  the LIVE value (an in-flight cold start / auto-heal must not act after stop). */
+    stopped(): boolean;
+}
+/** The phases a customer can register handlers into, in pipeline order. */
+export type GatewayPhase = 'onRequest' | 'beforeAuth' | 'afterAuth' | 'beforeForward' | 'onResponse' | 'onError' | 'onUpgrade';
+export type HookHandler = (ctx: HookContext) => void | Promise<void>;
+/** Per-phase handler lists. Handlers run in array order; the first to respond
+ *  (write the response / destroy the socket) short-circuits the pipeline. */
+export interface GatewayHooks {
+    onRequest?: HookHandler[];
+    beforeAuth?: HookHandler[];
+    afterAuth?: HookHandler[];
+    beforeForward?: HookHandler[];
+    onResponse?: HookHandler[];
+    onError?: HookHandler[];
+    onUpgrade?: HookHandler[];
+}
+/**
+ * The context passed to every hook — a typed view over the in-flight request.
+ * `caller`/`pod`/`claims`/`trace` mirror the `req.__lensmcp*` fields the
+ * built-in layers also read, so a hook and the built-ins see the same values.
+ */
+export interface HookContext {
+    readonly req: http.IncomingMessage;
+    /** Absent on the `onUpgrade` (WebSocket) path. */
+    readonly res?: http.ServerResponse;
+    /** Present only on the `onUpgrade` path. */
+    readonly socket?: stream.Duplex;
+    /** The matched route (undefined before `onRequest`'s match). */
+    route?: Route;
+    /** Verified JWT claims once `afterAuth` has run (public/jwt routes). */
+    claims?: Record<string, unknown>;
+    /** Validated caller project (internal-route x-api-key). Mirrors `__lensmcpCaller`. */
+    caller?: string;
+    /** Chosen pod basename once forwarding to a pool. Mirrors `__lensmcpPod`. */
+    pod?: string;
+    /** The in-flight trace, if this request is being narrated. Mirrors `__lensmcpTrace`. */
+    readonly trace?: GwTrace;
+    /** The error available in `onError`. */
+    error?: Error;
+    /** The response status available in `onResponse`. */
+    status?: number;
+    /** Short-circuit the pipeline with a gateway edge error (the only sanctioned exit). */
+    sendError(status: number, reason: GatewayErrorReason, detail?: string): void;
+    /** Has a prior handler already responded? (`res` ended/headers-sent, or `socket` destroyed.) */
+    responded(): boolean;
+}
+/** Edge-auth verdict returned by the auth layer; the handler turns a denial
+ *  (`ok:false`) into `finishTrace` + `sendError`. A flat shape (not a
+ *  discriminated union) because this package compiles with `strict:false`, under
+ *  which boolean-discriminant narrowing is unreliable. */
+export interface AuthVerdict {
+    ok: boolean;
+    /** internal route: the validated caller project (when ok). */
+    caller?: string;
+    /** public/jwt route: verified claims (when ok). */
+    claims?: Record<string, unknown>;
+    /** denial details (present when !ok). */
+    status?: number;
+    reason?: GatewayErrorReason;
+    detail?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/executors/gateway/runtime/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/types.ts"],"names":[],"mappings":"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"}

package/executors/gateway/runtime/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/executors/gateway/runtime/upgrade.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The WebSocket upgrade pipeline. WS upgrades enforce the SAME trust model as
+ * HTTP — otherwise an `internal.<host>` socket would be reachable with no
+ * x-api-key, and a public socket would reach pods without the x-internal-token
+ * they expect. Reuses the shared auth + proxy layers so it can't drift from the
+ * HTTP handler.
+ */
+import type * as http from 'node:http';
+import type * as stream from 'node:stream';
+import type { GatewayRuntime } from './types';
+import type { EdgeAuth } from './auth';
+import type { ProxyLayer } from './proxy';
+import type { HooksLayer } from './hooks';
+export interface UpgradeDeps {
+    rt: GatewayRuntime;
+    auth: EdgeAuth;
+    proxy: ProxyLayer;
+    hooks: HooksLayer;
+}
+export type UpgradeListener = (req: http.IncomingMessage, socket: stream.Duplex, head: Buffer) => void;
+export declare function createUpgrade(deps: UpgradeDeps): UpgradeListener;
+//# sourceMappingURL=upgrade.d.ts.map

package/executors/gateway/runtime/upgrade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/upgrade.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,KAAK,IAAI,MAAM,WAAW,CAAC;AACvC,OAAO,KAAK,KAAK,MAAM,MAAM,aAAa,CAAC;AAI3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,cAAc,CAAC;IACnB,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,UAAU,CAAC;IAClB,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAEvG,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,eAAe,CAqChE"}

package/executors/gateway/runtime/upgrade.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUpgrade = createUpgrade;
+const manifest_1 = require("../manifest");
+const discovery_1 = require("./discovery");
+const edge_1 = require("./edge");
+function createUpgrade(deps) {
+    const { rt, auth, proxy, hooks } = deps;
+    const match = (req) => (0, manifest_1.matchRoute)(rt.routes, (req.headers.host || '').split(':')[0], req.url ?? '/');
+    const run = async (req, socket, head) => {
+        for (const h of edge_1.GATEWAY_OWNED_HEADERS)
+            delete req.headers[h];
+        const route = match(req);
+        if (!route) {
+            socket.destroy();
+            return;
+        }
+        const ctx = hooks.upgradeContext(req, socket, undefined);
+        ctx.route = route;
+        if (route.internal) {
+            const v = auth.internal(req, route, undefined);
+            if (!v.ok) {
+                socket.destroy();
+                return;
+            } // no valid key → no internal WS
+            ctx.caller = v.caller;
+        }
+        else {
+            const v = auth.public(req, route, undefined);
+            if (!v.ok) {
+                socket.destroy();
+                return;
+            }
+            ctx.claims = v.claims;
+            // afterAuth (= builtin middleware first, then user hooks) — public branch only
+            if (hooks.has('afterAuth')) {
+                await hooks.run('afterAuth', ctx);
+                if (ctx.responded())
+                    return;
+            }
+        }
+        if (route.pool && rt.serviceKeys[route.project]) {
+            req.headers['x-internal-token'] = rt.serviceKeys[route.project];
+        }
+        if (route.prependPrefix && !req.url?.startsWith(route.prependPrefix)) {
+            req.url = route.prependPrefix + (req.url ?? '/');
+        }
+        if (hooks.has('onUpgrade')) {
+            await hooks.run('onUpgrade', ctx);
+            if (ctx.responded())
+                return;
+        }
+        const target = route.pool
+            ? (() => { const s = (0, discovery_1.pickSock)(route.pool, rt.scanTtlMs); return s ? { socketPath: s } : undefined; })()
+            : route.target;
+        if (!target) {
+            socket.destroy();
+            return;
+        }
+        proxy.proxy.ws(req, socket, head, { target, changeOrigin: !route.pool, agent: proxy.agentForTarget(target) }, () => socket.destroy());
+    };
+    return (req, socket, head) => { void run(req, socket, head); };
+}