@lensmcp/cluster 1.0.0 → 1.2.0

package/executors/gateway/rate-limit.d.ts

@@ -0,0 +1,66 @@
+/**
+ * In-memory token-bucket rate limiter — OPT-IN, per-instance, per-key.
+ *
+ * Defense-in-depth, NOT the primary limiter: Cloudflare / Cloud Armor remain the
+ * global edge throttle. This caps abuse per gateway instance, keyed by the real
+ * client IP (resolved through the same trusted-proxy logic as ABAC), and only on
+ * the proxied catch-all — the ops endpoints (/livez, /readyz, /statusz) are
+ * registered routes and are never subject to it.
+ *
+ * Token bucket: `limit` tokens refill smoothly over `windowMs`; each request
+ * spends one. Empty bucket → denied with the ms until the next token. Idle
+ * (refilled-to-full) buckets are swept so the key map can't grow unbounded.
+ */
+export interface RateLimiterOptions {
+    /** Tokens (requests) per window. */
+    limit: number;
+    /** Window length the `limit` refills over (ms). */
+    windowMs: number;
+    /** Injectable clock (tests). Defaults to Date.now. */
+    now?: () => number;
+}
+export interface RateDecision {
+    allowed: boolean;
+    remaining: number;
+    retryAfterMs: number;
+}
+export interface RateLimiter {
+    /** Spend one token for `key`. In-memory returns synchronously; the Redis-backed
+     *  limiter returns a Promise (one round-trip) — the gateway `await`s either. */
+    check(key: string): RateDecision | Promise<RateDecision>;
+    stop(): void;
+}
+export declare function createRateLimiter(opts: RateLimiterOptions): RateLimiter;
+/**
+ * Redis-backed token-bucket rate limiter — ONE GLOBAL budget shared by every
+ * gateway container/instance (so a per-IP limit is N-container-independent, unlike
+ * the in-memory limiter whose limit silently multiplies by instance count).
+ *
+ * The check is a single atomic Lua EVAL (no GET-then-SET race), using Redis's own
+ * clock (`TIME`) so instances agree on refill regardless of host clock skew. The
+ * bucket key TTLs out shortly after a full refill, so idle clients leave no residue.
+ *
+ * Hot-path cost: one Redis round-trip per request. It is bounded by `timeoutMs` and
+ * **fails open** by default — a slow/unreachable Redis must not 429 all traffic and
+ * take the gateway down (it's defense-in-depth; Cloudflare/Cloud Armor stay the
+ * primary edge throttle). Set `failOpen: false` only if you'd rather shed load than
+ * risk exceeding the budget during a Redis outage.
+ */
+export interface RedisRateLimiterOptions {
+    /** Tokens (requests) per window. */
+    limit: number;
+    /** Window the `limit` refills over (ms). */
+    windowMs: number;
+    /** Key namespace — the Redis key is `<prefix><key>`. Default 'lensmcp:gw:rl:'. */
+    prefix?: string;
+    /** Max ms to wait on the Redis round-trip before applying the fail policy. Default 100. */
+    timeoutMs?: number;
+    /** On Redis error/timeout: true → allow (default), false → deny. */
+    failOpen?: boolean;
+}
+/** The single ioredis method the limiter needs — an atomic script eval. */
+export interface RateLimitRedis {
+    eval(script: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
+}
+export declare function createRedisRateLimiter(client: RateLimitRedis, opts: RedisRateLimiterOptions): RateLimiter;
+//# sourceMappingURL=rate-limit.d.ts.map

package/executors/gateway/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../../../../libs/cluster/src/executors/gateway/rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,kBAAkB;IACjC,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAAG,OAAO,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE;AAE3F,MAAM,WAAW,WAAW;IAC1B;oFACgF;IAChF,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACzD,IAAI,IAAI,IAAI,CAAC;CACd;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,kBAAkB,GAAG,WAAW,CA6BvE;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,uBAAuB;IACtC,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACvF;AA2BD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,uBAAuB,GAAG,WAAW,CAgCzG"}

package/executors/gateway/rate-limit.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRateLimiter = createRateLimiter;
+exports.createRedisRateLimiter = createRedisRateLimiter;
+function createRateLimiter(opts) {
+    const limit = Math.max(1, opts.limit);
+    const windowMs = Math.max(1, opts.windowMs);
+    const now = opts.now ?? Date.now;
+    const refillPerMs = limit / windowMs;
+    const buckets = new Map();
+    const refilled = (b, t) => Math.min(limit, b.tokens + (t - b.last) * refillPerMs);
+    // Evict buckets that have refilled to full (idle) so the map stays bounded.
+    const sweep = setInterval(() => {
+        const t = now();
+        for (const [k, b] of buckets)
+            if (refilled(b, t) >= limit)
+                buckets.delete(k);
+    }, windowMs);
+    sweep.unref?.();
+    return {
+        check(key) {
+            const t = now();
+            let b = buckets.get(key);
+            if (!b) {
+                b = { tokens: limit, last: t };
+                buckets.set(key, b);
+            }
+            b.tokens = refilled(b, t);
+            b.last = t;
+            if (b.tokens >= 1) {
+                b.tokens -= 1;
+                return { allowed: true, remaining: Math.floor(b.tokens), retryAfterMs: 0 };
+            }
+            return { allowed: false, remaining: 0, retryAfterMs: Math.ceil((1 - b.tokens) / refillPerMs) };
+        },
+        stop() { clearInterval(sweep); },
+    };
+}
+// Atomic token bucket in one round-trip. Stores fractional tokens (Redis keeps the
+// string form) so refill is exact across calls; only the returned remaining/retry
+// are integer-coerced by the Lua→RESP boundary, which is fine.
+const BUCKET_LUA = `
+local b = redis.call('HMGET', KEYS[1], 't', 's')
+local cap = tonumber(ARGV[1])
+local refill = tonumber(ARGV[2])
+local ttl = tonumber(ARGV[3])
+local tm = redis.call('TIME')
+local now = tm[1] * 1000 + tm[2] / 1000
+local tokens = tonumber(b[1])
+local ts = tonumber(b[2])
+if tokens == nil then tokens = cap; ts = now end
+tokens = math.min(cap, tokens + (now - ts) * refill)
+local ok = 0
+if tokens >= 1 then tokens = tokens - 1; ok = 1 end
+redis.call('HSET', KEYS[1], 't', tokens, 's', now)
+redis.call('PEXPIRE', KEYS[1], ttl)
+local retry = 0
+if ok == 0 then retry = math.ceil((1 - tokens) / refill) end
+return {ok, math.floor(tokens), retry}`;
+const RL_TIMEOUT = Symbol('rl-timeout');
+const RL_FAIL = Symbol('rl-fail');
+function createRedisRateLimiter(client, opts) {
+    const limit = Math.max(1, opts.limit);
+    const windowMs = Math.max(1, opts.windowMs);
+    const prefix = opts.prefix ?? 'lensmcp:gw:rl:';
+    const timeoutMs = Math.max(1, opts.timeoutMs ?? 100);
+    const failOpen = opts.failOpen !== false;
+    const refillPerMs = limit / windowMs;
+    const ttlMs = Math.ceil(windowMs) + 1000; // evict idle buckets shortly after a full refill
+    const onFail = () => failOpen
+        ? { allowed: true, remaining: limit, retryAfterMs: 0 }
+        : { allowed: false, remaining: 0, retryAfterMs: windowMs };
+    return {
+        async check(key) {
+            let timer;
+            // The eval branch is mapped so it can never reject (→ RL_FAIL) — that keeps a
+            // late rejection (after a timeout already won the race) from going unhandled.
+            const evalP = Promise.resolve(client.eval(BUCKET_LUA, 1, `${prefix}${key}`, limit, refillPerMs, ttlMs)).then((v) => v, () => RL_FAIL);
+            const timeoutP = new Promise((res) => { timer = setTimeout(() => res(RL_TIMEOUT), timeoutMs); });
+            const res = await Promise.race([evalP, timeoutP]);
+            clearTimeout(timer);
+            if (res === RL_TIMEOUT || res === RL_FAIL)
+                return onFail();
+            const [ok, remaining, retry] = res;
+            return ok === 1
+                ? { allowed: true, remaining: Number(remaining) || 0, retryAfterMs: 0 }
+                : { allowed: false, remaining: 0, retryAfterMs: Number(retry) || windowMs };
+        },
+        stop() { },
+    };
+}

package/executors/gateway/schema.d.ts

@@ -7,4 +7,12 @@ export interface GatewayExecutorSchema {
   trafficFlushMs?: number;
   /** Workspace-relative path to a per-request middleware module (the JWT seam). */
   middleware?: string;
+  /** Spawn the lens dashboard as a gateway-managed child + route lens.<baseDomain>. Default true. */
+  dashboard?: boolean;
+  /** Spawn the single MCP server as a gateway-managed child when a `lens:true` app exists. Default true. */
+  mcp?: boolean;
+  /** Port the managed dashboard listens on (proxied behind lens.<baseDomain>). Default 4321. */
+  dashboardPort?: number;
+  /** Override the dashboard hostname. Default lens.<baseDomain>. */
+  lensHost?: string;
 }

package/executors/gateway/schema.json

@@ -24,6 +24,25 @@
     "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."
+    },
+    "dashboard": {
+      "type": "boolean",
+      "default": true,
+      "description": "Spawn the LensMCP dashboard (the human web view of the lens) as a gateway-managed child and route it at lens.<baseDomain>. The gateway also owns the single MCP server, so `lens:true` frontend apps run only their Vite + instrumentation. Set false to skip (e.g. when a separate `lensmcp dashboard` is already running)."
+    },
+    "mcp": {
+      "type": "boolean",
+      "default": true,
+      "description": "Spawn the single LensMCP MCP server (the agent surface) as a gateway-managed child when any `lens:true` frontend app is declared. Set false if an external `lensmcp mcp` / agent-dev already owns it."
+    },
+    "dashboardPort": {
+      "type": "number",
+      "default": 4321,
+      "description": "Port the gateway-managed dashboard listens on (proxied behind lens.<baseDomain>). Default 4321."
+    },
+    "lensHost": {
+      "type": "string",
+      "description": "Override the dashboard's dev hostname. Default lens.<baseDomain>, where <baseDomain> is the longest common dotted suffix of the declared cluster hosts (e.g. lens.tetros.ai.local)."
     }
   },
   "additionalProperties": false

