@irtio/cli 0.5.2 → 0.7.0

package/dist/rooms-52Q5KBUS.js

@@ -0,0 +1,411 @@
+import {
+  readProjectConfig
+} from "./chunk-JL235KIE.js";
+import {
+  HelpRequested,
+  helpFor,
+  helpRequested
+} from "./chunk-OCVALOGK.js";
+import {
+  createApiClient,
+  isLoginRequired
+} from "./chunk-IDF46P7R.js";
+import {
+  resolveControlUrlForUser
+} from "./chunk-UPHQM6NZ.js";
+
+// src/rooms.ts
+import "fs";
+import "fs/promises";
+import "path";
+import pc from "picocolors";
+var USAGE = `usage: irtio rooms [--active|--idle] [--idle-longer-than <d>] [options]
+       irtio rooms get <room> [options]
+       irtio rooms set <room> --retention <d|forever|clear> [options]
+       irtio rooms saves <room> [options]
+       irtio rooms restore <room> --save <id> [options]
+       irtio rooms delete <room> [--force] [options]
+
+Lists a project's rooms, with the retention window in force for each one and when it will be
+deleted. Rows not reported for longer than the control plane's row-pruning window (30 days by
+default) are pruned; that prunes the listing only and never a room's stored state.
+
+subcommands:
+  get <room>                one room in full: its type and size class, how many save generations
+                            it holds, how big its stored state is, and the exact deletion time
+  set <room> --retention <d|forever|clear>
+                            override the retention window for THIS room. A duration like 30m, 6h
+                            or 7d keeps it that long past its last activity; forever keeps it
+                            indefinitely; clear goes back to what its type declares
+  saves <room>              list a room's save generations, newest first
+  restore <room> --save <id>
+                            bring a room back from a save. This DISCARDS its current state, and
+                            stops the tenant if it is live
+  delete <room>             delete a room's stored state: its snapshot, its saves and its alarms.
+                            This is permanent. Refused while the room is awake unless --force
+
+list filters:
+  --active           only rooms that are awake in a live tenant
+  --idle             only rooms that are not
+  --idle-longer-than <d>
+                     only rooms whose last report is older than a duration like 30m, 6h or 7d
+
+options:
+  --force            with delete: disconnect the room's clients first, then delete it
+  --project <id>     project id (default: the project file)
+  -c, --config <f>   the project file to read (default irtio.json)
+  --url <control>    control plane (default: your stored login, or IRT_API_KEY)
+  -h, --help         print this
+`;
+function parseRoomsArgs(args) {
+  if (helpRequested(args)) throw helpFor(USAGE);
+  const parsed = { sub: "list" };
+  let rest = args;
+  const first = args[0];
+  if (first === "saves" || first === "restore" || first === "delete" || first === "get" || first === "set") {
+    parsed.sub = first;
+    const room = args[1];
+    if (room === void 0 || room.startsWith("-")) {
+      throw new Error(`irtio rooms ${first}: needs a room id`);
+    }
+    parsed.room = room;
+    rest = args.slice(2);
+  }
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    switch (arg) {
+      case "--save": {
+        const value = rest[++i];
+        if (value === void 0) throw new Error("irtio rooms: --save needs a value");
+        parsed.save = value;
+        break;
+      }
+      // ---- M6 lane A: rooms API ----
+      case "--active":
+        parsed.active = true;
+        break;
+      case "--idle":
+        parsed.active = false;
+        break;
+      case "--idle-longer-than": {
+        const value = rest[++i];
+        if (value === void 0) {
+          throw new Error("irtio rooms: --idle-longer-than needs a duration like 30m, 6h or 7d");
+        }
+        parsed.idleLongerThan = value;
+        break;
+      }
+      case "--retention": {
+        const value = rest[++i];
+        if (value === void 0) {
+          throw new Error("irtio rooms: --retention needs a duration, forever, or clear");
+        }
+        parsed.retention = value;
+        break;
+      }
+      case "--force":
+        parsed.force = true;
+        break;
+      // ---- end M6 lane A ----
+      case "--project": {
+        const value = rest[++i];
+        if (value === void 0) throw new Error("irtio rooms: --project needs a value");
+        parsed.project = value;
+        break;
+      }
+      case "-c":
+      case "--config": {
+        const value = args[++i];
+        if (value === void 0 || value === "")
+          throw new Error("irtio rooms: --config needs a value");
+        parsed.config = value;
+        break;
+      }
+      case "--url": {
+        const value = rest[++i];
+        if (value === void 0) throw new Error("irtio rooms: --url needs a value");
+        parsed.url = value;
+        break;
+      }
+      default:
+        throw new Error(`irtio rooms: unknown option ${JSON.stringify(arg)}`);
+    }
+  }
+  if (parsed.sub === "restore" && parsed.save === void 0) {
+    throw new Error(
+      "irtio rooms restore: --save <id> is required \u2014 run `irtio rooms saves <room>` to see them"
+    );
+  }
+  if (parsed.sub === "set" && parsed.retention === void 0) {
+    throw new Error(
+      "irtio rooms set: --retention <d|forever|clear> is required. A duration like 7d keeps this room that long past its last activity, forever keeps it indefinitely, and clear goes back to what its type declares"
+    );
+  }
+  if (parsed.active !== void 0 && parsed.sub !== "list") {
+    throw new Error("irtio rooms: --active and --idle are filters for the listing");
+  }
+  if (parsed.idleLongerThan !== void 0 && parsed.sub !== "list") {
+    throw new Error("irtio rooms: --idle-longer-than is a filter for the listing");
+  }
+  if (parsed.force === true && parsed.sub !== "delete") {
+    throw new Error("irtio rooms: --force belongs to `irtio rooms delete`");
+  }
+  if (parsed.retention !== void 0 && parsed.sub !== "set") {
+    throw new Error("irtio rooms: --retention belongs to `irtio rooms set`");
+  }
+  return parsed;
+}
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function formatAge(iso, now) {
+  const ms = now - Date.parse(iso);
+  if (!Number.isFinite(ms) || ms < 0) return "\u2014";
+  const mins = Math.floor(ms / 6e4);
+  if (mins < 1) return "just now";
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  return `${Math.floor(hours / 24)}d ago`;
+}
+function statusColor(status) {
+  return status === "active" || status === "running" ? pc.green(status) : status === "draining" ? pc.yellow(status) : pc.dim(status);
+}
+function formatTable(rows, now) {
+  if (rows.length === 0) return [pc.dim("no rooms")];
+  const idWidth = Math.max(4, ...rows.map((r) => r.roomId.length));
+  const sharded = rows.some((r) => (r.shard ?? 0) > 0);
+  const head = `${"ROOM".padEnd(idWidth)}  STATUS      RETAIN  DELETES        LAST SEEN` + (sharded ? "  SHARD" : "");
+  const out = [pc.dim(head)];
+  for (const r of rows) {
+    const retention = r.retention ?? "forever";
+    const mark = r.retentionOverride ? "*" : "";
+    out.push(
+      `${r.roomId.padEnd(idWidth)}  ${statusColor(r.status).padEnd(10)}  ${`${retention}${mark}`.padEnd(6)}  ${formatDeadline(r.deletesAt, now).padEnd(13)}  ${pc.dim(r.lastSeen)}` + (sharded ? `  ${String(r.shard ?? 0)}` : "")
+    );
+  }
+  if (rows.some((r) => r.retentionOverride)) {
+    out.push(pc.dim("* set on this room, not declared by its type"));
+  }
+  return out;
+}
+function formatDeadline(deletesAt, now) {
+  if (!deletesAt) return pc.dim("never");
+  const ms = Date.parse(deletesAt) - now;
+  if (!Number.isFinite(ms)) return pc.dim("never");
+  if (ms <= 0) return pc.yellow("next sweep");
+  const mins = Math.floor(ms / 6e4);
+  if (mins < 60) return `in ${mins}m`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 48) return `in ${hours}h`;
+  return `in ${Math.floor(hours / 24)}d`;
+}
+function formatDetail(room, now) {
+  const line = (label, value) => `${pc.dim(label.padEnd(12))}${value}`;
+  const out = [
+    line("room", pc.bold(room.roomId)),
+    line("status", statusColor(room.status)),
+    line("type", room.type ?? pc.dim("not a room id"))
+  ];
+  out.push(line("class", room.class ?? pc.dim("not declared (billed as small)")));
+  if (room.clients !== null && room.clients !== void 0) {
+    const max = room.maxClients ? `/${room.maxClients}` : "";
+    out.push(line("clients", `${room.clients}${max}`));
+  }
+  out.push(line("retention", room.retention ?? "forever"));
+  if (room.retentionOverride) {
+    out.push(line("", pc.dim(`set on this room (${room.retentionOverride}), not by its type`)));
+  }
+  out.push(line("deletes", formatDeadline(room.deletesAt, now)));
+  out.push(line("saves", String(room.saves)));
+  out.push(
+    line(
+      "state",
+      room.stateBytes === void 0 ? pc.dim("unknown while the room is awake; read it after it sleeps") : formatBytes(room.stateBytes)
+    )
+  );
+  out.push(line("last seen", pc.dim(room.lastSeen)));
+  return out;
+}
+function formatSaves(rows, now) {
+  if (rows.length === 0) {
+    return [pc.dim("no saves"), pc.dim("a room writes one when its code calls room.save()")];
+  }
+  const idWidth = Math.max(7, ...rows.map((r) => r.saveId.length));
+  const out = [pc.dim(`${"SAVE ID".padEnd(idWidth)}  AGE         SIZE      DEPLOY`)];
+  for (const r of rows) {
+    out.push(
+      `${r.saveId.padEnd(idWidth)}  ${formatAge(r.createdAt, now).padEnd(10)}  ${formatBytes(r.bytes).padEnd(8)}  ${pc.dim(`v${r.version}`)}`
+    );
+  }
+  return out;
+}
+async function runSaves(options) {
+  const log = options.log ?? ((line) => console.log(line));
+  const controlUrl = await resolveControlUrlForUser(options.controlUrl);
+  const client = options.client ?? await createApiClient(controlUrl);
+  const rows = await client.get(
+    `/v1/projects/${options.project}/rooms/${encodeURIComponent(options.room)}/saves`
+  );
+  for (const line of formatSaves(rows, options.now ?? Date.now())) log(line);
+  return rows;
+}
+async function runRestore(options) {
+  const log = options.log ?? ((line) => console.log(line));
+  const controlUrl = await resolveControlUrlForUser(options.controlUrl);
+  const client = options.client ?? await createApiClient(controlUrl);
+  log(
+    `${pc.yellow("discarding")} the current state of room ${pc.bold(options.room)} and restoring save ${pc.bold(options.saveId)}`
+  );
+  const result = await client.post(
+    `/v1/projects/${options.project}/rooms/${encodeURIComponent(options.room)}/restore`,
+    { saveId: options.saveId }
+  );
+  if (result.applied === "stopped") {
+    log(pc.green(`restored: ${options.room} was live, so its tenant was stopped`));
+    log(
+      pc.dim(
+        "the room comes back from the save on the next join; every other room in this project was stopped too and comes back from its own snapshot, unchanged"
+      )
+    );
+  } else {
+    log(pc.green(`queued: ${options.room} was not running`));
+    log(pc.dim("the restore is applied at the next placement \u2014 the next join starts it"));
+  }
+  return result;
+}
+async function runDeleteRoom(options) {
+  const log = options.log ?? ((line) => console.log(line));
+  const controlUrl = await resolveControlUrlForUser(options.controlUrl);
+  const client = options.client ?? await createApiClient(controlUrl);
+  log(
+    `${pc.yellow("deleting")} room ${pc.bold(options.room)}: its snapshot, its saves and its alarms`
+  );
+  if (options.force === true) {
+    log(
+      pc.yellow(
+        "forced: if the room is awake, every client in it is disconnected first and sees E_ROOM_DELETED. They cannot rejoin the same room; a fresh one starts empty"
+      )
+    );
+  }
+  const result = await client.del(
+    `/v1/projects/${options.project}/rooms/${encodeURIComponent(options.room)}`,
+    options.force === true ? { force: "true" } : {}
+  );
+  log(pc.green(`deleted ${options.room}: ${result.objects} stored object(s) removed`));
+  log(pc.dim("player data and leaderboard scores are keyed to the player and are untouched"));
+  return result;
+}
+async function runRooms(options) {
+  const log = options.log ?? ((line) => console.log(line));
+  const controlUrl = await resolveControlUrlForUser(options.controlUrl);
+  const client = options.client ?? await createApiClient(controlUrl);
+  const rows = await client.get(`/v1/projects/${options.project}/rooms`, {
+    ...options.active !== void 0 ? { active: String(options.active) } : {},
+    ...options.idleLongerThan !== void 0 ? { "idle-longer-than": options.idleLongerThan } : {}
+  });
+  for (const line of formatTable(rows, options.now ?? Date.now())) log(line);
+  return rows;
+}
+async function runGetRoom(options) {
+  const log = options.log ?? ((line) => console.log(line));
+  const controlUrl = await resolveControlUrlForUser(options.controlUrl);
+  const client = options.client ?? await createApiClient(controlUrl);
+  const room = await client.get(
+    `/v1/projects/${options.project}/rooms/${encodeURIComponent(options.room)}`
+  );
+  for (const line of formatDetail(room, options.now ?? Date.now())) log(line);
+  return room;
+}
+async function runSetRoom(options) {
+  const log = options.log ?? ((line) => console.log(line));
+  const controlUrl = await resolveControlUrlForUser(options.controlUrl);
+  const client = options.client ?? await createApiClient(controlUrl);
+  const retention = options.retention === "clear" ? null : options.retention;
+  const room = await client.patch(
+    `/v1/projects/${options.project}/rooms/${encodeURIComponent(options.room)}`,
+    { retention }
+  );
+  log(
+    retention === null ? pc.green(
+      `${options.room}: override cleared, back to its type's window (${room.retention ?? "forever"})`
+    ) : pc.green(`${options.room}: retention set to ${retention}`)
+  );
+  for (const line of formatDetail(room, options.now ?? Date.now())) log(line);
+  return room;
+}
+async function rooms(args, deps = {}) {
+  const log = deps.log ?? ((line) => console.log(line));
+  const errorLog = deps.errorLog ?? ((line) => console.error(line));
+  try {
+    const parsed = parseRoomsArgs(args);
+    const config = await readProjectConfig(process.cwd(), "irtio rooms", parsed.config);
+    const project = parsed.project ?? config.project;
+    if (project === void 0) {
+      throw new Error(
+        "irtio rooms: no project id \u2014 pass --project or run this from a project with irtio.json"
+      );
+    }
+    const common = {
+      project,
+      log,
+      ...parsed.url !== void 0 ? { controlUrl: parsed.url } : {},
+      ...deps.client !== void 0 ? { client: deps.client } : {}
+    };
+    if (parsed.sub === "saves") {
+      await runSaves({ ...common, room: parsed.room });
+    } else if (parsed.sub === "delete") {
+      await runDeleteRoom({
+        ...common,
+        room: parsed.room,
+        ...parsed.force === true ? { force: true } : {}
+      });
+    } else if (parsed.sub === "restore") {
+      await runRestore({
+        ...common,
+        room: parsed.room,
+        saveId: parsed.save
+      });
+    } else if (parsed.sub === "get") {
+      await runGetRoom({ ...common, room: parsed.room });
+    } else if (parsed.sub === "set") {
+      await runSetRoom({
+        ...common,
+        room: parsed.room,
+        retention: parsed.retention
+      });
+    } else {
+      await runRooms({
+        ...common,
+        ...parsed.active !== void 0 ? { active: parsed.active } : {},
+        ...parsed.idleLongerThan !== void 0 ? { idleLongerThan: parsed.idleLongerThan } : {}
+      });
+    }
+  } catch (err) {
+    if (err instanceof HelpRequested) {
+      log(err.usage);
+      return;
+    }
+    if (isLoginRequired(err)) {
+      errorLog(pc.red("not logged in"));
+      errorLog("run: irtio login");
+      process.exitCode = 1;
+      return;
+    }
+    errorLog(pc.red(err instanceof Error ? err.message : String(err)));
+    process.exitCode = 1;
+  }
+}
+export {
+  USAGE,
+  parseRoomsArgs,
+  rooms,
+  runDeleteRoom,
+  runGetRoom,
+  runRestore,
+  runRooms,
+  runSaves,
+  runSetRoom
+};