@joystyk/rooms 0.0.0 → 0.2.0

package/dist/node/host.js

@@ -0,0 +1,323 @@
+import "../protocol/schemas.js";
+import { CloseCode, RejectionCode, encodeFor } from "../protocol/index.js";
+import { expiresAt } from "./store.js";
+//#region src/node/host.ts
+var DROP_CODES = {
+	replaced: CloseCode.replaced,
+	"left-room": CloseCode.leftRoom,
+	"room-closed": CloseCode.noSuchRoom,
+	"room-full": CloseCode.policy
+};
+var RoomHost = class {
+	rooms = /* @__PURE__ */ new Map();
+	o;
+	constructor(options) {
+		this.o = options;
+	}
+	log(level, event, fields = {}) {
+		this.o.log.write(level, event, fields);
+	}
+	/** The live room, loading it from storage (and resuming it) on first use. */
+	load(code) {
+		const existing = this.rooms.get(code);
+		if (existing !== void 0) return { live: existing };
+		if (this.rooms.size >= this.o.maxRooms) return { problem: "busy" };
+		const record = this.o.store.load(code);
+		if (record === null || record.phase === "closed") return { problem: "missing" };
+		const pin = record.match?.game ?? record.game;
+		const core = this.o.registry.core(pin.id, pin.rulesVersion) ?? (record.match === null ? this.o.registry.current(pin.id)?.core ?? null : null);
+		if (core === null) {
+			this.log("error", "engine_missing", {
+				room: code,
+				game: pin.id,
+				rules: pin.rulesVersion
+			});
+			return { problem: "engine-missing" };
+		}
+		if (record.match !== null) {
+			const checked = core.engine.schemas.state["~standard"].validate(record.match.state);
+			if (checked instanceof Promise || checked.issues !== void 0) {
+				this.o.store.quarantine(code, "state");
+				return { problem: "missing" };
+			}
+		}
+		const live = {
+			room: core.load(record),
+			core,
+			timer: null,
+			conns: /* @__PURE__ */ new Map(),
+			idleSince: this.o.clock.now(),
+			retry: []
+		};
+		this.rooms.set(code, live);
+		this.log("info", "room_loaded", {
+			room: code,
+			game: pin.id,
+			rules: pin.rulesVersion
+		});
+		this.dispatch(code, { type: "resume" });
+		return { live };
+	}
+	/** Steps one command and carries out its effects: persist first, then everything else. */
+	dispatch(code, command) {
+		const live = this.rooms.get(code);
+		if (live === void 0) return;
+		let core = live.core;
+		const before = live.room;
+		const now = this.o.clock.now();
+		let step = null;
+		const newest = this.o.registry.current(before.record.game.id)?.core;
+		if (command.type === "control" && before.record.phase !== "playing" && newest !== void 0 && newest !== core) {
+			const upgraded = newest.step(before, command, now);
+			if (upgraded.room.record.match?.number !== before.record.match?.number) {
+				core = newest;
+				step = upgraded;
+			}
+		}
+		step ??= core.step(before, command, now);
+		const first = step.effects[0];
+		if (first?.type === "persist") {
+			let saved;
+			try {
+				saved = this.o.store.save(first.record, first.inputs, before.record.writes);
+			} catch (error) {
+				this.log("error", "persist_failed", {
+					room: code,
+					revision: first.record.revision,
+					error: String(error)
+				});
+				this.storageUnavailable(live, command);
+				this.armRetry(code, live);
+				return;
+			}
+			if (saved === "conflict") {
+				this.log("error", "write_conflict", { room: code });
+				this.unload(code, "conflict");
+				return;
+			}
+		}
+		live.room = step.room;
+		if (step.room.record.match?.number !== before.record.match?.number) live.core = core;
+		for (const effect of step.effects) if (effect.type !== "persist") this.perform(code, live, effect);
+	}
+	/** The old state stays; tell whoever asked, and keep what must not be lost for the retry. */
+	storageUnavailable(live, command) {
+		switch (command.type) {
+			case "act":
+			case "control": {
+				const message = {
+					v: 1,
+					t: "receipt",
+					id: command.id,
+					result: {
+						status: "rejected",
+						code: RejectionCode.storageUnavailable,
+						message: "The table could not be saved. Try again.",
+						revision: live.room.record.revision
+					}
+				};
+				this.sendTo(live, [command.conn], message);
+				break;
+			}
+			case "join": {
+				const conn = live.conns.get(command.conn);
+				live.conns.delete(command.conn);
+				conn?.close(CloseCode.tryAgainLater, "storage unavailable");
+				break;
+			}
+			case "leave":
+			case "ai-chosen":
+			case "resume":
+			case "job-completed": live.retry.push(command);
+		}
+	}
+	armRetry(code, live) {
+		live.timer?.cancel();
+		live.timer = this.o.clock.setTimer(this.o.clock.now() + this.o.persistRetryMs, () => {
+			live.timer = null;
+			const queued = live.retry.splice(0);
+			for (const command of queued) this.dispatch(code, command);
+			this.dispatch(code, { type: "timer-fired" });
+		});
+		live.room = {
+			...live.room,
+			alarmAt: null
+		};
+	}
+	sendTo(live, to, message) {
+		const encoded = /* @__PURE__ */ new Map();
+		for (const id of to) {
+			const conn = live.conns.get(id);
+			if (conn === void 0) continue;
+			if (conn.bufferedAmount > this.o.outgoingBufferBytes) {
+				conn.close(CloseCode.tryAgainLater, "connection too slow");
+				continue;
+			}
+			let text = encoded.get(conn.protocol);
+			if (text === void 0) {
+				text = JSON.stringify(encodeFor(message, conn.protocol));
+				encoded.set(conn.protocol, text);
+			}
+			conn.send(text);
+		}
+	}
+	perform(code, live, effect) {
+		switch (effect.type) {
+			case "persist": return;
+			case "welcome": {
+				const conn = live.conns.get(effect.conn);
+				if (conn === void 0) return;
+				const token = effect.issueToken ? conn.pendingToken : null;
+				conn.pendingToken = null;
+				this.sendTo(live, [effect.conn], token === null ? effect.message : {
+					...effect.message,
+					token
+				});
+				return;
+			}
+			case "send":
+				this.sendTo(live, effect.to, effect.message);
+				return;
+			case "drop": {
+				const conn = live.conns.get(effect.conn);
+				live.conns.delete(effect.conn);
+				conn?.close(DROP_CODES[effect.reason], effect.reason);
+				if (live.conns.size === 0) live.idleSince = this.o.clock.now();
+				return;
+			}
+			case "alarm":
+				if (live.retry.length > 0) {
+					this.armRetry(code, live);
+					return;
+				}
+				live.timer?.cancel();
+				live.timer = effect.at === null ? null : this.o.clock.setTimer(effect.at, () => this.dispatch(code, { type: "timer-fired" }));
+				return;
+			case "start-job":
+				this.startJob(code, live, effect);
+				return;
+			case "start-ai":
+				this.startAi(code, live, effect);
+				return;
+			case "log":
+				this.o.log.write(effect.level, effect.event, {
+					...effect.fields,
+					game: live.core.pin.id,
+					rules: live.core.pin.rulesVersion
+				});
+				return;
+		}
+	}
+	startJob(code, live, effect) {
+		if (this.o.draining()) return;
+		const started = this.o.clock.now();
+		const spec = live.core.engine.jobs?.[effect.kind];
+		this.o.pool.run({
+			room: code,
+			jobId: effect.jobId,
+			gameId: live.core.pin.id,
+			rulesVersion: live.core.pin.rulesVersion,
+			kind: effect.kind,
+			payload: effect.payload,
+			timeoutMs: effect.timeoutMs
+		}).then((outcome) => {
+			if (!outcome.ok) return {
+				ok: false,
+				reason: outcome.reason === "timeout" ? "timeout" : "failed"
+			};
+			if (spec === void 0) return outcome;
+			const checked = spec.result["~standard"].validate(outcome.value);
+			if (checked instanceof Promise || checked.issues !== void 0) return {
+				ok: false,
+				reason: "failed"
+			};
+			return outcome;
+		}).then((outcome) => {
+			this.log("info", "job_finished", {
+				room: code,
+				kind: effect.kind,
+				ok: outcome.ok,
+				ms: this.o.clock.now() - started
+			});
+			if (this.rooms.get(code) === live) this.dispatch(code, {
+				type: "job-completed",
+				jobId: effect.jobId,
+				outcome
+			});
+		});
+	}
+	/** Heavy AI on the pool, through the game's `jobs/ai.worker.ts`; a failure answers null and says why. */
+	startAi(code, live, effect) {
+		if (this.o.draining()) return;
+		const started = this.o.clock.now();
+		this.o.pool.run({
+			room: code,
+			jobId: `ai-${effect.seat}-${effect.decisionRevision}`,
+			gameId: live.core.pin.id,
+			rulesVersion: live.core.pin.rulesVersion,
+			kind: "ai",
+			payload: {
+				view: effect.view,
+				seat: effect.seat,
+				level: effect.level,
+				rng: effect.rng
+			},
+			timeoutMs: this.o.aiTimeoutMs,
+			answer: "value"
+		}).then((outcome) => {
+			this.log("info", "ai_finished", {
+				room: code,
+				seat: effect.seat,
+				ok: outcome.ok,
+				...outcome.ok ? {} : { failure: outcome.reason },
+				ms: this.o.clock.now() - started
+			});
+			if (this.rooms.get(code) !== live) return;
+			const { seat, decisionRevision } = effect;
+			this.dispatch(code, outcome.ok ? {
+				type: "ai-chosen",
+				seat,
+				decisionRevision,
+				command: outcome.value
+			} : {
+				type: "ai-chosen",
+				seat,
+				decisionRevision,
+				command: null,
+				failure: outcome.reason
+			});
+		});
+	}
+	/** Forgets a room: no further callback may write it (the core marks it closed). */
+	unload(code, reason) {
+		const live = this.rooms.get(code);
+		if (live === void 0) return;
+		live.timer?.cancel();
+		live.timer = null;
+		live.room = live.core.step(live.room, {
+			type: "close",
+			reason: "unload"
+		}, this.o.clock.now()).room;
+		this.rooms.delete(code);
+		if (reason === "conflict") for (const conn of live.conns.values()) conn.close(CloseCode.tryAgainLater, "room moved");
+		this.log("info", "room_unloaded", {
+			room: code,
+			reason
+		});
+	}
+	/** Unloads idle rooms and closes expired ones. */
+	sweep(idleMs) {
+		const now = this.o.clock.now();
+		for (const [code, live] of [...this.rooms]) if (now >= expiresAt(live.room.record) && live.room.record.phase !== "closed") {
+			this.dispatch(code, {
+				type: "close",
+				reason: "expired"
+			});
+			this.unload(code, "expired");
+		} else if (live.conns.size === 0 && now - live.idleSince >= idleMs) this.unload(code, "idle");
+	}
+};
+//#endregion
+export { RoomHost };
+
+//# sourceMappingURL=host.js.map

