@hadoku/rooms-protocol 0.45.75 → 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.
- package/dist/game-bundle.d.ts +66 -0
- package/dist/game-bundle.d.ts.map +1 -1
- package/dist/game-bundle.js +6 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/match-channel.d.ts +31 -0
- package/dist/match-channel.d.ts.map +1 -0
- package/dist/match-channel.js +62 -0
- package/package.json +2 -2
package/dist/game-bundle.d.ts
CHANGED
|
@@ -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
|
|
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"}
|
package/dist/game-bundle.js
CHANGED
|
@@ -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';
|
package/dist/index.d.ts.map
CHANGED
|
@@ -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.
|
|
4
|
-
"gitHead": "
|
|
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.",
|