@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.
- 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 +36 -4
- package/README.md +0 -3
|
@@ -0,0 +1,482 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where a match's Forge runs: matches placed into shared `--host` bridge JVMs.
|
|
3
|
+
*
|
|
4
|
+
* ## Many matches per JVM
|
|
5
|
+
*
|
|
6
|
+
* Every bridge JVM is a `PlayBridge --host <hostId>` (`docs/spikes/multi-match-jvm.md`): it boots
|
|
7
|
+
* Forge's model once, says `warm`, and then takes any number of
|
|
8
|
+
* `{"t":"start","match":<hostId>,"config":{…}}` lines, each starting one match on a Forge server
|
|
9
|
+
* of its own. Every line it prints carries its match's id, commands are routed by it, and a
|
|
10
|
+
* match's `stop` ends that match alone, answered by `{"t":"stopped"}`. A `stop` addressed to the
|
|
11
|
+
* host id ends the JVM.
|
|
12
|
+
*
|
|
13
|
+
* This file is the coordinator. `jvmHostFactory` places each match into a JVM with room — the
|
|
14
|
+
* fullest warm one first, so idle JVMs empty out and retire — up to `perJvm` matches each
|
|
15
|
+
* (`MATCHES_PER_JVM`, 25), and opens a new JVM when every one is full. Where a JVM runs and how
|
|
16
|
+
* its line stream is reached is a `JvmLauncher`'s (`jvm-transport.ts`): this machine's (`local-jvm.ts`), by
|
|
17
|
+
* default; a claw's, through a remote agent.
|
|
18
|
+
*
|
|
19
|
+
* - **A match's exit is its `stopped`.** A match asked to stop whose `stopped` never comes is let
|
|
20
|
+
* go after `MATCH_STOP_MS` and logged (`match-stop-unanswered`); its JVM keeps the others.
|
|
21
|
+
* - **A JVM's death fails EVERY match on it**, with the JVM's reason (`jvm-lost`). Nothing on
|
|
22
|
+
* that JVM retries in place: a failed claw always fails over (the hosting rulings), and the
|
|
23
|
+
* failover acts on this signal.
|
|
24
|
+
* - **A JVM with no matches for `IDLE_JVM_MS` is retired**, unless it is the one JVM left with
|
|
25
|
+
* room (the warm one).
|
|
26
|
+
*
|
|
27
|
+
* ## The warm JVM
|
|
28
|
+
*
|
|
29
|
+
* One JVM with room is kept booted ahead of the next match (unless `warmJvm` is off): when the
|
|
30
|
+
* last JVM with room fills, another is launched behind it. A match placed into a warm JVM starts
|
|
31
|
+
* at once; one placed into a JVM still booting starts the moment it is warm (its `start` waits in
|
|
32
|
+
* the fifo). A JVM that dies before `warm` is a failed boot: the next is tried after
|
|
33
|
+
* `WARM_RETRY_MS`, and after `WARM_MAX_FAILURES` in a row no JVM is kept warm — a match still
|
|
34
|
+
* launches one when it needs one — which is logged.
|
|
35
|
+
*
|
|
36
|
+
* ## The ceiling: at most `MAX_CONCURRENT_MATCHES` matches being played
|
|
37
|
+
*
|
|
38
|
+
* **50** since 2026-10-28 (the operator: "if we hit just 50 concurrent matches that'd be fine"):
|
|
39
|
+
* two claws at `MATCHES_PER_JVM` each. It was 10 while every match was its own ~0.7–1 GB JVM.
|
|
40
|
+
* Counted over the matches still `starting` or `running` (a finished match keeps its slot in its
|
|
41
|
+
* JVM for `overGraceMs`, not a place in the ceiling). `socket.ts` refuses one more with a 503
|
|
42
|
+
* before any JVM is spent. Each person may play at most 5 at once
|
|
43
|
+
* (`http/routes.ts`). The JVM count is bounded separately (`JvmPoolOptions.maxJvms`). A JVM's
|
|
44
|
+
* heap is capped (`JVM_HEAP_MB` for `MATCHES_PER_JVM` matches, `local-jvm.ts`) so a runaway
|
|
45
|
+
* cannot take the box.
|
|
46
|
+
*
|
|
47
|
+
* Nothing outside this file knows a JVM exists: `match.ts` sees a `MatchHost` — send a command,
|
|
48
|
+
* get lines back, stop — and a `MatchHostFactory` makes one.
|
|
49
|
+
*
|
|
50
|
+
* ## A match outlives its server (Wave 22, §E)
|
|
51
|
+
*
|
|
52
|
+
* A deploy must not end live games. The JVM survives the server (`local-jvm.ts`, "A JVM
|
|
53
|
+
* outlives its server"), and the next server has to be able to rebuild each match on it: a
|
|
54
|
+
* re-attached JVM keeps Forge's games, but `Match`'s per-seat projectors, histories, cursors and
|
|
55
|
+
* parked asks lived in the process that died. So:
|
|
56
|
+
*
|
|
57
|
+
* - **Every protocol line and every command of a match is appended to its own stream**,
|
|
58
|
+
* `<dir>/<matchId>.jsonl`, as it is read or sent; a re-attach replays that file into the new
|
|
59
|
+
* `Match` before a single live line reaches it. Replay is deterministic, so each seat's `seq`
|
|
60
|
+
* comes back identical. A line is kept as the bridge wrote it, `match` stamp and all, through
|
|
61
|
+
* a descriptor held open for the match's life; each append is synchronous, so the file is
|
|
62
|
+
* whole for any reader the moment `persist` returns — this process's own `attach`, or the next
|
|
63
|
+
* server's after a crash.
|
|
64
|
+
* - **One record per JVM**, `<dir>/jvm.json` (`JvmRecord`): its host id, when it started, when it
|
|
65
|
+
* was handed over, and every match on it with its epoch, its seats' owners and its spec. A
|
|
66
|
+
* client therefore resyncs on the cursor it already held, and seat 2 cannot come back as seat 1.
|
|
67
|
+
* - **At boot** the launcher offers back every JVM still running (`running()`); each is attached
|
|
68
|
+
* at once, and every match its record lists is offered through `orphans()`. Lines arriving for
|
|
69
|
+
* a match not yet claimed are kept in its stream and replayed when `attach` claims it.
|
|
70
|
+
* - **A degraded match is never handed over** (hosting-test-plan H4): one whose stream could not
|
|
71
|
+
* be written has a hole a replay would turn into a board Forge does not have. Its stream is
|
|
72
|
+
* renamed out of the way (a rename needs no space on a disk that just filled), `handOver` refuses
|
|
73
|
+
* in words, and a later boot stops it instead of offering it.
|
|
74
|
+
*
|
|
75
|
+
* **Nothing keeps an orphan for ever**: a JVM `ORPHAN_MAX_MS` past its `orphanedAt` is retired,
|
|
76
|
+
* not re-attached; a match nobody claims within `ORPHAN_CLAIM_MS` of boot is stopped; and a
|
|
77
|
+
* re-attached match whose seats never come back is stopped by `Match.armRejoinGrace`.
|
|
78
|
+
*
|
|
79
|
+
* ## Going down: what must die before we do (Wave 22, lane U)
|
|
80
|
+
*
|
|
81
|
+
* A JVM with a match that was handed over outlives us on purpose; every other must not. Measured
|
|
82
|
+
* against a real match JVM (lane U): `{"t":"stop"}` → gone 9355 ms, SIGTERM 4322 ms, SIGKILL
|
|
83
|
+
* 0 ms; an idle JVM's host stop 314 ms. pm2 SIGKILLs us after 1.6 s, so there is no budget for a
|
|
84
|
+
* polite end, and `reapOnExit()` is the last word, **synchronous and immediate**: every JVM with
|
|
85
|
+
* no handed-over match is asked to go and killed now (confirmed gone, so its run directory is
|
|
86
|
+
* settled), and every JVM with one is let go with its `orphanedAt` stamped.
|
|
87
|
+
*
|
|
88
|
+
* ## Liveness
|
|
89
|
+
*
|
|
90
|
+
* A JVM's pid says it exists, not that it runs: a SIGSTOPped bridge kept its match `running` for
|
|
91
|
+
* good (hosting-test-plan C2). So the bridge says `alive` every 2 s (`PlayBridge.ALIVE_MS`) from a
|
|
92
|
+
* thread of its own, and a JVM this file has heard nothing from for `UNRESPONSIVE_MS` is killed
|
|
93
|
+
* and every match on it failed through the exit path, exactly as a crash.
|
|
94
|
+
*
|
|
95
|
+
* Why 40 s: a 30 s stop-the-world pause must not end a match, and the silence a pause of P makes
|
|
96
|
+
* is at most P + one interval (2 s), so 32 s; 40 s leaves 8 s for scheduling on a loaded host.
|
|
97
|
+
* Forge's own client timeout is raised far past this (`FORGE_HEARTBEAT_TIMEOUT_S`). A JVM
|
|
98
|
+
* re-attached from an earlier server is watched only from its first line.
|
|
99
|
+
*
|
|
100
|
+
* **Per match, there is no watchdog**, because the bridge reports nothing a watchdog could read:
|
|
101
|
+
* `alive` is one line per JVM from a thread of its own (`PlayBridge.startAlive`), and a match's
|
|
102
|
+
* own lines stop for as long as a player thinks, which is not a fault. A game thread that dies is
|
|
103
|
+
* already the bridge's to report (`MatchContext.fail` → `fatal`, then `stopped`). What a per-match
|
|
104
|
+
* watchdog would need is in "What remains" of `docs/spikes/multi-match-jvm.md`.
|
|
105
|
+
*
|
|
106
|
+
* ## AI cutoffs
|
|
107
|
+
*
|
|
108
|
+
* Forge gives each AI decision a 5 s wall-clock cutoff, and past it the AI plays its best so far:
|
|
109
|
+
* on a host short of CPU the AI plays worse, not slower. The bridge says `cutoff` each time
|
|
110
|
+
* (`PlayBridge.CutoffWatch`), for the match whose game was cut, or for the JVM when no match owns
|
|
111
|
+
* the thread. Like `alive` it is the pool's, never a match's: it is logged (`ai-cutoff`) and handed
|
|
112
|
+
* to `JvmPoolOptions.onCutoff`, which placement counts against the host, and it is neither kept in
|
|
113
|
+
* a stream nor forwarded, so a replay never counts one twice.
|
|
114
|
+
*
|
|
115
|
+
* ## The line protocol
|
|
116
|
+
*
|
|
117
|
+
* `bridge/PlayBridge.java` writes one JSON object per line on stdout and reads one per line on
|
|
118
|
+
* stdin. Its class comment has the list. Stdout carries nothing else, so a line that is not JSON
|
|
119
|
+
* is a bug and is logged, not parsed.
|
|
120
|
+
*/
|
|
121
|
+
export { bridgeDiagnostics } from './diagnostics.js';
|
|
122
|
+
import type { JvmLauncher } from './jvm-transport.js';
|
|
123
|
+
import { type JvmHostConfig } from './local-jvm.js';
|
|
124
|
+
export { BRIDGE_CACHE_MAX_AGE_MS, BRIDGE_JVM_FLAGS, CRASH_RECORD_FILES, CRASH_RECORD_MAX_AGE_MS, CRASH_RECORDS_KEPT, FORGE_HEARTBEAT_TIMEOUT_S, FORGE_PREFERENCES, JVM_HEAP_MB, MATCHES_PER_JVM, bridgeLaunch, bridgeVersion, jvmHostConfig, liveJvmCount, stageRunDir, sweepRunDirs, writeFileAtomic, type JvmAvailability, type JvmHostConfig, } from './local-jvm.js';
|
|
125
|
+
export interface SeatSpec {
|
|
126
|
+
/** Forge's player name. Shown to both seats, so never an identity. */
|
|
127
|
+
name: string;
|
|
128
|
+
ai: boolean;
|
|
129
|
+
/** `.dck` text, or null for a random Forge precon. */
|
|
130
|
+
deck: string | null;
|
|
131
|
+
}
|
|
132
|
+
/**
|
|
133
|
+
* A bot game: Forge's AI against Forge's AI, best of `bestOf`, each game drawn past `gameS` seconds
|
|
134
|
+
* (`PlayBridge.java`'s `playHeadless`). It runs on the same JVMs as every match and is never a `Match`:
|
|
135
|
+
* `play/botgames.ts` reads its lines.
|
|
136
|
+
*/
|
|
137
|
+
export interface HeadlessRules {
|
|
138
|
+
bestOf: 1 | 3;
|
|
139
|
+
gameS: number;
|
|
140
|
+
}
|
|
141
|
+
export interface MatchSpec {
|
|
142
|
+
/**
|
|
143
|
+
* Seat 0 is a human in every match a player sees: the bridge refuses a match with no human seat,
|
|
144
|
+
* because Forge watches an AI-against-AI game through a desktop window a headless JVM cannot open.
|
|
145
|
+
* Only a bot game ({@link headless}) seats two AIs, and it never opens that window.
|
|
146
|
+
*/
|
|
147
|
+
seats: [SeatSpec & {
|
|
148
|
+
ai: false;
|
|
149
|
+
}, SeatSpec] | [SeatSpec & {
|
|
150
|
+
ai: true;
|
|
151
|
+
}, SeatSpec & {
|
|
152
|
+
ai: true;
|
|
153
|
+
}];
|
|
154
|
+
/** A bot game ({@link HeadlessRules}); absent for every match a player plays or watches. */
|
|
155
|
+
headless?: HeadlessRules;
|
|
156
|
+
/** Seeds Forge's shuffles and the precon pick, for a repeatable test run. Omitted in play. */
|
|
157
|
+
seed?: number;
|
|
158
|
+
/**
|
|
159
|
+
* Wave 33 §S — a TEST-only starting position: the text of a Forge puzzle file's
|
|
160
|
+
* `[state]` section (`humanlife=`, `humanhand=`, `humanbattlefield=`,
|
|
161
|
+
* `activephase=`, … — `GameState.parseLine` in the deploy tree's forge-build
|
|
162
|
+
* cache has the full key list), with `human…` keys applying to seat 0 and
|
|
163
|
+
* `ai…` keys to seat 1. `bridgeConfig` spreads it onto `config.json` like every
|
|
164
|
+
* other `MatchSpec` field; `PlayBridge.java`'s `configFrom` reads it and
|
|
165
|
+
* `BridgeGui.hostMatch` applies it from `HostedMatch`'s own start-game hook —
|
|
166
|
+
* see that method's doc. Omitted in play: `socket.ts`'s `parseStartBody`
|
|
167
|
+
* accepts this key only behind `CARDTABLE_PLAY_PROBE=1` and refuses it
|
|
168
|
+
* otherwise, so production never sends one.
|
|
169
|
+
*/
|
|
170
|
+
scenario?: string;
|
|
171
|
+
/**
|
|
172
|
+
* Start on {@link scenario}'s board with no coin toss and no mulligan — Forge's
|
|
173
|
+
* own Puzzle game type, which skips both (`GameAction.startGame`). Set only by
|
|
174
|
+
* `socket.ts` for a board-state room's own scenario; a test's scenario keeps the
|
|
175
|
+
* ordinary opening its drivers click through.
|
|
176
|
+
*/
|
|
177
|
+
skipOpening?: boolean;
|
|
178
|
+
/**
|
|
179
|
+
* {@link scenario} is this match's own turn-start snapshot (`restoredSpec`): its board goes back
|
|
180
|
+
* as it was, running no replacement effect ("enters tapped", "you may pay 2 life"), where a
|
|
181
|
+
* board room's scenario plays each permanent's entry. Implies {@link skipOpening}.
|
|
182
|
+
*/
|
|
183
|
+
restore?: boolean;
|
|
184
|
+
/**
|
|
185
|
+
* The room's format id (`room/lobby.ts`'s `FormatId`): what a card-name ask is
|
|
186
|
+
* narrowed to (`names.ts`). Inert in the JVM — `configFrom` never reads it — and
|
|
187
|
+
* kept in `config.json` so a match taken back after a restart still has it.
|
|
188
|
+
*/
|
|
189
|
+
format?: string;
|
|
190
|
+
/**
|
|
191
|
+
* The room's hand smoothing setting (`room/lobby.ts`'s `RoomSettings`): the
|
|
192
|
+
* opening hand is the closer of two to the deck's land ratio, and each
|
|
193
|
+
* mulligan's redraw is weighted toward it. `PlayBridge.java`'s `configFrom`
|
|
194
|
+
* turns it into Forge's filtered hands. Absent is off, Forge's default — a
|
|
195
|
+
* spec built directly, as the jvm suites build theirs, deals what it always did.
|
|
196
|
+
*/
|
|
197
|
+
handSmoothing?: boolean;
|
|
198
|
+
/**
|
|
199
|
+
* Wave 71 §E — names the seat Forge asks to choose play or draw. Every game we
|
|
200
|
+
* host is a fresh Forge `Match`, so Forge always treats it as the FIRST game of
|
|
201
|
+
* that match and tosses a coin (`GameAction.determineFirstTurnPlayer`,
|
|
202
|
+
* `forge/forge-game/src/main/java/forge/game/GameAction.java:2364-2416`) rather
|
|
203
|
+
* than asking the previous loser — this field is how the room still names that
|
|
204
|
+
* player. `PlayBridge.java`'s `startMatch` rigs the coin toss so the named seat
|
|
205
|
+
* is the one Forge asks (`SeatGui`'s `updateButtons` with `label1:'Play',
|
|
206
|
+
* label2:'Draw'`), which makes the published `coinToss.winner` (`match.ts:1055`)
|
|
207
|
+
* that seat too — the client's existing flip/notice needs no change. Omitted:
|
|
208
|
+
* byte-identical to today, an unrigged coin toss. Never set alongside a change
|
|
209
|
+
* to `forge/` — a fork change is a jar switch, and that switch is the operator's.
|
|
210
|
+
*/
|
|
211
|
+
chooser?: 0 | 1;
|
|
212
|
+
/**
|
|
213
|
+
* The chess clock: each seat's time left, in ms, when this game starts — a room
|
|
214
|
+
* with the clock on carries what the series' last game left (`play/clock.ts`).
|
|
215
|
+
* Absent: no clock. Inert in the JVM, like `format`.
|
|
216
|
+
*/
|
|
217
|
+
clockMs?: [number, number];
|
|
218
|
+
}
|
|
219
|
+
/**
|
|
220
|
+
* The four lines the host and placement read from any engine's own line type `L`; everything else
|
|
221
|
+
* is the game's own (w103 §H's pinned shape). Forge's full `BridgeLine` (now `bridge-protocol.ts`)
|
|
222
|
+
* narrows onto this through {@link isLifecycle} — TypeScript cannot narrow a generic `L extends {
|
|
223
|
+
* t: string }` on its `t` member directly (w100 finding 3.2), so a caller holding an `L` checks
|
|
224
|
+
* `isLifecycle(line)` first and reads the narrowed shape, never `line.t === 'ready'` on the bare `L`.
|
|
225
|
+
*/
|
|
226
|
+
export type HostLifecycleLine = {
|
|
227
|
+
t: 'ready';
|
|
228
|
+
} | {
|
|
229
|
+
t: 'fatal';
|
|
230
|
+
message: string;
|
|
231
|
+
} | {
|
|
232
|
+
t: 'frame';
|
|
233
|
+
} | {
|
|
234
|
+
t: 'snapshot';
|
|
235
|
+
};
|
|
236
|
+
/** Narrows any engine's line onto the four the host itself understands. See {@link HostLifecycleLine}. */
|
|
237
|
+
export declare function isLifecycle<L extends {
|
|
238
|
+
t: string;
|
|
239
|
+
}>(line: L): line is L & HostLifecycleLine;
|
|
240
|
+
/** The latest `snapshot` line a match has had: what a restore starts it from. */
|
|
241
|
+
export interface TurnSnapshot {
|
|
242
|
+
turn: number;
|
|
243
|
+
state: string;
|
|
244
|
+
/** What the game held that {@link state} does not; absent or empty is the whole game. */
|
|
245
|
+
lossy?: readonly string[];
|
|
246
|
+
}
|
|
247
|
+
/**
|
|
248
|
+
* A bot game's (`MatchSpec.headless`) exit when Forge ended it on its own: the bridge plays the whole
|
|
249
|
+
* best-of and stops, so this is the game finishing, never its host failing.
|
|
250
|
+
*/
|
|
251
|
+
export declare const PLAYED_OUT = "played out";
|
|
252
|
+
/**
|
|
253
|
+
* What a match host tells its match, generic over the engine's own line type `L` (w103 §H's pinned
|
|
254
|
+
* shape: Forge instantiates this `HostEvents<BridgeLine>`, `bridge-protocol.ts`).
|
|
255
|
+
*/
|
|
256
|
+
export interface HostEvents<L extends {
|
|
257
|
+
t: string;
|
|
258
|
+
}, C extends {
|
|
259
|
+
t: string;
|
|
260
|
+
}> {
|
|
261
|
+
line(line: L): void;
|
|
262
|
+
/** The host is gone. `reason` says why, for the match's status. */
|
|
263
|
+
exit(reason: string): void;
|
|
264
|
+
log(entry: Record<string, unknown>): void;
|
|
265
|
+
/**
|
|
266
|
+
* Replay only (`attach`): a command an EARLIER server had already sent to this
|
|
267
|
+
* JVM. Nothing the bridge says records that an ask was answered, so without
|
|
268
|
+
* this a resumed match would re-open asks Forge has already returned from.
|
|
269
|
+
*/
|
|
270
|
+
replayed?(command: C): void;
|
|
271
|
+
}
|
|
272
|
+
/** What a match sends its host, generic over the engine's own command type `C`. */
|
|
273
|
+
export interface MatchHost<C extends {
|
|
274
|
+
t: string;
|
|
275
|
+
}> {
|
|
276
|
+
send(command: C): void;
|
|
277
|
+
/** Ask the match to stop; force it after a grace period. Idempotent. */
|
|
278
|
+
stop(): void;
|
|
279
|
+
/**
|
|
280
|
+
* Write down what a re-attach or a restore of this match would need that only
|
|
281
|
+
* the match knows: its epoch, which participant owns each seat, and its latest
|
|
282
|
+
* turn-start snapshot. Absent on a host that cannot outlive the process (the
|
|
283
|
+
* replay host in the tests).
|
|
284
|
+
*/
|
|
285
|
+
remember?(state: Durable & {
|
|
286
|
+
snapshot?: TurnSnapshot | null;
|
|
287
|
+
clockMs?: [number, number];
|
|
288
|
+
}): void;
|
|
289
|
+
/**
|
|
290
|
+
* The server is going down and this match is being LEFT RUNNING. Let go of
|
|
291
|
+
* the transport without killing anything and without settling the run
|
|
292
|
+
* directory, so the next process can `attach` to it. Absent on a host whose
|
|
293
|
+
* JVM cannot outlive us, and false when there was nothing to hand over — the
|
|
294
|
+
* caller then owes the seats an explanation instead.
|
|
295
|
+
*/
|
|
296
|
+
handOver?(): boolean;
|
|
297
|
+
}
|
|
298
|
+
/**
|
|
299
|
+
* What a restart needs to resume a match, independent of the engine (w103 §H's pinned shape):
|
|
300
|
+
* its epoch, so a re-attached client resyncs on the cursor it holds, and which participant owns
|
|
301
|
+
* each seat, so a re-attach cannot seat someone at the wrong hand. `checkpoint` is w105's: a
|
|
302
|
+
* per-engine mid-game save, opaque to the host — whatever `GameAdapter.classify`'s `{ t:
|
|
303
|
+
* 'checkpoint' }` line carried last (`match/shell.ts`'s `latestCheckpoint`), written down beside
|
|
304
|
+
* Forge's own {@link TurnSnapshot} (`MatchRecord.snapshot`, kept unchanged this wave) rather than
|
|
305
|
+
* replacing it. Absent before a match's first checkpoint. `readJvmRecord`/`hostFace`'s `remember`
|
|
306
|
+
* pass through whatever the caller sent, never forcing it to `null` themselves.
|
|
307
|
+
*/
|
|
308
|
+
export interface Durable {
|
|
309
|
+
epoch: string;
|
|
310
|
+
owners: (string | null)[];
|
|
311
|
+
checkpoint?: unknown;
|
|
312
|
+
}
|
|
313
|
+
/**
|
|
314
|
+
* A match an earlier server left running, as `orphans()` offers it: everything a re-attach needs
|
|
315
|
+
* and nothing a seat could not already see (`owners` are participant ids, which never leave this
|
|
316
|
+
* host). `epoch`/`owners`/`checkpoint` are {@link Durable}'s; `epoch` widens to `null` here (unlike
|
|
317
|
+
* `Durable`'s own, always-set `epoch`) because a freshly placed match has none yet — before its
|
|
318
|
+
* first `remember()`, it has no durable identity to resume by.
|
|
319
|
+
*/
|
|
320
|
+
export interface MatchRecord extends Pick<Durable, 'owners' | 'checkpoint'> {
|
|
321
|
+
matchId: string;
|
|
322
|
+
/** The JVM it runs in. */
|
|
323
|
+
hostId: string;
|
|
324
|
+
startedAt: string;
|
|
325
|
+
/** The match's epoch, so a re-attached client resyncs on the cursor it holds. Null before its first `remember()`. */
|
|
326
|
+
epoch: string | null;
|
|
327
|
+
spec: MatchSpec;
|
|
328
|
+
/** The match's latest turn-start snapshot, absent before its first turn. */
|
|
329
|
+
snapshot?: TurnSnapshot | null;
|
|
330
|
+
/** Each seat's chess-clock time left when the match last wrote this record; absent with no clock. */
|
|
331
|
+
clockMs?: [number, number];
|
|
332
|
+
/** When the server that ran it handed its JVM over. */
|
|
333
|
+
orphanedAt?: string;
|
|
334
|
+
}
|
|
335
|
+
/** One JVM's record, `<dir>/jvm.json`: what a later server re-attaches it and its matches by. */
|
|
336
|
+
export interface JvmRecord {
|
|
337
|
+
hostId: string;
|
|
338
|
+
startedAt: string;
|
|
339
|
+
/** Set when a server handed this JVM over on its way out. */
|
|
340
|
+
orphanedAt?: string;
|
|
341
|
+
matches: Omit<MatchRecord, 'hostId' | 'orphanedAt'>[];
|
|
342
|
+
}
|
|
343
|
+
/**
|
|
344
|
+
* Makes a host for one match. `close`, when present, releases whatever the factory holds between
|
|
345
|
+
* matches (an idle JVM); `attachPlay`'s `close()` calls it. `orphans`/`attach` are the re-attach
|
|
346
|
+
* seam — a factory whose JVMs cannot outlive the process has neither.
|
|
347
|
+
*/
|
|
348
|
+
export type MatchHostFactory<L extends {
|
|
349
|
+
t: string;
|
|
350
|
+
}, C extends {
|
|
351
|
+
t: string;
|
|
352
|
+
}> = ((matchId: string, spec: MatchSpec, events: HostEvents<L, C>) => MatchHost<C>) & {
|
|
353
|
+
close?(): void;
|
|
354
|
+
/** Matches still running from an earlier server, oldest first. Asked once, at boot. */
|
|
355
|
+
orphans?(): Promise<MatchRecord[]>;
|
|
356
|
+
/** Take one back: replay its stream into `events` before returning, then hand it live lines. */
|
|
357
|
+
attach?(record: MatchRecord, events: HostEvents<L, C>): MatchHost<C>;
|
|
358
|
+
/** Leave every live match running for the next process (SIGTERM). */
|
|
359
|
+
handOverAll?(): void;
|
|
360
|
+
/**
|
|
361
|
+
* The last word before `process.exit`: kill every JVM this process still holds with no
|
|
362
|
+
* handed-over match, and let go of the rest. Synchronous, immediate, and idempotent — see
|
|
363
|
+
* "Going down" in the module header.
|
|
364
|
+
*/
|
|
365
|
+
reapOnExit?(): ReapResult;
|
|
366
|
+
/**
|
|
367
|
+
* Where a match placed now would go, for `start-queue.ts`: into a warm JVM with room (it starts
|
|
368
|
+
* at once), into one still booting, nowhere yet (placing it launches a JVM), or nowhere at all
|
|
369
|
+
* (`full`: no host may take it now; it waits until `watchRoom` says otherwise).
|
|
370
|
+
*/
|
|
371
|
+
room?(): 'warm' | 'booting' | 'none' | 'full';
|
|
372
|
+
/** JVMs booting now. */
|
|
373
|
+
booting?(): number;
|
|
374
|
+
/** Called whenever `room()` or `booting()` may have changed. */
|
|
375
|
+
watchRoom?(listener: () => void): void;
|
|
376
|
+
};
|
|
377
|
+
/** What `reapOnExit` did, by JVM host id, for the shutdown log. */
|
|
378
|
+
export interface ReapResult {
|
|
379
|
+
/** Confirmed gone because we killed them, and their run directories settled. */
|
|
380
|
+
killed: string[];
|
|
381
|
+
/** Already gone, or handed over. Nothing to do and nothing owed. */
|
|
382
|
+
kept: string[];
|
|
383
|
+
/** Still running after the kill. A leak, said out loud — the boot sweep is the next chance. */
|
|
384
|
+
left: string[];
|
|
385
|
+
}
|
|
386
|
+
/** See "The ceiling" in the module header. Also `PlayDeps.maxMatches`'s default. */
|
|
387
|
+
export declare const MAX_CONCURRENT_MATCHES = 50;
|
|
388
|
+
/** See "Liveness" in the module header. */
|
|
389
|
+
export declare const UNRESPONSIVE_MS = 40000;
|
|
390
|
+
/**
|
|
391
|
+
* A match asked to stop is let go after this long without its `stopped`. The bridge concedes,
|
|
392
|
+
* answers parked asks as aborted until the game is over (up to 10 s), then tears the match down:
|
|
393
|
+
* a real match took ~9.3 s (lane U).
|
|
394
|
+
*/
|
|
395
|
+
export declare const MATCH_STOP_MS = 30000;
|
|
396
|
+
/** A JVM with no matches for this long is retired, unless it is the warm one. */
|
|
397
|
+
export declare const IDLE_JVM_MS: number;
|
|
398
|
+
/** …and after this many failed boots in a row, no JVM is kept warm. */
|
|
399
|
+
export declare const WARM_MAX_FAILURES = 3;
|
|
400
|
+
/** `JvmRecord`'s file, in each JVM's directory. */
|
|
401
|
+
export declare const JVM_RECORD_FILE = "jvm.json";
|
|
402
|
+
/** A JVM orphaned longer than this is retired, not re-attached. */
|
|
403
|
+
export declare const ORPHAN_MAX_MS: number;
|
|
404
|
+
/** A match nobody claimed this long after boot is stopped, so ignoring `orphans()` leaks nothing. */
|
|
405
|
+
export declare const ORPHAN_CLAIM_MS = 60000;
|
|
406
|
+
/** A match's stream: every line and command, in order, for a re-attach to replay. */
|
|
407
|
+
export declare function streamFile(dir: string, matchId: string): string;
|
|
408
|
+
/**
|
|
409
|
+
* The `bridge.stderr.txt` of the local JVM that hosts `matchId`, found by the `match-placed`
|
|
410
|
+
* line the coordinator logged to that match's log. A JVM's run directory is named for the JVM,
|
|
411
|
+
* not the match, so this is how a test or a dump reaches a match's stderr. Null before placement.
|
|
412
|
+
*/
|
|
413
|
+
export declare function matchStderrPath(workDir: string, log: readonly Record<string, unknown>[], matchId: string): string | null;
|
|
414
|
+
/** `<dir>/jvm.json`, or null when it is missing, unreadable or not a record. */
|
|
415
|
+
export declare function readJvmRecord(dir: string): JvmRecord | null;
|
|
416
|
+
export interface JvmPoolOptions {
|
|
417
|
+
/** Keep one JVM with room booted ahead of the next match. Default: `config.warmJvm`. */
|
|
418
|
+
warm?: boolean;
|
|
419
|
+
/**
|
|
420
|
+
* JVMs this pool will run at once, or a function read at each launch (a claw's count falls while
|
|
421
|
+
* it also runs the draft bot). Default `MAX_CONCURRENT_MATCHES`.
|
|
422
|
+
*/
|
|
423
|
+
maxJvms?: number | (() => number);
|
|
424
|
+
/** Wait before launching a warm JVM again after one failed to boot. Default `WARM_RETRY_MS`. */
|
|
425
|
+
warmRetryMs?: number;
|
|
426
|
+
/** A JVM empty this long is retired, unless it is the warm one. Default `IDLE_JVM_MS`. */
|
|
427
|
+
idleMs?: number;
|
|
428
|
+
/** A match asked to stop is let go this long without its `stopped`. Default `MATCH_STOP_MS`. */
|
|
429
|
+
matchStopMs?: number;
|
|
430
|
+
/** Sweep `workDir` of what an earlier process left before the first JVM. Default true. Ignored with `launcher`. */
|
|
431
|
+
sweep?: boolean;
|
|
432
|
+
/** Where JVMs run. Default: this machine (`localJvmLauncher`). */
|
|
433
|
+
launcher?: JvmLauncher;
|
|
434
|
+
/** Forge cut an AI decision short in one of this pool's JVMs ("AI cutoffs" in the module header). */
|
|
435
|
+
onCutoff?: (cutoff: AiCutoff) => void;
|
|
436
|
+
log?: (entry: Record<string, unknown>) => void;
|
|
437
|
+
}
|
|
438
|
+
/** One `cutoff` line: its JVM, the match whose game was cut (null: the JVM's own), and the AI's top Forge frame. */
|
|
439
|
+
export interface AiCutoff {
|
|
440
|
+
hostId: string;
|
|
441
|
+
matchId: string | null;
|
|
442
|
+
where: string | null;
|
|
443
|
+
}
|
|
444
|
+
/** The JVM factory. `room()` and friends are for `start-queue.ts`, diagnostics and the benchmark. */
|
|
445
|
+
export type JvmHostFactory<L extends {
|
|
446
|
+
t: string;
|
|
447
|
+
}, C extends {
|
|
448
|
+
t: string;
|
|
449
|
+
}> = MatchHostFactory<L, C> & {
|
|
450
|
+
close(): void;
|
|
451
|
+
room(): 'warm' | 'booting' | 'none';
|
|
452
|
+
booting(): number;
|
|
453
|
+
watchRoom(listener: () => void): void;
|
|
454
|
+
orphans(): Promise<MatchRecord[]>;
|
|
455
|
+
attach(record: MatchRecord, events: HostEvents<L, C>): MatchHost<C>;
|
|
456
|
+
handOverAll(): string[];
|
|
457
|
+
reapOnExit(): ReapResult;
|
|
458
|
+
/** JVMs this pool holds, with their matches: for diagnostics and tests. */
|
|
459
|
+
jvms(): {
|
|
460
|
+
hostId: string;
|
|
461
|
+
warm: boolean;
|
|
462
|
+
draining: boolean;
|
|
463
|
+
adopted: boolean;
|
|
464
|
+
matches: string[];
|
|
465
|
+
}[];
|
|
466
|
+
/** Place nothing more into this JVM, and retire it once its matches end (a heap past `recycleWanted`). */
|
|
467
|
+
drain(hostId: string, why: string): void;
|
|
468
|
+
/**
|
|
469
|
+
* Kill every JVM now and launch none again: the host failed, and its matches were moved. Each
|
|
470
|
+
* match's exit still reaches its events, with `why`.
|
|
471
|
+
*/
|
|
472
|
+
abandon(why: string): void;
|
|
473
|
+
};
|
|
474
|
+
/**
|
|
475
|
+
* Matches placed into shared `--host` JVMs. A match's own `HostEvents.log` receives what is about
|
|
476
|
+
* that match; what is about a JVM goes to `options.log`.
|
|
477
|
+
*/
|
|
478
|
+
export declare function jvmHostFactory<L extends {
|
|
479
|
+
t: string;
|
|
480
|
+
}, C extends {
|
|
481
|
+
t: string;
|
|
482
|
+
}>(config: JvmHostConfig, options?: JvmPoolOptions): JvmHostFactory<L, C>;
|