@hadoku/game-server 0.0.0-stage → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (119) hide show
  1. package/LICENSE +21 -0
  2. package/dist/base-path.d.ts +29 -0
  3. package/dist/base-path.js +30 -0
  4. package/dist/busy.d.ts +40 -0
  5. package/dist/busy.js +23 -0
  6. package/dist/capacity.d.ts +9 -0
  7. package/dist/capacity.js +6 -0
  8. package/dist/config.d.ts +247 -0
  9. package/dist/config.js +271 -0
  10. package/dist/edge-auth.d.ts +43 -0
  11. package/dist/edge-auth.js +47 -0
  12. package/dist/erase/anonymise.d.ts +7 -0
  13. package/dist/erase/anonymise.js +7 -0
  14. package/dist/erase/index.d.ts +18 -0
  15. package/dist/erase/index.js +20 -0
  16. package/dist/erase/legacy-ids.d.ts +7 -0
  17. package/dist/erase/legacy-ids.js +24 -0
  18. package/dist/erase/recordings.d.ts +26 -0
  19. package/dist/erase/recordings.js +128 -0
  20. package/dist/erase/rooms.d.ts +63 -0
  21. package/dist/erase/rooms.js +67 -0
  22. package/dist/gate.d.ts +27 -0
  23. package/dist/gate.js +15 -0
  24. package/dist/http/client-events.d.ts +25 -0
  25. package/dist/http/client-events.js +15 -0
  26. package/dist/http/page.d.ts +26 -0
  27. package/dist/http/page.js +35 -0
  28. package/dist/http/prepared.d.ts +14 -0
  29. package/dist/http/prepared.js +16 -0
  30. package/dist/http/request.d.ts +59 -0
  31. package/dist/http/request.js +37 -0
  32. package/dist/http/room-core.d.ts +160 -0
  33. package/dist/http/room-core.js +278 -0
  34. package/dist/http/trim.d.ts +23 -0
  35. package/dist/http/trim.js +76 -0
  36. package/dist/http/usage.d.ts +22 -0
  37. package/dist/http/usage.js +16 -0
  38. package/dist/kernel.d.ts +4 -0
  39. package/dist/kernel.js +26 -0
  40. package/dist/log.d.ts +9 -0
  41. package/dist/log.js +9 -0
  42. package/dist/people.d.ts +105 -0
  43. package/dist/people.js +145 -0
  44. package/dist/play/clock.d.ts +39 -0
  45. package/dist/play/clock.js +81 -0
  46. package/dist/play/diagnostics.d.ts +21 -0
  47. package/dist/play/diagnostics.js +35 -0
  48. package/dist/play/engine-runtime.d.ts +200 -0
  49. package/dist/play/engine-runtime.js +309 -0
  50. package/dist/play/game-adapter.d.ts +158 -0
  51. package/dist/play/game-adapter.js +1 -0
  52. package/dist/play/host.d.ts +482 -0
  53. package/dist/play/host.js +950 -0
  54. package/dist/play/jvm-transport.d.ts +25 -0
  55. package/dist/play/jvm-transport.js +1 -0
  56. package/dist/play/local-jvm.d.ts +325 -0
  57. package/dist/play/local-jvm.js +829 -0
  58. package/dist/play/match/hosted.d.ts +92 -0
  59. package/dist/play/match/hosted.js +151 -0
  60. package/dist/play/match/outcome.d.ts +26 -0
  61. package/dist/play/match/outcome.js +21 -0
  62. package/dist/play/match/shell.d.ts +378 -0
  63. package/dist/play/match/shell.js +613 -0
  64. package/dist/play/recording/retention.d.ts +36 -0
  65. package/dist/play/recording/retention.js +89 -0
  66. package/dist/play/recording/writer.d.ts +185 -0
  67. package/dist/play/recording/writer.js +90 -0
  68. package/dist/play/relay-socket.d.ts +128 -0
  69. package/dist/play/relay-socket.js +194 -0
  70. package/dist/play/runtimes/in-process.d.ts +47 -0
  71. package/dist/play/runtimes/in-process.js +43 -0
  72. package/dist/play/runtimes/relay-match.d.ts +166 -0
  73. package/dist/play/runtimes/relay-match.js +240 -0
  74. package/dist/play/runtimes/relay.d.ts +128 -0
  75. package/dist/play/runtimes/relay.js +183 -0
  76. package/dist/play/runtimes/streamed.d.ts +116 -0
  77. package/dist/play/runtimes/streamed.js +148 -0
  78. package/dist/play/start-queue.d.ts +65 -0
  79. package/dist/play/start-queue.js +187 -0
  80. package/dist/room/avatar.d.ts +1 -0
  81. package/dist/room/avatar.js +28 -0
  82. package/dist/room/caller.d.ts +21 -0
  83. package/dist/room/caller.js +1 -0
  84. package/dist/room/constants.d.ts +27 -0
  85. package/dist/room/constants.js +27 -0
  86. package/dist/room/events.d.ts +59 -0
  87. package/dist/room/events.js +174 -0
  88. package/dist/room/identity.d.ts +89 -0
  89. package/dist/room/identity.js +98 -0
  90. package/dist/room/lobby.d.ts +426 -0
  91. package/dist/room/lobby.js +880 -0
  92. package/dist/room/membership.d.ts +64 -0
  93. package/dist/room/membership.js +76 -0
  94. package/dist/room/provisioning.d.ts +22 -0
  95. package/dist/room/provisioning.js +46 -0
  96. package/dist/room/record.d.ts +63 -0
  97. package/dist/room/record.js +39 -0
  98. package/dist/room/room-list.d.ts +67 -0
  99. package/dist/room/room-list.js +66 -0
  100. package/dist/room/seats.d.ts +39 -0
  101. package/dist/room/seats.js +58 -0
  102. package/dist/room/session.d.ts +91 -0
  103. package/dist/room/session.js +156 -0
  104. package/dist/room/socket-auth.d.ts +2 -0
  105. package/dist/room/socket-auth.js +10 -0
  106. package/dist/room/watching.d.ts +35 -0
  107. package/dist/room/watching.js +72 -0
  108. package/dist/room/watchparty-link.d.ts +1 -0
  109. package/dist/room/watchparty-link.js +17 -0
  110. package/dist/stream/alloc.d.ts +115 -0
  111. package/dist/stream/alloc.js +368 -0
  112. package/dist/stream/index.d.ts +66 -0
  113. package/dist/stream/index.js +293 -0
  114. package/dist/telemetry.d.ts +46 -0
  115. package/dist/telemetry.js +25 -0
  116. package/dist/testPort.d.ts +1 -0
  117. package/dist/testPort.js +28 -0
  118. package/package.json +36 -4
  119. package/README.md +0 -3
