@hadoku/game-server 0.0.0-stage → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (119) hide show
  1. package/LICENSE +21 -0
  2. package/dist/base-path.d.ts +29 -0
  3. package/dist/base-path.js +30 -0
  4. package/dist/busy.d.ts +40 -0
  5. package/dist/busy.js +23 -0
  6. package/dist/capacity.d.ts +9 -0
  7. package/dist/capacity.js +6 -0
  8. package/dist/config.d.ts +247 -0
  9. package/dist/config.js +271 -0
  10. package/dist/edge-auth.d.ts +43 -0
  11. package/dist/edge-auth.js +47 -0
  12. package/dist/erase/anonymise.d.ts +7 -0
  13. package/dist/erase/anonymise.js +7 -0
  14. package/dist/erase/index.d.ts +18 -0
  15. package/dist/erase/index.js +20 -0
  16. package/dist/erase/legacy-ids.d.ts +7 -0
  17. package/dist/erase/legacy-ids.js +24 -0
  18. package/dist/erase/recordings.d.ts +26 -0
  19. package/dist/erase/recordings.js +128 -0
  20. package/dist/erase/rooms.d.ts +63 -0
  21. package/dist/erase/rooms.js +67 -0
  22. package/dist/gate.d.ts +27 -0
  23. package/dist/gate.js +15 -0
  24. package/dist/http/client-events.d.ts +25 -0
  25. package/dist/http/client-events.js +15 -0
  26. package/dist/http/page.d.ts +26 -0
  27. package/dist/http/page.js +35 -0
  28. package/dist/http/prepared.d.ts +14 -0
  29. package/dist/http/prepared.js +16 -0
  30. package/dist/http/request.d.ts +59 -0
  31. package/dist/http/request.js +37 -0
  32. package/dist/http/room-core.d.ts +160 -0
  33. package/dist/http/room-core.js +278 -0
  34. package/dist/http/trim.d.ts +23 -0
  35. package/dist/http/trim.js +76 -0
  36. package/dist/http/usage.d.ts +22 -0
  37. package/dist/http/usage.js +16 -0
  38. package/dist/kernel.d.ts +4 -0
  39. package/dist/kernel.js +26 -0
  40. package/dist/log.d.ts +9 -0
  41. package/dist/log.js +9 -0
  42. package/dist/people.d.ts +105 -0
  43. package/dist/people.js +145 -0
  44. package/dist/play/clock.d.ts +39 -0
  45. package/dist/play/clock.js +81 -0
  46. package/dist/play/diagnostics.d.ts +21 -0
  47. package/dist/play/diagnostics.js +35 -0
  48. package/dist/play/engine-runtime.d.ts +200 -0
  49. package/dist/play/engine-runtime.js +309 -0
  50. package/dist/play/game-adapter.d.ts +158 -0
  51. package/dist/play/game-adapter.js +1 -0
  52. package/dist/play/host.d.ts +482 -0
  53. package/dist/play/host.js +950 -0
  54. package/dist/play/jvm-transport.d.ts +25 -0
  55. package/dist/play/jvm-transport.js +1 -0
  56. package/dist/play/local-jvm.d.ts +325 -0
  57. package/dist/play/local-jvm.js +829 -0
  58. package/dist/play/match/hosted.d.ts +92 -0
  59. package/dist/play/match/hosted.js +151 -0
  60. package/dist/play/match/outcome.d.ts +26 -0
  61. package/dist/play/match/outcome.js +21 -0
  62. package/dist/play/match/shell.d.ts +378 -0
  63. package/dist/play/match/shell.js +613 -0
  64. package/dist/play/recording/retention.d.ts +36 -0
  65. package/dist/play/recording/retention.js +89 -0
  66. package/dist/play/recording/writer.d.ts +185 -0
  67. package/dist/play/recording/writer.js +90 -0
  68. package/dist/play/relay-socket.d.ts +128 -0
  69. package/dist/play/relay-socket.js +194 -0
  70. package/dist/play/runtimes/in-process.d.ts +47 -0
  71. package/dist/play/runtimes/in-process.js +43 -0
  72. package/dist/play/runtimes/relay-match.d.ts +166 -0
  73. package/dist/play/runtimes/relay-match.js +240 -0
  74. package/dist/play/runtimes/relay.d.ts +128 -0
  75. package/dist/play/runtimes/relay.js +183 -0
  76. package/dist/play/runtimes/streamed.d.ts +116 -0
  77. package/dist/play/runtimes/streamed.js +148 -0
  78. package/dist/play/start-queue.d.ts +65 -0
  79. package/dist/play/start-queue.js +187 -0
  80. package/dist/room/avatar.d.ts +1 -0
  81. package/dist/room/avatar.js +28 -0
  82. package/dist/room/caller.d.ts +21 -0
  83. package/dist/room/caller.js +1 -0
  84. package/dist/room/constants.d.ts +27 -0
  85. package/dist/room/constants.js +27 -0
  86. package/dist/room/events.d.ts +59 -0
  87. package/dist/room/events.js +174 -0
  88. package/dist/room/identity.d.ts +89 -0
  89. package/dist/room/identity.js +98 -0
  90. package/dist/room/lobby.d.ts +426 -0
  91. package/dist/room/lobby.js +880 -0
  92. package/dist/room/membership.d.ts +64 -0
  93. package/dist/room/membership.js +76 -0
  94. package/dist/room/provisioning.d.ts +22 -0
  95. package/dist/room/provisioning.js +46 -0
  96. package/dist/room/record.d.ts +63 -0
  97. package/dist/room/record.js +39 -0
  98. package/dist/room/room-list.d.ts +67 -0
  99. package/dist/room/room-list.js +66 -0
  100. package/dist/room/seats.d.ts +39 -0
  101. package/dist/room/seats.js +58 -0
  102. package/dist/room/session.d.ts +91 -0
  103. package/dist/room/session.js +156 -0
  104. package/dist/room/socket-auth.d.ts +2 -0
  105. package/dist/room/socket-auth.js +10 -0
  106. package/dist/room/watching.d.ts +35 -0
  107. package/dist/room/watching.js +72 -0
  108. package/dist/room/watchparty-link.d.ts +1 -0
  109. package/dist/room/watchparty-link.js +17 -0
  110. package/dist/stream/alloc.d.ts +115 -0
  111. package/dist/stream/alloc.js +368 -0
  112. package/dist/stream/index.d.ts +66 -0
  113. package/dist/stream/index.js +293 -0
  114. package/dist/telemetry.d.ts +46 -0
  115. package/dist/telemetry.js +25 -0
  116. package/dist/testPort.d.ts +1 -0
  117. package/dist/testPort.js +28 -0
  118. package/package.json +36 -4
  119. package/README.md +0 -3
