@lensmcp/cluster 1.0.0

package/executors/gateway/providers-prod.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.staticManifestProvider = staticManifestProvider;
+exports.fileManifestProvider = fileManifestProvider;
+exports.rolloutPodProvider = rolloutPodProvider;
+exports.endpointsPodProvider = endpointsPodProvider;
+/**
+ * Production providers — the environment-specific halves of the gateway that
+ * the dev side fills with workspace-scan + unix-socket pools. Here:
+ *
+ *   - manifest source: a JSON file (or a static array), watched + atomically
+ *     swapped. A registry-backed provider (Redis key-space / k8s ConfigMaps)
+ *     plugs in behind the same `ManifestProvider` interface later.
+ *   - pod resolution: `endpointsPodProvider` round-robins per-service upstream
+ *     URLs (gateway-side LB). When a manifest carries its own `upstream` (a
+ *     k8s Service URL that load-balances pods itself), the core uses that
+ *     directly and no PodProvider is needed.
+ *
+ * Bad input never takes the gateway down: an unparseable manifest file is
+ * rejected and the last-good table keeps serving (versioned swap).
+ */
+const node_fs_1 = require("node:fs");
+const manifest_1 = require("./manifest");
+const toSpec = (v) => Array.isArray(v) ? { rules: [], cohorts: v } : { rules: v.rules ?? [], cohorts: v.cohorts ?? [] };
+/** A fixed set of manifests (tests, single-shot config). */
+function staticManifestProvider(manifests) {
+    return { list: () => manifests };
+}
+function parseManifests(raw) {
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    // Accept either a bare array or `{ manifests: [...] }`.
+    const arr = Array.isArray(data) ? data : data?.manifests;
+    if (!Array.isArray(arr))
+        return undefined;
+    const ok = arr.filter((m) => !!m && typeof m === 'object' && typeof m.service === 'string' && Array.isArray(m.mounts));
+    // A file that parsed but yielded ZERO valid manifests is treated as bad
+    // (likely a truncated/half-written deploy) — keep last-good rather than
+    // black-hole all traffic.
+    return ok.length > 0 ? ok : undefined;
+}
+/**
+ * Watch a manifests JSON file; atomically swap the in-memory set on a valid
+ * change, reject and keep last-good on a bad one. `watch` notifies subscribers
+ * with the new set. Poll fallback covers editors/atomic-rename + platforms
+ * where fs.watch is unreliable.
+ */
+function fileManifestProvider(filePath, opts = {}) {
+    const onError = opts.onError ?? (() => undefined);
+    let current = [];
+    let lastMtimeMs = -1;
+    const subs = new Set();
+    const reload = () => {
+        if (!(0, node_fs_1.existsSync)(filePath))
+            return;
+        let mtime;
+        try {
+            mtime = (0, node_fs_1.statSync)(filePath).mtimeMs;
+        }
+        catch {
+            return;
+        }
+        if (mtime === lastMtimeMs)
+            return;
+        let raw;
+        try {
+            raw = (0, node_fs_1.readFileSync)(filePath, 'utf8');
+        }
+        catch (e) {
+            onError(e);
+            return;
+        }
+        const parsed = parseManifests(raw);
+        if (!parsed) {
+            onError(new Error(`[gateway] rejecting invalid manifest file ${filePath} — keeping last-good`));
+            return;
+        }
+        lastMtimeMs = mtime;
+        current = parsed;
+        for (const cb of subs) {
+            try {
+                cb(current);
+            }
+            catch (e) {
+                onError(e);
+            }
+        }
+    };
+    reload(); // initial load (best-effort; empty until the file appears)
+    let watcher;
+    try {
+        watcher = (0, node_fs_1.watch)(filePath, { persistent: false }, () => reload());
+    }
+    catch { /* dir may not exist yet — poll covers it */ }
+    const timer = setInterval(reload, opts.pollMs ?? 1000);
+    timer.unref?.();
+    return {
+        list: () => current,
+        watch: (cb) => { subs.add(cb); return () => subs.delete(cb); },
+        stop: () => { try {
+            watcher?.close();
+        }
+        catch { /* ignore */ } clearInterval(timer); },
+    };
+}
+/**
+ * Rollout-aware pod provider: each service is a set of VERSION COHORTS, and
+ * `pick` splits traffic across them by weight (smooth weighted round-robin —
+ * a 90/10 canary interleaves, never bursts) and round-robins endpoints WITHIN
+ * the chosen cohort. `pick(svc, {version})` pins a cohort (sticky canary /
+ * debugging). `update` swaps weights/cohorts live — a rollout ramps
+ * (10→25→50→100) or rolls back without redeploying the gateway. The returned
+ * Upstream carries `version` so the gateway can surface which cohort served.
+ */
+function rolloutPodProvider(table) {
+    const svc = new Map();
+    const build = (spec) => ({
+        cohorts: spec.cohorts.map((c) => ({ ...c, urls: c.urls.slice() })),
+        select: (0, manifest_1.smoothWeightedSelector)(spec.cohorts.map((c) => c.weight)),
+        rr: spec.cohorts.map(() => -1),
+        rules: spec.rules ?? [],
+    });
+    const load = (t) => {
+        for (const [s, v] of Object.entries(t))
+            svc.set(s, build(toSpec(v)));
+        for (const s of [...svc.keys()])
+            if (!t[s])
+                svc.delete(s);
+    };
+    load(table);
+    const firstNonEmpty = (st) => st.cohorts.findIndex((c) => c.urls.length > 0);
+    return {
+        pick(service, opts) {
+            const st = svc.get(service);
+            if (!st || st.cohorts.length === 0)
+                return undefined;
+            let ci = -1;
+            if (opts?.version)
+                ci = st.cohorts.findIndex((c) => c.version === opts.version && c.urls.length > 0);
+            if (ci < 0) {
+                ci = st.select();
+                // chosen cohort drained/empty → fall back to any cohort with endpoints
+                if (!st.cohorts[ci] || st.cohorts[ci].urls.length === 0)
+                    ci = firstNonEmpty(st);
+            }
+            const cohort = st.cohorts[ci];
+            if (!cohort || cohort.urls.length === 0)
+                return undefined;
+            st.rr[ci] = (st.rr[ci] + 1) % cohort.urls.length;
+            return { url: cohort.urls[st.rr[ci]], version: cohort.version };
+        },
+        // first targeting rule that matches the request's attributes (sticky-by-attribute)
+        resolveVersion(service, attrs) {
+            const st = svc.get(service);
+            return st && st.rules.length ? (0, manifest_1.pickTargetedVersion)(st.rules, attrs) : undefined;
+        },
+        // consistent-hash a stable key to a cohort version (sticky weighted split)
+        bucket(service, key) {
+            const st = svc.get(service);
+            if (!st || st.cohorts.length === 0)
+                return undefined;
+            const cohort = st.cohorts[(0, manifest_1.bucketByWeight)(`${key}:${service}`, st.cohorts.map((c) => c.weight))];
+            return cohort ? { version: cohort.version } : undefined;
+        },
+        ensureUp: async () => true, // prod services are always-on (k8s keeps them up)
+        drop(service, upstream) {
+            const st = svc.get(service);
+            if (st && 'url' in upstream)
+                for (const c of st.cohorts)
+                    c.urls = c.urls.filter((u) => u !== upstream.url);
+        },
+        update: load,
+    };
+}
+/**
+ * Flat single-version load balancing — the common case (no rollout in
+ * progress). A thin wrapper over `rolloutPodProvider` with one synthetic
+ * cohort per service, so the rollout path is the only code path. The synthetic
+ * version is STRIPPED from the result: flat LB carries no `version`, so a
+ * response only gets `x-lensmcp-version` (and a `rollout` trace step) when a
+ * genuine multi-cohort rollout served it.
+ */
+function endpointsPodProvider(endpoints) {
+    const toCohorts = (eps) => Object.fromEntries(Object.entries(eps).map(([s, urls]) => [s, [{ version: '_flat', weight: 1, urls }]]));
+    const inner = rolloutPodProvider(toCohorts(endpoints));
+    const unversion = (u) => u && 'url' in u ? { url: u.url } : u;
+    return {
+        ...inner,
+        pick: (service, opts) => unversion(inner.pick(service, opts)),
+        resolveVersion: () => undefined, // flat LB: no targeting rules
+        bucket: () => undefined, // flat LB: single version, nothing to stick to
+        update: (next) => inner.update(toCohorts(next)),
+    };
+}

