@joystyk/rooms 0.0.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# @joystyk/rooms
+
+## 0.2.0
+
+### Minor Changes
+
+- bb095c7: A heavy AI the job pool couldn't answer is asked again with backoff instead of playing the
+  timeout move. `ai-chosen` without a command now carries the pool's `failure`, `LiveRoom` gains
+  `aiRetry`, and `CoreLimits` gains `aiRetryMs`, `aiRetryMaxMs` and `aiAttempts`. The worker pool
+  runs each worker's jobs one at a time, counts a job's timeout from when it starts, and reports
+  `busy`, `lost` and `crashed` separately (`PoolOutcome`).
+
+### Patch Changes
+
+- bb095c7: Share canonical IPv4 and IPv6 /64 rate-limit keys across Node services. Keep room
+  initialization diagnostics on the server behind a client-safe reference, and expire old
+  message-rate strikes. Extend hidden-information conformance checks with transition-aware
+  perturbations so private events remain testable when recipients gain cards.
+- Updated dependencies [bb095c7]
+- Updated dependencies [bb095c7]
+- Updated dependencies [bb095c7]
+  - @joystyk/contracts@0.2.0
+  - @joystyk/ops@0.2.0
+  - @joystyk/identity@0.2.0
+  - @joystyk/kit@0.2.0
+
+## 0.1.0
+
+### Minor Changes
+
+- Prepare the first compiled library release: ESM and API declarations for every public entry point, runtime assets, and checks against installed npm tarballs. Games and applications remain private.
+
+### Patch Changes
+
+- Updated dependencies
+  - @joystyk/contracts@0.1.0
+  - @joystyk/kit@0.1.0
+  - @joystyk/identity@0.1.0

package/README.md

@@ -1,5 +1,150 @@
 # @joystyk/rooms
 
-The first Joystyk library release is not yet available. This placeholder reserves the package name.
+The room server for every server-authoritative multiplayer game: a pure room core, the
+versioned wire protocol, and a Node adapter that runs the core on WebSockets, SQLite, one
+timer per room and a `worker_threads` job pool. The design is
+room-server.md (Joystyk host reference); its "Changes from implementation"
+section lists where this package departs from the first draft.
 
