@rivalis/fleet 8.0.0

package/lib/CommandEngine.js

@@ -0,0 +1,258 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/orchestrator/CommandEngine.ts
+var CommandEngine_exports = {};
+__export(CommandEngine_exports, {
+  CommandEngine: () => CommandEngine
+});
+module.exports = __toCommonJS(CommandEngine_exports);
+
+// 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/wire/topics.ts
+var MAX_INFLIGHT_COMMANDS = 32;
+var Topics = {
+  /** orch → agent: assigns id + heartbeat (poll cadence) on join; followed by the first poll. */
+  hello: "fleet/hello",
+  /** orch → agent: state poll. Carries `knownHash` (dedup) + the last recorded `status` (echo). */
+  poll: "fleet/poll",
+  /** agent → orch: poll reply. Full snapshot when the hash differs from `knownHash`, hash-only otherwise. */
+  state: "fleet/state",
+  /** orch → agent: command push. */
+  cmd: "fleet/cmd",
+  /** agent → orch: command result. */
+  ack: "fleet/ack"
+};
+
+// src/wire/serializer.ts
+var import_node_module = require("module");
+var Type = {
+  Label: "Label",
+  SyncRoom: "SyncRoom",
+  Capacity: "Capacity",
+  AckRoom: "AckRoom",
+  Hello: "Hello",
+  Poll: "Poll",
+  State: "State",
+  Cmd: "Cmd",
+  Ack: "Ack"
+};
+var TOPIC_TYPE = {
+  [Topics.hello]: Type.Hello,
+  [Topics.poll]: Type.Poll,
+  [Topics.state]: Type.State,
+  [Topics.cmd]: Type.Cmd,
+  [Topics.ack]: Type.Ack
+};
+
+// src/util/errors.ts
+function describe(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/orchestrator/CommandEngine.ts
+var CommandEngine = class {
+  constructor(scheduler, reservations, commandTimeoutMs) {
+    this.scheduler = scheduler;
+    this.reservations = reservations;
+    this.commandTimeoutMs = commandTimeoutMs;
+  }
+  scheduler;
+  reservations;
+  commandTimeoutMs;
+  /** Pending commands keyed by instance id, then by `cmdId`. */
+  pending = /* @__PURE__ */ new Map();
+  cmdSeq = 0;
+  /** Monotonic command id (`cmd_N`) — connection-agnostic, unique per orchestrator. */
+  nextCmdId() {
+    return `cmd_${++this.cmdSeq}`;
+  }
+  /** How many commands are currently in flight for an instance. */
+  inFlight(instanceId) {
+    return this.pending.get(instanceId)?.size ?? 0;
+  }
+  /**
+   * Push a `fleet/cmd` and return a promise that resolves on its `fleet/ack`
+   * (rejects on `COMMAND_FAILED`), or rejects on timeout (`COMMAND_TIMEOUT`) /
+   * disconnect (`INSTANCE_DISCONNECTED`). Caps in-flight commands per instance at
+   * {@link MAX_INFLIGHT_COMMANDS} → `INSTANCE_BUSY` rather than queueing unbounded
+   * promises behind a slow agent (§7). Reservations (create only) ride on the
+   * pending entry and are released on every settle path.
+   */
+  send(link, cmd, reservation = null, roomIdReservation = null) {
+    const map = this.mapFor(link.instanceId);
+    if (map.size >= MAX_INFLIGHT_COMMANDS) {
+      if (reservation !== null) {
+        this.reservations.release(reservation);
+      }
+      if (roomIdReservation !== null) {
+        this.reservations.releaseRoomId(roomIdReservation);
+      }
+      return Promise.reject(new FleetError(
+        "INSTANCE_BUSY",
+        `instance ${link.instanceId} has ${map.size} commands in flight (max ${MAX_INFLIGHT_COMMANDS})`
+      ));
+    }
+    return new Promise((resolve, reject) => {
+      const timer = this.scheduler.setTimeout(() => {
+        this.settle(link.instanceId, cmd.cmdId, (pending) => {
+          this.holdOrRelease(pending);
+          pending.reject(new FleetError(
+            "COMMAND_TIMEOUT",
+            `command ${cmd.cmdId} (${cmd.op}) timed out after ${this.commandTimeoutMs}ms`
+          ));
+        });
+      }, this.commandTimeoutMs);
+      map.set(cmd.cmdId, { resolve, reject, timer, reservation, roomIdReservation });
+      try {
+        link.send(Topics.cmd, cmd);
+      } catch (error) {
+        this.settle(link.instanceId, cmd.cmdId, (pending) => {
+          this.releaseReservations(pending);
+          pending.reject(new FleetError(
+            "INSTANCE_DISCONNECTED",
+            `failed to send command ${cmd.cmdId} (${cmd.op}) to instance ${link.instanceId}: ${describe(error)}`
+          ));
+        });
+      }
+    });
+  }
+  /**
+   * Resolve/reject the originating promise for an inbound `fleet/ack`. Returns
+   * `false` when no such pending exists (a late ack after a timeout, or an unknown
+   * cmd) so the caller can log-and-drop — never a double-resolve (§14).
+   */
+  ack(instanceId, ack) {
+    return this.settle(instanceId, ack.cmdId, (pending) => {
+      if (ack.ok) {
+        this.holdOrRelease(pending);
+        pending.resolve(ack);
+      } else {
+        this.releaseReservations(pending);
+        pending.reject(ack.exists === true ? new FleetError("ROOM_EXISTS", ack.error ?? "room id already exists") : new FleetError("COMMAND_FAILED", ack.error ?? "agent reported command failure"));
+      }
+    });
+  }
+  /**
+   * Reject every in-flight command for a disconnected/evicted instance immediately
+   * with `INSTANCE_DISCONNECTED` — callers never wait out `commandTimeoutMs` for an
+   * instance the orchestrator already knows is gone (§7).
+   */
+  rejectAll(instanceId, reason) {
+    const map = this.pending.get(instanceId);
+    if (map === void 0) {
+      return;
+    }
+    for (const cmdId of [...map.keys()]) {
+      this.settle(instanceId, cmdId, (pending) => {
+        this.releaseReservations(pending);
+        pending.reject(new FleetError("INSTANCE_DISCONNECTED", `instance ${instanceId} disconnected (${reason})`));
+      });
+    }
+    this.pending.delete(instanceId);
+  }
+  /**
+   * Settle exactly one pending command: delete it and clear its timer, then run
+   * `action` (which disposes the reservations — release or {@link holdOrRelease} —
+   * and resolves/rejects). Returns `false` when no such pending exists (already
+   * settled) — the single guard against double-resolve from a timeout-then-late-ack
+   * or disconnect-then-ack race (§14). Reservation disposition moved into the per-path
+   * `action` callbacks (task 003): ack-OK / timeout hold until visible, every other
+   * path releases.
+   */
+  settle(instanceId, cmdId, action) {
+    const map = this.pending.get(instanceId);
+    const pending = map?.get(cmdId);
+    if (map === void 0 || pending === void 0) {
+      return false;
+    }
+    map.delete(cmdId);
+    this.scheduler.clearTimeout(pending.timer);
+    action(pending);
+    return true;
+  }
+  /**
+   * Hold a create's reservations until its room is visible (task 003) — used on
+   * ack-OK and timeout. A create carries BOTH a capacity and a room-id reservation;
+   * any other command (destroy/drain/undrain) carries neither, so this degrades to a
+   * release of whatever (if anything) is present.
+   */
+  holdOrRelease(pending) {
+    if (pending.reservation !== null && pending.roomIdReservation !== null) {
+      this.reservations.holdUntilVisible(pending.roomIdReservation, pending.reservation);
+    } else {
+      this.releaseReservations(pending);
+    }
+  }
+  /** Release a settled command's reservations immediately (failure / disconnect / busy). */
+  releaseReservations(pending) {
+    if (pending.reservation !== null) {
+      this.reservations.release(pending.reservation);
+    }
+    if (pending.roomIdReservation !== null) {
+      this.reservations.releaseRoomId(pending.roomIdReservation);
+    }
+  }
+  mapFor(instanceId) {
+    let map = this.pending.get(instanceId);
+    if (map === void 0) {
+      map = /* @__PURE__ */ new Map();
+      this.pending.set(instanceId, map);
+    }
+    return map;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CommandEngine
+});

package/lib/EventReconciler.js

@@ -0,0 +1,90 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/orchestrator/EventReconciler.ts
+var EventReconciler_exports = {};
+__export(EventReconciler_exports, {
+  EventReconciler: () => EventReconciler
+});
+module.exports = __toCommonJS(EventReconciler_exports);
+var EventReconciler = class {
+  constructor(state, emit) {
+    this.state = state;
+    this.emit = emit;
+  }
+  state;
+  emit;
+  knownInstanceIds = /* @__PURE__ */ new Set();
+  knownRooms = /* @__PURE__ */ new Map();
+  lastStatsHash = "";
+  /**
+   * Diff the read model and emit the derived events: `instance:join` for a new
+   * instance, `room:create`/`room:destroy` for room churn, and `sync` whenever the
+   * semantic `stateHash` changes. `instance:leave` is emitted by
+   * {@link instanceRemoved}, not here.
+   */
+  reconcile() {
+    const instances = this.state.instances;
+    const currentInstanceIds = /* @__PURE__ */ new Set();
+    const currentRoomIds = /* @__PURE__ */ new Set();
+    for (const instance of instances) {
+      currentInstanceIds.add(instance.id);
+      if (!this.knownInstanceIds.has(instance.id)) {
+        this.knownInstanceIds.add(instance.id);
+        this.emit("instance:join", instance);
+      }
+      for (const room of instance.rooms) {
+        currentRoomIds.add(room.id);
+        if (!this.knownRooms.has(room.id)) {
+          this.knownRooms.set(room.id, room);
+          this.emit("room:create", room);
+        }
+      }
+    }
+    for (const [roomId, room] of [...this.knownRooms]) {
+      if (!currentRoomIds.has(roomId)) {
+        this.knownRooms.delete(roomId);
+        this.emit("room:destroy", room);
+      }
+    }
+    for (const id of [...this.knownInstanceIds]) {
+      if (!currentInstanceIds.has(id)) {
+        this.knownInstanceIds.delete(id);
+      }
+    }
+    const stats = this.state.stats;
+    if (stats.stateHash !== this.lastStatsHash) {
+      this.lastStatsHash = stats.stateHash;
+      this.emit("sync", stats);
+    }
+  }
+  /**
+   * An instance was removed from the read model (socket close or eviction): forget
+   * it and emit `instance:leave`. The caller follows with a {@link reconcile} so the
+   * vanished instance's rooms surface as `room:destroy` and the `sync` fires.
+   */
+  instanceRemoved(removed) {
+    this.knownInstanceIds.delete(removed.id);
+    this.emit("instance:leave", removed);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EventReconciler
+});