package/dist/node/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","names":[],"sources":["../../src/node/host.ts"],"sourcesContent":["// The room host: live rooms in memory, `dispatch` (room-server.md section 4.2) and the code\n// that carries out each effect. It knows nothing about HTTP or `ws`; a connection is anything\n// that can send text and close.\nimport type { JobOutcome } from '@joystyk/contracts';\nimport { CloseCode, encodeFor, RejectionCode, PROTOCOL_VERSION, type ServerMessage } from '../protocol/index.ts';\nimport type { ConnId, DropReason, LiveRoom, RoomCode, RoomCommand, RoomCore, RoomEffect, Step } from '../types.ts';\nimport type { JobPool } from './jobs.ts';\nimport type { EngineRegistry } from './registry.ts';\nimport { expiresAt, type RoomStore } from './store.ts';\nimport type { Clock, Logger } from './support.ts';\n\nexport interface Connection {\n  readonly id: ConnId;\n  /** The wire version this connection joined with. */\n  protocol: number;\n  /** The fresh token generated for this connection's join; revealed only if the core issues a seat. */\n  pendingToken: string | null;\n  readonly bufferedAmount: number;\n  send(text: string): void;\n  close(code: number, reason: string): void;\n}\n\ntype Live = {\n  room: LiveRoom;\n  core: RoomCore;\n  timer: { cancel(): void } | null;\n  readonly conns: Map<ConnId, Connection>;\n  idleSince: number;\n  /** Commands whose persist failed and that must not be lost: retried before the next timer. */\n  retry: RoomCommand[];\n};\n\nexport type HostOptions = {\n  readonly store: RoomStore;\n  readonly registry: EngineRegistry;\n  readonly clock: Clock;\n  readonly pool: JobPool;\n  readonly log: Logger;\n  readonly maxRooms: number;\n  readonly outgoingBufferBytes: number;\n  readonly persistRetryMs: number;\n  /** How long a heavy AI may choose (ROOMS_AI_TIMEOUT_MS). */\n  readonly aiTimeoutMs: number;\n  readonly draining: () => boolean;\n};\n\nconst DROP_CODES: Record<DropReason, number> = {\n  replaced: CloseCode.replaced,\n  'left-room': CloseCode.leftRoom,\n  'room-closed': CloseCode.noSuchRoom,\n  'room-full': CloseCode.policy,\n};\n\nexport type LoadResult = { readonly live: Live } | { readonly problem: 'missing' | 'busy' | 'engine-missing' };\n\nexport class RoomHost {\n  readonly rooms = new Map<RoomCode, Live>();\n  private readonly o: HostOptions;\n\n  constructor(options: HostOptions) {\n    this.o = options;\n  }\n\n  private log(\n    level: 'info' | 'warn' | 'error',\n    event: string,\n    fields: { readonly [k: string]: string | number | boolean | null } = {},\n  ): void {\n    this.o.log.write(level, event, fields);\n  }\n\n  /** The live room, loading it from storage (and resuming it) on first use. */\n  load(code: RoomCode): LoadResult {\n    const existing = this.rooms.get(code);\n    if (existing !== undefined) return { live: existing };\n    if (this.rooms.size >= this.o.maxRooms) return { problem: 'busy' };\n    const record = this.o.store.load(code);\n    if (record === null || record.phase === 'closed') return { problem: 'missing' };\n    const pin = record.match?.game ?? record.game;\n    const core =\n      this.o.registry.core(pin.id, pin.rulesVersion) ??\n      (record.match === null ? (this.o.registry.current(pin.id)?.core ?? null) : null);\n    if (core === null) {\n      this.log('error', 'engine_missing', { room: code, game: pin.id, rules: pin.rulesVersion });\n      return { problem: 'engine-missing' };\n    }\n    if (record.match !== null) {\n      const checked = core.engine.schemas.state['~standard'].validate(record.match.state);\n      if (checked instanceof Promise || checked.issues !== undefined) {\n        this.o.store.quarantine(code, 'state');\n        return { problem: 'missing' };\n      }\n    }\n    const live: Live = {\n      room: core.load(record),\n      core,\n      timer: null,\n      conns: new Map(),\n      idleSince: this.o.clock.now(),\n      retry: [],\n    };\n    this.rooms.set(code, live);\n    this.log('info', 'room_loaded', { room: code, game: pin.id, rules: pin.rulesVersion });\n    this.dispatch(code, { type: 'resume' });\n    return { live };\n  }\n\n  /** Steps one command and carries out its effects: persist first, then everything else. */\n  dispatch(code: RoomCode, command: RoomCommand): void {\n    const live = this.rooms.get(code);\n    if (live === undefined) return;\n    let core = live.core;\n    const before = live.room;\n    const now = this.o.clock.now();\n    let step: Step | null = null;\n    const newest = this.o.registry.current(before.record.game.id)?.core;\n    if (command.type === 'control' && before.record.phase !== 'playing' && newest !== undefined && newest !== core) {\n      // A new match runs on the newest engine: a start, or the answer that completes a rematch\n      // offer, is the upgrade point (section 6.1). Steps are pure, so a step on the newest core\n      // that starts no match is dropped and the room's own core takes the command.\n      const upgraded = newest.step(before, command, now);\n      if (upgraded.room.record.match?.number !== before.record.match?.number) {\n        core = newest;\n        step = upgraded;\n      }\n    }\n    step ??= core.step(before, command, now);\n    const first = step.effects[0];\n    if (first?.type === 'persist') {\n      let saved: 'saved' | 'conflict';\n      try {\n        saved = this.o.store.save(first.record, first.inputs, before.record.writes);\n      } catch (error) {\n        this.log('error', 'persist_failed', { room: code, revision: first.record.revision, error: String(error) });\n        this.storageUnavailable(live, command);\n        this.armRetry(code, live);\n        return;\n      }\n      if (saved === 'conflict') {\n        this.log('error', 'write_conflict', { room: code });\n        this.unload(code, 'conflict');\n        return;\n      }\n    }\n    live.room = step.room;\n    if (step.room.record.match?.number !== before.record.match?.number) live.core = core;\n    for (const effect of step.effects) if (effect.type !== 'persist') this.perform(code, live, effect);\n  }\n\n  /** The old state stays; tell whoever asked, and keep what must not be lost for the retry. */\n  private storageUnavailable(live: Live, command: RoomCommand): void {\n    switch (command.type) {\n      case 'act':\n      case 'control': {\n        const message: ServerMessage = {\n          v: PROTOCOL_VERSION,\n          t: 'receipt',\n          id: command.id,\n          result: {\n            status: 'rejected',\n            code: RejectionCode.storageUnavailable,\n            message: 'The table could not be saved. Try again.',\n            revision: live.room.record.revision,\n          },\n        };\n        this.sendTo(live, [command.conn], message);\n        break;\n      }\n      case 'join': {\n        const conn = live.conns.get(command.conn);\n        live.conns.delete(command.conn);\n        conn?.close(CloseCode.tryAgainLater, 'storage unavailable');\n        break;\n      }\n      case 'leave':\n      case 'ai-chosen':\n      case 'resume':\n      case 'job-completed':\n        live.retry.push(command);\n        break;\n      default:\n        break;\n    }\n  }\n\n  private armRetry(code: RoomCode, live: Live): void {\n    live.timer?.cancel();\n    live.timer = this.o.clock.setTimer(this.o.clock.now() + this.o.persistRetryMs, () => {\n      live.timer = null;\n      const queued = live.retry.splice(0);\n      for (const command of queued) this.dispatch(code, command);\n      this.dispatch(code, { type: 'timer-fired' });\n    });\n    // The core will ask for its alarm again once a step succeeds.\n    live.room = { ...live.room, alarmAt: null };\n  }\n\n  private sendTo(live: Live, to: readonly ConnId[], message: ServerMessage): void {\n    const encoded = new Map<number, string>();\n    for (const id of to) {\n      const conn = live.conns.get(id);\n      if (conn === undefined) continue;\n      if (conn.bufferedAmount > this.o.outgoingBufferBytes) {\n        conn.close(CloseCode.tryAgainLater, 'connection too slow');\n        continue;\n      }\n      let text = encoded.get(conn.protocol);\n      if (text === undefined) {\n        text = JSON.stringify(encodeFor(message, conn.protocol));\n        encoded.set(conn.protocol, text);\n      }\n      conn.send(text);\n    }\n  }\n\n  private perform(code: RoomCode, live: Live, effect: RoomEffect): void {\n    switch (effect.type) {\n      case 'persist':\n        return;\n      case 'welcome': {\n        const conn = live.conns.get(effect.conn);\n        if (conn === undefined) return;\n        const token = effect.issueToken ? conn.pendingToken : null;\n        conn.pendingToken = null;\n        this.sendTo(live, [effect.conn], token === null ? effect.message : { ...effect.message, token });\n        return;\n      }\n      case 'send':\n        this.sendTo(live, effect.to, effect.message);\n        return;\n      case 'drop': {\n        const conn = live.conns.get(effect.conn);\n        live.conns.delete(effect.conn);\n        conn?.close(DROP_CODES[effect.reason], effect.reason);\n        if (live.conns.size === 0) live.idleSince = this.o.clock.now();\n        return;\n      }\n      case 'alarm':\n        if (live.retry.length > 0) {\n          this.armRetry(code, live);\n          return;\n        }\n        live.timer?.cancel();\n        live.timer =\n          effect.at === null\n            ? null\n            : this.o.clock.setTimer(effect.at, () => this.dispatch(code, { type: 'timer-fired' }));\n        return;\n      case 'start-job':\n        this.startJob(code, live, effect);\n        return;\n      case 'start-ai':\n        this.startAi(code, live, effect);\n        return;\n      case 'log':\n        this.o.log.write(effect.level, effect.event, {\n          ...effect.fields,\n          game: live.core.pin.id,\n          rules: live.core.pin.rulesVersion,\n        });\n        return;\n    }\n  }\n\n  private startJob(code: RoomCode, live: Live, effect: Extract<RoomEffect, { type: 'start-job' }>): void {\n    // While draining, unstarted jobs stay in match.jobs and re-run after the restart.\n    if (this.o.draining()) return;\n    const started = this.o.clock.now();\n    const spec = live.core.engine.jobs?.[effect.kind];\n    void this.o.pool\n      .run({\n        room: code,\n        jobId: effect.jobId,\n        gameId: live.core.pin.id,\n        rulesVersion: live.core.pin.rulesVersion,\n        kind: effect.kind,\n        payload: effect.payload,\n        timeoutMs: effect.timeoutMs,\n      })\n      .then((outcome): JobOutcome => {\n        // An engine sees only the contract's two failures.\n        if (!outcome.ok) return { ok: false, reason: outcome.reason === 'timeout' ? 'timeout' : 'failed' };\n        if (spec === undefined) return outcome;\n        const checked = spec.result['~standard'].validate(outcome.value);\n        if (checked instanceof Promise || checked.issues !== undefined) return { ok: false, reason: 'failed' };\n        return outcome;\n      })\n      .then((outcome) => {\n        this.log('info', 'job_finished', {\n          room: code,\n          kind: effect.kind,\n          ok: outcome.ok,\n          ms: this.o.clock.now() - started,\n        });\n        if (this.rooms.get(code) === live) this.dispatch(code, { type: 'job-completed', jobId: effect.jobId, outcome });\n      });\n  }\n\n  /** Heavy AI on the pool, through the game's `jobs/ai.worker.ts`; a failure answers null and says why. */\n  private startAi(code: RoomCode, live: Live, effect: Extract<RoomEffect, { type: 'start-ai' }>): void {\n    if (this.o.draining()) return;\n    const started = this.o.clock.now();\n    void this.o.pool\n      .run({\n        room: code,\n        jobId: `ai-${effect.seat}-${effect.decisionRevision}`,\n        gameId: live.core.pin.id,\n        rulesVersion: live.core.pin.rulesVersion,\n        kind: 'ai',\n        payload: { view: effect.view, seat: effect.seat, level: effect.level, rng: effect.rng },\n        timeoutMs: this.o.aiTimeoutMs,\n        answer: 'value',\n      })\n      .then((outcome) => {\n        this.log('info', 'ai_finished', {\n          room: code,\n          seat: effect.seat,\n          ok: outcome.ok,\n          ...(outcome.ok ? {} : { failure: outcome.reason }),\n          ms: this.o.clock.now() - started,\n        });\n        if (this.rooms.get(code) !== live) return;\n        const { seat, decisionRevision } = effect;\n        this.dispatch(\n          code,\n          outcome.ok\n            ? { type: 'ai-chosen', seat, decisionRevision, command: outcome.value }\n            : { type: 'ai-chosen', seat, decisionRevision, command: null, failure: outcome.reason },\n        );\n      });\n  }\n\n  /** Forgets a room: no further callback may write it (the core marks it closed). */\n  unload(code: RoomCode, reason: 'idle' | 'conflict' | 'drain' | 'expired'): void {\n    const live = this.rooms.get(code);\n    if (live === undefined) return;\n    live.timer?.cancel();\n    live.timer = null;\n    live.room = live.core.step(live.room, { type: 'close', reason: 'unload' }, this.o.clock.now()).room;\n    this.rooms.delete(code);\n    if (reason === 'conflict')\n      for (const conn of live.conns.values()) conn.close(CloseCode.tryAgainLater, 'room moved');\n    this.log('info', 'room_unloaded', { room: code, reason });\n  }\n\n  /** Unloads idle rooms and closes expired ones. */\n  sweep(idleMs: number): void {\n    const now = this.o.clock.now();\n    for (const [code, live] of [...this.rooms]) {\n      if (now >= expiresAt(live.room.record) && live.room.record.phase !== 'closed') {\n        this.dispatch(code, { type: 'close', reason: 'expired' });\n        this.unload(code, 'expired');\n      } else if (live.conns.size === 0 && now - live.idleSince >= idleMs) {\n        this.unload(code, 'idle');\n      }\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/node/index.d.ts