package/executors/gateway/registry-source.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Registry-backed gateway config — true zero-touch discovery. Instead of a
+ * mounted file, the manifests + rollout cohorts live in a shared registry
+ * (Redis here; k8s ConfigMap/Endpoints can drop in behind `RegistrySource`).
+ * A service deploy / the `lensmcp rollout --redis` CD helper writes its keys and
+ * publishes a change; the gateway re-reads and live-swaps its route table +
+ * cohorts in ~instant — no gateway redeploy, no file mounts.
+ *
+ * The cluster lib stays dependency-light: `redisRegistrySource` works against a
+ * minimal injected `RedisLike` (ioredis satisfies it; the prod entry wires the
+ * real client, tests pass a fake). See docs/design/targeted-rollout.md and
+ * docs/design/prod-gateway.md (§Distribution).
+ */
+import { type RolloutTable } from './providers-prod';
+import type { ManifestProvider, PodProvider, RouteManifest } from './manifest';
+/** A change-notifying source of the gateway's full config (manifests + rollout). */
+export interface RegistrySource {
+    /** Read the current snapshot. */
+    read(): Promise<{
+        manifests: RouteManifest[];
+        endpoints: RolloutTable;
+    }>;
+    /** Subscribe to change notifications; returns an unsubscribe. Optional. */
+    watch?(onChange: () => void): Promise<() => void>;
+    /** Release any held connections. */
+    stop?(): void;
+}
+/** The minimal Redis surface `redisRegistrySource` uses (ioredis satisfies it). */
+export interface RedisLike {
+    keys(pattern: string): Promise<string[]>;
+    mget(...keys: string[]): Promise<(string | null)[]>;
+    set(key: string, value: string): Promise<unknown>;
+    del(key: string): Promise<unknown>;
+    publish(channel: string, message: string): Promise<unknown>;
+    duplicate(): RedisLike;
+    subscribe(channel: string): Promise<unknown>;
+    on(event: 'message', cb: (channel: string, message: string) => void): void;
+    quit(): Promise<unknown>;
+}
+export declare const DEFAULT_REGISTRY_PREFIX = "lensmcp:gw";
+export declare const manifestKey: (prefix: string, service: string) => string;
+export declare const rolloutKey: (prefix: string, service: string) => string;
+export declare const changeChannel: (prefix: string) => string;
+/**
+ * Redis-backed source. Per-service keys (so a deploy touches only its own key,
+ * no read-modify-write races): `<prefix>:manifest:<svc>` (a RouteManifest) and
+ * `<prefix>:rollout:<svc>` (a VersionCohort[] | RolloutSpec). Writers publish
+ * `<prefix>:changed` after a SET; the gateway re-reads on the message.
+ */
+export declare function redisRegistrySource(client: RedisLike, opts?: {
+    prefix?: string;
+}): RegistrySource;
+/**
+ * Compose a ManifestProvider + PodProvider over a RegistrySource. Both refresh
+ * together on every change (source.watch) and on a poll fallback. Call
+ * `start()` (awaits the first read so the route table is warm) before handing
+ * the providers to `startProdGateway`.
+ */
+export declare function createRegistryProviders(source: RegistrySource, opts?: {
+    pollMs?: number;
+    onError?: (e: unknown) => void;
+}): {
+    manifests: ManifestProvider;
+    pods: PodProvider;
+    start(): Promise<void>;
+    stop(): void;
+};
+//# sourceMappingURL=registry-source.d.ts.map