@@ -0,0 +1,194 @@
1
+ /**
2
+ * The relay's socket path: joins a seat's or a watcher's connection to a
3
+ * match's `RelaySession` (`runtimes/relay.ts`), and fans each relayed
4
+ * message out to the right live sockets. A real roster
5
+ * (`runtimes/relay-match.ts`'s `RelayMatch`, registered from a room's seats
6
+ * by `room/lobby.ts`'s one hook and read back by `plugins/relay.ts`'s
7
+ * `rosterOf`) now backs it — before that this file was proven only with a
8
+ * directly-injected test roster, refusing every join for lack of one.
9
+ *
10
+ * ## The gate is the play socket's, re-applied
11
+ *
12
+ * `../gate.ts`'s `gateSocketIo` (or the game's own, `RelayDeps.gate`) with the SAME `surface: 'play-socket'` the
13
+ * play socket itself uses (`play/socket.ts`) — not a new check, the
14
+ * identical one, installed again on the same `io` for the same reason
15
+ * `play/socket.ts`'s own header gives: an ordering dependency on who
16
+ * attaches first is how a gate goes missing.
17
+ *
18
+ * ## Identity is derived, never accepted
19
+ *
20
+ * `identityFromHeaders` over the sanitized handshake, exactly as the play
21
+ * socket does. `relay:join`'s `matchId` is read from the payload; nothing
22
+ * else about who is speaking is.
23
+ *
24
+ * ## One session per match, created on its first join
25
+ *
26
+ * A `RelaySession` has nothing to do until somebody joins it, so there is
27
+ * no reason to build one earlier. It is dropped from `live` once it ends.
28
+ *
29
+ * ## A room's next match is joined with the same `relay:join`
30
+ *
31
+ * When a match ends, its roster's owner has already put the room's next match under the same id
32
+ * (`runtimes/relay-match.ts`'s registry), and every live socket is told `relay:ended`. A screen
33
+ * rejoins by sending `relay:join` again on the socket it already has (`relay-channel.ts` does on
34
+ * every `relay:ended`): no new event and no reconnect. Until it does, that socket speaks for
35
+ * nothing — its sends and its disconnect belong to the match it joined, which is over.
36
+ */
37
+ import { gateSocketIo } from '../gate.js';
38
+ import { identityFromHeaders } from '../room/identity.js';
39
+ import { costlyActLimit } from '../http/request.js';
40
+ export const RELAY_EVENTS = {
41
+ join: 'relay:join',
42
+ message: 'relay:message',
43
+ /** The host's own word that the match ended: `{ winners }` (the `over` message's seat
44
+ * numbers), or `{ winners: null }` when every seat left. To every live socket of the match,
45
+ * the sender of `over` and every watcher included, so the room can show the result. */
46
+ ended: 'relay:ended',
47
+ };
48
+ /** Joins per caller: a burst of 10, then one every 10 s. A seat opens one
49
+ * relay connection per tab, so a burst covers a refresh storm without
50
+ * covering a scan. */
51
+ export const RELAY_JOIN_RATE_LIMIT = {
52
+ capacity: 10,
53
+ refillAmount: 1,
54
+ refillIntervalMs: 10_000,
55
+ };
56
+ function readMatchId(payload) {
57
+ const matchId = payload?.matchId;
58
+ return typeof matchId === 'string' && matchId !== '' ? matchId : null;
59
+ }
60
+ /**
61
+ * Attaches the relay's `connection`/`relay:join`/`relay:message` handlers to
62
+ * `io`. Safe to call once per process; a second call on the same `io` would
63
+ * install the gate twice (harmless, same precedent as `play/socket.ts`) and
64
+ * a second, independent `live` map, so callers should not do that.
65
+ */
66
+ export function attachRelay(io, deps) {
67
+ (deps.gate ?? { gateSocketIo }).gateSocketIo(io, { minTier: deps.minTier, surface: 'play-socket' });
68
+ const log = deps.log ?? (() => { });
69
+ const live = new Map();
70
+ const joinLimit = costlyActLimit(deps.joinRateLimit === undefined ? RELAY_JOIN_RATE_LIMIT : deps.joinRateLimit, {
71
+ act: 'relay-join',
72
+ onRefused: () => log({ evt: 'relay-join-refused', reason: 'rate-limited' }),
73
+ });
74
+ function matchOf(matchId, roster) {
75
+ const found = live.get(matchId);
76
+ if (found !== undefined)
77
+ return found;
78
+ const seatSockets = new Map();
79
+ const watcherSockets = new Set();
80
+ const session = roster.attach({
81
+ toSeat: (seat, msg) => {
82
+ for (const s of seatSockets.get(seat) ?? [])
83
+ s.emit(RELAY_EVENTS.message, msg);
84
+ },
85
+ toWatchers: (msg) => {
86
+ for (const s of watcherSockets)
87
+ s.emit(RELAY_EVENTS.message, msg);
88
+ },
89
+ }, (outcome) => {
90
+ const ending = live.get(matchId);
91
+ const word = { winners: outcome?.winners ?? null };
92
+ for (const set of ending?.seatSockets.values() ?? [])
93
+ for (const s of set)
94
+ s.emit(RELAY_EVENTS.ended, word);
95
+ for (const s of ending?.watcherSockets ?? [])
96
+ s.emit(RELAY_EVENTS.ended, word);
97
+ live.delete(matchId);
98
+ log({ evt: 'relay-ended', matchId, winners: word.winners });
99
+ deps.onEnded?.(matchId, outcome);
100
+ });
101
+ const entry = { session, roster, seatSockets, watcherSockets };
102
+ live.set(matchId, entry);
103
+ return entry;
104
+ }
105
+ io.on('connection', (socket) => {
106
+ const participantId = identityFromHeaders(socket.request.headers, socket.id);
107
+ // The match this socket joined, by its live entry rather than its id: a room's next match
108
+ // lives under the same id, and a socket that has not rejoined it speaks for nothing there.
109
+ let joined = null;
110
+ socket.on(RELAY_EVENTS.join, (payload, ack) => {
111
+ const reply = ack ?? (() => { });
112
+ const matchId = readMatchId(payload);
113
+ if (matchId === null) {
114
+ reply({ ok: false, error: 'bad-request' });
115
+ return;
116
+ }
117
+ if (!joinLimit(participantId, socket.handshake.headers)) {
118
+ reply({ ok: false, error: 'rate-limited' });
119
+ return;
120
+ }
121
+ const roster = deps.rosterOf(matchId);
122
+ if (roster === undefined) {
123
+ reply({ ok: false, error: 'unknown-match' });
124
+ return;
125
+ }
126
+ const role = roster.roleOf(participantId);
127
+ if (role === undefined) {
128
+ reply({ ok: false, error: 'not-joined' });
129
+ return;
130
+ }
131
+ const match = matchOf(matchId, roster);
132
+ if (role === null) {
133
+ match.watcherSockets.add(socket);
134
+ }
135
+ else {
136
+ const set = match.seatSockets.get(role) ?? new Set();
137
+ set.add(socket);
138
+ match.seatSockets.set(role, set);
139
+ // This seat had no live socket a moment ago (a fresh join, or a rejoin after every
140
+ // earlier one dropped) — told every time regardless, same as `MatchShell.seatConnected`
141
+ // itself is: harmless to tell twice, and cheaper than tracking "was it already zero".
142
+ match.roster.seatConnected?.(role);
143
+ }
144
+ joined = { matchId, match, seat: role };
145
+ log({ evt: 'relay-joined', matchId, seat: role });
146
+ const ended = match.roster.lastEnded?.();
147
+ reply(ended === undefined ? { ok: true, seat: role } : { ok: true, seat: role, ended });
148
+ });
149
+ socket.on(RELAY_EVENTS.message, (msg) => {
150
+ if (joined === null)
151
+ return;
152
+ const { match } = joined;
153
+ if (live.get(joined.matchId) !== match)
154
+ return;
155
+ if (joined.seat === null) {
156
+ // A watcher's own send is refused, always — `RelaySession.fromWatcher`
157
+ // is the no-op behind this, but the refusal belongs here: this is
158
+ // the one place that knows a connection is a watcher's.
159
+ log({ evt: 'relay-send-refused', matchId: joined.matchId, reason: 'watcher' });
160
+ return;
161
+ }
162
+ match.session.fromSeat(joined.seat, msg);
163
+ });
164
+ socket.on('disconnect', () => {
165
+ if (joined === null)
166
+ return;
167
+ const { match } = joined;
168
+ if (live.get(joined.matchId) !== match)
169
+ return;
170
+ if (joined.seat === null) {
171
+ match.watcherSockets.delete(socket);
172
+ }
173
+ else {
174
+ const set = match.seatSockets.get(joined.seat);
175
+ set?.delete(socket);
176
+ // A plain disconnect is not a leave: rejoining is `relay:join` again on a new socket,
177
+ // which simply re-adds it to the same seat's set above. Whether THIS is a leave for
178
+ // good is the roster's own rejoin-grace timer's call — told only once the
179
+ // seat's last live socket is actually gone, never on an earlier one among several tabs.
180
+ if (set === undefined || set.size === 0)
181
+ match.roster.seatDisconnected?.(joined.seat);
182
+ }
183
+ log({ evt: 'relay-disconnected', matchId: joined.matchId, seat: joined.seat });
184
+ });
185
+ });
186
+ return {
187
+ sessionOf: (matchId) => live.get(matchId)?.session,
188
+ close: () => {
189
+ for (const { session } of live.values())
190
+ session.ended('server-stopping');
191
+ live.clear();
192
+ },
193
+ };
194
+ }
@@ -0,0 +1,47 @@
1
+ /**
2
+ * The simplest host there is: a game's own engine, run in THIS process, with no child process, no
3
+ * fifo, and nothing to re-attach. `host.ts`'s Forge host spawns a JVM and talks to it over named
4
+ * pipes because Forge's rules live in Java; a game whose rules are plain TypeScript needs none of
5
+ * that — this file is the host for those. The toy game (`fixtures/toy-game/`) is its first, and
6
+ * phase 6's native bomberman is expected to be its second.
7
+ *
8
+ * Reuses `host.ts`'s own generic `HostEvents<L, C>` / `MatchHost<C>` — so a `HostedMatch` built
9
+ * over this runtime and one built over `host.ts`'s real JVM one differ
10
+ * only in which factory they are handed. The one thing `host.ts`'s own `MatchHostFactory<L, C>`
11
+ * does NOT give us is a factory generic over the match's `Spec` too — it is hardcoded to `host.ts`'s
12
+ * own `MatchSpec`, because `host.ts` only ever hosts Forge. {@link GameHostFactory} is that one
13
+ * further step, for a game whose config is not a `MatchSpec` at all.
14
+ */
15
+ import type { HostEvents, MatchHost } from '../host.js';
16
+ /** A line or a command from any engine: `t` is the one thing every engine's own vocabulary agrees on. */
17
+ type EngineMsg = {
18
+ t: string;
19
+ };
20
+ /** Makes a host for one match, generic over the match's own config too — see this file's header. */
21
+ export type GameHostFactory<Spec, L extends EngineMsg, C extends EngineMsg> = (matchId: string, spec: Spec, events: HostEvents<L, C>) => MatchHost<C>;
22
+ /**
23
+ * The one thing an in-process engine supplies: run `spec`, call `line` for everything the game
24
+ * says — including whatever it says before `start` even returns, a `ready` line, say — and hand
25
+ * back how the host sends it commands and stops it.
26
+ *
27
+ * Nothing here is async. A toy game plays out as fast as the calling test drives it, on the same
28
+ * tick: a `send` can be followed at once by an assertion on the lines it produced, with no `await`
29
+ * and no fifo in between. An engine with real asynchrony of its own (a timer, a promise) is free
30
+ * to call `line` later — `inProcessHost` below makes no assumption either way — but the toy game
31
+ * does not need to.
32
+ */
33
+ export interface InProcessEngine<Spec, L extends EngineMsg, C extends EngineMsg> {
34
+ start(matchId: string, spec: Spec, line: (l: L) => void): {
35
+ send(cmd: C): void;
36
+ stop(): void;
37
+ };
38
+ }
39
+ /**
40
+ * The simplest `EngineRuntime`-shaped host (`engine-runtime.ts`'s doc calls out the shape this
41
+ * fits): wraps an {@link InProcessEngine} as a {@link GameHostFactory}, so a `HostedMatch` runs it
42
+ * exactly as it runs Forge's JVM host — `send`/`stop` reach the engine directly, in this process,
43
+ * and its lines reach `events.line` with nothing in between. `send`/`stop` after `stop()` are
44
+ * silently dropped, the same idempotence `host.ts`'s own `MatchHost.stop` documents.
45
+ */
46
+ export declare function inProcessHost<Spec, L extends EngineMsg, C extends EngineMsg>(engine: InProcessEngine<Spec, L, C>): GameHostFactory<Spec, L, C>;
47
+ export {};
@@ -0,0 +1,43 @@
1
+ /**
2
+ * The simplest host there is: a game's own engine, run in THIS process, with no child process, no
3
+ * fifo, and nothing to re-attach. `host.ts`'s Forge host spawns a JVM and talks to it over named
4
+ * pipes because Forge's rules live in Java; a game whose rules are plain TypeScript needs none of
5
+ * that — this file is the host for those. The toy game (`fixtures/toy-game/`) is its first, and
6
+ * phase 6's native bomberman is expected to be its second.
7
+ *
8
+ * Reuses `host.ts`'s own generic `HostEvents<L, C>` / `MatchHost<C>` — so a `HostedMatch` built
9
+ * over this runtime and one built over `host.ts`'s real JVM one differ
10
+ * only in which factory they are handed. The one thing `host.ts`'s own `MatchHostFactory<L, C>`
11
+ * does NOT give us is a factory generic over the match's `Spec` too — it is hardcoded to `host.ts`'s
12
+ * own `MatchSpec`, because `host.ts` only ever hosts Forge. {@link GameHostFactory} is that one
13
+ * further step, for a game whose config is not a `MatchSpec` at all.
14
+ */
15
+ /**
16
+ * The simplest `EngineRuntime`-shaped host (`engine-runtime.ts`'s doc calls out the shape this
17
+ * fits): wraps an {@link InProcessEngine} as a {@link GameHostFactory}, so a `HostedMatch` runs it
18
+ * exactly as it runs Forge's JVM host — `send`/`stop` reach the engine directly, in this process,
19
+ * and its lines reach `events.line` with nothing in between. `send`/`stop` after `stop()` are
20
+ * silently dropped, the same idempotence `host.ts`'s own `MatchHost.stop` documents.
21
+ */
22
+ export function inProcessHost(engine) {
23
+ return (matchId, spec, events) => {
24
+ let stopped = false;
25
+ const running = engine.start(matchId, spec, (line) => {
26
+ if (!stopped)
27
+ events.line(line);
28
+ });
29
+ return {
30
+ send(cmd) {
31
+ if (stopped)
32
+ return;
33
+ running.send(cmd);
34
+ },
35
+ stop() {
36
+ if (stopped)
37
+ return;
38
+ stopped = true;
39
+ running.stop();
40
+ },
41
+ };
42
+ };
43
+ }
@@ -0,0 +1,166 @@
1
+ /**
2
+ * The relay's own `HostedMatch` — `RelaySession` (`./relay.ts`) composed with the same
3
+ * seat/rejoin-grace/watcher machinery every other hosted game runs on, so a relay match's end is
4
+ * recorded by the shell rather than only by `relay-socket.ts`'s bare `onEnded` callback, and a
5
+ * seat gone past its own grace is driven out of the game (`RelaySession.seatLeft`) — the first
6
+ * thing that ever drove one.
7
+ *
8
+ * There is no engine underneath a relay match — `RelaySession.command`/`fromSeat` are reached
9
+ * directly, never through a spawned process — so this file's own `MatchHostFactory` (below) is a
10
+ * trivial one, reused from `runtimes/in-process.ts` rather than written by hand: nothing ever
11
+ * calls `send`, nothing ever produces a line (`RelayLine` is `never`; see `./relay.ts`'s own
12
+ * header), and the match is `running` the instant {@link RelayMatch.attach} gives it somewhere to
13
+ * relay to — there is no boot to wait for.
14
+ *
15
+ * `RelayMatch` also implements `relay-socket.ts`'s own `RelayRoster`: it is both the match AND the
16
+ * roster a relay socket joins against (seating each socket where the room seats its owner), so
17
+ * `plugins/relay.ts`'s `rosterOf` can simply read one back
18
+ * out of {@link relayMatches} — the module singleton `plugins/relay.ts` registers into, from
19
+ * `room/lobby.ts`'s `onRelayRoomOpened` hook (kept out of this file's own importers; see
20
+ * {@link relayMatches}'s own doc).
21
+ */
22
+ import type { ParticipantId } from '@wolffm/rooms-protocol';
23
+ import { HostedMatch, type HostedMatchDeps } from '../match/hosted.js';
24
+ import type { ShellSeat } from '../match/shell.js';
25
+ import type { MatchHostFactory } from '../host.js';
26
+ import type { RelayRoster } from '../relay-socket.js';
27
+ import { RelaySession, type RelayCommand, type RelayLine, type RelayOutcome, type RelaySink } from './relay.js';
28
+ /** What `RelayMatch`'s own constructor is handed: {@link HostedMatchDeps} with `host` always
29
+ * filled in (by {@link createRelayMatch}, below) plus this file's own grace. */
30
+ interface RelayMatchInternalDeps extends HostedMatchDeps<RelayLine, RelayCommand> {
31
+ seatRejoinGraceMs?: number;
32
+ roomSeatOf: (participantId: ParticipantId) => number | null;
33
+ leaderSeat: () => number | null;
34
+ previous?: RelayEnded;
35
+ }
36
+ /** How the room's previous match ended: its winners' seat numbers, or null when every seat left. */
37
+ export interface RelayEnded {
38
+ winners: readonly number[] | null;
39
+ }
40
+ /** What a `RelayMatch` needs beyond {@link HostedMatchDeps}: `host` is optional here (unlike the
41
+ * interface it extends) because {@link createRelayMatch} fills {@link relayNullHost} in when it
42
+ * is left out — nothing about a relay match ever needs a different one. */
43
+ export interface RelayMatchDeps extends Omit<HostedMatchDeps<RelayLine, RelayCommand>, 'host'> {
44
+ host?: MatchHostFactory<RelayLine, RelayCommand>;
45
+ /**
46
+ * A seat gone this long without reconnecting is out: `RelaySession.seatLeft` fires for it
47
+ * (through the same `command` sink the shell's own concede paths use), and the match goes on
48
+ * for whoever is left. Absent (0, the default): a seat that never comes back never leaves on
49
+ * its own — only the whole match's `rejoinGraceMs` (NOBODY here at all) ever stops anything.
50
+ */
51
+ seatRejoinGraceMs?: number;
52
+ /**
53
+ * The seat the room has this participant in (`Lobby.gameSeatOf`), or null for one it seats
54
+ * nowhere: the room's seating is the one seat list, so the relay seats a socket exactly where
55
+ * every screen's `RoomView.seats` shows its owner — never by which socket arrived first.
56
+ */
57
+ roomSeatOf: (participantId: ParticipantId) => number | null;
58
+ /**
59
+ * The seat the room's leader holds now, or null when the leader holds none. Only that seat's
60
+ * `{ t: 'over' }` ends the match: the protocol's host is the room's leader. Read fresh on every
61
+ * `over`, so it follows leadership when the leader leaves the room (`Lobby.leave`).
62
+ */
63
+ leaderSeat: () => number | null;
64
+ }
65
+ /**
66
+ * `RelaySession` composed with `HostedMatch`'s seat/rejoin-grace/watcher machinery — see this
67
+ * file's own header. A `RelayMatch` is also the `RelayRoster` `relay-socket.ts` joins against:
68
+ * `roleOf` seats a participant where the room seats them (every room auto-sits every joiner, the
69
+ * 2026-11-02 ruling, and the room's seats are the one record of who sat where) and `attach` is
70
+ * where its `RelaySession` is actually built, the moment it has live sockets to relay through.
71
+ */
72
+ export declare class RelayMatch extends HostedMatch<RelayLine, RelayCommand> implements RelayRoster {
73
+ readonly seats: ShellSeat[];
74
+ /** Set once the match ends ({@link RelaySession}'s own `onEnded`) — mirrors `ToyMatch`'s own result field. */
75
+ result: RelayOutcome | null;
76
+ /** When the match ended; null until then. */
77
+ endedAt: number | null;
78
+ private sessionRef;
79
+ private readonly seatGrace;
80
+ protected readonly deps: RelayMatchInternalDeps;
81
+ constructor(id: string, seatCount: number, deps: RelayMatchInternalDeps, restore?: {
82
+ epoch: string | null;
83
+ owners: (string | null)[];
84
+ startedAt: number;
85
+ clockMs?: [number, number];
86
+ });
87
+ /**
88
+ * `RelayRoster.lastEnded`: how the room's previous match ended, until this one is under way
89
+ * (its first message), so a screen that loads the room in between still shows the result.
90
+ * Undefined for a room's first match, and once this one has started.
91
+ */
92
+ lastEnded(): RelayEnded | undefined;
93
+ /** `RelayRoster.seatCount`. */
94
+ get seatCount(): number;
95
+ /**
96
+ * `RelayRoster.roleOf`: the seat the room has this participant in (`deps.roomSeatOf`), read
97
+ * fresh on every join, or null — a watcher — for one the room seats nowhere. The seat's owner
98
+ * follows the room: a member who moved seats, or a match restored with no owners, is seated
99
+ * where the room says, whichever socket reaches here first. Never `undefined` — this match
100
+ * keeps no membership list to refuse a stranger by, because the room's own join already settled
101
+ * that before any socket reached here.
102
+ */
103
+ roleOf(participantId: ParticipantId): number | null;
104
+ /**
105
+ * `RelayRoster.attach`: this match's own `RelaySession`, built the moment it has somewhere to
106
+ * relay to (`relay-socket.ts`'s first join). A second call — should not happen, `relay-socket.ts`
107
+ * calls this at most once per roster — returns the session already built rather than replacing it.
108
+ */
109
+ attach(sink: RelaySink, onEnded: (outcome: RelayOutcome | null) => void): RelaySession;
110
+ /** Only the leader's seat ends the match; anyone else's `over` is refused and logged. */
111
+ private mayEnd;
112
+ private applyEnded;
113
+ /**
114
+ * The shell's notice hook (see `runtimes/relay.ts`'s own `notice` method). `Match.serverStopping`'s
115
+ * own twin: the server is going down and this match cannot outlive it, so every seat is told
116
+ * in words.
117
+ */
118
+ serverStopping(message: string): void;
119
+ /**
120
+ * Drives `RelaySession.seatLeft` after `seatRejoinGraceMs` — R's own "unverified" line settles
121
+ * here: nothing drove a rejoin-grace timer for a relay match before this file existed.
122
+ */
123
+ seatConnected(seat: number): void;
124
+ seatDisconnected(seat: number): void;
125
+ protected onLine(_line: RelayLine): void;
126
+ protected concedeCommand(seat: number): RelayCommand;
127
+ /**
128
+ * `MatchShell.forceConcede`: relay's own `command` is synchronous and unconditional
129
+ * (`RelaySession.command` → `seatLeft`), so there is nothing to wait on before forcing it —
130
+ * this IS the concede, the same one path that ever reaches it (a seat past its own grace, or
131
+ * the whole match's chess-clock flag, which a relay match never has).
132
+ */
133
+ protected forceConcede(seat: number): void;
134
+ }
135
+ /** Builds one `RelayMatch`, filling {@link relayNullHost} in when `deps.host` is left out. */
136
+ export declare function createRelayMatch(id: string, seatCount: number, deps: RelayMatchDeps, previous?: RelayEnded): RelayMatch;
137
+ export interface RelayMatchRegistry {
138
+ /**
139
+ * Builds one `RelayMatch` under `id` — a room's own id, since a relay room IS its own match:
140
+ * there is no separate "start" a non-Magic room's UI ever presses (`rooms/BundleSlot.tsx`'s own
141
+ * doc). Replaces whatever was already registered under `id`. When that match ends, the room's
142
+ * next one is registered in its place with the same `deps` (so the same seats, by
143
+ * `roomSeatOf`): a room plays as many matches as its players start, one after another.
144
+ */
145
+ register(id: string, seatCount: number, deps: RelayMatchDeps): RelayMatch;
146
+ get(id: string): RelayMatch | undefined;
147
+ }
148
+ /**
149
+ * A registry of `RelayMatch`es, keyed by match (room) id. A match that ends is replaced by the
150
+ * room's next one at once, before `relay-socket.ts` tells any screen it ended, so every screen's
151
+ * rejoin (`relay-channel.ts` sends its join again on `relay:ended`) finds the new match. The next
152
+ * match carries how the last one ended (`RelayMatch.lastEnded`) until it is under way.
153
+ */
154
+ export declare function createRelayMatchRegistry(): RelayMatchRegistry;
155
+ /**
156
+ * The one instance `plugins/relay.ts` shares between `ctx.state.lobby.onRelayRoomOpened`'s hook
157
+ * (what puts a `RelayMatch` in) and `rosterOf` (what reads one back out). `room/lobby.ts` never
158
+ * imports this module itself — see `Lobby.onRelayRoomOpened`'s own doc for the import cycle that
159
+ * would otherwise close back to `match.ts`'s `HostedMatch`. A plain module-level singleton rather
160
+ * than a field on `plugins/state.ts`'s `Cardtable` bag, which carries none for it this wave (that
161
+ * file is nobody's lane this wave). Unit tests build their own with
162
+ * {@link createRelayMatchRegistry} instead, so they never share state with this one or with each
163
+ * other.
164
+ */
165
+ export declare const relayMatches: RelayMatchRegistry;
166
+ export {};