@@ -0,0 +1,6 @@
+export { RoomHost, type Connection, type HostOptions, type LoadResult } from './host.js';
+export { inlineJobPool, workerJobPool, type JobPool, type PoolJob, type PoolOutcome, type WorkerPoolOptions, } from './jobs.js';
+export { createEngineRegistry, type CurrentEngine, type EngineRegistry, type RegisteredEngine } from './registry.js';
+export { createRoomServer, DEFAULT_SERVER_LIMITS, type RoomServer, type RoomServerOptions, type ServerLimits, } from './server.js';
+export { expiresAt, MIGRATIONS, openSqliteStore, SCHEMA_VERSION, type RoomStore, type SqliteStoreOptions, } from './store.js';
+export { clientAddress, createLogger, hashToken, memoryLogger, newRoomCode, newSeatToken, parseTrustedProxy, randomWords, systemClock, TokenBucket, WindowCounter, type Clock, type Logger, type LogLevel, } from './support.js';

package/dist/node/index.js

@@ -0,0 +1,7 @@
+import { MIGRATIONS, SCHEMA_VERSION, expiresAt, openSqliteStore } from "./store.js";
+import { RoomHost } from "./host.js";
+import { inlineJobPool, workerJobPool } from "./jobs.js";
+import { createEngineRegistry } from "./registry.js";
+import { TokenBucket, WindowCounter, clientAddress, createLogger, hashToken, memoryLogger, newRoomCode, newSeatToken, parseTrustedProxy, randomWords, systemClock } from "./support.js";
+import { DEFAULT_SERVER_LIMITS, createRoomServer } from "./server.js";
+export { DEFAULT_SERVER_LIMITS, MIGRATIONS, RoomHost, SCHEMA_VERSION, TokenBucket, WindowCounter, clientAddress, createEngineRegistry, createLogger, createRoomServer, expiresAt, hashToken, inlineJobPool, memoryLogger, newRoomCode, newSeatToken, openSqliteStore, parseTrustedProxy, randomWords, systemClock, workerJobPool };

