@rivalis/fleet 8.0.0

package/lib/routers.js

@@ -0,0 +1,598 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/routers/index.ts
+var routers_exports = {};
+__export(routers_exports, {
+  AUTH_FAILURE_LIMIT: () => AUTH_FAILURE_LIMIT,
+  AUTH_FAILURE_WINDOW_MS: () => AUTH_FAILURE_WINDOW_MS,
+  AuthThrottle: () => AuthThrottle,
+  MAX_BODY_BYTES: () => MAX_BODY_BYTES,
+  MAX_SSE_STREAMS: () => MAX_SSE_STREAMS,
+  MAX_THROTTLE_BUCKETS: () => MAX_THROTTLE_BUCKETS,
+  SSE_PING_MS: () => SSE_PING_MS,
+  createHttpApi: () => createHttpApi
+});
+module.exports = __toCommonJS(routers_exports);
+var import_fastify = __toESM(require("fastify"));
+var import_cors = __toESM(require("@fastify/cors"));
+var import_node8 = require("@toolcase/node");
+
+// src/routers/shared.ts
+var import_node_crypto2 = require("crypto");
+var import_base = require("@toolcase/base");
+var import_node2 = require("@toolcase/node");
+
+// src/orchestrator/AgentAuthenticator.ts
+var import_node_crypto = require("crypto");
+function matchKey(presented, keys) {
+  if (typeof presented !== "string" || presented.length === 0 || keys.length === 0) {
+    return null;
+  }
+  const presentedDigest = (0, import_node_crypto.createHash)("sha256").update(presented).digest();
+  let matched = null;
+  for (const key of keys) {
+    const candidate = (0, import_node_crypto.createHash)("sha256").update(key).digest();
+    if ((0, import_node_crypto.timingSafeEqual)(presentedDigest, candidate)) {
+      matched = key;
+    }
+  }
+  return matched;
+}
+
+// src/domain/roomId.ts
+var ROOM_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+
+// src/domain/roomCreate.ts
+var roomCreateSchema = {
+  type: { type: "string", required: true, min: 1 },
+  roomId: { type: "string", pattern: ROOM_ID_PATTERN.source },
+  placement: { type: "object" }
+};
+
+// src/domain/errors.ts
+var import_node = require("@toolcase/node");
+var CODE_TO_STATUS = {
+  VALIDATION: 400,
+  UNAUTHORIZED: 401,
+  INSTANCE_NOT_FOUND: 404,
+  ROOM_NOT_FOUND: 404,
+  NO_CANDIDATE: 409,
+  ROOM_EXISTS: 409,
+  INSTANCE_DRAINING: 409,
+  PAYLOAD_TOO_LARGE: 413,
+  INSTANCE_BUSY: 429,
+  AUTH_THROTTLED: 429,
+  SSE_LIMIT: 429,
+  COMMAND_FAILED: 502,
+  INSTANCE_DISCONNECTED: 502,
+  COMMAND_TIMEOUT: 504
+};
+var FleetError = class extends import_node.EndpointError {
+  constructor(code, message) {
+    super(CODE_TO_STATUS[code], code, message);
+    this.name = "FleetError";
+  }
+};
+
+// src/util/errors.ts
+function describe(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/routers/shared.ts
+var MAX_BODY_BYTES = 64 * 1024;
+var SSE_PING_MS = 15e3;
+var AUTH_FAILURE_LIMIT = 10;
+var AUTH_FAILURE_WINDOW_MS = 6e4;
+var MAX_SSE_STREAMS = 100;
+var MAX_THROTTLE_BUCKETS = 4096;
+function createContext(deps) {
+  const now = deps.now ?? Date.now;
+  return {
+    deps,
+    throttle: new AuthThrottle(AUTH_FAILURE_LIMIT, AUTH_FAILURE_WINDOW_MS, now),
+    streams: /* @__PURE__ */ new Set(),
+    pingMs: deps.ssePingMs ?? SSE_PING_MS,
+    maxStreams: deps.maxSseStreams ?? MAX_SSE_STREAMS,
+    authInfo: /* @__PURE__ */ new WeakMap()
+  };
+}
+function restOk(reply, data, status = import_base.HTTP.Status.OK) {
+  reply.code(status);
+  return new import_base.HTTP.RESTResponse(status, data);
+}
+function restError(reply, status, cause) {
+  reply.code(status);
+  return new import_base.HTTP.RESTError(status, cause).toJSON();
+}
+function installErrorHandlers(fastify, getLogger) {
+  fastify.setNotFoundHandler((req, reply) => restError(reply, import_base.HTTP.Status.NOT_FOUND, "NOT_FOUND"));
+  fastify.setErrorHandler((error, req, reply) => {
+    const meta = (0, import_node2.errorMeta)(error);
+    if (meta !== null) {
+      return restError(reply, meta.status, meta.code ?? "INTERNAL");
+    }
+    const status = error.statusCode;
+    if (status === import_base.HTTP.Status.PAYLOAD_TOO_LARGE) {
+      return restError(reply, import_base.HTTP.Status.PAYLOAD_TOO_LARGE, "PAYLOAD_TOO_LARGE");
+    }
+    if (typeof status === "number" && status >= 400 && status < 500) {
+      return restError(reply, status, "VALIDATION");
+    }
+    getLogger().error(`unhandled error on ${req.method} ${pathOf(req)}: ${describe(error)}`);
+    return restError(reply, import_base.HTTP.Status.INTERNAL_SERVER_ERROR, "INTERNAL");
+  });
+}
+function sendConditional(req, reply, deps, data) {
+  const etag = weakEtag(deps.fleet.stats.stateHash);
+  reply.header("etag", etag);
+  if (ifNoneMatchMatches(req, etag)) {
+    reply.code(import_base.HTTP.Status.NOT_MODIFIED);
+    return null;
+  }
+  return restOk(reply, data);
+}
+function weakEtag(stateHash) {
+  return `W/"${stateHash}"`;
+}
+function ifNoneMatchMatches(req, etag) {
+  const header = req.headers["if-none-match"];
+  if (typeof header !== "string") {
+    return false;
+  }
+  if (header.trim() === "*") {
+    return true;
+  }
+  return header.split(",").some((candidate) => candidate.trim() === etag);
+}
+function bearerToken(req) {
+  const header = req.headers["authorization"];
+  if (typeof header !== "string") {
+    return null;
+  }
+  const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+  return match === null ? null : match[1];
+}
+function fingerprint(key) {
+  return "key#" + (0, import_node_crypto2.createHash)("sha256").update(key).digest("hex").slice(0, 8);
+}
+function remoteIp(req) {
+  return req.ip ?? "unknown";
+}
+function pathOf(req) {
+  const url = req.url;
+  const q = url.indexOf("?");
+  return q === -1 ? url : url.slice(0, q);
+}
+function isEventsPath(req) {
+  return req.method === "GET" && pathOf(req) === "/v1/events";
+}
+function isMutatingRoute(req) {
+  const path = pathOf(req);
+  if (req.method === "POST" && path === "/v1/rooms") {
+    return true;
+  }
+  if (req.method === "DELETE" && /^\/v1\/rooms\/.+$/.test(path)) {
+    return true;
+  }
+  if (req.method === "POST" && /^\/v1\/instances\/[^/]+\/(drain|undrain)$/.test(path)) {
+    return true;
+  }
+  return false;
+}
+async function authHook(ctx, req) {
+  const ip = remoteIp(req);
+  const path = pathOf(req);
+  if (ctx.throttle.blocked(ip)) {
+    ctx.deps.getLogger().warning(`auth throttled ip=${ip} route=${req.method} ${path}`);
+    throw new FleetError("AUTH_THROTTLED", "too many failed authentication attempts");
+  }
+  let matched = matchKey(bearerToken(req), ctx.deps.config.adminKeys);
+  if (matched === null && isEventsPath(req) && ctx.deps.config.sseQueryAuth) {
+    const queryKey = req.query?.["key"];
+    if (typeof queryKey === "string") {
+      matched = matchKey(queryKey, ctx.deps.config.adminKeys);
+    }
+  }
+  if (matched === null) {
+    ctx.throttle.recordFailure(ip);
+    ctx.deps.getLogger().warning(`auth failure ip=${ip} route=${req.method} ${path}`);
+    throw new FleetError("UNAUTHORIZED", "missing or invalid admin key");
+  }
+  ctx.authInfo.set(req, { fingerprint: fingerprint(matched), ip });
+}
+async function auditHook(ctx, req, reply) {
+  if (!isMutatingRoute(req)) {
+    return;
+  }
+  const info = ctx.authInfo.get(req);
+  ctx.deps.getLogger().info(
+    `audit route=${req.method} ${pathOf(req)} key=${info?.fingerprint ?? "unknown"} ip=${info?.ip ?? remoteIp(req)} outcome=${reply.statusCode}`
+  );
+}
+function corsHeadersForSse(req, cors2) {
+  if (cors2 === false) {
+    return {};
+  }
+  const origin = req.headers["origin"];
+  if (typeof origin !== "string") {
+    return {};
+  }
+  if (cors2.origins.includes("*")) {
+    return { "access-control-allow-origin": "*" };
+  }
+  if (cors2.origins.includes(origin)) {
+    return { "access-control-allow-origin": origin, vary: "Origin" };
+  }
+  return {};
+}
+var AuthThrottle = class {
+  constructor(limit, windowMs, now, maxBuckets = MAX_THROTTLE_BUCKETS) {
+    this.limit = limit;
+    this.windowMs = windowMs;
+    this.now = now;
+    this.maxBuckets = maxBuckets;
+  }
+  limit;
+  windowMs;
+  now;
+  maxBuckets;
+  buckets = /* @__PURE__ */ new Map();
+  /** Wall-clock of the last opportunistic sweep; gates pruning to once per window. */
+  lastPruneAt = -Infinity;
+  /** True when the IP is over its failed-auth budget (no tokens left). */
+  blocked(ip) {
+    return this.refill(ip).tokens < 1;
+  }
+  /** Charge one token for a failed attempt (floored at zero). */
+  recordFailure(ip) {
+    const bucket = this.refill(ip);
+    bucket.tokens = Math.max(0, bucket.tokens - 1);
+  }
+  /** Current bucket count — a test seam for the §13 memory-bound assertions. */
+  get size() {
+    return this.buckets.size;
+  }
+  refill(ip) {
+    const now = this.now();
+    this.prune(now);
+    let bucket = this.buckets.get(ip);
+    if (bucket === void 0) {
+      bucket = { tokens: this.limit, last: now };
+      this.buckets.set(ip, bucket);
+      this.evictIfOver();
+      return bucket;
+    }
+    const elapsed = now - bucket.last;
+    if (elapsed > 0) {
+      bucket.tokens = Math.min(this.limit, bucket.tokens + elapsed / this.windowMs * this.limit);
+      bucket.last = now;
+    }
+    return bucket;
+  }
+  /**
+   * Opportunistic sweep (≤ once per window): delete every bucket that has fully
+   * refilled and not been touched within the last window. Such a bucket holds no
+   * information — a fresh IP starts full — so removing it cannot un-throttle anyone.
+   * Computing the *refilled* token count (not the stored one) also reclaims buckets
+   * stuck below full only because the IP never returned after a single failure.
+   */
+  prune(now) {
+    if (now - this.lastPruneAt < this.windowMs) {
+      return;
+    }
+    this.lastPruneAt = now;
+    for (const [ip, bucket] of this.buckets) {
+      const elapsed = now - bucket.last;
+      if (elapsed <= this.windowMs) {
+        continue;
+      }
+      const refilled = Math.min(this.limit, bucket.tokens + elapsed / this.windowMs * this.limit);
+      if (refilled >= this.limit) {
+        this.buckets.delete(ip);
+      }
+    }
+  }
+  /** Hard cap: when over {@link maxBuckets}, evict the oldest-touched bucket. */
+  evictIfOver() {
+    if (this.buckets.size <= this.maxBuckets) {
+      return;
+    }
+    let oldestIp = null;
+    let oldest = Infinity;
+    for (const [ip, bucket] of this.buckets) {
+      if (bucket.last < oldest) {
+        oldest = bucket.last;
+        oldestIp = ip;
+      }
+    }
+    if (oldestIp !== null) {
+      this.buckets.delete(oldestIp);
+    }
+  }
+};
+
+// src/routers/HealthRouter.ts
+var import_node3 = require("@toolcase/node");
+var import_base2 = require("@toolcase/base");
+var HealthRouter = class extends import_node3.RouteHandler {
+  constructor(ctx) {
+    super();
+    this.ctx = ctx;
+  }
+  ctx;
+  register(fastify) {
+    fastify.get("/healthz", async (_req, reply) => restOk(reply));
+    fastify.get("/readyz", async (_req, reply) => {
+      if (this.ctx.deps.isReady()) {
+        return restOk(reply);
+      }
+      return restError(reply, import_base2.HTTP.Status.SERVICE_UNAVAILABLE, "NOT_READY");
+    });
+  }
+};
+
+// src/routers/StatsRouter.ts
+var import_node4 = require("@toolcase/node");
+var StatsRouter = class extends import_node4.RouteHandler {
+  constructor(ctx) {
+    super();
+    this.ctx = ctx;
+  }
+  ctx;
+  register(fastify) {
+    fastify.get("/stats", async (req, reply) => sendConditional(req, reply, this.ctx.deps, this.ctx.deps.fleet.stats));
+  }
+};
+
+// src/routers/InstancesRouter.ts
+var import_node5 = require("@toolcase/node");
+var InstancesRouter = class extends import_node5.RouteHandler {
+  constructor(ctx) {
+    super();
+    this.ctx = ctx;
+  }
+  ctx;
+  register(fastify) {
+    const deps = this.ctx.deps;
+    fastify.get("/instances", async (req, reply) => sendConditional(req, reply, deps, deps.fleet.instances));
+    fastify.get("/instances/:id", async (req, reply) => {
+      const id = paramId(req);
+      const instance = deps.fleet.getInstance(id);
+      if (instance === null) {
+        throw new FleetError("INSTANCE_NOT_FOUND", `instance ${id} not found`);
+      }
+      return restOk(reply, instance);
+    });
+    fastify.get("/instances/:id/rooms", async (req, reply) => {
+      const id = paramId(req);
+      if (deps.fleet.getInstance(id) === null) {
+        throw new FleetError("INSTANCE_NOT_FOUND", `instance ${id} not found`);
+      }
+      return restOk(reply, deps.fleet.findRooms({ instanceId: id }));
+    });
+    fastify.post("/instances/:id/drain", async (req, reply) => {
+      await deps.fleet.drainInstance(paramId(req));
+      return restOk(reply);
+    });
+    fastify.post("/instances/:id/undrain", async (req, reply) => {
+      await deps.fleet.undrainInstance(paramId(req));
+      return restOk(reply);
+    });
+  }
+};
+function paramId(req) {
+  return req.params.id;
+}
+
+// src/routers/RoomsRouter.ts
+var import_node6 = require("@toolcase/node");
+var import_base3 = require("@toolcase/base");
+var roomCreateBodySchema = (0, import_node6.deriveJsonSchema)(roomCreateSchema, "create");
+var RoomsRouter = class extends import_node6.RouteHandler {
+  constructor(ctx) {
+    super();
+    this.ctx = ctx;
+  }
+  ctx;
+  register(fastify) {
+    const deps = this.ctx.deps;
+    fastify.get("/rooms", async (req, reply) => sendConditional(req, reply, deps, deps.fleet.findRooms(roomFilter(req))));
+    fastify.post("/rooms", { schema: { body: roomCreateBodySchema } }, async (req, reply) => {
+      const created = await deps.fleet.createRoom(
+        req.body
+      );
+      return restOk(reply, created, import_base3.HTTP.Status.CREATED);
+    });
+    fastify.get("/rooms/:roomId", async (req, reply) => {
+      const roomId = publicRoomId(req);
+      const room = deps.fleet.getRoom(roomId);
+      if (room === null) {
+        throw new FleetError("ROOM_NOT_FOUND", `room ${roomId} not found`);
+      }
+      return restOk(reply, room);
+    });
+    fastify.delete("/rooms/:roomId", async (req, reply) => {
+      await deps.fleet.destroyRoom(publicRoomId(req));
+      return restOk(reply);
+    });
+  }
+};
+function roomFilter(req) {
+  const query = req.query ?? {};
+  const filter = {};
+  if (typeof query.type === "string") {
+    filter.type = query.type;
+  }
+  if (typeof query.instanceId === "string") {
+    filter.instanceId = query.instanceId;
+  }
+  const raw = query.label;
+  const labelParams = Array.isArray(raw) ? raw : raw !== void 0 ? [raw] : [];
+  if (labelParams.length > 0) {
+    const labels = {};
+    for (const entry of labelParams) {
+      if (typeof entry !== "string") {
+        continue;
+      }
+      const idx = entry.indexOf(":");
+      if (idx > 0) {
+        labels[entry.slice(0, idx)] = entry.slice(idx + 1);
+      }
+    }
+    filter.labels = labels;
+  }
+  return filter;
+}
+function publicRoomId(req) {
+  const path = pathnameOf(req);
+  const segments = path.split("/");
+  return segments[segments.length - 1] ?? "";
+}
+function pathnameOf(req) {
+  const url = req.url;
+  const q = url.indexOf("?");
+  return q === -1 ? url : url.slice(0, q);
+}
+
+// src/routers/EventsRouter.ts
+var import_node7 = require("@toolcase/node");
+var EventsRouter = class extends import_node7.RouteHandler {
+  constructor(ctx) {
+    super();
+    this.ctx = ctx;
+  }
+  ctx;
+  register(fastify) {
+    fastify.get("/events", async (req, reply) => this.stream(req, reply));
+  }
+  stream(req, reply) {
+    const ctx = this.ctx;
+    if (ctx.streams.size >= ctx.maxStreams) {
+      ctx.deps.getLogger().warning(
+        `sse stream cap reached (${ctx.maxStreams}) \u2014 rejecting new stream from ip=${remoteIp(req)}`
+      );
+      throw new FleetError("SSE_LIMIT", `concurrent SSE stream cap reached (${ctx.maxStreams})`);
+    }
+    reply.hijack();
+    const raw = reply.raw;
+    raw.writeHead(200, {
+      ...corsHeadersForSse(req, ctx.deps.config.cors),
+      "content-type": "text/event-stream; charset=utf-8",
+      "cache-control": "no-cache, no-transform",
+      connection: "keep-alive",
+      // No Last-Event-ID replay (§10): a reconnecting consumer re-GETs stats+instances.
+      "x-accel-buffering": "no"
+    });
+    const write = (chunk) => {
+      if (raw.writableEnded || raw.destroyed) {
+        return;
+      }
+      try {
+        raw.write(chunk);
+      } catch {
+      }
+    };
+    write(": connected\n\n");
+    const unsubscribe = ctx.deps.subscribe((event) => {
+      write(`event: ${event.type}
+data: ${JSON.stringify(event.data ?? null)}
+
+`);
+    });
+    const ping = setInterval(() => write(": ping\n\n"), ctx.pingMs);
+    ping.unref?.();
+    const stream = {
+      end: () => {
+        if (!raw.writableEnded) {
+          raw.end();
+        }
+      },
+      cleanup: () => {
+        clearInterval(ping);
+        unsubscribe();
+        ctx.streams.delete(stream);
+      }
+    };
+    ctx.streams.add(stream);
+    req.raw.on("close", () => stream.cleanup());
+  }
+};
+
+// src/routers/index.ts
+function createHttpApi(deps, options = {}) {
+  const ctx = createContext(deps);
+  const base = { logger: false, bodyLimit: MAX_BODY_BYTES, trustProxy: deps.config.trustProxy };
+  const fastify = options.serverFactory !== void 0 ? (0, import_fastify.default)({ ...base, serverFactory: options.serverFactory }) : (0, import_fastify.default)({ ...base });
+  installErrorHandlers(fastify, deps.getLogger);
+  if (deps.config.cors !== false) {
+    const origins = deps.config.cors.origins;
+    void fastify.register(import_cors.default, { origin: origins.includes("*") ? "*" : origins });
+  }
+  new HealthRouter(ctx).register(fastify);
+  if (deps.config.api) {
+    void fastify.register(async (v1) => {
+      v1.addHook("onRequest", (req) => authHook(ctx, req));
+      v1.addHook("onResponse", (req, reply) => auditHook(ctx, req, reply));
+      new import_node8.Router().add(new StatsRouter(ctx)).add(new InstancesRouter(ctx)).add(new RoomsRouter(ctx)).add(new EventsRouter(ctx)).register(v1);
+    }, { prefix: "/v1" });
+  }
+  const drainStreams = () => {
+    for (const stream of [...ctx.streams]) {
+      stream.cleanup();
+      stream.end();
+    }
+  };
+  return {
+    fastify,
+    ready: async () => {
+      await fastify.ready();
+    },
+    listen: async (opts) => {
+      await fastify.listen(opts);
+    },
+    shutdown: drainStreams,
+    close: async () => {
+      drainStreams();
+      await fastify.close();
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AUTH_FAILURE_LIMIT,
+  AUTH_FAILURE_WINDOW_MS,
+  AuthThrottle,
+  MAX_BODY_BYTES,
+  MAX_SSE_STREAMS,
+  MAX_THROTTLE_BUCKETS,
+  SSE_PING_MS,
+  createHttpApi
+});