-Source: https://github.com/joystyk-games/game-libraries
+## npm package
+
+The first `0.1.0` release is being prepared; it has not been published. Once available:
+
+```sh
+npm install @joystyk/rooms
+```
+
+Node consumers require Node 24.15 or later. Browser entry points require a modern
+browser and should be loaded in the browser.
+
+| Import | Format |
+| --- | --- |
+| `@joystyk/rooms` | ES module and TypeScript declarations |
+| `@joystyk/rooms/protocol` | ES module and TypeScript declarations |
+| `@joystyk/rooms/node` | ES module and TypeScript declarations |
+
+Only the entries listed above are public API. Installed packages contain compiled ESM,
+type declarations and runtime assets. Repository-relative links describe the Joystyk
+workspace and are not needed to use the npm package.
+
+| Entry | Kind | Contents |
+| --- | --- | --- |
+| `@joystyk/rooms` | Pure | `createRoomCore`, the room types, the record schema and migrations, `policyFromManifest`, `admitName` |
+| `@joystyk/rooms/protocol` | Pure (`zod/mini`) | Wire schemas and types, `PROTOCOL_VERSION`, close and rejection codes |
+| `@joystyk/rooms/node` | Node | `createRoomServer`, `RoomHost`, `openSqliteStore`, `workerJobPool`, `createEngineRegistry` |
+
+The `session` package, and the `p2p` package that comes after launch (host policy), may import
+`@joystyk/rooms/protocol` and nothing else from here. The service that deploys all of this
+is `apps/rooms` (`@joystyk/rooms-server`).
+
+## The core
+
+A room is a value. Everything that happens to it goes through one function:
+
+```ts
+import { createRoomCore } from '@joystyk/rooms';
+
+const core = createRoomCore({ engine, pin: { id: 'hearts', build: '1.4.0', rulesVersion: 3, saveVersion: 2 }, rng: sfc32 });
+const created = core.create({ code, policy, config, seeds, creator: { name, tokenHash } }, now);
+let room = core.load(created.value);
+const { room: next, effects } = core.step(room, { type: 'resume' }, now);
+```
+
+`step(room, command, now)` reads no clock, randomness, storage or network. Commands are
+`join`, `leave`, `act`, `control` (ready, settings, fill-with-ai, remove-seat, start,
+offer, accept, decline, withdraw, leave-seat, resign), `resync`, `timer-fired`, `job-completed`, `ai-chosen`,
+`resume` and `close`. Effects are data for the adapter: `persist` (always first, at most
+once), `welcome`, `send`, `drop`, `alarm`, `start-job`, `start-ai` and `log`.
+
+What the core guarantees, each covered by the property tests in `core.property.test.ts`:
+
+- **Deterministic.** The same room, command and `now` give deeply equal steps.
+- **Persist before broadcast.** If the record changed, the first effect saves it; a
+  rejection changes nothing durable.
+- **Per-seat staleness.** An action is stale only if the seat's `decisionKey` changed
+  after the revision the client saw, so simultaneous moves aren't refused.
+- **Receipts.** A retried action ID with the same payload gets its original receipt, even
+  after a restart; the same ID with a different payload is refused.
+- **Clocks as data.** Deadlines live in the record; whatever is due at `now` applies before
+  the command. A timer that fires early, late or twice can't apply a stale move. A room
+  runs a per-move clock or a time bank with increment (`policy.bank`); banks are charged
+  from the record alone, never for a playback hold.
+- **The AI's stream.** Each AI decision gets a child forked from `aiRng` with the kit's
+  `forkRng`; the stream moves only when an AI move is accepted. A heavy AI
+  (`heavyAi: true`) never chooses inside a step: the core emits `start-ai`, the adapter runs
+  it on the pool, and `ai-chosen` applies only if the seat still waits on that decision.
+- **No leaks.** Each seat receives `viewFor(state, seat)` and `eventFor(event, seat)`;
+  spectators get the `null` view.
+- **Paused when empty.** With no player connected, no AI move, clock, offer or absence
+  policy runs. The pause is recorded (`match.pausedAt`), and when a player returns every
+  deadline moves on by its length, so no clock or bank is charged for it (host policy).
+- **Offers.** Any seated player offers a rematch, or to end a match early; the others
+  accept or decline, and the proposer may withdraw. A rematch starts once every seated
+  player has accepted (computer seats accept on their own); an early end needs every other
+  connected player, or a minute with nobody declining, and leaves no result (host policy).
+- **Pinned versions.** A match keeps its game build and rules version; a rematch starts on
+  the newest engine.
+- **Filtered names.** The creator's name and every name that claims a seat pass
+  `checkDisplayName` from `@joystyk/identity/names`, the only part of identity this package
+  imports. A refused name becomes a generated one, seeded by the room's code, epoch, revision
+  and seat, so the step stays deterministic; the player gets a `name-replaced` notice that
+  says why, and `POST /api/rooms` answers with the seat's `name` and the same `notice`.
+
+The core takes the engine's seeded generator as an argument (`rng: (state) => Rng`; the
+service passes the kit's `restoreRng`). The adapter supplies fresh seeds and token hashes; no
+secret ever enters the core.
+
+## The Node adapter
+
+```ts
+import { createEngineRegistry, createRoomServer, openSqliteStore, workerJobPool } from '@joystyk/rooms/node';
+
+const store = await openSqliteStore('/data/rooms.sqlite');
+const registry = createEngineRegistry([{ pin, engine, policy, jobs: { throw: new URL('./jobs/throw.worker.ts', import.meta.url) } }], sfc32);
+const server = createRoomServer({ store, registry, seeds, pool: workerJobPool({ workers: 1, module: registry.jobModule }), publicOrigin });
+await server.listen(8787);
+process.once('SIGTERM', () => void server.drain());
+```
+
+- **HTTP.** `POST /api/rooms` creates a room and returns its code with the creator's seat
+  token; `GET /api/rooms/:code` describes it; `GET /api/rooms/games` lists the games the
+  registry hosts and the protocol versions (`HostedGames`), which the launcher reads before
+  offering Online with friends; `/healthz` and `/readyz` serve Compose.
+- **WebSocket** at `/ws`. Messages are decoded with the protocol schemas, then the game's
+  own command schema. The server answers each connection in the protocol version it joined
+  with.
+- **Persistence.** `node:sqlite` in WAL mode. Each persist is one transaction that updates
+  the row only if its `writes` count matches, so a second writer gets `conflict` and
+  unloads. A failed write keeps the old state, sends nothing and retries. Schema migrations
+  run at start-up, a newer database is refused, and corrupt rows move to `room_archive`.
+- **Limits.** Payload size, a message-rate token bucket, rooms per address per hour,
+  unknown-code joins per address, connections per address and in total, rooms in memory,
+  spectators per room, outgoing buffer size and a WebSocket ping heartbeat. The client address
+  is read only from a trusted proxy (an IP or CIDR range).
+- **Jobs.** A game's `jobs/<kind>.worker.ts` default-exports `(payload) => JobOutcome`; its
+  `jobs/ai.worker.ts` (heavy AI) maps `{ view, seat, level, rng }` to a command. The pool
+  bounds queued work, times out stuck jobs from when they start (a heavy AI after
+  `aiTimeoutMs`) and restarts the worker. A heavy AI the pool couldn't answer is asked again
+  with backoff.
+- **Drain and resume.** `drain()` refuses new work, waits for running jobs, sends
+  `closing` and closes with 1012. On start, rooms with an outstanding job load at once so
+  the job re-runs; other rooms load when someone joins.
+- **Logs.** One JSON object per line, never with tokens, names, addresses or game state.
+
+## Tests
+
+| File | What it proves |
+| --- | --- |
+| `core.test.ts` | Seats and display names, receipts, stale and future revisions, controls, AI handover, the host, clocks, jobs, failures |
+| `core.clocks-ai.test.ts` | Time banks, the AI stream, heavy AI |
+| `core.pause.test.ts` | A paused table: clocks stop and resume, banks are charged only for live time, a pause survives a restart |
+| `core.offers.test.ts` | Rematch and end-match offers: offer, accept, decline, withdraw, computer seats accepting, the one-minute end, a pause during it |
+| `core.property.test.ts` | The invariants above, under random command sequences for five set-ups: hidden hands, AI handover, heavy AI, a time bank and a simultaneous phase |
+| `protocol/protocol.test.ts` | Message schemas, and that every message the core sends decodes |
+| `node/store.test.ts` | The SQLite store on a real file: conflicts, migrations, quarantine, backups |
+| `node/host.test.ts` | Restart and resume, a failing store, two writers, jobs that survive a restart |
+| `node/server.test.ts` | Two real WebSocket clients: join, play, reconnect, newest tab wins, spectators, a replaced name, limits, drain |
+| `node/jobs.test.ts` | The `worker_threads` pool with real worker modules |
+
+The test games live in `src/__tests__/fixtures.ts`: Nim (turn-based), Peek (hidden hands,
+a job, an AI) and Pass (a simultaneous phase whose decision key ignores who has passed).