package/dist/node/jobs.d.ts

@@ -0,0 +1,48 @@
+import type { JobOutcome, Json } from '@joystyk/contracts';
+import type { AiFailure, RoomCode } from '../types.js';
+import type { Logger } from './support.js';
+export type PoolJob = {
+    readonly room: RoomCode;
+    readonly jobId: string;
+    readonly gameId: string;
+    /** A room always supplies its pin; omitted internal probes use the current engine. */
+    readonly rulesVersion?: number;
+    readonly kind: string;
+    readonly payload: Json;
+    readonly timeoutMs: number;
+    /**
+     * 'outcome' (default): the module answers with a JobOutcome. 'value': it answers with a
+     * plain value (a heavy AI's command), which the pool wraps as { ok: true, value }.
+     */
+    readonly answer?: 'outcome' | 'value';
+};
+/** A job's outcome, or why the pool could not run it to the end (see `AiFailure`). */
+export type PoolOutcome = JobOutcome | {
+    readonly ok: false;
+    readonly reason: AiFailure;
+};
+export interface JobPool {
+    /** Never rejects: failures come back as { ok: false }. */
+    run(job: PoolJob): Promise<PoolOutcome>;
+    readonly inFlight: number;
+    /** Resolves true once nothing is running, or false after `timeoutMs`. */
+    idle(timeoutMs: number): Promise<boolean>;
+    close(): Promise<void>;
+}
+/** Runs jobs in the main thread through a handler. For tests and development fixtures. */
+export declare const inlineJobPool: (handler: (job: PoolJob) => PoolOutcome | Promise<PoolOutcome>) => JobPool;
+export type WorkerPoolOptions = {
+    /** Worker threads (ROOMS_JOB_WORKERS). */
+    readonly workers: number;
+    /** The entry module URL for a game's job kind, or null when this build has none. */
+    readonly module: (gameId: string, kind: string, rulesVersion?: number) => URL | null;
+    /** Queued or running jobs per worker. */
+    readonly perWorker?: number;
+    readonly log?: Logger;
+};
+/**
+ * Greed's physics pool, generalized. A full pool refuses a job at once (`busy`). A timeout or
+ * crash terminates that worker and starts a fresh one; the job it was running fails with
+ * `timeout` or `crashed`, and every job queued behind it with `lost`.
+ */
+export declare const workerJobPool: (options: WorkerPoolOptions) => JobPool;

