@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,25 @@
|
|
|
1
|
+
/** One `--host` bridge JVM's line protocol, wherever the JVM runs. */
|
|
2
|
+
export interface JvmTransport {
|
|
3
|
+
/** The JVM's host id: what `--host <hostId>` was given. */
|
|
4
|
+
readonly hostId: string;
|
|
5
|
+
/** One protocol line (JSON, no newline) to the JVM's stdin. Lines are delivered in order. */
|
|
6
|
+
send(line: string): void;
|
|
7
|
+
/** Every stdout line, in order. One listener; set before the first line can arrive. */
|
|
8
|
+
onLine(listener: (line: string) => void): void;
|
|
9
|
+
/** The JVM, or the link to it, is gone for good. Fires once. Lines after it are dropped. */
|
|
10
|
+
onExit(listener: (reason: string) => void): void;
|
|
11
|
+
/** End the JVM now. Idempotent. Fires onExit. */
|
|
12
|
+
kill(): void;
|
|
13
|
+
/** Let go without killing (coordinator restart); a later `attach` takes it back. */
|
|
14
|
+
release(): void;
|
|
15
|
+
}
|
|
16
|
+
export interface JvmLauncher {
|
|
17
|
+
/** Boot a new `--host` JVM. Its first line is `warm` (or it exits). */
|
|
18
|
+
launch(hostId: string, opts: {
|
|
19
|
+
xmxMb: number;
|
|
20
|
+
}): JvmTransport;
|
|
21
|
+
/** JVMs still running from an earlier coordinator. */
|
|
22
|
+
running(): Promise<string[]>;
|
|
23
|
+
/** Take one back. Lines it printed while nobody was attached are replayed first, in order. */
|
|
24
|
+
attach(hostId: string): JvmTransport;
|
|
25
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,325 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `--host` bridge JVMs on THIS machine: the local `JvmLauncher` (`jvm-transport.ts` is the seam;
|
|
3
|
+
* `remote/launcher.ts` is the same seam over a claw's agent). The coordinator (`host.ts`) places
|
|
4
|
+
* matches into JVMs; this file starts them, reaches their line streams and settles what they
|
|
5
|
+
* leave on disk.
|
|
6
|
+
*
|
|
7
|
+
* What is generic to any process hosted this way — the fifo transport, pid liveness, the run-dir
|
|
8
|
+
* and crash-record bookkeeping — lives in `engine-runtime.ts`; what is here is Forge's own:
|
|
9
|
+
* compiling and launching the bridge, its preferences, and `stageRunDir`'s Forge-specific profile
|
|
10
|
+
* layout. `forgeEngineRuntime` at the bottom of this file is `EngineRuntime` mapped onto that, and
|
|
11
|
+
* `LocalJvm`'s own spawn (below) launches through its `argv`, appending only the host id `argv`'s
|
|
12
|
+
* sketch has no room for — `host.ts` itself still places matches through `localJvmLauncher`'s
|
|
13
|
+
* `JvmLauncher`, not `EngineRuntime` directly; lifting the pool itself onto `EngineRuntime`, so a
|
|
14
|
+
* non-Forge engine shares the same coordinator, is w105's.
|
|
15
|
+
*
|
|
16
|
+
* ## The run directory
|
|
17
|
+
*
|
|
18
|
+
* Every local JVM gets `<workDir>/<hostId>` (`stageRunDir`): Forge's profile, a `res` symlink,
|
|
19
|
+
* empty user and cache dirs, two fifos, `launch.json` (its pid), the coordinator's `jvm.json` and
|
|
20
|
+
* per-match streams, and `bridge.stderr.txt`. `workDir` is on tmpfs by default, so a directory
|
|
21
|
+
* nobody removes is RAM nobody gets back. What happens to it is decided when the JVM is gone:
|
|
22
|
+
*
|
|
23
|
+
* - **A clean end is removed whole**: the coordinator asked the JVM to go and it went.
|
|
24
|
+
* - **Anything else is a crash record**, pruned to `CRASH_RECORD_FILES` (stderr, the
|
|
25
|
+
* coordinator's `jvm.json` with every match's decks, and a `crash.json` saying how it ended).
|
|
26
|
+
* The exit reason names its path.
|
|
27
|
+
* - **Crash records are bounded**: the newest `CRASH_RECORDS_KEPT`, none older than
|
|
28
|
+
* `CRASH_RECORD_MAX_AGE_MS`.
|
|
29
|
+
* - **The boot sweep** (`sweepRunDirs`, run when the launcher is made) removes what an earlier
|
|
30
|
+
* process left, and spares a directory some process is standing in (`/proc/<pid>/cwd` — so
|
|
31
|
+
* another server's live JVM survives), one changed in the last `RUN_DIR_FRESH_MS`, and crash
|
|
32
|
+
* records within the bound. A live directory whose `launch.json` pid IS the process standing in
|
|
33
|
+
* it is one of ours, and `running()` offers it back. A live one-match JVM from before many
|
|
34
|
+
* matches per JVM (`m-…`, `spare-…`) is ended: nothing re-attaches one any more. Where `/proc`
|
|
35
|
+
* cannot be read the sweep does nothing and says so.
|
|
36
|
+
*
|
|
37
|
+
* ## A JVM outlives its server (Wave 22, §E)
|
|
38
|
+
*
|
|
39
|
+
* A deploy must not end live games, so a JVM survives the server that started it:
|
|
40
|
+
*
|
|
41
|
+
* 1. **The transport is not an inherited pipe**, which dies with its process. The run dir holds
|
|
42
|
+
* two named pipes, `in.fifo` and `out.fifo`, and the JVM's stdin/stdout are fds on those. Both
|
|
43
|
+
* ends open them **`O_RDWR`**, which on Linux succeeds without a peer and means neither side
|
|
44
|
+
* ever sees EOF (each is its own last writer). The bridge exits on stdin EOF. stderr is an
|
|
45
|
+
* `O_APPEND` fd on `bridge.stderr.txt`, for the same reason.
|
|
46
|
+
* 2. **The JVM is not in our process group, and nothing kills it on the way out**: `detached`,
|
|
47
|
+
* `unref`, and no exit hook.
|
|
48
|
+
* 3. **The next process finds it** by `launch.json`, confirmed through `/proc/<pid>/cwd` (a
|
|
49
|
+
* recycled pid is some other program, in some other directory), and `attach` re-opens the
|
|
50
|
+
* fifos. Lines the JVM wrote while nobody was attached are still in `out.fifo`, so they are the
|
|
51
|
+
* first ones read. Rebuilding each MATCH from its history is the coordinator's (`host.ts`).
|
|
52
|
+
*
|
|
53
|
+
* ## The bridge, compiled once
|
|
54
|
+
*
|
|
55
|
+
* See `bridgeLaunch`.
|
|
56
|
+
*
|
|
57
|
+
* ## Configuration (environment)
|
|
58
|
+
*
|
|
59
|
+
* CARDTABLE_FORGE_JAR the fat jar, `forge-gui-desktop-*-jar-with-dependencies.jar` (required)
|
|
60
|
+
* CARDTABLE_FORGE_RES Forge's `forge-gui/res` directory (required)
|
|
61
|
+
* CARDTABLE_JAVA a JDK 21 `java`; default: `$JAVA_HOME/bin/java`, then `java` on `PATH`,
|
|
62
|
+
* the fleet's managed JDK (`defaultJava`, D14 amended 2026-11-02)
|
|
63
|
+
* CARDTABLE_PLAY_WORK_DIR per-JVM run directories; default `<os tmpdir>/cardtable-play`
|
|
64
|
+
* CARDTABLE_PLAY_JVM_OPTS extra JVM flags, space-separated; an `-Xmx` here beats `JVM_HEAP_MB`
|
|
65
|
+
* CARDTABLE_PLAY_WARM_JVM `0` to keep no JVM booted ahead of a match; default on
|
|
66
|
+
* CARDTABLE_PLAY_MATCHES_PER_JVM matches one JVM hosts at most; default `MATCHES_PER_JVM`
|
|
67
|
+
* CARDTABLE_PLAY_BRIDGE_CACHE where the compiled bridge is kept; default `~/.cache/cardtable/bridge`
|
|
68
|
+
* CARDTABLE_AI_FLAT_MC how hard the AI a person plays thinks: `off`, `base`, `lite` or `max`
|
|
69
|
+
* (`AiFlatMc`); default `AI_FLAT_MC`. Read per match, so a restart of the
|
|
70
|
+
* server flips it for every match started after, on JVMs already running too
|
|
71
|
+
*
|
|
72
|
+
* The bridge needs a JDK — `javac` to compile, or `jdk.compiler` for the source launcher it falls
|
|
73
|
+
* back to — which is why the user-local Temurin comes first, ahead of whatever `java` is on `PATH`
|
|
74
|
+
* (on the production host that is a JRE with no `javac`).
|
|
75
|
+
*/
|
|
76
|
+
import { type EngineRuntime, type SweepResult } from './engine-runtime.js';
|
|
77
|
+
import type { JvmLauncher } from './jvm-transport.js';
|
|
78
|
+
/**
|
|
79
|
+
* Forge's server drops a client it has read nothing from for this long
|
|
80
|
+
* (`FServerManager.HEARTBEAT_TIMEOUT_SECONDS`, `forge.net.heartbeatTimeout`, default 45 s;
|
|
81
|
+
* its clients write a heartbeat every 15 s). Every client of a bridge's server is a
|
|
82
|
+
* loopback `FGameClient` in the same JVM, so the only thing that silences one is the
|
|
83
|
+
* whole JVM pausing — and a dropped client is never reconnected: the seat's every later
|
|
84
|
+
* press is lost (hosting-test-plan C2b: a 60 s pause wedged the match for good). A day is
|
|
85
|
+
* far past any pause a JVM comes back from; a JVM that stops for longer is
|
|
86
|
+
* `UNRESPONSIVE_MS`'s to end (host.ts), not Forge's.
|
|
87
|
+
*/
|
|
88
|
+
export declare const FORGE_HEARTBEAT_TIMEOUT_S = 86400;
|
|
89
|
+
/**
|
|
90
|
+
* Flags every bridge JVM gets, before the heap cap and the operator's `jvmOpts` (so a later flag
|
|
91
|
+
* of theirs wins). `ExitOnOutOfMemoryError`: G1 has no GC-overhead limit, and without this a JVM
|
|
92
|
+
* out of heap never exits — its games die of `OutOfMemoryError` and the JVM limps on
|
|
93
|
+
* (hosting-test-plan B4: 62 % GC, act p99 14.6 s). With it the JVM exits (code 3), which fails
|
|
94
|
+
* every match on it through the exit path.
|
|
95
|
+
*/
|
|
96
|
+
export declare const BRIDGE_JVM_FLAGS: readonly string[];
|
|
97
|
+
export interface JvmHostConfig {
|
|
98
|
+
java: string;
|
|
99
|
+
jar: string;
|
|
100
|
+
res: string;
|
|
101
|
+
workDir: string;
|
|
102
|
+
jvmOpts: string[];
|
|
103
|
+
bridgeSource: string;
|
|
104
|
+
/** Compiled bridges, one directory per version. See `bridgeLaunch`. */
|
|
105
|
+
bridgeCache: string;
|
|
106
|
+
/**
|
|
107
|
+
* A JVM asked to stop (`{"t":"stop"}` to its host id) is killed after this long, and a
|
|
108
|
+
* match asked to stop is let go after `MATCH_STOP_MS` (host.ts).
|
|
109
|
+
*/
|
|
110
|
+
stopGraceMs: number;
|
|
111
|
+
/** Keep one booted JVM with room for the next match. See host.ts, "The warm JVM". */
|
|
112
|
+
warmJvm: boolean;
|
|
113
|
+
/** Matches one JVM hosts at most. Default `MATCHES_PER_JVM`. */
|
|
114
|
+
perJvm?: number;
|
|
115
|
+
/** Each JVM's heap cap, unless `jvmOpts` names an `-Xmx` of its own. Default `JVM_HEAP_MB`. */
|
|
116
|
+
xmxMb?: number;
|
|
117
|
+
/** A JVM silent this long is killed and every match on it failed. Default `UNRESPONSIVE_MS` (host.ts); see "Liveness". */
|
|
118
|
+
unresponsiveMs?: number;
|
|
119
|
+
/** Each match's `AiFlatMc`, sent with its `start`. Absent is `off`. */
|
|
120
|
+
aiFlatMc?: AiFlatMc;
|
|
121
|
+
}
|
|
122
|
+
/**
|
|
123
|
+
* Forge's Flat Monte Carlo AI: on each decision with more than one sensible play, the AI plays
|
|
124
|
+
* each out a few times on a copy of the game and takes the best (`FlatMonteCarloPicker`).
|
|
125
|
+
* `off` is the heuristic AI alone; `base` the AI profile's own search (450 ms a decision, 2 s a
|
|
126
|
+
* turn); `lite` Forge's phone setting (600 ms, 2.5 s, plus its attack search and a look at the
|
|
127
|
+
* opponent's next turn for small decisions); `max` its desktop setting (1.5 s, 6 s, more lines,
|
|
128
|
+
* more samples, the opponent's turn always). `PlayBridge.java`'s `MatchContext.aiFlatMc`.
|
|
129
|
+
*/
|
|
130
|
+
export type AiFlatMc = 'off' | 'base' | 'lite' | 'max';
|
|
131
|
+
/** `CARDTABLE_AI_FLAT_MC`'s default. See docs/planning/flat-mc-ai.md for the measurement behind it. */
|
|
132
|
+
export declare const AI_FLAT_MC: AiFlatMc;
|
|
133
|
+
/**
|
|
134
|
+
* `CARDTABLE_AI_FLAT_MC`: unset is {@link AI_FLAT_MC}; anything that is not a level is `off`, so a
|
|
135
|
+
* typo made while turning it down in a hurry never leaves it on.
|
|
136
|
+
*/
|
|
137
|
+
export declare function aiFlatMcFrom(raw: string | undefined): AiFlatMc;
|
|
138
|
+
/**
|
|
139
|
+
* See host.ts, "Many matches per JVM". `CARDTABLE_PLAY_MATCHES_PER_JVM` overrides it. 25 since
|
|
140
|
+
* 2026-10-28: a claw's 4 GB slice holds one JVM, and two claws at 25 make the operator's 50
|
|
141
|
+
* concurrent matches. A slice held 50 paced matches inside every quality gate (hosting-test-plan
|
|
142
|
+
* A2), so 25 is half of what was proven; the limit is the slice's 4 cores, not the heap.
|
|
143
|
+
*/
|
|
144
|
+
export declare const MATCHES_PER_JVM = 25;
|
|
145
|
+
/**
|
|
146
|
+
* Each JVM's heap cap: the budget for {@link MATCHES_PER_JVM} matches. A JVM is ~172 MB live idle
|
|
147
|
+
* and ~10 MB per match (Wave 9 lane D; 4–9 MB in hosting-test-plan B3), so 25 matches live in
|
|
148
|
+
* ~420 MB of a 2 GB heap. G1 does not hand committed heap back, so a JVM's RSS is budgeted at its
|
|
149
|
+
* peak: ~2.3 GB with metaspace, code cache and Netty.
|
|
150
|
+
*/
|
|
151
|
+
export declare const JVM_HEAP_MB = 2048;
|
|
152
|
+
export type JvmAvailability = {
|
|
153
|
+
ok: true;
|
|
154
|
+
config: JvmHostConfig;
|
|
155
|
+
} | {
|
|
156
|
+
ok: false;
|
|
157
|
+
reason: string;
|
|
158
|
+
};
|
|
159
|
+
/** Where compiled bridges are kept, shared by every tree on the host (keyed by `bridgeVersion`). */
|
|
160
|
+
export declare function defaultBridgeCache(env?: NodeJS.ProcessEnv): string;
|
|
161
|
+
/**
|
|
162
|
+
* Resolve the JVM host's configuration, or say exactly what is missing. `bridgeSource` is the game's
|
|
163
|
+
* own bridge (Magic's is `@hadoku/magic-server/root`'s `BRIDGE_SOURCE`): the platform knows no game's tree.
|
|
164
|
+
*/
|
|
165
|
+
export declare function jvmHostConfig(bridgeSource: string, env?: NodeJS.ProcessEnv): JvmAvailability;
|
|
166
|
+
/**
|
|
167
|
+
* A compiled bridge nobody has launched for this long is removed when the next
|
|
168
|
+
* one is compiled. Far past `ORPHAN_MAX_MS`, so no JVM that could still load a
|
|
169
|
+
* class from it is alive.
|
|
170
|
+
*/
|
|
171
|
+
export declare const BRIDGE_CACHE_MAX_AGE_MS: number;
|
|
172
|
+
/**
|
|
173
|
+
* What a bridge JVM is launched with after its flags: `-cp <classpath> <main>`.
|
|
174
|
+
*
|
|
175
|
+
* Launching the SOURCE (`java -cp <jar> PlayBridge.java`, JEP 330) compiles the
|
|
176
|
+
* whole file inside every JVM before `main` runs — about 0.6 s of a 5 s cold
|
|
177
|
+
* start (median 5.68 s against 5.03 s over sixteen alternating starts,
|
|
178
|
+
* 2026-10-06). So it is
|
|
179
|
+
* compiled once instead, by the `javac` beside `config.java`, into a directory
|
|
180
|
+
* named for a hash of everything that decides the result: the source's bytes,
|
|
181
|
+
* the jar it is compiled against, and the JDK. An edited bridge is therefore a
|
|
182
|
+
* different directory, never a stale one, and it still takes effect at the next
|
|
183
|
+
* JVM with no restart, as it did under the source launcher. `-proc:none` is what
|
|
184
|
+
* that launcher does too.
|
|
185
|
+
*
|
|
186
|
+
* Two processes may compile the same version at once (a deploy beside a CI job):
|
|
187
|
+
* each compiles into its own temporary directory and RENAMES it into place, so
|
|
188
|
+
* a JVM never sees half a directory, and the loser's copy is deleted. The
|
|
189
|
+
* directory name carries the main's own name as well as `bridgeVersion`
|
|
190
|
+
* (below) precisely so this stays true even though two different mains
|
|
191
|
+
* (`PlayBridge`, `PoolService`) can share a version: each still gets its own
|
|
192
|
+
* directory, so a reader finding ITS main's class already there is never
|
|
193
|
+
* looking at one another process is still mid-write on for a DIFFERENT main.
|
|
194
|
+
*
|
|
195
|
+
* With no `javac` there (a `java` from `PATH`), or a compile that fails, this is
|
|
196
|
+
* the source launcher exactly as before, and a failed compile is logged. Each
|
|
197
|
+
* `jvm-spawned` line says which one that JVM got.
|
|
198
|
+
*
|
|
199
|
+
* `-sourcepath <bridgeSource's own directory>` is on every `javac` invocation
|
|
200
|
+
* (wave 73 §D): `PlayBridge.java` and `PoolService.java` sit beside each other
|
|
201
|
+
* there, and `PoolService.java` calls `PlayBridge.forgeCardName` — a
|
|
202
|
+
* package-private static method, reachable because both are top-level classes
|
|
203
|
+
* in the same (unnamed) package — so compiling `PoolService.java` alone needs
|
|
204
|
+
* `javac` to find and compile `PlayBridge.java` too. It is a no-op for
|
|
205
|
+
* `PlayBridge.java`'s own compile: nothing in that file references a sibling
|
|
206
|
+
* class `javac` cannot already resolve from the jar, so `-sourcepath` is never
|
|
207
|
+
* consulted for it, and the compiled output is unchanged.
|
|
208
|
+
*/
|
|
209
|
+
/** What compiling and launching a bridge reads from a host's configuration. */
|
|
210
|
+
export type BridgeConfig = Pick<JvmHostConfig, 'java' | 'jar' | 'bridgeSource' | 'bridgeCache'>;
|
|
211
|
+
export declare function bridgeLaunch(config: BridgeConfig, log: (entry: Record<string, unknown>) => void): {
|
|
212
|
+
args: string[];
|
|
213
|
+
how: 'compiled' | 'source';
|
|
214
|
+
};
|
|
215
|
+
/**
|
|
216
|
+
* Every input that decides a compiled bridge's cache directory. Not just
|
|
217
|
+
* `config.bridgeSource`'s own bytes: `javac`'s `-sourcepath` (above) can pull
|
|
218
|
+
* ANY `.java` file beside it into the compile, so the key has to cover every
|
|
219
|
+
* sibling in that directory, hashed in a fixed (sorted) order for a
|
|
220
|
+
* deterministic digest — otherwise an edit to a file that IS referenced,
|
|
221
|
+
* with the referencing file itself unchanged, would keep the old key and so
|
|
222
|
+
* silently serve a stale compiled class for it.
|
|
223
|
+
*
|
|
224
|
+
* Covering the whole directory means `PlayBridge.java`'s own key also changes
|
|
225
|
+
* when `PoolService.java` changes, and vice versa, even on an edit that
|
|
226
|
+
* changes nothing either file's compile actually depends on. Accepted for
|
|
227
|
+
* simplicity: the alternative is having `javac` report exactly which
|
|
228
|
+
* siblings it resolved for THAT compile (it does not expose this), and
|
|
229
|
+
* tracking it per bridge source — real staleness is worse than an occasional
|
|
230
|
+
* needless recompile.
|
|
231
|
+
*
|
|
232
|
+
* Exported so the key itself is unit-testable (`host.test.ts`, "an edited
|
|
233
|
+
* SIBLING .java changes the key too") without a real compile.
|
|
234
|
+
*/
|
|
235
|
+
export declare function bridgeVersion(config: BridgeConfig): string;
|
|
236
|
+
/** `{hostId, pid, startedAt}`: what a later process finds a running JVM by. Written at launch. */
|
|
237
|
+
export declare const LAUNCH_RECORD_FILE = "launch.json";
|
|
238
|
+
/**
|
|
239
|
+
* Write `file` whole or not at all: into a temporary file beside it, then renamed over
|
|
240
|
+
* it. `writeFileSync` in place truncates first, so a full disk left `jvm.json` empty and
|
|
241
|
+
* its match un-re-attachable (hosting-test-plan C6); here a failed write leaves the old
|
|
242
|
+
* file as it was, and throws.
|
|
243
|
+
*/
|
|
244
|
+
export declare function writeFileAtomic(file: string, text: string): void;
|
|
245
|
+
/**
|
|
246
|
+
* Forge resolves `res/` against the working directory (`ForgeConstants.RES_DIR`
|
|
247
|
+
* is "res/" when the version string carries no "git"), and reads its user and
|
|
248
|
+
* cache dirs from `forge.profile.properties` there. So each match gets its own
|
|
249
|
+
* directory — the same staging `scripts/spike/tierc/run.sh` does — and
|
|
250
|
+
* nothing is written into the Forge build it reads from. Exported for
|
|
251
|
+
* `multi-match.jvm.test.ts`, which stages a `--host` JVM itself.
|
|
252
|
+
*/
|
|
253
|
+
export declare function stageRunDir(config: JvmHostConfig, name: string): string;
|
|
254
|
+
/**
|
|
255
|
+
* Forge preferences every match runs with, and why each one is here.
|
|
256
|
+
*
|
|
257
|
+
* These are **Forge's own settings**, not rules: each turns off a desktop-UI
|
|
258
|
+
* behaviour that makes no sense for a browser client, and the file is the
|
|
259
|
+
* documented way to set them (`AbstractPreferences`). A JVM is one match, so
|
|
260
|
+
* the file is written per run directory and nothing outlives it.
|
|
261
|
+
*/
|
|
262
|
+
export declare const FORGE_PREFERENCES: Readonly<Record<string, string>>;
|
|
263
|
+
/** Crash records kept at most, newest first. See "The run directory". */
|
|
264
|
+
export declare const CRASH_RECORDS_KEPT = 20;
|
|
265
|
+
/** A crash record older than this is removed. */
|
|
266
|
+
export declare const CRASH_RECORD_MAX_AGE_MS: number;
|
|
267
|
+
/** The boot sweep leaves a directory changed this recently: another process may be staging it. */
|
|
268
|
+
export declare const RUN_DIR_FRESH_MS = 60000;
|
|
269
|
+
/**
|
|
270
|
+
* What a crashed JVM's directory is pruned to. `crash.json` marks it as a record; `jvm.json` is the
|
|
271
|
+
* coordinator's record of the matches it hosted, with their decks, so one can be replayed.
|
|
272
|
+
*/
|
|
273
|
+
export declare const CRASH_RECORD_FILES: readonly ["bridge.stderr.txt", "jvm.json", "crash.json"];
|
|
274
|
+
/** Why a JVM that did not end cleanly ended — written as `crash.json`. */
|
|
275
|
+
export interface CrashRecord {
|
|
276
|
+
id: string;
|
|
277
|
+
reason: string;
|
|
278
|
+
code: number | null;
|
|
279
|
+
signal: string | null;
|
|
280
|
+
at: string;
|
|
281
|
+
}
|
|
282
|
+
/** `<run>/launch.json`, or null when it is missing, unreadable or not one. */
|
|
283
|
+
export declare function readLaunchRecord(run: string): {
|
|
284
|
+
hostId: string;
|
|
285
|
+
pid: number;
|
|
286
|
+
startedAt: string;
|
|
287
|
+
} | null;
|
|
288
|
+
/**
|
|
289
|
+
* Remove the run directories an earlier process left behind, and hand back the JVMs that are
|
|
290
|
+
* still running. See "The run directory" and "A JVM outlives its server" in the module header for
|
|
291
|
+
* what it spares and why.
|
|
292
|
+
*/
|
|
293
|
+
export declare function sweepRunDirs(workDir: string, now?: number): SweepResult;
|
|
294
|
+
/** Number of bridge JVMs this process currently has running. */
|
|
295
|
+
export declare function liveJvmCount(): number;
|
|
296
|
+
export interface LocalLauncherOptions {
|
|
297
|
+
/** Sweep `workDir` of what an earlier process left (`sweepRunDirs`) now. Default true. */
|
|
298
|
+
sweep?: boolean;
|
|
299
|
+
log?: (entry: Record<string, unknown>) => void;
|
|
300
|
+
}
|
|
301
|
+
/** {@link JvmLauncher} for JVMs on this machine, plus what its boot sweep found. */
|
|
302
|
+
export type LocalJvmLauncher = JvmLauncher & {
|
|
303
|
+
readonly swept: SweepResult | null;
|
|
304
|
+
};
|
|
305
|
+
/**
|
|
306
|
+
* `--host` JVMs on this machine, one run directory each (`<workDir>/<hostId>`), reached over the
|
|
307
|
+
* directory's fifos so a later process can take one back. The boot sweep runs here, once, when the
|
|
308
|
+
* launcher is made: it removes what an earlier process left and finds the JVMs still running.
|
|
309
|
+
*/
|
|
310
|
+
export declare function localJvmLauncher(config: JvmHostConfig, options?: LocalLauncherOptions): LocalJvmLauncher;
|
|
311
|
+
/**
|
|
312
|
+
* `EngineRuntime` (`engine-runtime.ts`) mapped onto Forge's own code. `LocalJvm`'s constructor
|
|
313
|
+
* (below) launches through this `spawn` — the actual `child_process.spawn` call lives here, not
|
|
314
|
+
* in `LocalJvm`, which only builds the argv and hands it over — rather than building the child
|
|
315
|
+
* process itself; `host.ts` itself still places matches through `localJvmLauncher`'s
|
|
316
|
+
* `JvmLauncher`, never `EngineRuntime` directly — lifting the POOL onto `EngineRuntime`, so a
|
|
317
|
+
* non-Forge engine shares the same coordinator, is still ahead of this.
|
|
318
|
+
*
|
|
319
|
+
* One honest gap, unchanged: the sketch's `argv(dir, size)` carries no host id, so Forge's real
|
|
320
|
+
* spawn appends `'--host', hostId` itself, after exactly these flags — the interface doesn't carry
|
|
321
|
+
* a host id to launch with.
|
|
322
|
+
*/
|
|
323
|
+
export declare function forgeEngineRuntime(config: JvmHostConfig, log: (entry: Record<string, unknown>) => void): EngineRuntime & {
|
|
324
|
+
spawn: NonNullable<EngineRuntime['spawn']>;
|
|
325
|
+
};
|