@rivalis/fleet 8.0.0

package/lib/wire.js

@@ -0,0 +1,507 @@
+"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/wire/index.ts
+var wire_exports = {};
+__export(wire_exports, {
+  ALLOWED_ENDPOINT_SCHEMES: () => ALLOWED_ENDPOINT_SCHEMES,
+  MAX_ENDPOINT_URL_LENGTH: () => MAX_ENDPOINT_URL_LENGTH,
+  MAX_INFLIGHT_COMMANDS: () => MAX_INFLIGHT_COMMANDS,
+  MAX_LABELS: () => MAX_LABELS,
+  MAX_LABEL_KEY_LENGTH: () => MAX_LABEL_KEY_LENGTH,
+  MAX_LABEL_VALUE_LENGTH: () => MAX_LABEL_VALUE_LENGTH,
+  MAX_NAME_LENGTH: () => MAX_NAME_LENGTH,
+  MAX_ROOMS: () => MAX_ROOMS,
+  MAX_ROOM_CONNECTIONS: () => MAX_ROOM_CONNECTIONS,
+  MAX_ROOM_ID_LENGTH: () => MAX_ROOM_ID_LENGTH,
+  MAX_ROOM_TYPES: () => MAX_ROOM_TYPES,
+  MAX_ROOM_TYPE_LENGTH: () => MAX_ROOM_TYPE_LENGTH,
+  PROTOCOL_VERSION: () => PROTOCOL_VERSION,
+  Topics: () => Topics,
+  WS_SUBPROTOCOL: () => WS_SUBPROTOCOL,
+  WireVersionError: () => WireVersionError,
+  decodeFrame: () => decodeFrame,
+  encodeFrame: () => encodeFrame,
+  syncPayloadSchema: () => syncPayloadSchema,
+  validateSnapshot: () => validateSnapshot
+});
+module.exports = __toCommonJS(wire_exports);
+
+// src/wire/topics.ts
+var PROTOCOL_VERSION = 3;
+var WS_SUBPROTOCOL = "rivalis-fleet.v1";
+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/snapshotSchema.ts
+var MAX_ENDPOINT_URL_LENGTH = 512;
+var MAX_NAME_LENGTH = 64;
+var MAX_LABELS = 32;
+var MAX_LABEL_KEY_LENGTH = 64;
+var MAX_LABEL_VALUE_LENGTH = 64;
+var MAX_ROOM_TYPES = 256;
+var MAX_ROOMS = 5e4;
+var MAX_ROOM_ID_LENGTH = 256;
+var MAX_ROOM_TYPE_LENGTH = 64;
+var MAX_ROOM_CONNECTIONS = 1e6;
+var ALLOWED_ENDPOINT_SCHEMES = /* @__PURE__ */ new Set(["ws:", "wss:", "http:", "https:"]);
+var syncPayloadSchema = {
+  endpointUrl: { type: "string", required: true, max: MAX_ENDPOINT_URL_LENGTH },
+  name: { type: "string", required: true, max: MAX_NAME_LENGTH },
+  labels: { type: "object", required: true },
+  roomTypes: { type: "array", required: true, max: MAX_ROOM_TYPES, items: { type: "string", max: MAX_ROOM_TYPE_LENGTH } },
+  rooms: { type: "array", required: true, max: MAX_ROOMS, items: { type: "object" } }
+};
+function checkRule(field, value, rule) {
+  if (value === void 0 || value === null) {
+    return rule.required === true ? `${field} is required` : null;
+  }
+  switch (rule.type) {
+    case "string":
+      if (typeof value !== "string") {
+        return `${field} must be a string`;
+      }
+      if (rule.max !== void 0 && value.length > rule.max) {
+        return `${field} exceeds ${rule.max} characters`;
+      }
+      if (rule.min !== void 0 && value.length < rule.min) {
+        return `${field} must be at least ${rule.min} characters`;
+      }
+      if (rule.pattern !== void 0 && !new RegExp(rule.pattern).test(value)) {
+        return `${field} has an invalid format`;
+      }
+      return null;
+    case "number":
+    case "integer":
+      if (typeof value !== "number" || rule.type === "integer" && !Number.isInteger(value)) {
+        return `${field} must be a number`;
+      }
+      if (rule.max !== void 0 && value > rule.max) {
+        return `${field} exceeds ${rule.max}`;
+      }
+      if (rule.min !== void 0 && value < rule.min) {
+        return `${field} is below ${rule.min}`;
+      }
+      return null;
+    case "boolean":
+      return typeof value === "boolean" ? null : `${field} must be a boolean`;
+    case "object":
+      return typeof value === "object" && !Array.isArray(value) ? null : `${field} must be an object`;
+    case "array":
+      if (!Array.isArray(value)) {
+        return `${field} must be an array`;
+      }
+      if (rule.max !== void 0 && value.length > rule.max) {
+        return `${field} exceeds ${rule.max} entries`;
+      }
+      if (rule.min !== void 0 && value.length < rule.min) {
+        return `${field} must have at least ${rule.min} entries`;
+      }
+      if (rule.items !== void 0) {
+        for (const entry of value) {
+          const reason = checkRule(`${field} entry`, entry, rule.items);
+          if (reason !== null) {
+            return reason;
+          }
+        }
+      }
+      return null;
+    default:
+      return null;
+  }
+}
+function checkSchema(schema, data) {
+  for (const key of Object.keys(schema)) {
+    const rule = schema[key];
+    if (rule === void 0) {
+      continue;
+    }
+    const reason = checkRule(key, data[key], rule);
+    if (reason !== null) {
+      return reason;
+    }
+  }
+  return null;
+}
+function validateSnapshot(payload) {
+  const data = payload;
+  const reason = checkSchema(syncPayloadSchema, data);
+  if (reason !== null) {
+    return reason;
+  }
+  let parsed;
+  try {
+    parsed = new URL(payload.endpointUrl);
+  } catch {
+    return "endpointUrl is not a valid URL";
+  }
+  if (!ALLOWED_ENDPOINT_SCHEMES.has(parsed.protocol)) {
+    return "endpointUrl scheme is not allowed";
+  }
+  const labels = payload.labels;
+  const labelKeys = Object.keys(labels);
+  if (labelKeys.length > MAX_LABELS) {
+    return `labels exceeds ${MAX_LABELS} entries`;
+  }
+  for (const key of labelKeys) {
+    if (key.length > MAX_LABEL_KEY_LENGTH) {
+      return `a label key exceeds ${MAX_LABEL_KEY_LENGTH} characters`;
+    }
+    const value = labels[key];
+    if (typeof value !== "string" || value.length > MAX_LABEL_VALUE_LENGTH) {
+      return `a label value is not a string of at most ${MAX_LABEL_VALUE_LENGTH} characters`;
+    }
+  }
+  const rooms = payload.rooms;
+  for (const entry of rooms) {
+    const id = entry.id;
+    if (typeof id !== "string" || id.length > MAX_ROOM_ID_LENGTH) {
+      return `a room id is not a string of at most ${MAX_ROOM_ID_LENGTH} characters`;
+    }
+    const type = entry.type;
+    if (typeof type !== "string" || type.length > MAX_ROOM_TYPE_LENGTH) {
+      return `a room type is not a string of at most ${MAX_ROOM_TYPE_LENGTH} characters`;
+    }
+    const connections = entry.connections;
+    if (typeof connections !== "number" || connections > MAX_ROOM_CONNECTIONS) {
+      return `a room connections value exceeds ${MAX_ROOM_CONNECTIONS}`;
+    }
+  }
+  return null;
+}
+
+// src/wire/serializer.ts
+var import_node_module = require("module");
+var import_meta = {};
+var WIRE_MAJOR = PROTOCOL_VERSION;
+var WIRE_MINOR = 0;
+var HEADER_BYTES = 2;
+var WireVersionError = class extends Error {
+  /** The major byte read off the incompatible frame (123 for a legacy JSON `{...}` frame). */
+  theirVersion;
+  /** This build's protocol major. */
+  ourVersion;
+  constructor(theirVersion) {
+    super(
+      `fleet wire protocol version mismatch: peer speaks major v${theirVersion}, this build speaks v${PROTOCOL_VERSION} \u2014 agents and orchestrator must run the same @rivalis/fleet major (\xA77). A v1 (JSON) peer against a v${PROTOCOL_VERSION} peer is exactly this case; upgrade both halves in lockstep.`
+    );
+    this.name = "WireVersionError";
+    this.theirVersion = theirVersion;
+    this.ourVersion = PROTOCOL_VERSION;
+  }
+};
+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
+};
+var serializer = null;
+function getSerializer() {
+  if (serializer !== null) {
+    return serializer;
+  }
+  const metaUrl = import_meta.url;
+  const req = metaUrl ? (0, import_node_module.createRequire)(metaUrl) : require;
+  const mod = req("@toolcase/serializer");
+  const Serializer = mod.Serializer ?? mod.default;
+  const F = Serializer.FieldType;
+  const s = new Serializer("fleet");
+  s.define(Type.Label, [
+    { key: "key", type: F.STRING, rule: "optional" },
+    { key: "value", type: F.STRING, rule: "optional" }
+  ]);
+  s.define(Type.SyncRoom, [
+    { key: "id", type: F.STRING, rule: "optional" },
+    { key: "type", type: F.STRING, rule: "optional" },
+    { key: "connections", type: F.UINT32, rule: "optional" },
+    { key: "origin", type: F.STRING, rule: "optional" }
+  ]);
+  s.define(Type.Capacity, [
+    // null = unlimited (§6). Absent on the wire ⇒ null; an explicit 0 ⇒ 0.
+    { key: "maxConnections", type: F.INT32, rule: "optional", default: null },
+    { key: "maxRooms", type: F.INT32, rule: "optional", default: null }
+  ]);
+  s.define(Type.AckRoom, [
+    { key: "id", type: F.STRING, rule: "optional" },
+    { key: "type", type: F.STRING, rule: "optional" }
+  ]);
+  s.define(Type.Hello, [
+    { key: "instanceId", type: F.STRING, rule: "optional" },
+    { key: "protocolVersion", type: F.UINT32, rule: "optional" },
+    { key: "heartbeatMs", type: F.UINT32, rule: "optional" }
+  ]);
+  s.define(Type.Poll, [
+    { key: "reqId", type: F.STRING, rule: "optional" },
+    // Absent ⇒ null (no prior state / forced full, subsumes the old fleet/resync).
+    { key: "knownHash", type: F.STRING, rule: "optional" },
+    { key: "status", type: F.STRING, rule: "optional" }
+  ]);
+  s.define(Type.State, [
+    { key: "reqId", type: F.STRING, rule: "optional" },
+    // full=false is a hash-only liveness reply: the snapshot fields below are
+    // omitted on the wire (preserving the old sync/ping dedup, orch-initiated).
+    { key: "full", type: F.BOOL, rule: "optional" },
+    { key: "seq", type: F.UINT32, rule: "optional" },
+    { key: "hash", type: F.STRING, rule: "optional" },
+    { key: "name", type: F.STRING, rule: "optional" },
+    { key: "processUid", type: F.STRING, rule: "optional" },
+    { key: "agentVersion", type: F.STRING, rule: "optional" },
+    { key: "protocolVersion", type: F.UINT32, rule: "optional" },
+    { key: "endpointUrl", type: F.STRING, rule: "optional" },
+    { key: "labels", type: Type.Label, rule: "repeated" },
+    { key: "capacity", type: Type.Capacity, rule: "optional" },
+    { key: "autoCreate", type: F.BOOL, rule: "optional" },
+    { key: "roomTypes", type: F.STRING, rule: "repeated" },
+    { key: "rooms", type: Type.SyncRoom, rule: "repeated" },
+    { key: "status", type: F.STRING, rule: "optional" }
+  ]);
+  s.define(Type.Cmd, [
+    { key: "cmdId", type: F.STRING, rule: "optional" },
+    { key: "op", type: F.STRING, rule: "optional" },
+    { key: "roomId", type: F.STRING, rule: "optional" },
+    { key: "roomType", type: F.STRING, rule: "optional" }
+  ]);
+  s.define(Type.Ack, [
+    { key: "cmdId", type: F.STRING, rule: "optional" },
+    { key: "ok", type: F.BOOL, rule: "optional" },
+    { key: "error", type: F.STRING, rule: "optional" },
+    { key: "alreadyGone", type: F.BOOL, rule: "optional" },
+    { key: "room", type: Type.AckRoom, rule: "optional" },
+    // APPEND-ONLY (task 003): the room-already-exists signal must stay LAST so
+    // existing tags are unmoved (see the append-only tag rule in the file header).
+    { key: "exists", type: F.BOOL, rule: "optional" }
+  ]);
+  serializer = s;
+  return s;
+}
+function present(obj, key) {
+  return obj !== null && obj !== void 0 && Object.prototype.hasOwnProperty.call(obj, key);
+}
+function labelsToList(labels) {
+  return Object.entries(labels ?? {}).map(([key, value]) => ({ key, value }));
+}
+function labelsFromList(list) {
+  const labels = {};
+  for (const entry of list ?? []) {
+    labels[entry.key ?? ""] = entry.value ?? "";
+  }
+  return labels;
+}
+function capacityToMessage(capacity) {
+  return {
+    maxConnections: capacity?.maxConnections ?? null,
+    maxRooms: capacity?.maxRooms ?? null
+  };
+}
+function capacityFromMessage(capacity) {
+  return {
+    // Absent ⇒ null (unlimited, §6); an explicit 0 is preserved as 0.
+    maxConnections: present(capacity, "maxConnections") ? capacity.maxConnections : null,
+    maxRooms: present(capacity, "maxRooms") ? capacity.maxRooms : null
+  };
+}
+function stateToMessage(p) {
+  if (!p.full) {
+    return { reqId: p.reqId, full: false, seq: p.seq, hash: p.hash };
+  }
+  return {
+    reqId: p.reqId,
+    full: true,
+    seq: p.seq,
+    hash: p.hash,
+    name: p.name,
+    processUid: p.processUid,
+    agentVersion: p.agentVersion,
+    protocolVersion: p.protocolVersion,
+    endpointUrl: p.endpointUrl,
+    labels: labelsToList(p.labels),
+    capacity: capacityToMessage(p.capacity),
+    autoCreate: p.autoCreate,
+    roomTypes: p.roomTypes ?? [],
+    rooms: (p.rooms ?? []).map((r) => ({
+      id: r.id,
+      type: r.type,
+      connections: r.connections,
+      origin: r.origin
+    })),
+    status: p.status
+  };
+}
+function stateFromMessage(m) {
+  return {
+    reqId: m.reqId ?? "",
+    full: m.full ?? false,
+    seq: m.seq ?? 0,
+    hash: m.hash ?? "",
+    name: m.name ?? "",
+    processUid: m.processUid ?? "",
+    agentVersion: m.agentVersion ?? "",
+    protocolVersion: m.protocolVersion ?? 0,
+    endpointUrl: m.endpointUrl ?? "",
+    labels: labelsFromList(m.labels),
+    capacity: capacityFromMessage(m.capacity),
+    autoCreate: m.autoCreate ?? false,
+    roomTypes: Array.isArray(m.roomTypes) ? m.roomTypes : [],
+    rooms: (Array.isArray(m.rooms) ? m.rooms : []).map((r) => ({
+      id: r.id ?? "",
+      type: r.type ?? "",
+      connections: r.connections ?? 0,
+      origin: r.origin ?? "local"
+    })),
+    status: m.status ?? "active"
+  };
+}
+function toMessage(topic, payload) {
+  switch (topic) {
+    case Topics.state:
+      return stateToMessage(payload);
+    case Topics.poll: {
+      const p = payload;
+      const msg = { reqId: p.reqId, status: p.status };
+      if (p.knownHash !== null && p.knownHash !== void 0) {
+        msg.knownHash = p.knownHash;
+      }
+      return msg;
+    }
+    default:
+      return payload;
+  }
+}
+function fromMessage(topic, m) {
+  switch (topic) {
+    case Topics.hello:
+      return {
+        instanceId: m.instanceId ?? "",
+        protocolVersion: m.protocolVersion ?? 0,
+        heartbeatMs: m.heartbeatMs ?? 0
+      };
+    case Topics.poll:
+      return {
+        reqId: m.reqId ?? "",
+        // Absent knownHash ⇒ null (no prior state / forced full).
+        knownHash: present(m, "knownHash") ? m.knownHash : null,
+        status: m.status ?? "active"
+      };
+    case Topics.state:
+      return stateFromMessage(m);
+    case Topics.cmd: {
+      const cmd = { cmdId: m.cmdId ?? "", op: m.op };
+      if (present(m, "roomId")) {
+        cmd.roomId = m.roomId;
+      }
+      if (present(m, "roomType")) {
+        cmd.roomType = m.roomType;
+      }
+      return cmd;
+    }
+    case Topics.ack: {
+      const ack = { cmdId: m.cmdId ?? "", ok: m.ok ?? false };
+      if (present(m, "error")) {
+        ack.error = m.error;
+      }
+      if (present(m, "alreadyGone")) {
+        ack.alreadyGone = m.alreadyGone;
+      }
+      if (present(m, "exists")) {
+        ack.exists = m.exists;
+      }
+      if (present(m, "room")) {
+        ack.room = { id: m.room.id ?? "", type: m.room.type ?? "" };
+      }
+      return ack;
+    }
+    default:
+      return m;
+  }
+}
+function encodeFrame(topic, payload) {
+  const type = TOPIC_TYPE[topic];
+  if (type === void 0) {
+    throw new Error(`fleet wire: no message type for topic=${topic}`);
+  }
+  const body = getSerializer().encode(type, toMessage(topic, payload));
+  const frame = new Uint8Array(HEADER_BYTES + body.length);
+  frame[0] = WIRE_MAJOR;
+  frame[1] = WIRE_MINOR;
+  frame.set(body, HEADER_BYTES);
+  return frame;
+}
+function decodeFrame(topic, frame) {
+  const type = TOPIC_TYPE[topic];
+  if (type === void 0) {
+    throw new Error(`fleet wire: no message type for topic=${topic}`);
+  }
+  if (frame === null || frame === void 0 || frame.length < HEADER_BYTES) {
+    throw new Error("fleet wire: truncated frame (shorter than the 2-byte version header)");
+  }
+  const major = frame[0];
+  if (major !== WIRE_MAJOR) {
+    throw new WireVersionError(major);
+  }
+  const body = frame.subarray(HEADER_BYTES);
+  const decoded = getSerializer().decode(type, body);
+  return fromMessage(topic, decoded);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ALLOWED_ENDPOINT_SCHEMES,
+  MAX_ENDPOINT_URL_LENGTH,
+  MAX_INFLIGHT_COMMANDS,
+  MAX_LABELS,
+  MAX_LABEL_KEY_LENGTH,
+  MAX_LABEL_VALUE_LENGTH,
+  MAX_NAME_LENGTH,
+  MAX_ROOMS,
+  MAX_ROOM_CONNECTIONS,
+  MAX_ROOM_ID_LENGTH,
+  MAX_ROOM_TYPES,
+  MAX_ROOM_TYPE_LENGTH,
+  PROTOCOL_VERSION,
+  Topics,
+  WS_SUBPROTOCOL,
+  WireVersionError,
+  decodeFrame,
+  encodeFrame,
+  syncPayloadSchema,
+  validateSnapshot
+});