package/dist/canonical.d.ts

@@ -0,0 +1,10 @@
+import type { Json } from '@joystyk/contracts';
+/** JSON with object keys sorted, so equal values always produce the same text. */
+export declare const canonicalJson: (value: Json) => string;
+/**
+ * A 64-bit hash of a string as 16 hex digits (two independent 32-bit FNV-1a style lanes).
+ * Not cryptographic: it only tells a retried action from a different one with the same ID.
+ */
+export declare const hashText: (text: string) => string;
+/** The receipt fingerprint of an action: canonical JSON of what the client sent, hashed. */
+export declare const fingerprint: (value: Json) => string;

package/dist/canonical.js

@@ -0,0 +1,30 @@
+//#region src/canonical.ts
+/** JSON with object keys sorted, so equal values always produce the same text. */
+var canonicalJson = (value) => {
+	if (value === null || typeof value !== "object") return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+	const object = value;
+	return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(object[key])}`).join(",")}}`;
+};
+/**
+* A 64-bit hash of a string as 16 hex digits (two independent 32-bit FNV-1a style lanes).
+* Not cryptographic: it only tells a retried action from a different one with the same ID.
+*/
+var hashText = (text) => {
+	let a = 2166136261;
+	let b = 16777619 ^ text.length;
+	for (let i = 0; i < text.length; i += 1) {
+		const code = text.charCodeAt(i);
+		a = Math.imul(a ^ code, 16777619);
+		b = Math.imul(b ^ code, 1540483477);
+		b ^= b >>> 13;
+	}
+	const hex = (n) => (n >>> 0).toString(16).padStart(8, "0");
+	return hex(a) + hex(b);
+};
+/** The receipt fingerprint of an action: canonical JSON of what the client sent, hashed. */
+var fingerprint = (value) => hashText(canonicalJson(value));
+//#endregion
+export { canonicalJson, fingerprint, hashText };
+
+//# sourceMappingURL=canonical.js.map