package/executors/gateway/registry-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-source.d.ts","sourceRoot":"","sources":["../../../../../libs/cluster/src/executors/gateway/registry-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE/E,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,iCAAiC;IACjC,IAAI,IAAI,OAAO,CAAC;QAAE,SAAS,EAAE,aAAa,EAAE,CAAC;QAAC,SAAS,EAAE,YAAY,CAAA;KAAE,CAAC,CAAC;IACzE,2EAA2E;IAC3E,KAAK,CAAC,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;IAClD,oCAAoC;IACpC,IAAI,CAAC,IAAI,IAAI,CAAC;CACf;AAED,mFAAmF;AACnF,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC,IAAI,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC;IACpD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5D,SAAS,IAAI,SAAS,CAAC;IACvB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7C,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IAC3E,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1B;AAED,eAAO,MAAM,uBAAuB,eAAe,CAAC;AACpD,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,WAAoC,CAAC;AAChG,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,WAAmC,CAAC;AAC9F,eAAO,MAAM,aAAa,GAAI,QAAQ,MAAM,WAAwB,CAAC;AASrE;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,cAAc,CA6BrG;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,cAAc,EACtB,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;CAAO,GAC7D;IAAE,SAAS,EAAE,gBAAgB,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,IAAI,IAAI,IAAI,CAAA;CAAE,CA2B1F"}

