@journey-to-code/rooms 0.0.0-stage → 0.1.0
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/README.md +154 -2
- package/dist/client.d.ts +62 -0
- package/dist/client.js +134 -0
- package/dist/client.js.map +1 -0
- package/dist/server.d.ts +303 -0
- package/dist/server.js +875 -0
- package/dist/server.js.map +1 -0
- package/package.json +43 -4
package/dist/server.d.ts
ADDED
|
@@ -0,0 +1,303 @@
|
|
|
1
|
+
import { type Log } from "@zubra/sync/server";
|
|
2
|
+
export interface RoomDefinition<State, Move, View, Options, Summary = unknown> {
|
|
3
|
+
/** Seats at the table: a number, or worked out from the room's options (a game for 2 to 6, say). */
|
|
4
|
+
seats: number | ((options: Options) => number);
|
|
5
|
+
/** A new game, from the options a room was created with and a seed. */
|
|
6
|
+
setup(options: Options, seed: number): State;
|
|
7
|
+
/**
|
|
8
|
+
* Apply a move by a seat. Throw a RefusedMove (or any Error) to refuse it; the message goes back to the player.
|
|
9
|
+
* `time` is when the server decided the move and how long the table had waited for it. A game with
|
|
10
|
+
* clocks (a bank per seat that runs down) keeps them in its state from this, and nothing else: the
|
|
11
|
+
* move log keeps each move's time, so a replay hands `act` the same numbers. Never read the clock yourself.
|
|
12
|
+
*/
|
|
13
|
+
act(state: State, seat: number, move: Move, time: MoveTime): State;
|
|
14
|
+
/** What one seat may see. */
|
|
15
|
+
view(state: State, seat: number): View;
|
|
16
|
+
/**
|
|
17
|
+
* What someone watching the table may see, from the state and every seat's view (in seat order).
|
|
18
|
+
* Without it a table can't be watched. `sharedView` builds one from the views: what every seat
|
|
19
|
+
* can see already.
|
|
20
|
+
*/
|
|
21
|
+
watch?(state: State, views: View[]): unknown;
|
|
22
|
+
/** What everyone may see (lobby, scoreboards, a blog embed). */
|
|
23
|
+
summary?(state: State): Summary;
|
|
24
|
+
/** What everyone may see before the game starts, from the room's options: its game and rules, say. */
|
|
25
|
+
info?(options: Options): unknown;
|
|
26
|
+
/**
|
|
27
|
+
* A table's settings (how well and how fast its bots play, say), from a page: checked, with defaults
|
|
28
|
+
* for anything missing. Without it a room has no settings. They're public, and anyone seated can change
|
|
29
|
+
* them mid-game.
|
|
30
|
+
*/
|
|
31
|
+
settings?(given: unknown): unknown;
|
|
32
|
+
/** A bot's move for a seat, or null when it isn't that seat's move. `name` is the bot's name in that seat. */
|
|
33
|
+
bot?(state: State, seat: number, name: string, settings?: any): Move | null;
|
|
34
|
+
/**
|
|
35
|
+
* `bot`, for a game whose computer players can take a while: the same move, worked out somewhere
|
|
36
|
+
* that doesn't hold up every other table (a worker thread, say). When a room has it, its bots are
|
|
37
|
+
* asked here and `bot` is left to whoever else wants a move at once (a deadline's timeout move).
|
|
38
|
+
*
|
|
39
|
+
* Return null, at once, when it isn't that seat's move; otherwise the move, or a promise of it.
|
|
40
|
+
* The room starts the think as the bot's pause begins and plays the move when both are done, so a
|
|
41
|
+
* think shorter than the pause costs the table no time at all. A promised move is only ever played
|
|
42
|
+
* on the state it was asked for: if the game has moved on by the time it arrives (someone else
|
|
43
|
+
* moved, a deadline fired) it is dropped and the seat is asked again, and if the bot was stopped
|
|
44
|
+
* meanwhile (the settings changed, the seat changed hands, the game ended, the table closed) it is
|
|
45
|
+
* dropped and that's that. `thinking.signal` aborts when the room no longer wants the answer.
|
|
46
|
+
* A promise that resolves null, or rejects, leaves the seat waiting: resolve a move.
|
|
47
|
+
*/
|
|
48
|
+
think?(state: State, seat: number, name: string, settings: any, thinking: Thinking): Move | null | Promise<Move | null>;
|
|
49
|
+
/** Whether the game is over. Finished rooms are dropped from memory (the log keeps them). */
|
|
50
|
+
finished?(state: State): boolean;
|
|
51
|
+
/** How long (ms) a bot takes over its move, so bots feel like people. Default 700. */
|
|
52
|
+
botDelay?(state: State, seat: number, name: string, settings?: any): number;
|
|
53
|
+
/**
|
|
54
|
+
* What happens if nobody moves: by when, and the move the server then makes for which seat (a turn
|
|
55
|
+
* timer playing for someone who walked away, a flag falling on a chess clock, a claim window closing).
|
|
56
|
+
* Null when the game waits for ever. Asked again after every move, so it describes this state only.
|
|
57
|
+
* It must not read the clock: `after` counts from the last move, and a state that needs real times
|
|
58
|
+
* gets them from `act`'s `time`.
|
|
59
|
+
*/
|
|
60
|
+
deadline?(state: State, table: TableInfo): Deadline<Move> | null;
|
|
61
|
+
}
|
|
62
|
+
/** What a think is told besides the position (see RoomDefinition.think). */
|
|
63
|
+
export interface Thinking {
|
|
64
|
+
/** Aborts when the room has stopped waiting for this answer: there's no need to finish working it out. */
|
|
65
|
+
signal: AbortSignal;
|
|
66
|
+
/** The room's id, for sharing thinking time fairly between tables. */
|
|
67
|
+
table: string;
|
|
68
|
+
}
|
|
69
|
+
/** When a move was decided. */
|
|
70
|
+
export interface MoveTime {
|
|
71
|
+
/** Server time (ms). Never earlier than the move before it. */
|
|
72
|
+
at: number;
|
|
73
|
+
/** Ms since the move before it (or since the deal, for the first move). */
|
|
74
|
+
elapsed: number;
|
|
75
|
+
}
|
|
76
|
+
/** What a deadline may depend on besides the state: the table's settings, and who sits where. */
|
|
77
|
+
export interface TableInfo {
|
|
78
|
+
/** The table's settings (see RoomDefinition.settings), or null. */
|
|
79
|
+
settings: any;
|
|
80
|
+
seats: Seat[];
|
|
81
|
+
}
|
|
82
|
+
export interface Deadline<Move> {
|
|
83
|
+
/**
|
|
84
|
+
* When time runs out, one of two ways. `after`: this many ms after the last move (or the deal); "30
|
|
85
|
+
* seconds a turn" is `after: 30_000`, and a chess clock is `after: bank[turn]` with `act` taking each
|
|
86
|
+
* move's `elapsed` off the mover's bank. `at`: a server time, for a state that keeps times itself
|
|
87
|
+
* (it learned them from `act`'s `time`).
|
|
88
|
+
*/
|
|
89
|
+
after?: number;
|
|
90
|
+
at?: number;
|
|
91
|
+
/** The seat the clock is on: the timeout move is made as this seat, and pages count down on it. */
|
|
92
|
+
seat: number;
|
|
93
|
+
/**
|
|
94
|
+
* Ms the server waits past that time before it makes the move (none unless given). For a clock
|
|
95
|
+
* short enough that the trip to the page and back matters: pages still count down to the time
|
|
96
|
+
* itself, and a move sent as it reaches zero has this long to arrive.
|
|
97
|
+
*/
|
|
98
|
+
grace?: number;
|
|
99
|
+
/**
|
|
100
|
+
* The move to make when time runs out, worked out only then (it may be a bot's whole think). Null
|
|
101
|
+
* for nothing to do. It goes through `act` and into the move log like any other move.
|
|
102
|
+
*/
|
|
103
|
+
move(): Move | null;
|
|
104
|
+
}
|
|
105
|
+
/** The deadline as pages see it: whose clock, and when it runs out (server time, ms). Never the move. */
|
|
106
|
+
export interface DeadlineDoc {
|
|
107
|
+
at: number;
|
|
108
|
+
seat: number;
|
|
109
|
+
}
|
|
110
|
+
/** What happened in a room, for an app that wants to react (bots chatting, say). */
|
|
111
|
+
export interface MoveEvent<State, Move, Summary> {
|
|
112
|
+
id: string;
|
|
113
|
+
before: State;
|
|
114
|
+
after: State;
|
|
115
|
+
seat: number;
|
|
116
|
+
move: Move;
|
|
117
|
+
room: RoomDoc<Summary>;
|
|
118
|
+
/** The server made this move because the seat's time ran out (see RoomDefinition.deadline). */
|
|
119
|
+
timeout?: boolean;
|
|
120
|
+
}
|
|
121
|
+
export declare class RefusedMove extends Error {
|
|
122
|
+
name: string;
|
|
123
|
+
}
|
|
124
|
+
export interface Seat {
|
|
125
|
+
name: string | null;
|
|
126
|
+
bot: boolean;
|
|
127
|
+
}
|
|
128
|
+
export interface RoomDoc<Summary = unknown> {
|
|
129
|
+
seats: Seat[];
|
|
130
|
+
/** The room's public info from its options (see RoomDefinition.info), or null. */
|
|
131
|
+
info: unknown;
|
|
132
|
+
/** The table's settings (see RoomDefinition.settings), or null. */
|
|
133
|
+
settings?: unknown;
|
|
134
|
+
started: boolean;
|
|
135
|
+
/** Seats set by the server (a tournament match, say): nobody may sit, swap or change bots. */
|
|
136
|
+
locked?: boolean;
|
|
137
|
+
/** A name for the table, set by the server, for pages to show. */
|
|
138
|
+
label?: string;
|
|
139
|
+
/** Set by an app that lists the table somewhere public (a lobby), so its page can say so. */
|
|
140
|
+
open?: boolean;
|
|
141
|
+
/** The seat of whoever runs a listed table (they can remove players), set by the app. */
|
|
142
|
+
host?: number | null;
|
|
143
|
+
/** Seats that may not chat, set by the app. */
|
|
144
|
+
muted?: number[];
|
|
145
|
+
/**
|
|
146
|
+
* A table to watch: every seat is a computer player and anyone may read every seat's view. Only
|
|
147
|
+
* the server makes one (see `exhibit`).
|
|
148
|
+
*/
|
|
149
|
+
watchable?: boolean;
|
|
150
|
+
/** What the cards look like at this table, for everyone at it and watching: the app's to define (see `setDeck`). */
|
|
151
|
+
deck?: unknown;
|
|
152
|
+
/** Why the server's admin closed this table. A closed table takes no more seats, moves or chat. */
|
|
153
|
+
closed?: string;
|
|
154
|
+
summary: Summary | null;
|
|
155
|
+
/** The clock that's running, if the game has one (see RoomDefinition.deadline). */
|
|
156
|
+
deadline?: DeadlineDoc | null;
|
|
157
|
+
/**
|
|
158
|
+
* When the last move was decided (server time, ms), in a room with deadlines: where a clock the
|
|
159
|
+
* game keeps in its own state (a chess clock's two banks) has been running from.
|
|
160
|
+
*/
|
|
161
|
+
moved?: number;
|
|
162
|
+
version: number;
|
|
163
|
+
}
|
|
164
|
+
export interface ChatMessage {
|
|
165
|
+
/** The seat that said it. */
|
|
166
|
+
seat: number;
|
|
167
|
+
name: string;
|
|
168
|
+
text: string;
|
|
169
|
+
/** Server time (ms). */
|
|
170
|
+
at: number;
|
|
171
|
+
bot: boolean;
|
|
172
|
+
/** A moderator took the words away; `text` says so instead. */
|
|
173
|
+
removed?: boolean;
|
|
174
|
+
}
|
|
175
|
+
/** What a removed chat message says instead. */
|
|
176
|
+
export declare const REMOVED_TEXT = "(removed by a moderator)";
|
|
177
|
+
/** How long a message may be, and how often one player may send. */
|
|
178
|
+
export declare const CHAT_LIMIT = 280;
|
|
179
|
+
export interface ViewDoc<View = unknown> {
|
|
180
|
+
view: View;
|
|
181
|
+
version: number;
|
|
182
|
+
}
|
|
183
|
+
export interface RoomsOptions {
|
|
184
|
+
/** Where the rooms endpoints live. Default `/rooms`. */
|
|
185
|
+
mount?: string;
|
|
186
|
+
/** Where the sync log is served. Default `/_zb/sync`. */
|
|
187
|
+
syncMount?: string;
|
|
188
|
+
/** The sync log. Default: in memory, keeping each field's latest value. */
|
|
189
|
+
log?: Log;
|
|
190
|
+
/** A fixed time (ms) every bot waits before moving, overriding the room's own botDelay. For tests. */
|
|
191
|
+
botDelay?: number;
|
|
192
|
+
/**
|
|
193
|
+
* The least warning (ms) a seat gets when a deadline arrives out of nowhere: a room coming back after
|
|
194
|
+
* a restart with its time already up, or a setting that puts the clock on someone mid-turn. Default 5000.
|
|
195
|
+
*/
|
|
196
|
+
deadlineGrace?: number;
|
|
197
|
+
/** Whether people who aren't at a table may read its watch view. Default: they may. */
|
|
198
|
+
spectators?(): boolean | Promise<boolean>;
|
|
199
|
+
/** Whether a page may open a room with these options: a reason to refuse, or null. Server code's own `create` isn't asked. */
|
|
200
|
+
allow?(options: unknown): string | null | Promise<string | null>;
|
|
201
|
+
/** After every move is published. */
|
|
202
|
+
onMove?(event: MoveEvent<any, any, any>): void;
|
|
203
|
+
/** After the seats change before a game starts: someone sat, stood up, or a bot was added or removed. */
|
|
204
|
+
onSeats?(event: {
|
|
205
|
+
id: string;
|
|
206
|
+
room: RoomDoc<any>;
|
|
207
|
+
}): void;
|
|
208
|
+
/** After a game starts. */
|
|
209
|
+
onStart?(event: {
|
|
210
|
+
id: string;
|
|
211
|
+
state: any;
|
|
212
|
+
room: RoomDoc<any>;
|
|
213
|
+
}): void;
|
|
214
|
+
/**
|
|
215
|
+
* Before a person's message is added to the chat: return the text to post (changed, perhaps), or
|
|
216
|
+
* `{ error }` to turn it away with a reason.
|
|
217
|
+
*/
|
|
218
|
+
beforeSay?(event: {
|
|
219
|
+
id: string;
|
|
220
|
+
seat: number;
|
|
221
|
+
text: string;
|
|
222
|
+
room: RoomDoc<any>;
|
|
223
|
+
}): string | {
|
|
224
|
+
error: string;
|
|
225
|
+
} | Promise<string | {
|
|
226
|
+
error: string;
|
|
227
|
+
}>;
|
|
228
|
+
/** After a person (not a bot) says something. */
|
|
229
|
+
onSay?(event: {
|
|
230
|
+
id: string;
|
|
231
|
+
message: ChatMessage;
|
|
232
|
+
room: RoomDoc<any>;
|
|
233
|
+
}): void;
|
|
234
|
+
/** Seeds for new games. Default: random. */
|
|
235
|
+
seed?: () => number;
|
|
236
|
+
/** Room ids. Default: 6 random letters and digits. */
|
|
237
|
+
id?: () => string;
|
|
238
|
+
}
|
|
239
|
+
/** A new player id: the secret a browser's cookie holds. */
|
|
240
|
+
export declare const newPlayerId: () => string;
|
|
241
|
+
/** Whether the browser reached us over HTTPS: directly, or through a proxy that says so (Railway). */
|
|
242
|
+
export declare function overHttps(request?: Request): boolean;
|
|
243
|
+
/**
|
|
244
|
+
* The Set-Cookie value that makes a browser this player, for a year. Over HTTPS it's also Secure, so
|
|
245
|
+
* the browser never sends it over plain http; plain-http development (localhost) still works.
|
|
246
|
+
*/
|
|
247
|
+
export declare const playerCookie: (player: string, request?: Request) => string;
|
|
248
|
+
export declare function playerOf(request: Request): string | null;
|
|
249
|
+
export declare function createRooms<State, Move, View, Options, Summary = unknown>(def: RoomDefinition<State, Move, View, Options, Summary>, options?: RoomsOptions): {
|
|
250
|
+
sync: {
|
|
251
|
+
fetch(request: Request): Promise<Response | null>;
|
|
252
|
+
documents(): Promise<import("@zubra/sync/server").Documents>;
|
|
253
|
+
write(collection: string, key: string, fields: Record<string, unknown>): Promise<import("@zubra/sync/server").Change[]>;
|
|
254
|
+
handle(req: import("http").IncomingMessage, res: import("http").ServerResponse): Promise<boolean>;
|
|
255
|
+
};
|
|
256
|
+
/** Resolves once the rooms that had a deadline running before a restart have theirs again. */
|
|
257
|
+
restored: Promise<void>;
|
|
258
|
+
create: (roomOptions: Options, given?: unknown) => Promise<string>;
|
|
259
|
+
say: (id: string, seat: number, text: string) => Promise<ChatMessage | string>;
|
|
260
|
+
seatPlayer: (id: string, seat: number, player: string, name: string) => Promise<void>;
|
|
261
|
+
seatBot: (id: string, seat: number, name: string) => Promise<void>;
|
|
262
|
+
unseat: (id: string, seat: number) => Promise<boolean>;
|
|
263
|
+
replaceWithBot: (id: string, seat: number, name: string) => Promise<boolean>;
|
|
264
|
+
start: (id: string) => Promise<string | null>;
|
|
265
|
+
lock: (id: string, label?: string) => Promise<void>;
|
|
266
|
+
exhibit: (id: string, label?: string) => Promise<void>;
|
|
267
|
+
/** Set what the cards look like at a table (anything the app's pages understand), or null for the app's own. */
|
|
268
|
+
setDeck: (id: string, deck: unknown) => Promise<undefined>;
|
|
269
|
+
/** Get a table's computer players moving again (after a restart, nothing else would wake a table with no people). */
|
|
270
|
+
nudge: (id: string) => undefined;
|
|
271
|
+
holders: (id: string) => Promise<(string | null)[]>;
|
|
272
|
+
closeTable: (id: string, reason: string) => Promise<boolean>;
|
|
273
|
+
removePlayer: (id: string, seat: number, bot?: string) => Promise<string | null>;
|
|
274
|
+
redact: (id: string, key: string) => Promise<boolean>;
|
|
275
|
+
/** The public room doc, or undefined. */
|
|
276
|
+
room: (id: string) => Promise<RoomDoc<Summary> | undefined>;
|
|
277
|
+
/** How many rooms have their state in memory (finished ones are dropped). */
|
|
278
|
+
readonly inMemory: number;
|
|
279
|
+
/** Answers rooms and sync requests; null for anything else. */
|
|
280
|
+
fetch(request: Request): Promise<Response | null>;
|
|
281
|
+
/** For Node's http: answers rooms and sync requests and resolves true, else false. */
|
|
282
|
+
handle(req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse): Promise<boolean>;
|
|
283
|
+
/** Stop bot timers and deadlines (for tests and shutdown). */
|
|
284
|
+
close(): void;
|
|
285
|
+
};
|
|
286
|
+
/**
|
|
287
|
+
* A view for someone watching, made from every seat's view: whatever all the seats see alike is
|
|
288
|
+
* kept, and whatever differs between them (a hand, the moves on offer, a card only one player has
|
|
289
|
+
* peeked at) becomes null, or an empty list. A watcher so learns nothing that every player at the
|
|
290
|
+
* table doesn't already know, in any game, without the game saying which parts are private.
|
|
291
|
+
*
|
|
292
|
+
* Name a game's private parts in `blank` anyway (their values replace the seats' own before
|
|
293
|
+
* comparing): two hands that happened to match in some detail would otherwise show it. `from`
|
|
294
|
+
* takes the named keys from one seat's view as they are, for the parts that say where the viewer
|
|
295
|
+
* sits rather than what they know.
|
|
296
|
+
*/
|
|
297
|
+
export declare function sharedView<View extends object>(views: View[], { blank, from }?: {
|
|
298
|
+
blank?: Partial<View>;
|
|
299
|
+
from?: {
|
|
300
|
+
seat: number;
|
|
301
|
+
keys: (keyof View)[];
|
|
302
|
+
};
|
|
303
|
+
}): View;
|