@@ -0,0 +1,368 @@
1
+ /*
2
+ * Containers a ROOM owns — allocation, and getting them back.
3
+ *
4
+ * ## What this is
5
+ *
6
+ * `index.ts`'s static half (`/stream/<n>/`) is a fixed bench an operator
7
+ * starts by hand. This is the other half: a room created in `streamed` mode
8
+ * gets **one container per seat** (operator, 2026-09-22 — a 2-player streamed
9
+ * room is 2 containers, ~2.5 GiB; a shared screen is cheaper and is not a
10
+ * game), each with its own host port, recorded against the room key.
11
+ *
12
+ * ## Nothing here talks to docker
13
+ *
14
+ * Every container this module creates, destroys or counts goes through
15
+ * `scripts/stream/container.sh`. That script refuses the bench's names and
16
+ * ports, and has a dry-run mode — which is why this allocator is testable end
17
+ * to end on a machine with no docker, and why an auditor reads one file to
18
+ * know every container the product can make.
19
+ *
20
+ * ## Reclaim, because a container is 1.3 GiB
21
+ *
22
+ * Two ways an allocation goes away, both driven by `sweep()`:
23
+ *
24
+ * - **The room is gone.** `roomExists` is the server's own lookup (lobby
25
+ * rooms and draft pods). A room nobody can join keeps nothing running.
26
+ * - **Nobody is watching.** No websocket attached for `idleMs`
27
+ * (default 30 minutes) → the containers are destroyed.
28
+ *
29
+ * 30 minutes, and not 5: destroying a streamed container destroys the *match
30
+ * inside it* — the game state lives in that Forge process, not in our server
31
+ * — and a cold container is ~18 s from `docker run` to a usable window
32
+ * (`docs/spikes/streaming.md`). Reclaiming at coffee-break scale would delete
33
+ * real games; 30 minutes is past any break and far short of leaving a GiB
34
+ * burning overnight.
35
+ *
36
+ * A reclaimed room is remembered as **dead**, with the reason. That is the
37
+ * difference between a link that says "these streams were reclaimed" and one
38
+ * that 502s forever looking alive — see `statusOf`.
39
+ */
40
+ import { execFile } from 'node:child_process';
41
+ import { existsSync } from 'node:fs';
42
+ import { dirname, join, resolve } from 'node:path';
43
+ import { fileURLToPath } from 'node:url';
44
+ import { ROOM_ID_RE } from '@wolffm/platform-wire/room-feed';
45
+ import { CONFIG } from '../config.js';
46
+ /**
47
+ * The first host port a room's seat may take.
48
+ *
49
+ * Deliberately clear of everything else on this host: 6080–6081 are the static
50
+ * bench, and the e2e harness picks its ports from 20000 up (`e2e/ports.ts`). `container.sh` refuses
51
+ * anything below 6100 a second time, in case this constant is ever loosened.
52
+ */
53
+ export const ROOM_STREAM_BASE_PORT = CONFIG.roomStreamBasePort;
54
+ /**
55
+ * How many streamed seats may exist on this host AT ONCE, across all rooms.
56
+ *
57
+ * The real cap is memory, not ports: 1.3 GiB per desktop measured, ~22 GiB
58
+ * free on this box with production up (`docs/spikes/streaming.md` §host). Eight
59
+ * is ~10.4 GiB — four 2-player rooms, or one pod — and leaves the JVM pool and
60
+ * 24 PM2 services their room. Raising it is a memory decision, not a port one.
61
+ */
62
+ const ROOM_STREAM_POOL = 8;
63
+ /** Seats in one room. A pod is 8; a constructed table is 2. */
64
+ export const MAX_ROOM_SEATS = 8;
65
+ /** No websocket attached for this long → the containers go. See the header. */
66
+ export const IDLE_RECLAIM_MS = 30 * 60_000;
67
+ /**
68
+ * Container names: `<prefix>-<roomKey>-<seat>`. `container.sh` enforces it.
69
+ *
70
+ * **Env-settable because the prefix is this server's OWNERSHIP claim, and a
71
+ * host can run more than one cardtable.** `sweepOrphans()` destroys every
72
+ * container matching the prefix that this process's `live` map does not own —
73
+ * which is right for reclaiming what a restart of THIS server left behind, and
74
+ * catastrophic across two servers sharing one name. A `pnpm e2e` run boots a
75
+ * second server on the machine that runs production: with one prefix its boot
76
+ * sweep would delete a real player's containers mid-match. The e2e harness
77
+ * therefore sets its own prefix, and `container.sh` already reads the same
78
+ * variable, so the script and the server can never disagree about what this
79
+ * server may touch.
80
+ */
81
+ const CONTAINER_NAME_PREFIX = CONFIG.streamNamePrefix;
82
+ /**
83
+ * Where `scripts/stream/container.sh` is, found by walking up from this file.
84
+ *
85
+ * It cannot be a fixed relative path: in tests this module is
86
+ * `packages/game-server/src/stream/alloc.ts`, and in production it is bundled into
87
+ * `apps/server/dist/index.js`. Walking until the script is actually there is
88
+ * the one form that is right in both.
89
+ */
90
+ export function findContainerScript(from = fileURLToPath(import.meta.url)) {
91
+ let dir = dirname(from);
92
+ for (let i = 0; i < 8; i += 1) {
93
+ const candidate = join(dir, 'scripts', 'stream', 'container.sh');
94
+ if (existsSync(candidate))
95
+ return candidate;
96
+ const up = resolve(dir, '..');
97
+ if (up === dir)
98
+ break;
99
+ dir = up;
100
+ }
101
+ return null;
102
+ }
103
+ /** The real script, as a `ContainerScript`. `env` is merged over the process's. */
104
+ export function scriptRunner(scriptPath, env = {}) {
105
+ const run = (args) => new Promise((res, rej) => {
106
+ execFile('/usr/bin/env', ['bash', scriptPath, ...args], { env: { ...process.env, ...env }, timeout: 120_000 }, (err, stdout, stderr) => {
107
+ if (err !== null) {
108
+ rej(new Error(`container.sh ${args[0] ?? '?'}: ${stderr.trim() || err.message}`));
109
+ return;
110
+ }
111
+ res(stdout);
112
+ });
113
+ });
114
+ return {
115
+ async up(name, port, network) {
116
+ await run(['up', name, String(port), network]);
117
+ },
118
+ async down(name) {
119
+ await run(['down', name]);
120
+ },
121
+ async list(prefix) {
122
+ const out = await run(['list', prefix]);
123
+ return out.split('\n').map((l) => l.trim()).filter((l) => l !== '');
124
+ },
125
+ async netDown(network) {
126
+ await run(['net-down', network]);
127
+ },
128
+ };
129
+ }
130
+ /**
131
+ * A room key must not be readable as a static stream index.
132
+ *
133
+ * `/stream/3/` is the bench's third container; `/stream/3/0/` must never be a
134
+ * room called `3`. Room ids are minted by the lobby and may be all digits, so
135
+ * the two namespaces are kept disjoint HERE — at allocation — rather than by
136
+ * hoping a parser stays ambiguous in the right direction.
137
+ */
138
+ export function isStaticIndexLike(roomKey) {
139
+ return /^\d+$/.test(roomKey);
140
+ }
141
+ export function createRoomStreams(options) {
142
+ const now = options.now ?? Date.now;
143
+ const basePort = options.basePort ?? ROOM_STREAM_BASE_PORT;
144
+ const poolSize = options.poolSize ?? ROOM_STREAM_POOL;
145
+ const idleMs = options.idleMs ?? IDLE_RECLAIM_MS;
146
+ const prefix = options.namePrefix ?? CONTAINER_NAME_PREFIX;
147
+ const log = options.log ?? (() => { });
148
+ const script = options.script ??
149
+ (() => {
150
+ const found = findContainerScript();
151
+ if (found === null)
152
+ throw new Error('scripts/stream/container.sh not found — the allocator cannot run');
153
+ return scriptRunner(found);
154
+ })();
155
+ const live = new Map();
156
+ /** Reclaimed rooms, so a link answers honestly instead of 502ing forever. */
157
+ const dead = new Map();
158
+ const DEAD_MEMORY = 64;
159
+ const takenPorts = () => {
160
+ const taken = new Set();
161
+ for (const alloc of live.values())
162
+ for (const s of alloc.seats)
163
+ taken.add(s.port);
164
+ return taken;
165
+ };
166
+ const remember = (roomKey, reason) => {
167
+ dead.set(roomKey, { reason, at: now() });
168
+ // Bounded: the oldest entry goes first. A Map iterates in insertion
169
+ // order, and `set` above re-inserts, so this is a plain LRU by death.
170
+ while (dead.size > DEAD_MEMORY) {
171
+ const oldest = dead.keys().next();
172
+ if (oldest.done === true)
173
+ break;
174
+ dead.delete(oldest.value);
175
+ }
176
+ };
177
+ const destroy = async (alloc, reason) => {
178
+ for (const seat of alloc.seats) {
179
+ try {
180
+ await script.down(seat.container);
181
+ }
182
+ catch (err) {
183
+ // One container that will not die must not strand the others,
184
+ // nor abort a sweep with other rooms still to reclaim.
185
+ log({ evt: 'stream-reclaim-failed', room: alloc.roomKey, container: seat.container, err: String(err) });
186
+ }
187
+ }
188
+ try {
189
+ await script.netDown(alloc.network);
190
+ }
191
+ catch (err) {
192
+ log({ evt: 'stream-network-reclaim-failed', room: alloc.roomKey, err: String(err) });
193
+ }
194
+ live.delete(alloc.roomKey);
195
+ remember(alloc.roomKey, reason);
196
+ log({ evt: 'stream-reclaimed', room: alloc.roomKey, reason, seats: alloc.seats.length });
197
+ options.onEnded?.(alloc.roomKey, reason);
198
+ };
199
+ return {
200
+ async allocate(roomKey, seatCount) {
201
+ if (!ROOM_ID_RE.test(roomKey)) {
202
+ return { ok: false, reason: 'bad-room-key', detail: 'a room key is 1-40 of [a-z0-9-]' };
203
+ }
204
+ if (isStaticIndexLike(roomKey)) {
205
+ return {
206
+ ok: false,
207
+ reason: 'bad-room-key',
208
+ detail: `'${roomKey}' reads as a static stream index; a room key may not be all digits`,
209
+ };
210
+ }
211
+ if (!Number.isInteger(seatCount) || seatCount < 1 || seatCount > MAX_ROOM_SEATS) {
212
+ return { ok: false, reason: 'bad-seat-count', detail: `1-${String(MAX_ROOM_SEATS)} seats, got ${String(seatCount)}` };
213
+ }
214
+ const already = live.get(roomKey);
215
+ if (already !== undefined)
216
+ return { ok: true, allocation: already };
217
+ const taken = takenPorts();
218
+ const ports = [];
219
+ for (let p = basePort; p < basePort + poolSize && ports.length < seatCount; p += 1) {
220
+ if (!taken.has(p))
221
+ ports.push(p);
222
+ }
223
+ if (ports.length < seatCount) {
224
+ return {
225
+ ok: false,
226
+ reason: 'no-ports',
227
+ detail: `${String(seatCount)} seats wanted, ${String(ports.length)} free of ${String(poolSize)}`,
228
+ };
229
+ }
230
+ const network = `${prefix}-${roomKey}`;
231
+ const seats = ports.map((port, seat) => ({
232
+ seat,
233
+ port,
234
+ container: `${prefix}-${roomKey}-${String(seat)}`,
235
+ }));
236
+ // Claim the ports before the first `up`: two concurrent allocates
237
+ // must not be handed the same port while docker is still starting.
238
+ const allocation = {
239
+ roomKey,
240
+ network,
241
+ seats,
242
+ createdAt: now(),
243
+ lastActiveAt: now(),
244
+ attached: 0,
245
+ };
246
+ live.set(roomKey, allocation);
247
+ const started = [];
248
+ for (const seat of seats) {
249
+ try {
250
+ await script.up(seat.container, seat.port, network);
251
+ started.push(seat);
252
+ }
253
+ catch (err) {
254
+ // Half a room is not a room. Take back what came up, so a
255
+ // failed allocate leaves the host exactly as it found it.
256
+ for (const s of started) {
257
+ try {
258
+ await script.down(s.container);
259
+ }
260
+ catch {
261
+ log({ evt: 'stream-rollback-failed', room: roomKey, container: s.container });
262
+ }
263
+ }
264
+ try {
265
+ await script.netDown(network);
266
+ }
267
+ catch {
268
+ log({ evt: 'stream-rollback-failed', room: roomKey, network });
269
+ }
270
+ live.delete(roomKey);
271
+ log({ evt: 'stream-provision-failed', room: roomKey, err: String(err) });
272
+ return { ok: false, reason: 'provision-failed', detail: String(err) };
273
+ }
274
+ }
275
+ dead.delete(roomKey);
276
+ log({ evt: 'stream-allocated', room: roomKey, seats: seats.length, ports });
277
+ return { ok: true, allocation };
278
+ },
279
+ find(roomKey) {
280
+ return live.get(roomKey);
281
+ },
282
+ portOf(roomKey, seat) {
283
+ return live.get(roomKey)?.seats.find((s) => s.seat === seat)?.port ?? null;
284
+ },
285
+ statusOf(roomKey) {
286
+ const alloc = live.get(roomKey);
287
+ if (alloc !== undefined) {
288
+ return { roomKey, state: 'live', seats: alloc.seats.length };
289
+ }
290
+ const gone = dead.get(roomKey);
291
+ if (gone !== undefined) {
292
+ return { roomKey, state: 'dead', seats: 0, reason: gone.reason, since: new Date(gone.at).toISOString() };
293
+ }
294
+ return { roomKey, state: 'none', seats: 0 };
295
+ },
296
+ list() {
297
+ return [...live.values()];
298
+ },
299
+ noteAttach(roomKey) {
300
+ const alloc = live.get(roomKey);
301
+ if (alloc === undefined)
302
+ return;
303
+ alloc.attached += 1;
304
+ alloc.lastActiveAt = now();
305
+ },
306
+ noteDetach(roomKey) {
307
+ const alloc = live.get(roomKey);
308
+ if (alloc === undefined)
309
+ return;
310
+ alloc.attached = Math.max(0, alloc.attached - 1);
311
+ // The idle window starts when the LAST socket leaves, which is what
312
+ // this timestamp means — not "when something last happened".
313
+ alloc.lastActiveAt = now();
314
+ },
315
+ async release(roomKey, reason) {
316
+ const alloc = live.get(roomKey);
317
+ if (alloc === undefined)
318
+ return;
319
+ await destroy(alloc, reason);
320
+ },
321
+ async sweep() {
322
+ const reclaimed = [];
323
+ const at = now();
324
+ for (const alloc of [...live.values()]) {
325
+ if (!options.roomExists(alloc.roomKey)) {
326
+ await destroy(alloc, 'room-gone');
327
+ reclaimed.push({ roomKey: alloc.roomKey, reason: 'room-gone' });
328
+ continue;
329
+ }
330
+ if (alloc.attached === 0 && at - alloc.lastActiveAt >= idleMs) {
331
+ await destroy(alloc, 'idle');
332
+ reclaimed.push({ roomKey: alloc.roomKey, reason: 'idle' });
333
+ }
334
+ }
335
+ return { reclaimed };
336
+ },
337
+ async sweepOrphans() {
338
+ const reclaimed = [];
339
+ let names;
340
+ try {
341
+ names = await script.list(prefix);
342
+ }
343
+ catch (err) {
344
+ log({ evt: 'stream-orphan-list-failed', err: String(err) });
345
+ return { reclaimed };
346
+ }
347
+ const ours = new Set();
348
+ for (const alloc of live.values())
349
+ for (const s of alloc.seats)
350
+ ours.add(s.container);
351
+ for (const name of names) {
352
+ if (ours.has(name))
353
+ continue;
354
+ // A container with our prefix that no allocation owns is what a
355
+ // restart leaves behind: 1.3 GiB with nothing to reach it.
356
+ try {
357
+ await script.down(name);
358
+ reclaimed.push({ roomKey: name, reason: 'orphan' });
359
+ log({ evt: 'stream-orphan-reclaimed', container: name });
360
+ }
361
+ catch (err) {
362
+ log({ evt: 'stream-orphan-reclaim-failed', container: name, err: String(err) });
363
+ }
364
+ }
365
+ return { reclaimed };
366
+ },
367
+ };
368
+ }
@@ -0,0 +1,66 @@
1
+ import type { Server } from 'node:http';
2
+ import type { Router } from 'express';
3
+ import { type RoomStreams } from './alloc.js';
4
+ export interface StreamDeps {
5
+ /** The tier floor. `CONFIG.minTier` — never lower, never a new tier. */
6
+ minTier: string;
7
+ /** Container n's noVNC port is `streamBasePort + n`. */
8
+ streamBasePort: number;
9
+ /** How many STATIC stream containers to expose. 0 → attach none of them. */
10
+ streamCount: number;
11
+ /** Room-keyed streams. Absent → only the static form exists. */
12
+ rooms?: RoomStreams | null;
13
+ /**
14
+ * Called when a room-keyed path names a room with no live containers.
15
+ * Fire-and-forget: provisioning is ~18 s of cold boot, so the request that
16
+ * triggered it is answered honestly ("not up yet") rather than held open.
17
+ * Wired in `index.ts`, where the lobby is in scope.
18
+ */
19
+ ensureRoom?: (roomKey: string) => void;
20
+ log?: (entry: Record<string, unknown>) => void;
21
+ }
22
+ export interface StreamHandle {
23
+ close(): void;
24
+ }
25
+ /** `/stream/3/websockify` → 3, or null when the path is not a stream path. */
26
+ export declare function streamIndexOf(url: string | undefined, count: number): number | null;
27
+ export interface RoomStreamPath {
28
+ roomKey: string;
29
+ seat: number;
30
+ /** What is left for the container: `/vnc.html`, `/websockify`, `/`. */
31
+ rest: string;
32
+ }
33
+ /**
34
+ * `/stream/kitchen-table/1/vnc.html` → that room's seat 1.
35
+ *
36
+ * Null for anything else — including a key that is all digits, which belongs
37
+ * to the static form and is refused at allocation for exactly this reason.
38
+ * The seat is bounded to two digits because a room has at most eight.
39
+ */
40
+ export declare function roomStreamPathOf(url: string | undefined): RoomStreamPath | null;
41
+ /**
42
+ * How many containers to expose, read from `STREAMS` on disk.
43
+ *
44
+ * A malformed count is zero containers, not a guess — each container is a
45
+ * proxy to a port, and guessing here is a port scan. Bounded because an
46
+ * unbounded count is the same scan with more steps.
47
+ */
48
+ export declare function streamLayout(exists?: (p: string) => boolean, read?: (p: string) => string): {
49
+ streamCount: number;
50
+ };
51
+ /**
52
+ * The HTTP half: noVNC's pages and assets, straight out of websockify.
53
+ *
54
+ * **Must be registered BEFORE the SPA fallback.** Below it, the fallback
55
+ * answers `/stream/0/vnc.html` with index.html and the link renders the
56
+ * cardtable app instead of noVNC — which is exactly what happened to this
57
+ * route's bench predecessor on 2026-09-21, and read like two browsers
58
+ * joining one room.
59
+ */
60
+ export declare function attachStreamRoutes(app: Router, deps: StreamDeps): boolean;
61
+ /**
62
+ * The websocket half: noVNC talks RFB over a websocket to websockify.
63
+ * express never sees an `upgrade`, so the tier floor is re-applied here by
64
+ * hand, with `../gate.ts`'s `gateUpgrade`.
65
+ */
66
+ export declare function attachStream(server: Server, deps: StreamDeps): StreamHandle | null;