package/dist/node/jobs.js

@@ -0,0 +1,176 @@
+import { Worker } from "node:worker_threads";
+//#region src/node/jobs.ts
+/** Shared bookkeeping for `inFlight` and `idle`. */
+var Tracker = class {
+	inFlight = 0;
+	waiters = [];
+	track(work) {
+		this.inFlight += 1;
+		return work.finally(() => {
+			this.inFlight -= 1;
+			if (this.inFlight === 0) for (const wake of this.waiters.splice(0)) wake();
+		});
+	}
+	idle(timeoutMs) {
+		if (this.inFlight === 0) return Promise.resolve(true);
+		return new Promise((resolve) => {
+			const timer = setTimeout(() => resolve(false), timeoutMs);
+			this.waiters.push(() => {
+				clearTimeout(timer);
+				resolve(true);
+			});
+		});
+	}
+};
+/** Runs jobs in the main thread through a handler. For tests and development fixtures. */
+var inlineJobPool = (handler) => {
+	const tracker = new Tracker();
+	return {
+		run: (job) => tracker.track(Promise.resolve().then(() => handler(job)).catch(() => ({
+			ok: false,
+			reason: "failed"
+		}))),
+		get inFlight() {
+			return tracker.inFlight;
+		},
+		idle: (timeoutMs) => tracker.idle(timeoutMs),
+		close: async () => {}
+	};
+};
+/**
+* The worker host. It imports a job's entry module (a game's `jobs/<kind>.worker.ts`, whose
+* default export maps a payload to a JobOutcome, or `jobs/ai.worker.ts`, which maps
+* `{ view, seat, level, rng }` to a command) and answers each request. Jobs run one at a
+* time, in order, and each says when it starts, so its timeout never includes its wait in the
+* queue. Written as an eval'd script so it works the same from source and from a bundle.
+*/
+var HOST = `
+const { parentPort } = require('node:worker_threads');
+const modules = new Map();
+let queue = Promise.resolve();
+const run = async ({ job, module, payload, answer }) => {
+  parentPort.postMessage({ job, started: true });
+  try {
+    let loaded = modules.get(module);
+    if (loaded === undefined) { loaded = await import(module); modules.set(module, loaded); }
+    const result = await loaded.default(payload);
+    parentPort.postMessage({ job, outcome: answer === 'value' ? { ok: true, value: result } : result });
+  } catch (error) {
+    parentPort.postMessage({ job, error: String(error) });
+  }
+};
+parentPort.on('message', (message) => { queue = queue.then(() => run(message)); });
+`;
+/**
+* Greed's physics pool, generalized. A full pool refuses a job at once (`busy`). A timeout or
+* crash terminates that worker and starts a fresh one; the job it was running fails with
+* `timeout` or `crashed`, and every job queued behind it with `lost`.
+*/
+var workerJobPool = (options) => {
+	const perWorker = options.perWorker ?? 16;
+	const tracker = new Tracker();
+	let sequence = 0;
+	let stopped = false;
+	const slots = [];
+	const spawn = (slot) => {
+		const worker = new Worker(HOST, { eval: true });
+		worker.unref();
+		const target = slot ?? {
+			worker,
+			pending: /* @__PURE__ */ new Map(),
+			running: null
+		};
+		target.worker = worker;
+		target.running = null;
+		worker.on("message", (data) => {
+			if (target.worker !== worker) return;
+			const pending = target.pending.get(data.job);
+			if (pending === void 0) return;
+			if (data.started === true) {
+				target.running = data.job;
+				pending.timer = setTimeout(() => restart(target, worker, "timeout"), pending.timeoutMs);
+				return;
+			}
+			if (pending.timer !== null) clearTimeout(pending.timer);
+			target.pending.delete(data.job);
+			if (target.running === data.job) target.running = null;
+			if (data.error !== void 0) options.log?.write("warn", "job_failed", { error: data.error });
+			pending.resolve(data.outcome ?? {
+				ok: false,
+				reason: "failed"
+			});
+		});
+		worker.on("error", () => restart(target, worker, "crashed"));
+		worker.on("exit", () => restart(target, worker, "crashed"));
+		return target;
+	};
+	const restart = (slot, worker, reason) => {
+		if (stopped || slot.worker !== worker) return;
+		for (const [job, pending] of slot.pending) {
+			if (pending.timer !== null) clearTimeout(pending.timer);
+			pending.resolve({
+				ok: false,
+				reason: job === slot.running ? reason : "lost"
+			});
+		}
+		slot.pending.clear();
+		spawn(slot);
+		worker.terminate();
+	};
+	for (let i = 0; i < Math.max(1, options.workers); i += 1) slots.push(spawn());
+	const run = (job) => {
+		const module = options.module(job.gameId, job.kind, job.rulesVersion);
+		const slot = [...slots].sort((a, b) => a.pending.size - b.pending.size)[0];
+		if (stopped || module === null || slot === void 0 || slot.pending.size >= perWorker) {
+			options.log?.write("warn", module === null ? "job_module_missing" : "job_rejected_busy", {
+				room: job.room,
+				kind: job.kind
+			});
+			return Promise.resolve({
+				ok: false,
+				reason: module === null || stopped ? "failed" : "busy"
+			});
+		}
+		sequence += 1;
+		const id = sequence;
+		const worker = slot.worker;
+		return tracker.track(new Promise((resolve) => {
+			slot.pending.set(id, {
+				resolve,
+				timeoutMs: job.timeoutMs,
+				timer: null
+			});
+			worker.postMessage({
+				job: id,
+				module: module.href,
+				payload: job.payload,
+				answer: job.answer ?? "outcome"
+			});
+		}));
+	};
+	return {
+		run,
+		get inFlight() {
+			return tracker.inFlight;
+		},
+		idle: (timeoutMs) => tracker.idle(timeoutMs),
+		close: async () => {
+			stopped = true;
+			for (const slot of slots) {
+				for (const pending of slot.pending.values()) {
+					if (pending.timer !== null) clearTimeout(pending.timer);
+					pending.resolve({
+						ok: false,
+						reason: "failed"
+					});
+				}
+				slot.pending.clear();
+			}
+			await Promise.all(slots.map((slot) => slot.worker.terminate()));
+		}
+	};
+};
+//#endregion
+export { inlineJobPool, workerJobPool };
+
+//# sourceMappingURL=jobs.js.map