package/package.json

@@ -0,0 +1,78 @@
+{
+    "name": "@rivalis/fleet",
+    "version": "8.0.0",
+    "description": "Fleet orchestration for Rivalis: instance discovery, room placement, cluster control",
+    "source": "src/main.ts",
+    "main": "lib/main.js",
+    "module": "lib/module.js",
+    "types": "lib/main.d.ts",
+    "exports": {
+        ".": {
+            "types": "./lib/main.d.ts",
+            "import": "./lib/module.js",
+            "require": "./lib/main.js"
+        }
+    },
+    "bin": {
+        "rivalis-fleet": "bin/rivalis-fleet.js"
+    },
+    "engines": {
+        "node": ">=18"
+    },
+    "scripts": {
+        "dev": "tsup --watch",
+        "build": "tsup",
+        "test": "npm run build && node --test \"test/**/*.test.mts\""
+    },
+    "dependencies": {
+        "@fastify/cors": "^11.2.0",
+        "@toolcase/node": "^4.0.0",
+        "@toolcase/serializer": "3.x",
+        "commander": "^12.1.0",
+        "fastify": "^5.8.5",
+        "redis": "^5.12.1"
+    },
+    "peerDependencies": {
+        "@rivalis/core": ">=8 <9",
+        "@rivalis/node": ">=8 <9",
+        "@toolcase/base": "3.x",
+        "@toolcase/logging": "3.x",
+        "ws": "8.x"
+    },
+    "devDependencies": {
+        "@rivalis/core": "*",
+        "@rivalis/node": "*"
+    },
+    "keywords": [
+        "realtime",
+        "websockets",
+        "orchestration",
+        "fleet",
+        "cluster",
+        "multiplayer",
+        "rivalis"
+    ],
+    "directories": {
+        "lib": "lib"
+    },
+    "files": [
+        "lib",
+        "bin"
+    ],
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/kalevski/rivalis.git"
+    },
+    "author": {
+        "name": "kalevski"
+    },
+    "license": "MIT",
+    "bugs": {
+        "url": "https://github.com/kalevski/rivalis/issues"
+    },
+    "homepage": "https://github.com/kalevski/rivalis#readme"
+}