package/executors.json

@@ -1,23 +1,23 @@
 {
   "executors": {
     "build": {
-      "implementation": "./src/executors/build/build.impl",
-      "schema": "./src/executors/build/schema.json",
+      "implementation": "./executors/build/build.impl",
+      "schema": "./executors/build/schema.json",
       "description": "Production webpack build for a NestJS application."
     },
     "serve": {
-      "implementation": "./src/executors/serve/serve.impl",
-      "schema": "./src/executors/serve/schema.json",
+      "implementation": "./executors/serve/serve.impl",
+      "schema": "./executors/serve/schema.json",
       "description": "Webpack watch mode with integrated devserver for a NestJS application."
     },
     "trust": {
-      "implementation": "./src/executors/trust/trust.impl",
-      "schema": "./src/executors/trust/schema.json",
+      "implementation": "./executors/trust/trust.impl",
+      "schema": "./executors/trust/schema.json",
       "description": "One-time HTTPS dev setup: trust the davnx local CA + write /etc/hosts entries for gateway hostnames (idempotent, sudo prompts inline)."
     },
     "gateway": {
-      "implementation": "./src/executors/gateway/gateway.impl",
-      "schema": "./src/executors/gateway/schema.json",
+      "implementation": "./executors/gateway/gateway.impl",
+      "schema": "./executors/gateway/schema.json",
       "description": "Workspace https front door: reads every project davnx declaration (host/port/prefix), routes by hostname, serves the local-CA cert with all SANs."
     }
   }

package/main.devserver.js

@@ -119,7 +119,7 @@ function cleanupSock(sockPath) {
     try {
         fs.unlinkSync(sockPath);
     }
-    catch { }
+    catch { /* best-effort: socket already gone */ }
 }
 // delete from CJS cache + require fresh
 async function importFresh(spec) {
@@ -281,6 +281,7 @@ if (process.env.APP_RUNNER === '1') {
                 inspector?.close?.();
             }
             catch {
+                /* inspector may already be detached */
             }
         });
         const shutdown = async (sig) => {
@@ -546,7 +547,7 @@ else {
                 try {
                     w.proc.kill('SIGTERM');
                 }
-                catch { }
+                catch { /* worker already exited */ }
             }
             workerProcesses.length = 0;
             for (const name of WORKER_NAMES) {
@@ -789,7 +790,7 @@ else {
                 try {
                     w.proc.kill('SIGTERM');
                 }
-                catch { }
+                catch { /* worker already exited */ }
             }
             for (const c of children) {
                 try {
@@ -804,7 +805,7 @@ else {
             try {
                 fs.rmdirSync(SOCK_DIR);
             }
-            catch { }
+            catch { /* best-effort: dir missing or non-empty */ }
             setTimeout(() => process.exit(0), 700).unref();
         };
         ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT', 'SIGUSR2'].forEach(sig => process.on(sig, () => void shutdown(sig)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lensmcp/cluster",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Run your Nx workspace as a local production cluster: pods on unix sockets with true HMR, one https gateway with per-project domains, scale-from-zero, autoscale, idle-kill, local-CA TLS — observed by the LensMCP lens.",
   "main": "./index.js",
   "types": "./index.d.ts",
@@ -31,7 +31,12 @@
     "webpack": "^5.0.0",
     "fastify": "^5.0.0",
     "@fastify/reply-from": "^12.0.0",
-    "ioredis": "^5.0.0"
+    "ioredis": "^5.0.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "^1.30.0",
+    "@opentelemetry/resources": "^1.30.0",
+    "@opentelemetry/sdk-trace-base": "^1.30.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.57.0"
   },
   "peerDependenciesMeta": {
     "fastify": {
@@ -42,6 +47,21 @@
     },
     "ioredis": {
       "optional": true
+    },
+    "@opentelemetry/api": {
+      "optional": true
+    },
+    "@opentelemetry/core": {
+      "optional": true
+    },
+    "@opentelemetry/resources": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-trace-base": {
+      "optional": true
+    },
+    "@opentelemetry/exporter-trace-otlp-http": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -53,6 +73,7 @@
     "node-forge": "^1.3.1",
     "pino-pretty": "^13.0.0",
     "terser": "^5.0.0",
+    "tslib": "^2.3.0",
     "webpack-node-externals": "^3.0.0"
   },
   "devDependencies": {