package/dist/node/jobs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobs.js","names":[],"sources":["../../src/node/jobs.ts"],"sourcesContent":["// The job pool (room-server.md section 4.4): background work on worker_threads, behind an\n// interface so tests and development can run jobs inline.\nimport { Worker } from 'node:worker_threads';\nimport type { JobOutcome, Json } from '@joystyk/contracts';\nimport type { AiFailure, RoomCode } from '../types.ts';\nimport type { Logger } from './support.ts';\n\nexport type PoolJob = {\n  readonly room: RoomCode;\n  readonly jobId: string;\n  readonly gameId: string;\n  /** A room always supplies its pin; omitted internal probes use the current engine. */\n  readonly rulesVersion?: number;\n  readonly kind: string;\n  readonly payload: Json;\n  readonly timeoutMs: number;\n  /**\n   * 'outcome' (default): the module answers with a JobOutcome. 'value': it answers with a\n   * plain value (a heavy AI's command), which the pool wraps as { ok: true, value }.\n   */\n  readonly answer?: 'outcome' | 'value';\n};\n\n/** A job's outcome, or why the pool could not run it to the end (see `AiFailure`). */\nexport type PoolOutcome = JobOutcome | { readonly ok: false; readonly reason: AiFailure };\n\nexport interface JobPool {\n  /** Never rejects: failures come back as { ok: false }. */\n  run(job: PoolJob): Promise<PoolOutcome>;\n  readonly inFlight: number;\n  /** Resolves true once nothing is running, or false after `timeoutMs`. */\n  idle(timeoutMs: number): Promise<boolean>;\n  close(): Promise<void>;\n}\n\n/** Shared bookkeeping for `inFlight` and `idle`. */\nclass Tracker {\n  inFlight = 0;\n  private waiters: (() => void)[] = [];\n\n  track<T>(work: Promise<T>): Promise<T> {\n    this.inFlight += 1;\n    return work.finally(() => {\n      this.inFlight -= 1;\n      if (this.inFlight === 0) for (const wake of this.waiters.splice(0)) wake();\n    });\n  }\n\n  idle(timeoutMs: number): Promise<boolean> {\n    if (this.inFlight === 0) return Promise.resolve(true);\n    return new Promise((resolve) => {\n      const timer = setTimeout(() => resolve(false), timeoutMs);\n      this.waiters.push(() => {\n        clearTimeout(timer);\n        resolve(true);\n      });\n    });\n  }\n}\n\n/** Runs jobs in the main thread through a handler. For tests and development fixtures. */\nexport const inlineJobPool = (handler: (job: PoolJob) => PoolOutcome | Promise<PoolOutcome>): JobPool => {\n  const tracker = new Tracker();\n  return {\n    run: (job) =>\n      tracker.track(\n        Promise.resolve()\n          .then(() => handler(job))\n          .catch((): PoolOutcome => ({ ok: false, reason: 'failed' })),\n      ),\n    get inFlight() {\n      return tracker.inFlight;\n    },\n    idle: (timeoutMs) => tracker.idle(timeoutMs),\n    close: async () => {},\n  };\n};\n\n/**\n * The worker host. It imports a job's entry module (a game's `jobs/<kind>.worker.ts`, whose\n * default export maps a payload to a JobOutcome, or `jobs/ai.worker.ts`, which maps\n * `{ view, seat, level, rng }` to a command) and answers each request. Jobs run one at a\n * time, in order, and each says when it starts, so its timeout never includes its wait in the\n * queue. Written as an eval'd script so it works the same from source and from a bundle.\n */\nconst HOST = `\nconst { parentPort } = require('node:worker_threads');\nconst modules = new Map();\nlet queue = Promise.resolve();\nconst run = async ({ job, module, payload, answer }) => {\n  parentPort.postMessage({ job, started: true });\n  try {\n    let loaded = modules.get(module);\n    if (loaded === undefined) { loaded = await import(module); modules.set(module, loaded); }\n    const result = await loaded.default(payload);\n    parentPort.postMessage({ job, outcome: answer === 'value' ? { ok: true, value: result } : result });\n  } catch (error) {\n    parentPort.postMessage({ job, error: String(error) });\n  }\n};\nparentPort.on('message', (message) => { queue = queue.then(() => run(message)); });\n`;\n\ntype Pending = {\n  readonly resolve: (outcome: PoolOutcome) => void;\n  readonly timeoutMs: number;\n  timer: ReturnType<typeof setTimeout> | null;\n};\ntype Slot = { worker: Worker; readonly pending: Map<number, Pending>; running: number | null };\n\nexport type WorkerPoolOptions = {\n  /** Worker threads (ROOMS_JOB_WORKERS). */\n  readonly workers: number;\n  /** The entry module URL for a game's job kind, or null when this build has none. */\n  readonly module: (gameId: string, kind: string, rulesVersion?: number) => URL | null;\n  /** Queued or running jobs per worker. */\n  readonly perWorker?: number;\n  readonly log?: Logger;\n};\n\n/**\n * Greed's physics pool, generalized. A full pool refuses a job at once (`busy`). A timeout or\n * crash terminates that worker and starts a fresh one; the job it was running fails with\n * `timeout` or `crashed`, and every job queued behind it with `lost`.\n */\nexport const workerJobPool = (options: WorkerPoolOptions): JobPool => {\n  const perWorker = options.perWorker ?? 16;\n  const tracker = new Tracker();\n  let sequence = 0;\n  let stopped = false;\n  const slots: Slot[] = [];\n\n  const spawn = (slot?: Slot): Slot => {\n    const worker = new Worker(HOST, { eval: true });\n    worker.unref();\n    const target: Slot = slot ?? { worker, pending: new Map(), running: null };\n    target.worker = worker;\n    target.running = null;\n    worker.on('message', (data: { job: number; started?: true; outcome?: JobOutcome; error?: string }) => {\n      if (target.worker !== worker) return;\n      const pending = target.pending.get(data.job);\n      if (pending === undefined) return;\n      if (data.started === true) {\n        target.running = data.job;\n        pending.timer = setTimeout(() => restart(target, worker, 'timeout'), pending.timeoutMs);\n        return;\n      }\n      if (pending.timer !== null) clearTimeout(pending.timer);\n      target.pending.delete(data.job);\n      if (target.running === data.job) target.running = null;\n      if (data.error !== undefined) options.log?.write('warn', 'job_failed', { error: data.error });\n      pending.resolve(data.outcome ?? { ok: false, reason: 'failed' });\n    });\n    worker.on('error', () => restart(target, worker, 'crashed'));\n    worker.on('exit', () => restart(target, worker, 'crashed'));\n    return target;\n  };\n\n  const restart = (slot: Slot, worker: Worker, reason: 'timeout' | 'crashed'): void => {\n    if (stopped || slot.worker !== worker) return;\n    for (const [job, pending] of slot.pending) {\n      if (pending.timer !== null) clearTimeout(pending.timer);\n      pending.resolve({ ok: false, reason: job === slot.running ? reason : 'lost' });\n    }\n    slot.pending.clear();\n    spawn(slot);\n    void worker.terminate();\n  };\n\n  for (let i = 0; i < Math.max(1, options.workers); i += 1) slots.push(spawn());\n\n  const run = (job: PoolJob): Promise<PoolOutcome> => {\n    const module = options.module(job.gameId, job.kind, job.rulesVersion);\n    const slot = [...slots].sort((a, b) => a.pending.size - b.pending.size)[0];\n    if (stopped || module === null || slot === undefined || slot.pending.size >= perWorker) {\n      options.log?.write('warn', module === null ? 'job_module_missing' : 'job_rejected_busy', {\n        room: job.room,\n        kind: job.kind,\n      });\n      return Promise.resolve({ ok: false, reason: module === null || stopped ? 'failed' : 'busy' });\n    }\n    sequence += 1;\n    const id = sequence;\n    const worker = slot.worker;\n    return tracker.track(\n      new Promise<PoolOutcome>((resolve) => {\n        slot.pending.set(id, { resolve, timeoutMs: job.timeoutMs, timer: null });\n        worker.postMessage({ job: id, module: module.href, payload: job.payload, answer: job.answer ?? 'outcome' });\n      }),\n    );\n  };\n\n  return {\n    run,\n    get inFlight() {\n      return tracker.inFlight;\n    },\n    idle: (timeoutMs) => tracker.idle(timeoutMs),\n    close: async () => {\n      stopped = true;\n      for (const slot of slots) {\n        for (const pending of slot.pending.values()) {\n          if (pending.timer !== null) clearTimeout(pending.timer);\n          pending.resolve({ ok: false, reason: 'failed' });\n        }\n        slot.pending.clear();\n      }\n      await Promise.all(slots.map((slot) => slot.worker.terminate()));\n    },\n  };\n};\n"],"mappings":"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"}

