@lensmcp/cluster 1.12.0 → 1.13.0

package/executors/gateway/gateway.lib.d.ts

@@ -1,171 +1,19 @@
 /**
- * The gateway runtime, separated from the Nx executor so it is directly
- * testable: `startGateway()` returns a handle with the actually-bound ports
- * and a `stop()` — no signals needed. The executor is a thin wrapper.
+ * Public facade for the dev gateway runtime.
+ *
+ * The implementation now lives in `./runtime/*` as composable LAYERS — see
+ * `runtime/server.ts` for the composition root (`startGateway`), `runtime/types.ts`
+ * for the shared types + the customer **hooks** API, and the sibling modules for
+ * each layer (discovery, dev-auth, observability, lifecycle, lens-children, proxy,
+ * auth, hooks, handler, upgrade). This barrel preserves the original module's
+ * public surface so the executor wrapper (`gateway.impl.ts`) and the existing
+ * specs keep importing from one stable path, and additionally exposes the new
+ * hooks types so customers can author typed layers on top of the gateway.
  */
-import { type ChildProcess } from 'node:child_process';
-import * as http from 'node:http';
-import type { GatewayExecutorSchema } from './schema';
-import { type AuthPolicy } from './manifest';
 export { hostMatches } from './manifest';
-/**
- * Dev edge auth (HS256), mirroring the prod gateway: verify the end-user token, then stamp the
- * trusted identity headers the services read (via GatewayTrustGuard). RS256/JWKS is prod's job;
- * dev shares the `AUTH_JWT_SECRET` the auth host signs with. Returns the claims, or undefined.
- */
-export declare function verifyDevJwt(req: http.IncomingMessage): Record<string, unknown> | undefined;
-/** Stamp verified identity onto the forwarded request — tenant from the `tid` CLAIM, never a client header. */
-export declare function stampIdentity(req: http.IncomingMessage, claims: Record<string, unknown>): void;
-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;
-}
-export interface GatewayHandle {
-    /** Ports actually bound (resolves `0` to the assigned ephemeral port). */
-    ports: number[];
-    routes: Route[];
-    services: ServiceCtl[];
-    stop: () => Promise<void>;
-}
-/** 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. */
-export declare function baseDomainOf(hosts: string[]): string;
-/** 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. Mirrors the
- *  derivation in the `lensmcp` CLI's `workspace-scope` (kept in lock-step). */
-export declare function readLensScope(root: string): {
-    key: string;
-    dashboardPort: number;
-    basePath: string;
-};
-/** Round-robin over the pool's sockets, rescanning the dir when the cache ages out. */
-export declare function pickSock(pool: SockPool, scanTtlMs?: number): string | undefined;
-/**
- * Read every project's `cluster` (or legacy `davnx`) declaration and build
- * the route table: host routes first (plus auto `internal.<host>` for pod
- * services), the `default` catch-all last.
- */
-export declare function discoverRoutes(rootDir: string, projects: Record<string, {
-    root: string;
-}>, sockBaseDir?: string): {
-    routes: Route[];
-    services: ServiceCtl[];
-};
-export declare function startGateway(options: GatewayRuntimeOptions, context: GatewayContext): Promise<GatewayHandle>;
+export { startGateway } from './runtime/server';
+export { verifyDevJwt, stampIdentity } from './runtime/dev-auth';
+export { baseDomainOf, readLensScope } from './runtime/scope';
+export { pickSock, discoverRoutes } from './runtime/discovery';
+export type { GatewayContext, ClusterProjectDecl, SockPool, Route, LensFrontend, ServiceCtl, GatewayRuntimeOptions, GatewayHandle, GatewayHooks, GatewayPhase, HookHandler, HookContext, } from './runtime/types';
 //# sourceMappingURL=gateway.lib.d.ts.map

package/executors/gateway/gateway.lib.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gateway.lib.d.ts","sourceRoot":"","sources":["../../../../../libs/cluster/src/executors/gateway/gateway.lib.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"gateway.lib.d.ts","sourceRoot":"","sources":["../../../../../libs/cluster/src/executors/gateway/gateway.lib.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE/D,YAAY,EACV,cAAc,EACd,kBAAkB,EAClB,QAAQ,EACR,KAAK,EACL,YAAY,EACZ,UAAU,EACV,qBAAqB,EACrB,aAAa,EAEb,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,WAAW,GACZ,MAAM,iBAAiB,CAAC"}