package/executors/gateway/registry-source.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.changeChannel = exports.rolloutKey = exports.manifestKey = exports.DEFAULT_REGISTRY_PREFIX = void 0;
+exports.redisRegistrySource = redisRegistrySource;
+exports.createRegistryProviders = createRegistryProviders;
+/**
+ * Registry-backed gateway config — true zero-touch discovery. Instead of a
+ * mounted file, the manifests + rollout cohorts live in a shared registry
+ * (Redis here; k8s ConfigMap/Endpoints can drop in behind `RegistrySource`).
+ * A service deploy / the `lensmcp rollout --redis` CD helper writes its keys and
+ * publishes a change; the gateway re-reads and live-swaps its route table +
+ * cohorts in ~instant — no gateway redeploy, no file mounts.
+ *
+ * The cluster lib stays dependency-light: `redisRegistrySource` works against a
+ * minimal injected `RedisLike` (ioredis satisfies it; the prod entry wires the
+ * real client, tests pass a fake). See docs/design/targeted-rollout.md and
+ * docs/design/prod-gateway.md (§Distribution).
+ */
+const providers_prod_1 = require("./providers-prod");
+exports.DEFAULT_REGISTRY_PREFIX = 'lensmcp:gw';
+const manifestKey = (prefix, service) => `${prefix}:manifest:${service}`;
+exports.manifestKey = manifestKey;
+const rolloutKey = (prefix, service) => `${prefix}:rollout:${service}`;
+exports.rolloutKey = rolloutKey;
+const changeChannel = (prefix) => `${prefix}:changed`;
+exports.changeChannel = changeChannel;
+function parseManifest(s) {
+    try {
+        const m = JSON.parse(s);
+        return m && typeof m.service === 'string' && Array.isArray(m.mounts) ? m : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Redis-backed source. Per-service keys (so a deploy touches only its own key,
+ * no read-modify-write races): `<prefix>:manifest:<svc>` (a RouteManifest) and
+ * `<prefix>:rollout:<svc>` (a VersionCohort[] | RolloutSpec). Writers publish
+ * `<prefix>:changed` after a SET; the gateway re-reads on the message.
+ */
+function redisRegistrySource(client, opts = {}) {
+    const prefix = opts.prefix ?? exports.DEFAULT_REGISTRY_PREFIX;
+    let sub;
+    const rolloutPrefix = `${prefix}:rollout:`;
+    return {
+        async read() {
+            const mKeys = await client.keys(`${prefix}:manifest:*`);
+            const manifests = mKeys.length
+                ? (await client.mget(...mKeys)).filter((v) => !!v).map(parseManifest).filter((m) => !!m)
+                : [];
+            const rKeys = await client.keys(`${rolloutPrefix}*`);
+            const endpoints = {};
+            if (rKeys.length) {
+                const vals = await client.mget(...rKeys);
+                rKeys.forEach((k, i) => {
+                    const v = vals[i];
+                    if (v)
+                        try {
+                            endpoints[k.slice(rolloutPrefix.length)] = JSON.parse(v);
+                        }
+                        catch { /* skip a bad entry, keep the rest */ }
+                });
+            }
+            return { manifests, endpoints };
+        },
+        async watch(onChange) {
+            sub = client.duplicate();
+            await sub.subscribe((0, exports.changeChannel)(prefix));
+            sub.on('message', () => onChange());
+            return async () => { try {
+                await sub?.quit();
+            }
+            catch { /* ignore */ } };
+        },
+        stop() { void sub?.quit().catch(() => undefined); },
+    };
+}
+/**
+ * Compose a ManifestProvider + PodProvider over a RegistrySource. Both refresh
+ * together on every change (source.watch) and on a poll fallback. Call
+ * `start()` (awaits the first read so the route table is warm) before handing
+ * the providers to `startProdGateway`.
+ */
+function createRegistryProviders(source, opts = {}) {
+    const onError = opts.onError ?? (() => undefined);
+    let current = [];
+    const subs = new Set();
+    const inner = (0, providers_prod_1.rolloutPodProvider)({});
+    let unwatch;
+    let timer;
+    const refresh = async () => {
+        let snap;
+        try {
+            snap = await source.read();
+        }
+        catch (e) {
+            onError(e);
+            return;
+        } // keep last-good on a transient error
+        current = snap.manifests;
+        inner.update(snap.endpoints);
+        for (const cb of subs) {
+            try {
+                cb(current);
+            }
+            catch (e) {
+                onError(e);
+            }
+        }
+    };
+    return {
+        manifests: { list: () => current, watch: (cb) => { subs.add(cb); return () => subs.delete(cb); } },
+        pods: inner,
+        async start() {
+            await refresh();
+            if (source.watch) {
+                try {
+                    unwatch = await source.watch(() => void refresh());
+                }
+                catch (e) {
+                    onError(e);
+                }
+            }
+            timer = setInterval(() => void refresh(), opts.pollMs ?? 5000);
+            timer.unref?.();
+        },
+        stop() { unwatch?.(); if (timer)
+            clearInterval(timer); source.stop?.(); },
+    };
+}

package/executors/gateway/rollout-ops.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Rollout config operations — the brain behind `lensmcp rollout` (the CD helper).
+ * PURE: each op takes the rollout table and returns a NEW one, validating and
+ * throwing on bad input. The CLI (`main.rollout.ts`) wraps these with file IO +
+ * atomic write so pipelines never hand-edit JSON (and never write a half file).
+ *
+ * Works on the targeted/cohort shape (`{svc:{rules?,cohorts}}` or `{svc:[cohorts]}`);
+ * a flat endpoint list (`{svc:[url,…]}`) is rejected with a clear message — convert
+ * it to cohorts first. See docs/design/targeted-rollout.md.
+ */
+import type { RolloutTable } from './providers-prod';
+import type { TargetRule } from './manifest';
+export type RolloutOp = {
+    kind: 'add-cohort';
+    service: string;
+    version: string;
+    weight: number;
+    urls: string[];
+} | {
+    kind: 'set-weight';
+    service: string;
+    version: string;
+    weight: number;
+} | {
+    kind: 'remove-cohort';
+    service: string;
+    version: string;
+} | {
+    kind: 'promote';
+    service: string;
+    version: string;
+} | {
+    kind: 'abort';
+    service: string;
+    version: string;
+} | {
+    kind: 'add-rule';
+    service: string;
+    rule: TargetRule;
+} | {
+    kind: 'remove-rule';
+    service: string;
+    name: string;
+};
+/** Apply one operation to the rollout table; returns a NEW table. Throws on invalid input. */
+export declare function applyRolloutOp(config: RolloutTable, op: RolloutOp): RolloutTable;
+/** Human-readable status for one service (or all). Read-only. */
+export declare function summarizeRollout(config: RolloutTable, service?: string): string;
+/** Parse CLI argv (after the config-file path) into an op, a status request, or throw a usage error. */
+export declare function parseRolloutCommand(argv: string[]): {
+    op?: RolloutOp;
+    status?: string | undefined;
+};
+//# sourceMappingURL=rollout-ops.d.ts.map

package/executors/gateway/rollout-ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollout-ops.d.ts","sourceRoot":"","sources":["../../../../../libs/cluster/src/executors/gateway/rollout-ops.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,YAAY,EAAe,MAAM,kBAAkB,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAyB,MAAM,YAAY,CAAC;AAEpE,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GACxF;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACxE;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAwB3D,8FAA8F;AAC9F,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,EAAE,EAAE,EAAE,SAAS,GAAG,YAAY,CAgDhF;AAiBD,iEAAiE;AACjE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAe/E;AAUD,wGAAwG;AACxG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAAE,EAAE,CAAC,EAAE,SAAS,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAqBnG"}

package/executors/gateway/rollout-ops.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyRolloutOp = applyRolloutOp;
+exports.summarizeRollout = summarizeRollout;
+exports.parseRolloutCommand = parseRolloutCommand;
+const RULE_OPS = new Set(['eq', 'ne', 'in', 'nin', 'prefix', 'suffix', 'contains', 'regex', 'exists', 'gt', 'lt', 'cidr']);
+const clone = (v) => JSON.parse(JSON.stringify(v));
+/** Normalize a service entry to a `{rules,cohorts}` spec; reject a flat url list. */
+function asSpec(service, v) {
+    if (v === undefined)
+        return { rules: [], cohorts: [] };
+    if (Array.isArray(v)) {
+        if (v.length && typeof v[0] === 'string')
+            throw new Error(`service "${service}" is a flat endpoint list; convert it to cohorts first (e.g. add-cohort)`);
+        return { rules: [], cohorts: v };
+    }
+    return { rules: v.rules ?? [], cohorts: v.cohorts ?? [] };
+}
+const findCohort = (spec, version) => spec.cohorts.find((c) => c.version === version);
+function reqWeight(w) {
+    if (!Number.isFinite(w) || w < 0)
+        throw new Error(`weight must be a number ≥ 0 (got ${w})`);
+    return w;
+}
+/** Apply one operation to the rollout table; returns a NEW table. Throws on invalid input. */
+function applyRolloutOp(config, op) {
+    const next = clone(config);
+    const spec = asSpec(op.service, next[op.service]);
+    switch (op.kind) {
+        case 'add-cohort': {
+            if (findCohort(spec, op.version))
+                throw new Error(`cohort "${op.version}" already exists on "${op.service}" — use set-weight`);
+            if (!op.urls.length)
+                throw new Error('add-cohort needs at least one upstream url');
+            spec.cohorts.push({ version: op.version, weight: reqWeight(op.weight), urls: op.urls.slice() });
+            break;
+        }
+        case 'set-weight': {
+            const c = findCohort(spec, op.version);
+            if (!c)
+                throw new Error(`no cohort "${op.version}" on "${op.service}"`);
+            c.weight = reqWeight(op.weight);
+            break;
+        }
+        case 'remove-cohort': {
+            if (!findCohort(spec, op.version))
+                throw new Error(`no cohort "${op.version}" on "${op.service}"`);
+            spec.cohorts = spec.cohorts.filter((c) => c.version !== op.version);
+            break;
+        }
+        case 'promote': {
+            if (!findCohort(spec, op.version))
+                throw new Error(`no cohort "${op.version}" on "${op.service}"`);
+            for (const c of spec.cohorts)
+                c.weight = c.version === op.version ? 100 : 0;
+            break;
+        }
+        case 'abort': {
+            const c = findCohort(spec, op.version);
+            if (!c)
+                throw new Error(`no cohort "${op.version}" on "${op.service}"`);
+            c.weight = 0;
+            break;
+        }
+        case 'add-rule': {
+            validateRule(op.rule);
+            spec.rules = [...(spec.rules ?? []).filter((r) => !op.rule.name || r.name !== op.rule.name), op.rule]; // replace-by-name (idempotent)
+            break;
+        }
+        case 'remove-rule': {
+            const before = (spec.rules ?? []).length;
+            spec.rules = (spec.rules ?? []).filter((r) => r.name !== op.name);
+            if (spec.rules.length === before)
+                throw new Error(`no rule named "${op.name}" on "${op.service}"`);
+            break;
+        }
+    }
+    next[op.service] = spec.rules && spec.rules.length ? { rules: spec.rules, cohorts: spec.cohorts } : spec.cohorts;
+    return next;
+}
+function validateRule(rule) {
+    if (!rule || typeof rule.version !== 'string' || !rule.version)
+        throw new Error('rule needs a non-empty version');
+    if (!rule.when || typeof rule.when !== 'object')
+        throw new Error('rule needs a `when` condition');
+    const walk = (n) => {
+        const node = n;
+        if ('all' in node || 'any' in node || 'not' in node) {
+            for (const k of ['all', 'any'])
+                if (Array.isArray(node[k]))
+                    node[k].forEach(walk);
+            if (node.not)
+                walk(node.not);
+            return;
+        }
+        if (typeof node.attr !== 'string' || !RULE_OPS.has(node.op))
+            throw new Error(`invalid rule condition (attr/op): ${JSON.stringify(node)}`);
+    };
+    walk(rule.when);
+}
+/** Human-readable status for one service (or all). Read-only. */
+function summarizeRollout(config, service) {
+    const names = service ? [service] : Object.keys(config);
+    if (!names.length)
+        return '(no services in rollout config)';
+    const lines = [];
+    for (const s of names) {
+        const entry = config[s];
+        if (entry === undefined) {
+            lines.push(`${s}: (not present)`);
+            continue;
+        }
+        if (Array.isArray(entry) && entry.length && typeof entry[0] === 'string') {
+            lines.push(`${s}: flat LB → ${entry.join(', ')}`);
+            continue;
+        }
+        const spec = asSpec(s, entry);
+        const total = spec.cohorts.reduce((a, c) => a + Math.max(0, c.weight), 0) || 1;
+        lines.push(`${s}:`);
+        for (const c of spec.cohorts)
+            lines.push(`  • ${c.version.padEnd(16)} weight ${String(c.weight).padStart(3)} (${(Math.max(0, c.weight) / total * 100).toFixed(0)}%)  ${c.urls.length} url(s)`);
+        for (const r of spec.rules ?? [])
+            lines.push(`  ▸ rule ${(r.name ?? '(unnamed)').padEnd(16)} → ${r.version}   ${ruleSummary(r.when)}`);
+    }
+    return lines.join('\n');
+}
+function ruleSummary(n) {
+    const node = n;
+    if ('all' in node)
+        return '(' + node.all.map(ruleSummary).join(' AND ') + ')';
+    if ('any' in node)
+        return '(' + node.any.map(ruleSummary).join(' OR ') + ')';
+    if ('not' in node)
+        return 'NOT ' + ruleSummary(node.not);
+    return `${node.attr} ${node.op}${node.value !== undefined ? ' ' + JSON.stringify(node.value) : ''}`;
+}
+/** Parse CLI argv (after the config-file path) into an op, a status request, or throw a usage error. */
+function parseRolloutCommand(argv) {
+    const [cmd, ...a] = argv;
+    const need = (n, usage) => { if (a.length < n)
+        throw new Error(`usage: ${cmd} ${usage}`); };
+    switch (cmd) {
+        case 'status': return { status: a[0] };
+        case 'add-cohort':
+            need(4, '<service> <version> <weight> <url> [url...]');
+            return { op: { kind: 'add-cohort', service: a[0], version: a[1], weight: Number(a[2]), urls: a.slice(3) } };
+        case 'set-weight':
+            need(3, '<service> <version> <weight>');
+            return { op: { kind: 'set-weight', service: a[0], version: a[1], weight: Number(a[2]) } };
+        case 'remove-cohort':
+            need(2, '<service> <version>');
+            return { op: { kind: 'remove-cohort', service: a[0], version: a[1] } };
+        case 'promote':
+            need(2, '<service> <version>');
+            return { op: { kind: 'promote', service: a[0], version: a[1] } };
+        case 'abort':
+            need(2, '<service> <version>');
+            return { op: { kind: 'abort', service: a[0], version: a[1] } };
+        case 'add-rule':
+            need(6, '<service> <name> <attr> <op> <value> <version>');
+            return { op: { kind: 'add-rule', service: a[0], rule: { name: a[1], when: { attr: a[2], op: a[3], value: a[4] }, version: a[5] } } };
+        case 'remove-rule':
+            need(2, '<service> <name>');
+            return { op: { kind: 'remove-rule', service: a[0], name: a[1] } };
+        default: throw new Error(`unknown command "${cmd ?? ''}". commands: status, add-cohort, set-weight, remove-cohort, promote, abort, add-rule, remove-rule`);
+    }
+}

package/executors/gateway/schema.d.ts

@@ -0,0 +1,10 @@
+export interface GatewayExecutorSchema {
+  /** Listener ports. Default [443]. */
+  ports?: number[];
+  /** Terminate TLS with the davnx local CA. Default true. */
+  https?: boolean;
+  /** Traffic-edge aggregation window (ms) before flushing to the lens. Default 5000. */
+  trafficFlushMs?: number;
+  /** Workspace-relative path to a per-request middleware module (the JWT seam). */
+  middleware?: string;
+}

package/executors/gateway/schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "version": 2,
+  "title": "Gateway executor",
+  "description": "Workspace https front door. Reads every project's top-level `davnx` declaration ({ host, port|upstream, prependPrefix?, default? }), builds the hostname route table, serves a local-CA TLS cert with SANs for every host, and proxies requests + websocket upgrades. The optional middleware hook (JWT etc.) runs on every request — service-to-service traffic should use each service's internalPort instead and skip the gateway entirely.",
+  "type": "object",
+  "properties": {
+    "ports": {
+      "type": "array",
+      "items": {
+        "type": "number"
+      },
+      "description": "Listener ports. Default [443] so dev domains need no :port."
+    },
+    "https": {
+      "type": "boolean",
+      "default": true,
+      "description": "Terminate TLS with the davnx local CA (trust once via the trust executor)."
+    },
+    "middleware": {
+      "type": "string",
+      "description": "Workspace-relative path to a JS module (req) => void that runs on every gateway request — the JWT/auth seam. Throwing rejects the request with 401."
+    },
+    "trafficFlushMs": {
+      "type": "number",
+      "description": "Traffic-edge aggregation window in ms before flushing to the LensMCP bus. Default 5000; lower (e.g. 1000) for near-realtime canvases."
+    }
+  },
+  "additionalProperties": false
+}