package/dist/node/registry.d.ts

@@ -0,0 +1,32 @@
+import type { AnyDiscreteEngine, Rng, RngState } from '@joystyk/contracts';
+import type { CoreLimits, GamePin, RoomCore, RoomPolicy } from '../types.js';
+export type RegisteredEngine = {
+    readonly pin: GamePin;
+    readonly engine: AnyDiscreteEngine;
+    readonly policy: RoomPolicy;
+    /** The manifest's `ai.heavy`: choose on the worker pool with the `ai` job module. */
+    readonly heavyAi?: boolean;
+    /** Worker entry modules by job kind (a game's `jobs/<kind>.worker.ts`; `ai` for heavy AI). */
+    readonly jobs?: {
+        readonly [kind: string]: URL;
+    };
+};
+export type CurrentEngine = {
+    readonly core: RoomCore;
+    readonly pin: GamePin;
+    readonly policy: RoomPolicy;
+};
+export interface EngineRegistry {
+    /** The core for a game at a rules version, or null if this build no longer carries it. */
+    core(gameId: string, rulesVersion: number): RoomCore | null;
+    /** The newest engine for a game: new rooms and rematches use it. */
+    current(gameId: string): CurrentEngine | null;
+    games(): readonly string[];
+    /** Pinned room work uses its rules version; unversioned probes select current. */
+    jobModule(gameId: string, kind: string, rulesVersion?: number): URL | null;
+}
+/**
+ * Builds a registry. For each game, the entry with the highest rules version is current;
+ * the others are frozen engines kept for rooms already playing on them.
+ */
+export declare const createEngineRegistry: (entries: readonly RegisteredEngine[], rng: (state: RngState) => Rng, limits?: Partial<CoreLimits>) => EngineRegistry;