@hadoku/rooms-protocol 0.45.74 → 0.45.76

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.
@@ -10,6 +10,12 @@
10
10
  * relays who is looking, what theme they are in, and whether they lead.
11
11
  *
12
12
  * Adding a game is therefore a data edit on the host, never host code.
13
+ *
14
+ * `GameBundleContext.match`/`.channel` extend this for a game that wants a
15
+ * seat table and a message channel FROM the host instead of (or alongside)
16
+ * running its own server — see their own doc comments below. Both are
17
+ * optional, so a bundle or host written before they existed keeps working
18
+ * unchanged; see `match-channel.ts` for a reference `MatchChannel`.
13
19
  */
14
20
  /** Who is viewing. The same values the embeddable room chrome receives. */
15
21
  export interface GameBundleIdentity {
@@ -20,6 +26,56 @@ export interface GameBundleIdentity {
20
26
  /** Display name, or null when the viewer has none yet. */
21
27
  name: string | null;
22
28
  }
29
+ /** One seat at a match's table, as its roster reports it. */
30
+ export interface SeatInfo {
31
+ seat: number;
32
+ /** The key-registry userId holding this seat, or null for an AI seat or an
33
+ * empty one — never a session id, same rule as `GameBundleIdentity.userId`. */
34
+ userId: string | null;
35
+ /** Display name, or null when the seat has none yet (same as
36
+ * `GameBundleIdentity.name`). */
37
+ name: string | null;
38
+ }
39
+ /** The match this bundle is mounted in, when the host is running one. */
40
+ export interface MatchInfo {
41
+ id: string;
42
+ /** This participant's own seat, or null — a null seat is a watcher. */
43
+ seat: number | null;
44
+ /** Every seat at the table, in seat order. */
45
+ seats: SeatInfo[];
46
+ }
47
+ /**
48
+ * Talk to the other seat(s) in a match, over the HOST's own transport —
49
+ * for a game with no server of its own. The host hands each participant
50
+ * (every seat and every watcher) their own `MatchChannel` instance, scoped
51
+ * to that one participant; a bundle never sees anyone else's instance.
52
+ *
53
+ * - **Ordering**: messages from one sender arrive at a receiver in the order
54
+ * `send` was called. Never reordered, across seats or within one.
55
+ * - **Delivery is AT-MOST-ONCE, not at-least-once.** A message that the
56
+ * transport drops — a connection that cuts out, or a host that sheds this
57
+ * traffic under load (the room's own `EmitPolicy` already does this for
58
+ * its broadcasts) — is simply gone: never retried, never duplicated, and
59
+ * the channel never blocks `send` waiting for an ack. That is the honest
60
+ * contract for something riding on a transport that already makes no
61
+ * stronger promise to anything else on it, rather than one the channel
62
+ * cannot actually keep. A game whose state MUST survive a drop layers its
63
+ * own ack-and-resend on top of `send`/`on` — the same way `resync.ts`'s
64
+ * `SeqCursor` is opt-in per app rather than guaranteed on every envelope.
65
+ * - **A watcher may send nothing.** `MatchInfo.seat === null` marks a
66
+ * watcher; calling `send` on ITS channel is a silent no-op — nothing is
67
+ * queued, nothing is delivered, no error is thrown — because a watcher has
68
+ * no seat to speak from. `on` still delivers to a watcher like any other
69
+ * participant.
70
+ * - **`close`** ends the channel for every participant sharing it, not just
71
+ * the caller's own view. Idempotent, and `send`/`on` after close are no-ops.
72
+ */
73
+ export interface MatchChannel<TMsg = unknown> {
74
+ send(msg: TMsg): void;
75
+ /** Subscribe to incoming messages. Returns the unsubscribe function. */
76
+ on(handler: (msg: TMsg) => void): () => void;
77
+ close(): void;
78
+ }
23
79
  export interface GameBundleContext {
24
80
  /** The room the bundle is mounted in: the same value for every
25
81
  * participant. It is the room's id, not the key a viewer joined with —
@@ -33,6 +89,16 @@ export interface GameBundleContext {
33
89
  /** Ask the host to close the bundle. For the leader this closes it for
34
90
  * everyone; for anyone else it closes it for them only. */
35
91
  close(): void;
92
+ /** The match this bundle is mounted in, when the host is running one.
93
+ * Optional: a bundle written before this existed, and a host with no
94
+ * match concept (watchparty's own media-player bundle, for one), both
95
+ * simply omit it — nothing about the existing contract required it. */
96
+ match?: MatchInfo;
97
+ /** Talk to the other seat(s), when the host offers a channel instead of
98
+ * (or alongside) the bundle's own server. Optional for the same reason
99
+ * as `match`, and for the same reason: a game with its own server needs
100
+ * neither. */
101
+ channel?: MatchChannel;
36
102
  }
37
103
  export interface MountedGameBundle {
38
104
  /** Tear down everything `mount` created. Called once. */
@@ -1 +1 @@
1
- {"version":3,"file":"game-bundle.d.ts","sourceRoot":"","sources":["../src/game-bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC;0EACsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC;;;uCAGmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB;gEAC4D;IAC5D,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,OAAO,IAAI,IAAI,CAAC;IAChB,yDAAyD;IACzD,MAAM,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACrC;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,IAAI,CAAC;CAC7C;AAED,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,EAAE,WAAW,EAAE,GAAG,EAAE,iBAAiB,GAAG,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAChG;AAED;+EAC+E;AAC/E,MAAM,WAAW,SAAS;IAAG,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE;AAEpG;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAG5E;AAED,kEAAkE;AAClE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAM9E"}
1
+ {"version":3,"file":"game-bundle.d.ts","sourceRoot":"","sources":["../src/game-bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC;0EACsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,6DAA6D;AAC7D,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb;oFACgF;IAChF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;sCACkC;IAClC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,yEAAyE;AACzE,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,uEAAuE;IACvE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,8CAA8C;IAC9C,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,YAAY,CAAC,IAAI,GAAG,OAAO;IAC1C,IAAI,CAAC,GAAG,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,wEAAwE;IACxE,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC7C,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC;;;uCAGmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB;gEAC4D;IAC5D,KAAK,IAAI,IAAI,CAAC;IACd;;;4EAGwE;IACxE,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;mBAGe;IACf,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,OAAO,IAAI,IAAI,CAAC;IAChB,yDAAyD;IACzD,MAAM,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACrC;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,IAAI,CAAC;CAC7C;AAED,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,EAAE,WAAW,EAAE,GAAG,EAAE,iBAAiB,GAAG,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAChG;AAED;+EAC+E;AAC/E,MAAM,WAAW,SAAS;IAAG,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE;AAEpG;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAG5E;AAED,kEAAkE;AAClE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAM9E"}
@@ -10,6 +10,12 @@
10
10
  * relays who is looking, what theme they are in, and whether they lead.
11
11
  *
12
12
  * Adding a game is therefore a data edit on the host, never host code.
13
+ *
14
+ * `GameBundleContext.match`/`.channel` extend this for a game that wants a
15
+ * seat table and a message channel FROM the host instead of (or alongside)
16
+ * running its own server — see their own doc comments below. Both are
17
+ * optional, so a bundle or host written before they existed keeps working
18
+ * unchanged; see `match-channel.ts` for a reference `MatchChannel`.
13
19
  */
14
20
  /**
15
21
  * Whether `value` is a module that satisfies `GameBundleModule`. A bundle is
package/dist/index.d.ts CHANGED
@@ -11,6 +11,7 @@ export * from './participantId.js';
11
11
  export * from './seats.js';
12
12
  export * from './resync.js';
13
13
  export * from './game-bundle.js';
14
+ export * from './match-channel.js';
14
15
  export * from './avatars.js';
15
16
  export * from './session.js';
16
17
  export * from './feed.js';
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}
package/dist/index.js CHANGED
@@ -11,6 +11,7 @@ export * from './participantId.js';
11
11
  export * from './seats.js';
12
12
  export * from './resync.js';
13
13
  export * from './game-bundle.js';
14
+ export * from './match-channel.js';
14
15
  export * from './avatars.js';
15
16
  export * from './session.js';
16
17
  export * from './feed.js';
@@ -0,0 +1,31 @@
1
+ import type { MatchChannel } from './game-bundle.js';
2
+ /**
3
+ * A reference, in-memory `MatchChannel` implementation. For tests (either
4
+ * side of this package's boundary — watchparty's or a second consumer's),
5
+ * and for a host that wants the contract honoured in-process rather than
6
+ * over a real transport (a single-process dev server, a fixture).
7
+ *
8
+ * `createInMemoryMatchChannels(seats)` returns one `MatchChannel` per entry
9
+ * in `seats`, all wired to the same bus: whatever one sends, every OTHER
10
+ * entry's `on` handlers receive — synchronously, in the order `send` was
11
+ * called, which is what makes it a correct reference for the ordering
12
+ * guarantee in `MatchChannel`'s own doc comment. Delivery is at-most-once,
13
+ * same as the contract: there is no queue and no retry, so closing the set
14
+ * (or a handler that was never subscribed) simply loses whatever was in
15
+ * flight.
16
+ *
17
+ * A `null` entry is a watcher (see `MatchInfo.seat`): its channel's `send`
18
+ * is a silent no-op, exactly as the contract requires, while its `on` still
19
+ * receives everyone else's messages like any other participant.
20
+ *
21
+ * `close()` on ANY one of the returned channels ends the whole set — every
22
+ * channel's `send`/`on` becomes a no-op from that point on — because they
23
+ * are views onto one shared channel, not independent ones that happen to be
24
+ * wired together.
25
+ *
26
+ * Two seats and nothing else (`createInMemoryMatchChannels([0, 1])`) is the
27
+ * plain pair the contract describes; a third `null` entry layers a watcher
28
+ * on top of the same bus for a test that needs one.
29
+ */
30
+ export declare function createInMemoryMatchChannels<TMsg = unknown>(seats: ReadonlyArray<number | null>): MatchChannel<TMsg>[];
31
+ //# sourceMappingURL=match-channel.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"match-channel.d.ts","sourceRoot":"","sources":["../src/match-channel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,GAAG,OAAO,EACxD,KAAK,EAAE,aAAa,CAAC,MAAM,GAAG,IAAI,CAAC,GAClC,YAAY,CAAC,IAAI,CAAC,EAAE,CA8BtB"}
@@ -0,0 +1,62 @@
1
+ /**
2
+ * A reference, in-memory `MatchChannel` implementation. For tests (either
3
+ * side of this package's boundary — watchparty's or a second consumer's),
4
+ * and for a host that wants the contract honoured in-process rather than
5
+ * over a real transport (a single-process dev server, a fixture).
6
+ *
7
+ * `createInMemoryMatchChannels(seats)` returns one `MatchChannel` per entry
8
+ * in `seats`, all wired to the same bus: whatever one sends, every OTHER
9
+ * entry's `on` handlers receive — synchronously, in the order `send` was
10
+ * called, which is what makes it a correct reference for the ordering
11
+ * guarantee in `MatchChannel`'s own doc comment. Delivery is at-most-once,
12
+ * same as the contract: there is no queue and no retry, so closing the set
13
+ * (or a handler that was never subscribed) simply loses whatever was in
14
+ * flight.
15
+ *
16
+ * A `null` entry is a watcher (see `MatchInfo.seat`): its channel's `send`
17
+ * is a silent no-op, exactly as the contract requires, while its `on` still
18
+ * receives everyone else's messages like any other participant.
19
+ *
20
+ * `close()` on ANY one of the returned channels ends the whole set — every
21
+ * channel's `send`/`on` becomes a no-op from that point on — because they
22
+ * are views onto one shared channel, not independent ones that happen to be
23
+ * wired together.
24
+ *
25
+ * Two seats and nothing else (`createInMemoryMatchChannels([0, 1])`) is the
26
+ * plain pair the contract describes; a third `null` entry layers a watcher
27
+ * on top of the same bus for a test that needs one.
28
+ */
29
+ export function createInMemoryMatchChannels(seats) {
30
+ const subscribers = seats.map(() => new Set());
31
+ let closed = false;
32
+ return seats.map((seat, index) => {
33
+ const canSend = seat !== null;
34
+ return {
35
+ send(msg) {
36
+ if (closed || !canSend)
37
+ return;
38
+ subscribers.forEach((set, otherIndex) => {
39
+ if (otherIndex === index)
40
+ return;
41
+ // Snapshot first: a handler that subscribes/unsubscribes while
42
+ // running must not change who else receives THIS message.
43
+ for (const handler of [...set])
44
+ handler(msg);
45
+ });
46
+ },
47
+ on(handler) {
48
+ if (closed)
49
+ return () => { };
50
+ subscribers[index].add(handler);
51
+ return () => subscribers[index].delete(handler);
52
+ },
53
+ close() {
54
+ if (closed)
55
+ return;
56
+ closed = true;
57
+ for (const set of subscribers)
58
+ set.clear();
59
+ },
60
+ };
61
+ });
62
+ }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@hadoku/rooms-protocol",
3
- "version": "0.45.74",
4
- "gitHead": "543012f5ae843a05bd8d4cbc9bfa63b1d6ff933b",
3
+ "version": "0.45.76",
4
+ "gitHead": "c784ffa5e3ac97de8f17c0e3bbc0b83f07a95f1d",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "description": "Room, identity and seating protocol — the wire contract shared by rooms-server and rooms-client.",