package/dist/canonical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.js","names":[],"sources":["../src/canonical.ts"],"sourcesContent":["// Canonical JSON and a small pure hash, for receipt fingerprints and change detection. Pure\n// and deterministic in every JavaScript engine: integer arithmetic through Math.imul only.\nimport type { Json } from '@joystyk/contracts';\n\n/** JSON with object keys sorted, so equal values always produce the same text. */\nexport const canonicalJson = (value: Json): string => {\n  if (value === null || typeof value !== 'object') return JSON.stringify(value);\n  if (Array.isArray(value)) return `[${value.map((item: Json) => canonicalJson(item)).join(',')}]`;\n  const object = value as { readonly [key: string]: Json };\n  const keys = Object.keys(object).sort();\n  return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(object[key] as Json)}`).join(',')}}`;\n};\n\n/**\n * A 64-bit hash of a string as 16 hex digits (two independent 32-bit FNV-1a style lanes).\n * Not cryptographic: it only tells a retried action from a different one with the same ID.\n */\nexport const hashText = (text: string): string => {\n  let a = 0x811c9dc5;\n  let b = 0x01000193 ^ text.length;\n  for (let i = 0; i < text.length; i += 1) {\n    const code = text.charCodeAt(i);\n    a = Math.imul(a ^ code, 0x01000193);\n    b = Math.imul(b ^ code, 0x5bd1e995);\n    b ^= b >>> 13;\n  }\n  const hex = (n: number): string => (n >>> 0).toString(16).padStart(8, '0');\n  return hex(a) + hex(b);\n};\n\n/** The receipt fingerprint of an action: canonical JSON of what the client sent, hashed. */\nexport const fingerprint = (value: Json): string => hashText(canonicalJson(value));\n"],"mappings":";;AAKA,IAAa,iBAAiB,UAAwB;CACpD,IAAI,UAAU,QAAQ,OAAO,UAAU,UAAU,OAAO,KAAK,UAAU,KAAK;CAC5E,IAAI,MAAM,QAAQ,KAAK,GAAG,OAAO,IAAI,MAAM,KAAK,SAAe,cAAc,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE;CAC9F,MAAM,SAAS;CAEf,OAAO,IADM,OAAO,KAAK,MAAM,CAAC,CAAC,KACtB,CAAA,CAAK,KAAK,QAAQ,GAAG,KAAK,UAAU,GAAG,EAAE,GAAG,cAAc,OAAO,IAAY,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE;AACzG;;;;;AAMA,IAAa,YAAY,SAAyB;CAChD,IAAI,IAAI;CACR,IAAI,IAAI,WAAa,KAAK;CAC1B,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK,GAAG;EACvC,MAAM,OAAO,KAAK,WAAW,CAAC;EAC9B,IAAI,KAAK,KAAK,IAAI,MAAM,QAAU;EAClC,IAAI,KAAK,KAAK,IAAI,MAAM,UAAU;EAClC,KAAK,MAAM;CACb;CACA,MAAM,OAAO,OAAuB,MAAM,EAAA,CAAG,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG;CACzE,OAAO,IAAI,CAAC,IAAI,IAAI,CAAC;AACvB;;AAGA,IAAa,eAAe,UAAwB,SAAS,cAAc,KAAK,CAAC"}

package/dist/core.d.ts

@@ -0,0 +1,3 @@
+import { type RoomCore, type RoomCoreOptions } from './types.js';
+/** Binds the core to one engine at one rules version. */
+export declare const createRoomCore: (options: RoomCoreOptions) => RoomCore;