@hadoku/game-server 0.0.0-stage → 0.1.6
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.
- package/LICENSE +21 -0
- package/dist/base-path.d.ts +29 -0
- package/dist/base-path.js +30 -0
- package/dist/busy.d.ts +40 -0
- package/dist/busy.js +23 -0
- package/dist/capacity.d.ts +9 -0
- package/dist/capacity.js +6 -0
- package/dist/config.d.ts +247 -0
- package/dist/config.js +271 -0
- package/dist/edge-auth.d.ts +43 -0
- package/dist/edge-auth.js +47 -0
- package/dist/erase/anonymise.d.ts +7 -0
- package/dist/erase/anonymise.js +7 -0
- package/dist/erase/index.d.ts +18 -0
- package/dist/erase/index.js +20 -0
- package/dist/erase/legacy-ids.d.ts +7 -0
- package/dist/erase/legacy-ids.js +24 -0
- package/dist/erase/recordings.d.ts +26 -0
- package/dist/erase/recordings.js +128 -0
- package/dist/erase/rooms.d.ts +63 -0
- package/dist/erase/rooms.js +67 -0
- package/dist/gate.d.ts +27 -0
- package/dist/gate.js +15 -0
- package/dist/http/client-events.d.ts +25 -0
- package/dist/http/client-events.js +15 -0
- package/dist/http/page.d.ts +26 -0
- package/dist/http/page.js +35 -0
- package/dist/http/prepared.d.ts +14 -0
- package/dist/http/prepared.js +16 -0
- package/dist/http/request.d.ts +59 -0
- package/dist/http/request.js +37 -0
- package/dist/http/room-core.d.ts +160 -0
- package/dist/http/room-core.js +278 -0
- package/dist/http/trim.d.ts +23 -0
- package/dist/http/trim.js +76 -0
- package/dist/http/usage.d.ts +22 -0
- package/dist/http/usage.js +16 -0
- package/dist/kernel.d.ts +4 -0
- package/dist/kernel.js +26 -0
- package/dist/log.d.ts +9 -0
- package/dist/log.js +9 -0
- package/dist/people.d.ts +105 -0
- package/dist/people.js +145 -0
- package/dist/play/clock.d.ts +39 -0
- package/dist/play/clock.js +81 -0
- package/dist/play/diagnostics.d.ts +21 -0
- package/dist/play/diagnostics.js +35 -0
- package/dist/play/engine-runtime.d.ts +200 -0
- package/dist/play/engine-runtime.js +309 -0
- package/dist/play/game-adapter.d.ts +158 -0
- package/dist/play/game-adapter.js +1 -0
- package/dist/play/host.d.ts +482 -0
- package/dist/play/host.js +950 -0
- package/dist/play/jvm-transport.d.ts +25 -0
- package/dist/play/jvm-transport.js +1 -0
- package/dist/play/local-jvm.d.ts +325 -0
- package/dist/play/local-jvm.js +829 -0
- package/dist/play/match/hosted.d.ts +92 -0
- package/dist/play/match/hosted.js +151 -0
- package/dist/play/match/outcome.d.ts +26 -0
- package/dist/play/match/outcome.js +21 -0
- package/dist/play/match/shell.d.ts +378 -0
- package/dist/play/match/shell.js +613 -0
- package/dist/play/recording/retention.d.ts +36 -0
- package/dist/play/recording/retention.js +89 -0
- package/dist/play/recording/writer.d.ts +185 -0
- package/dist/play/recording/writer.js +90 -0
- package/dist/play/relay-socket.d.ts +128 -0
- package/dist/play/relay-socket.js +194 -0
- package/dist/play/runtimes/in-process.d.ts +47 -0
- package/dist/play/runtimes/in-process.js +43 -0
- package/dist/play/runtimes/relay-match.d.ts +166 -0
- package/dist/play/runtimes/relay-match.js +240 -0
- package/dist/play/runtimes/relay.d.ts +128 -0
- package/dist/play/runtimes/relay.js +183 -0
- package/dist/play/runtimes/streamed.d.ts +116 -0
- package/dist/play/runtimes/streamed.js +148 -0
- package/dist/play/start-queue.d.ts +65 -0
- package/dist/play/start-queue.js +187 -0
- package/dist/room/avatar.d.ts +1 -0
- package/dist/room/avatar.js +28 -0
- package/dist/room/caller.d.ts +21 -0
- package/dist/room/caller.js +1 -0
- package/dist/room/constants.d.ts +27 -0
- package/dist/room/constants.js +27 -0
- package/dist/room/events.d.ts +59 -0
- package/dist/room/events.js +174 -0
- package/dist/room/identity.d.ts +89 -0
- package/dist/room/identity.js +98 -0
- package/dist/room/lobby.d.ts +426 -0
- package/dist/room/lobby.js +880 -0
- package/dist/room/membership.d.ts +64 -0
- package/dist/room/membership.js +76 -0
- package/dist/room/provisioning.d.ts +22 -0
- package/dist/room/provisioning.js +46 -0
- package/dist/room/record.d.ts +63 -0
- package/dist/room/record.js +39 -0
- package/dist/room/room-list.d.ts +67 -0
- package/dist/room/room-list.js +66 -0
- package/dist/room/seats.d.ts +39 -0
- package/dist/room/seats.js +58 -0
- package/dist/room/session.d.ts +91 -0
- package/dist/room/session.js +156 -0
- package/dist/room/socket-auth.d.ts +2 -0
- package/dist/room/socket-auth.js +10 -0
- package/dist/room/watching.d.ts +35 -0
- package/dist/room/watching.js +72 -0
- package/dist/room/watchparty-link.d.ts +1 -0
- package/dist/room/watchparty-link.js +17 -0
- package/dist/stream/alloc.d.ts +115 -0
- package/dist/stream/alloc.js +368 -0
- package/dist/stream/index.d.ts +66 -0
- package/dist/stream/index.js +293 -0
- package/dist/telemetry.d.ts +46 -0
- package/dist/telemetry.js +25 -0
- package/dist/testPort.d.ts +1 -0
- package/dist/testPort.js +28 -0
- package/package.json +35 -4
- package/README.md +0 -3
|
@@ -0,0 +1,309 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Generic process hosting for a game engine run as a long-lived subprocess: a run directory
|
|
3
|
+
* reached over named pipes that outlive the server, pid-based liveness (a recycled pid is some
|
|
4
|
+
* other program, never ours to claim), and the crash-record bookkeeping a boot sweep prunes.
|
|
5
|
+
* `local-jvm.ts` is the one caller today — Forge's bridge JVM, hosted through this file's
|
|
6
|
+
* primitives — and `EngineRuntime` below is the seam a later lane (L2, `host.ts` going generic)
|
|
7
|
+
* can rewire the coordinator through, so a non-JVM engine fits the same host.
|
|
8
|
+
*
|
|
9
|
+
* Nothing here knows about Forge, bridges, or `.dck` files. See `local-jvm.ts`'s own header for
|
|
10
|
+
* the run directory's on-disk shape and why a JVM outlives its server.
|
|
11
|
+
*/
|
|
12
|
+
import { spawnSync } from 'node:child_process';
|
|
13
|
+
import { closeSync, constants as fsConstants, existsSync, lstatSync, openSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, statSync, writeSync } from 'node:fs';
|
|
14
|
+
import { Socket } from 'node:net';
|
|
15
|
+
import { delimiter, join, sep } from 'node:path';
|
|
16
|
+
/** An `EngineProcess` over a real `child_process` — what every `spawn` implementation here wraps. */
|
|
17
|
+
export function wrapChildProcess(child) {
|
|
18
|
+
return {
|
|
19
|
+
pid: child.pid ?? -1,
|
|
20
|
+
onExit(cb) {
|
|
21
|
+
child.on('exit', cb);
|
|
22
|
+
},
|
|
23
|
+
onError(cb) {
|
|
24
|
+
child.on('error', cb);
|
|
25
|
+
},
|
|
26
|
+
dispose() {
|
|
27
|
+
child.removeAllListeners('exit');
|
|
28
|
+
child.removeAllListeners('error');
|
|
29
|
+
},
|
|
30
|
+
};
|
|
31
|
+
}
|
|
32
|
+
/* ── A whole number from an environment variable ────────────────────── */
|
|
33
|
+
/** A whole number of at least 1 from `raw`, else `fallback`. */
|
|
34
|
+
export function positiveInt(raw, fallback) {
|
|
35
|
+
const n = raw === undefined || raw.trim() === '' ? Number.NaN : Number(raw);
|
|
36
|
+
return Number.isInteger(n) && n >= 1 ? n : fallback;
|
|
37
|
+
}
|
|
38
|
+
/* ── Finding a JDK's `java` ───────────────────────────────────────────── */
|
|
39
|
+
/**
|
|
40
|
+
* The `java` to run when nothing names one, as an ABSOLUTE path whenever one can be found: a
|
|
41
|
+
* caller that also wants `javac` (to compile a bridge, say) looks beside it, and beside a bare
|
|
42
|
+
* `java` is `./javac`, which never exists.
|
|
43
|
+
*
|
|
44
|
+
* In order: `$JAVA_HOME/bin/java`, then the first `java` on `PATH` with its symlinks followed
|
|
45
|
+
* (`/usr/local/bin/java` is a link into the fleet's JDK, and `javac` sits beside the real file,
|
|
46
|
+
* not the link). A bare `java` only when neither exists.
|
|
47
|
+
*/
|
|
48
|
+
export function defaultJava(env = process.env) {
|
|
49
|
+
const candidates = [
|
|
50
|
+
...(env.JAVA_HOME ? [join(env.JAVA_HOME, 'bin', 'java')] : []),
|
|
51
|
+
...(env.PATH ?? '').split(delimiter).filter((dir) => dir !== '').map((dir) => join(dir, 'java')),
|
|
52
|
+
];
|
|
53
|
+
const found = candidates.find((p) => existsSync(p) && statSync(p).isFile());
|
|
54
|
+
return found === undefined ? 'java' : realpathSync(found);
|
|
55
|
+
}
|
|
56
|
+
/* ── Named pipes: a run directory's stdio ────────────────────────────── */
|
|
57
|
+
/** A process's stdin, opened by both ends. */
|
|
58
|
+
export const IN_FIFO = 'in.fifo';
|
|
59
|
+
/** A process's stdout, same treatment. */
|
|
60
|
+
export const OUT_FIFO = 'out.fifo';
|
|
61
|
+
/** Where a process's own `java.io.tmpdir`-style scratch space goes, inside the run dir. */
|
|
62
|
+
export const JVM_TMP_DIR = 'tmp';
|
|
63
|
+
/**
|
|
64
|
+
* Two named pipes in the run dir. `mkfifo(3)` has no binding in `node:fs`, so
|
|
65
|
+
* this shells out — once per run directory, at staging time.
|
|
66
|
+
*/
|
|
67
|
+
export function makeFifos(run) {
|
|
68
|
+
const made = spawnSync('mkfifo', [join(run, IN_FIFO), join(run, OUT_FIFO)], { stdio: 'pipe' });
|
|
69
|
+
if (made.error !== undefined)
|
|
70
|
+
throw made.error;
|
|
71
|
+
if (made.status !== 0) {
|
|
72
|
+
throw new Error(`mkfifo failed in ${run} (status ${made.status}): ${made.stderr?.toString().trim() ?? ''}`);
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
/** How soon a write the fifo had no room for is tried again. */
|
|
76
|
+
const STDIN_RETRY_MS = 20;
|
|
77
|
+
/**
|
|
78
|
+
* The read end is a `net.Socket` over the fd, **not** `fs.createReadStream`.
|
|
79
|
+
* That is not a style choice: `fs.read` on a blocking fifo fd parks a libuv
|
|
80
|
+
* THREADPOOL thread for as long as the fifo is empty, and the pool is four
|
|
81
|
+
* threads by default. Two matches and a spare is three readers waiting on a
|
|
82
|
+
* quiet Forge, and the fourth thread is every other piece of async file work
|
|
83
|
+
* this process does — which is how the first version of this deadlocked
|
|
84
|
+
* `host.test.ts` outright. `net.Socket` puts the fd in libuv's event loop
|
|
85
|
+
* (`uv_pipe_open`, epoll) and occupies no thread at all.
|
|
86
|
+
*/
|
|
87
|
+
export function openJvmIo(run, log) {
|
|
88
|
+
// The write end is non-blocking, and a line the fifo has no room for waits in `pending`.
|
|
89
|
+
// A blocking `writeSync` into a fifo nobody drains — a process that died before its stdin thread
|
|
90
|
+
// ran — parks the whole event loop: its own `exit` is never handled, every other match and
|
|
91
|
+
// socket stops, and the matches placed on it hold their ceiling slots for good. Our fd is
|
|
92
|
+
// `O_RDWR`, so a dead reader is no EPIPE; the fifo just fills. The child's stdin is its own
|
|
93
|
+
// open (the caller's `spawn`), so the process still reads a blocking fd.
|
|
94
|
+
const writeFd = openSync(join(run, IN_FIFO), fsConstants.O_RDWR | fsConstants.O_NONBLOCK);
|
|
95
|
+
const readFd = openSync(join(run, OUT_FIFO), 'r+');
|
|
96
|
+
const lines = new Socket({ fd: readFd, readable: true, writable: false });
|
|
97
|
+
lines.on('error', () => {
|
|
98
|
+
// The fd went with the process, or was closed under us. The exit path says why.
|
|
99
|
+
});
|
|
100
|
+
const pending = [];
|
|
101
|
+
let retry = null;
|
|
102
|
+
let closed = false;
|
|
103
|
+
let waitingSince = null;
|
|
104
|
+
const flush = () => {
|
|
105
|
+
retry = null;
|
|
106
|
+
while (!closed && pending.length > 0) {
|
|
107
|
+
const head = pending[0];
|
|
108
|
+
let wrote;
|
|
109
|
+
try {
|
|
110
|
+
wrote = writeSync(writeFd, head);
|
|
111
|
+
}
|
|
112
|
+
catch (err) {
|
|
113
|
+
if (err.code === 'EAGAIN') {
|
|
114
|
+
if (waitingSince === null) {
|
|
115
|
+
waitingSince = Date.now();
|
|
116
|
+
log({ evt: 'bridge-stdin-full', run, queued: pending.reduce((n, b) => n + b.length, 0) });
|
|
117
|
+
}
|
|
118
|
+
retry = setTimeout(flush, STDIN_RETRY_MS);
|
|
119
|
+
return;
|
|
120
|
+
}
|
|
121
|
+
// The fd is gone with the process. The exit path reports that.
|
|
122
|
+
log({ evt: 'bridge-stdin-error', run, error: err.message });
|
|
123
|
+
pending.length = 0;
|
|
124
|
+
return;
|
|
125
|
+
}
|
|
126
|
+
if (wrote < head.length)
|
|
127
|
+
pending[0] = head.subarray(wrote);
|
|
128
|
+
else
|
|
129
|
+
pending.shift();
|
|
130
|
+
}
|
|
131
|
+
if (waitingSince !== null) {
|
|
132
|
+
log({ evt: 'bridge-stdin-drained', run, waitedMs: Date.now() - waitingSince });
|
|
133
|
+
waitingSince = null;
|
|
134
|
+
}
|
|
135
|
+
};
|
|
136
|
+
return {
|
|
137
|
+
write(line) {
|
|
138
|
+
if (closed)
|
|
139
|
+
return;
|
|
140
|
+
pending.push(Buffer.from(`${line}\n`));
|
|
141
|
+
if (retry === null && pending.length === 1)
|
|
142
|
+
flush();
|
|
143
|
+
},
|
|
144
|
+
lines,
|
|
145
|
+
close() {
|
|
146
|
+
closed = true;
|
|
147
|
+
pending.length = 0;
|
|
148
|
+
if (retry !== null)
|
|
149
|
+
clearTimeout(retry);
|
|
150
|
+
lines.destroy();
|
|
151
|
+
try {
|
|
152
|
+
closeSync(writeFd);
|
|
153
|
+
}
|
|
154
|
+
catch {
|
|
155
|
+
// Already closed, or the fd went with the stream. Nothing to recover.
|
|
156
|
+
}
|
|
157
|
+
},
|
|
158
|
+
};
|
|
159
|
+
}
|
|
160
|
+
/* ── Pid liveness: a recycled pid is some other program ──────────────── */
|
|
161
|
+
/**
|
|
162
|
+
* Is `pid` still the process standing in `run`? The cwd check is what makes
|
|
163
|
+
* this safe against pid reuse: a recycled pid is some other program, in some
|
|
164
|
+
* other directory. Null when `/proc` cannot answer.
|
|
165
|
+
*/
|
|
166
|
+
export function pidIsStandingIn(pid, run) {
|
|
167
|
+
let cwd;
|
|
168
|
+
try {
|
|
169
|
+
cwd = readlinkSync(`/proc/${pid}/cwd`);
|
|
170
|
+
}
|
|
171
|
+
catch (err) {
|
|
172
|
+
const code = err.code;
|
|
173
|
+
if (code === 'ENOENT' || code === 'ESRCH')
|
|
174
|
+
return false;
|
|
175
|
+
// EACCES/EPERM: the process exists and is not ours to inspect. Not ours to claim either.
|
|
176
|
+
if (code === 'EACCES' || code === 'EPERM')
|
|
177
|
+
return false;
|
|
178
|
+
return null;
|
|
179
|
+
}
|
|
180
|
+
return cwd === run;
|
|
181
|
+
}
|
|
182
|
+
/**
|
|
183
|
+
* `pidIsStandingIn`, tolerant of a run dir reached through a symlink: `/proc`
|
|
184
|
+
* answers with the resolved path and a run dir is not always resolved first, so the
|
|
185
|
+
* two spellings can differ.
|
|
186
|
+
*/
|
|
187
|
+
export function pidIsStandingInRun(pid, run) {
|
|
188
|
+
if (pidIsStandingIn(pid, run) === true)
|
|
189
|
+
return true;
|
|
190
|
+
let resolved;
|
|
191
|
+
try {
|
|
192
|
+
resolved = realpathSync(run);
|
|
193
|
+
}
|
|
194
|
+
catch {
|
|
195
|
+
return false;
|
|
196
|
+
}
|
|
197
|
+
return resolved !== run && pidIsStandingIn(pid, resolved) === true;
|
|
198
|
+
}
|
|
199
|
+
/**
|
|
200
|
+
* Alive, and not a zombie waiting to be reaped. A zombie still answers signal 0
|
|
201
|
+
* — it has a pid until its parent collects it — so `/proc/<pid>/stat` is what
|
|
202
|
+
* decides.
|
|
203
|
+
*/
|
|
204
|
+
export function pidIsRunning(pid) {
|
|
205
|
+
try {
|
|
206
|
+
return !readFileSync(`/proc/${pid}/stat`, 'utf8').includes(') Z ');
|
|
207
|
+
}
|
|
208
|
+
catch {
|
|
209
|
+
return false; // no /proc entry: it has exited
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
/** How long a kill will spin waiting for a SIGKILL to land. Measured at 0 ms. */
|
|
213
|
+
export const REAP_CONFIRM_MS = 100;
|
|
214
|
+
/** How often an attached process (which is nobody's child, so has no `exit` event) is checked for. */
|
|
215
|
+
export const PID_POLL_MS = 1000;
|
|
216
|
+
/**
|
|
217
|
+
* Block this thread for `ms`. Only ever used confirming a kill before the caller
|
|
218
|
+
* stops existing (`process.exit` a statement away), where there is no later tick to confirm in.
|
|
219
|
+
*/
|
|
220
|
+
export function sleepSync(ms) {
|
|
221
|
+
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
|
|
222
|
+
}
|
|
223
|
+
/** SIGKILL a pid we own, or say nothing: it may have gone between the check and here. */
|
|
224
|
+
export function killPid(pid) {
|
|
225
|
+
try {
|
|
226
|
+
process.kill(pid, 'SIGKILL');
|
|
227
|
+
}
|
|
228
|
+
catch {
|
|
229
|
+
// ESRCH — already gone, which is the outcome we wanted.
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
/** Marks a pruned-down run directory as a crash record rather than scaffolding to remove outright. */
|
|
233
|
+
export const CRASH_MARKER = 'crash.json';
|
|
234
|
+
/** Our run directories directly under `workDir`, as real paths, matching `namePattern`. */
|
|
235
|
+
export function runDirs(workDir, namePattern) {
|
|
236
|
+
if (!existsSync(workDir))
|
|
237
|
+
return [];
|
|
238
|
+
const root = realpathSync(workDir);
|
|
239
|
+
const dirs = [];
|
|
240
|
+
for (const name of readdirSync(root)) {
|
|
241
|
+
if (!namePattern.test(name))
|
|
242
|
+
continue;
|
|
243
|
+
const dir = join(root, name);
|
|
244
|
+
const stat = lstatSync(dir);
|
|
245
|
+
if (stat.isDirectory())
|
|
246
|
+
dirs.push({ name, dir, mtimeMs: stat.mtimeMs });
|
|
247
|
+
}
|
|
248
|
+
return dirs;
|
|
249
|
+
}
|
|
250
|
+
/** When a crash record (named `marker`, inside `dir`) was written: its own `at`, else `fallbackMtimeMs`. */
|
|
251
|
+
export function crashTime(dir, marker, fallbackMtimeMs) {
|
|
252
|
+
const at = Date.parse(JSON.parse(readFileSync(join(dir, marker), 'utf8')).at ?? '');
|
|
253
|
+
return Number.isNaN(at) ? fallbackMtimeMs : at;
|
|
254
|
+
}
|
|
255
|
+
/**
|
|
256
|
+
* Enforce a crash-record bound over directories matching `namePattern` under `workDir`: the
|
|
257
|
+
* newest `keep` within `maxAgeMs` stay, the rest are removed outright. Returns what it removed.
|
|
258
|
+
*/
|
|
259
|
+
export function pruneCrashRecords(workDir, namePattern, marker, keep, maxAgeMs, now = Date.now()) {
|
|
260
|
+
const records = runDirs(workDir, namePattern)
|
|
261
|
+
.filter((d) => existsSync(join(d.dir, marker)))
|
|
262
|
+
.map((d) => ({ ...d, at: crashTime(d.dir, marker, d.mtimeMs) }))
|
|
263
|
+
.sort((a, b) => b.at - a.at);
|
|
264
|
+
const kept = [];
|
|
265
|
+
const removed = [];
|
|
266
|
+
for (const r of records) {
|
|
267
|
+
if (kept.length < keep && now - r.at <= maxAgeMs) {
|
|
268
|
+
kept.push(r.name);
|
|
269
|
+
}
|
|
270
|
+
else {
|
|
271
|
+
rmSync(r.dir, { recursive: true, force: true });
|
|
272
|
+
removed.push(r.name);
|
|
273
|
+
}
|
|
274
|
+
}
|
|
275
|
+
return { kept, removed };
|
|
276
|
+
}
|
|
277
|
+
/**
|
|
278
|
+
* The working directory of every process on this host that we can see, or
|
|
279
|
+
* null when `/proc` cannot say (not Linux). A process that exits between the
|
|
280
|
+
* listing and the readlink, or belongs to another user, is not standing in one
|
|
281
|
+
* of our directories.
|
|
282
|
+
*/
|
|
283
|
+
export function processCwds() {
|
|
284
|
+
let pids;
|
|
285
|
+
try {
|
|
286
|
+
pids = readdirSync('/proc').filter((p) => /^\d+$/.test(p));
|
|
287
|
+
}
|
|
288
|
+
catch (err) {
|
|
289
|
+
if (err.code === 'ENOENT')
|
|
290
|
+
return null;
|
|
291
|
+
throw err;
|
|
292
|
+
}
|
|
293
|
+
const cwds = [];
|
|
294
|
+
for (const pid of pids) {
|
|
295
|
+
try {
|
|
296
|
+
cwds.push(readlinkSync(`/proc/${pid}/cwd`));
|
|
297
|
+
}
|
|
298
|
+
catch (err) {
|
|
299
|
+
const code = err.code;
|
|
300
|
+
if (code !== 'ENOENT' && code !== 'EACCES' && code !== 'ESRCH' && code !== 'EPERM')
|
|
301
|
+
throw err;
|
|
302
|
+
}
|
|
303
|
+
}
|
|
304
|
+
return cwds;
|
|
305
|
+
}
|
|
306
|
+
/** Is `cwd` this directory, or somewhere under it? */
|
|
307
|
+
export function cwdIsUnder(cwd, dir) {
|
|
308
|
+
return cwd === dir || cwd.startsWith(dir + sep);
|
|
309
|
+
}
|
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a game supplies to the match host: the Forge-specific half of a match, generalised to a
|
|
3
|
+
* shape any engine's own bridge protocol can satisfy. `play/match.ts`'s `Match` is a
|
|
4
|
+
* `MatchShell` (`play/match/shell.ts`) running a Forge {@link GameSession}
|
|
5
|
+
* (`play/match/forge-session.ts`); {@link GameAdapter} is the rest of that seam, and today has one
|
|
6
|
+
* caller, a toy adapter in `game-adapter.test.ts` that proves a non-Forge game's lines fit it.
|
|
7
|
+
*
|
|
8
|
+
* Four type parameters, one per thing a game owns the shape of, plus a fifth for what a
|
|
9
|
+
* mid-game save looks like:
|
|
10
|
+
* - `Spec` — how a match is configured (Forge's `MatchSpec`).
|
|
11
|
+
* - `Line` — what the engine's bridge sends up, one line at a time (Forge's `BridgeLine`).
|
|
12
|
+
* - `Cmd` — what the host sends down to the engine (Forge's `BridgeCommand`).
|
|
13
|
+
* - `Frame` — what a seat or a watcher is shown (Forge's `ServerFrame`).
|
|
14
|
+
* - `Checkpoint` — an opaque mid-game save a match can be restored from (Forge's
|
|
15
|
+
* `TurnSnapshot`). Nothing calls this generically yet, so it defaults to `unknown`.
|
|
16
|
+
*/
|
|
17
|
+
export interface GameAdapter<Spec, Line, Cmd, Frame, Checkpoint = unknown> {
|
|
18
|
+
/**
|
|
19
|
+
* The seats a spec wants, in order. `class Match`'s constructor reads exactly this off
|
|
20
|
+
* `spec.seats`: `ai`, and the `name`/`displayName` pair
|
|
21
|
+
* `SeatSpecWithIdentity` widens Forge's `SeatSpec` with.
|
|
22
|
+
*/
|
|
23
|
+
seats(spec: Spec): {
|
|
24
|
+
ai: boolean;
|
|
25
|
+
name: string;
|
|
26
|
+
}[];
|
|
27
|
+
/**
|
|
28
|
+
* What one line from the engine's bridge means, generically. `Match.onLine`
|
|
29
|
+
* is this switch for Forge today — its cases collapse onto this union
|
|
30
|
+
* one for one:
|
|
31
|
+
* - `'ready'` ← Forge's `'ready'`: the bridge has a game; record each seat's deck.
|
|
32
|
+
* - `'seat'` ← Forge's `'frame'`: a line addressed to one seat's game, forwarded
|
|
33
|
+
* to {@link GameSession.onLine}.
|
|
34
|
+
* - `'over'` ← Forge's `'gameover'`: the game ended. `winners`/`losers` name SEATS, not
|
|
35
|
+
* the engine's own ids (Forge's `winner`/`losers` read back through each seat's player id,
|
|
36
|
+
* `play/match/outcome.ts`'s `winnerSeatFromLosers`); `drawn` is true when the rules named no
|
|
37
|
+
* winner at all. A seat in neither array was simply not placed.
|
|
38
|
+
* - `'checkpoint'` ← Forge's `'snapshot'`: a mid-game save, kept as `latestSnapshot`
|
|
39
|
+
* for a later restart (`MatchRegistry.restore`).
|
|
40
|
+
* - `'fatal'` ← Forge's `'fatal'`: the bridge or the JVM died; `Match.fail`
|
|
41
|
+
* follows.
|
|
42
|
+
* - `'info'` ← everything else Forge logs but a shell need not act on itself
|
|
43
|
+
* (`'resent'`, `'input'`, `'probe'`, `'log'`, `'dropped'`, `'scan-overtaken'`,
|
|
44
|
+
* `'impersonated'`, `'rejected'`, `'stale'`, `'pace'`, `'unsupported'`).
|
|
45
|
+
*/
|
|
46
|
+
classify(line: Line): ClassifiedLine<Checkpoint>;
|
|
47
|
+
/**
|
|
48
|
+
* Builds this match's engine session: the half of `class Match` that actually talks to the
|
|
49
|
+
* engine, handed the three ways a shell may be told something (`out`). Forge has no single
|
|
50
|
+
* method shaped like this today — it is the generalisation of three separate sinks:
|
|
51
|
+
* `Match.command` (the `Cmd` sink: `out.command`), `Match.send`/`Match.emit`
|
|
52
|
+
* (the per-seat `Frame` sink: `out.toSeat`), and
|
|
53
|
+
* `Match.tellWatchers`/`Match.sendWatcher` (the watcher `Frame` sink:
|
|
54
|
+
* `out.toWatchers`). Forge's real session, `ForgeSession`, is built by `Match` itself and reaches
|
|
55
|
+
* those sinks directly; nothing builds one through here yet.
|
|
56
|
+
*/
|
|
57
|
+
session(out: {
|
|
58
|
+
toSeat(seat: number, f: Frame): void;
|
|
59
|
+
toWatchers(f: Frame): void;
|
|
60
|
+
command(c: Cmd): void;
|
|
61
|
+
}): GameSession<Line, Cmd>;
|
|
62
|
+
/**
|
|
63
|
+
* A spec that resumes from a checkpoint rather than starting fresh — Forge's own
|
|
64
|
+
* `restoredSpec` (`play/match/registry.ts`): drop
|
|
65
|
+
* the chooser, open on the checkpoint's state, skip the opening hand.
|
|
66
|
+
*/
|
|
67
|
+
restoreSpec(spec: Spec, cp: Checkpoint): Spec;
|
|
68
|
+
/**
|
|
69
|
+
* The command that ends this seat's game as a loss — Forge's
|
|
70
|
+
* `{ t: 'act', seat, frame: { kind: 'act', method: 'concede' } }`, repeated until the engine answers it.
|
|
71
|
+
*/
|
|
72
|
+
concede(seat: number): Cmd;
|
|
73
|
+
/**
|
|
74
|
+
* A frame that tells a seat something in words, with no game state behind it — Forge's
|
|
75
|
+
* `endNotice` (`showErrorDialog`, `MATCH_ENDED_TITLE`).
|
|
76
|
+
*/
|
|
77
|
+
notice(text: string): Frame;
|
|
78
|
+
}
|
|
79
|
+
/** What {@link GameAdapter.classify} reads one engine line as. */
|
|
80
|
+
export type ClassifiedLine<Checkpoint> = {
|
|
81
|
+
t: 'ready';
|
|
82
|
+
} | {
|
|
83
|
+
t: 'seat';
|
|
84
|
+
seat: number;
|
|
85
|
+
raw: unknown;
|
|
86
|
+
} | {
|
|
87
|
+
t: 'over';
|
|
88
|
+
winners: number[];
|
|
89
|
+
losers: number[];
|
|
90
|
+
drawn: boolean;
|
|
91
|
+
} | {
|
|
92
|
+
t: 'checkpoint';
|
|
93
|
+
cp: Checkpoint;
|
|
94
|
+
} | {
|
|
95
|
+
t: 'fatal';
|
|
96
|
+
why: string;
|
|
97
|
+
} | {
|
|
98
|
+
t: 'info';
|
|
99
|
+
};
|
|
100
|
+
/**
|
|
101
|
+
* What the platform shell (`play/match/shell.ts`'s `MatchShell`) asks of the game it runs:
|
|
102
|
+
* Forge's is `play/match/forge-session.ts`'s `ForgeSession`. The shell owns the match's lifecycle,
|
|
103
|
+
* its seats' holders, its clock and its restart ask; everything it needs to know about the game
|
|
104
|
+
* itself it asks through these, and nothing else of the game is reachable from it.
|
|
105
|
+
*/
|
|
106
|
+
export interface GameSession<Line, Cmd> {
|
|
107
|
+
/** One engine line the shell does not read itself: everything but the game's end, a fatal line and a checkpoint. */
|
|
108
|
+
onLine(line: Line): void;
|
|
109
|
+
/** Send the engine one command: the concede a seat's flag or an unanswered concede sends. */
|
|
110
|
+
command(command: Cmd): void;
|
|
111
|
+
/** The game waits on this seat's own decision now: its chess clock runs exactly then. */
|
|
112
|
+
waitedOn(seat: number): boolean;
|
|
113
|
+
/** Tell every seat the roster again: a clock, a holder's presence or a face moved. */
|
|
114
|
+
tellRoster(): void;
|
|
115
|
+
/** The turn the game is in, or null before the engine has dealt: what a restart ask is about. */
|
|
116
|
+
turn(): number | null;
|
|
117
|
+
/** The seat whose turn it is, with its engine player; null when no seat's is (before the deal, an AI's turn). */
|
|
118
|
+
activeSeat(): {
|
|
119
|
+
seat: number;
|
|
120
|
+
playerId: number;
|
|
121
|
+
} | null;
|
|
122
|
+
/** How many of this seat's questions are open: logged when its holder leaves and when they come back. */
|
|
123
|
+
openAsks(seat: number): number;
|
|
124
|
+
/**
|
|
125
|
+
* A command the EARLIER server had already sent, met again during a replay (`MatchHost.attach`):
|
|
126
|
+
* closes whatever open ask it was answering (Forge's `reply`/`abort`; `ForgeSession.replayed`).
|
|
127
|
+
* Nothing the engine's own line stream says records that an ask was answered, so without this a
|
|
128
|
+
* seat coming back after a restart would be re-shown a modal it had already dismissed. A session
|
|
129
|
+
* with no asks of its own (the toy game's) still implements it, trivially, to prove the hook fits.
|
|
130
|
+
*/
|
|
131
|
+
replayed(command: Cmd): void;
|
|
132
|
+
/**
|
|
133
|
+
* The match is ending for good — stopped on purpose, failed, or its host exited — and this is
|
|
134
|
+
* the session's one chance to sweep: `ForgeSession.ended` is `logFrames`/`closeAllAsks`/
|
|
135
|
+
* `tellSeatsItEnded`/`probes`. `reason` is the failure's or exit's message; null for a stop,
|
|
136
|
+
* which has none.
|
|
137
|
+
*/
|
|
138
|
+
ended(reason: string | null): void;
|
|
139
|
+
/**
|
|
140
|
+
* The notice hook: the shell has words for a seat with no game state behind them — today
|
|
141
|
+
* only `'server-stopping'` (`Match.serverStopping`'s `message`, said as Forge's own
|
|
142
|
+
* `endNotice` always has — `ForgeSession.notice` is a one-line call to it). `RelaySession`'s
|
|
143
|
+
* tells every seat the same message as a relayed line; the toy game implements it trivially,
|
|
144
|
+
* to prove it fits a session with nothing of its own to say.
|
|
145
|
+
*/
|
|
146
|
+
notice(kind: 'server-stopping', message: string): void;
|
|
147
|
+
/**
|
|
148
|
+
* What this seat could take back now (`docs/planning/undo-plan.md`): `can`, its last action, and `version`, the
|
|
149
|
+
* history that would rewind, which moves with every action and with whatever ends the history. Null or absent:
|
|
150
|
+
* the game has no undo.
|
|
151
|
+
*/
|
|
152
|
+
takeBack?(seat: number): {
|
|
153
|
+
can: boolean;
|
|
154
|
+
version: number;
|
|
155
|
+
} | null;
|
|
156
|
+
/** Take back this seat's last action, if its history is still at `version`: what the other seat allowed. */
|
|
157
|
+
rewind?(seat: number, version: number): void;
|
|
158
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|