castle-web-sdk 0.4.51 → 0.4.52
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/README.md +66 -2
- package/dist/castle.d.ts +3 -1
- package/dist/castle.js +1 -0
- package/dist/commands.d.ts +31 -0
- package/dist/multiplayer.js +30 -0
- package/dist/rooms.d.ts +11 -0
- package/dist/rooms.js +22 -0
- package/dist/store.d.ts +8 -2
- package/dist/store.js +5 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -28,6 +28,7 @@ import { setup, initCard, Store, Leaderboard } from "castle-web-sdk";
|
|
|
28
28
|
- [Snapshot](#snapshot)
|
|
29
29
|
- [Portal](#portal)
|
|
30
30
|
- [Social](#social)
|
|
31
|
+
- [Rooms](#rooms)
|
|
31
32
|
- [Party](#party)
|
|
32
33
|
- [Hub](#hub)
|
|
33
34
|
- [Decks](#decks)
|
|
@@ -539,6 +540,28 @@ the page made before calling it, even ones still being batched; await an
|
|
|
539
540
|
`increment` or a board `submit` first if the answer should include it. A player can only ever see their own usage, not
|
|
540
541
|
another player's.
|
|
541
542
|
|
|
543
|
+
`rate` says how much of the per-second rate limits (the last two rows of
|
|
544
|
+
the table below) is spent right now, so a deck that writes often can back
|
|
545
|
+
off before a call is refused rather than after:
|
|
546
|
+
|
|
547
|
+
```js
|
|
548
|
+
const { rate } = await Store.usage();
|
|
549
|
+
if (rate && rate.caller.opsUsed > rate.caller.opsLimit * 0.8) {
|
|
550
|
+
// Close to this player's calls-per-second limit: batch or slow down.
|
|
551
|
+
}
|
|
552
|
+
```
|
|
553
|
+
|
|
554
|
+
- `rate.caller` is the current player's own limit, and `rate.deck` is the
|
|
555
|
+
one every player of the deck shares.
|
|
556
|
+
- Each has `opsUsed`, `opsLimit`, `bytesUsed` and `bytesLimit`, counted
|
|
557
|
+
over the current one-second window, and the `usage` call itself is
|
|
558
|
+
counted in them.
|
|
559
|
+
- `rate.callerClass` names which limit `caller` is: `"client"` for a
|
|
560
|
+
page.
|
|
561
|
+
|
|
562
|
+
`rate` is missing when the app is older than it, so check for it before
|
|
563
|
+
reading it.
|
|
564
|
+
|
|
542
565
|
An app too old to know `usage` rejects with a `CastleError` whose `code`
|
|
543
566
|
is `UNKNOWN_COMMAND`.
|
|
544
567
|
|
|
@@ -1247,6 +1270,45 @@ const friends = await Social.friends();
|
|
|
1247
1270
|
const playingHere = await Social.presence();
|
|
1248
1271
|
```
|
|
1249
1272
|
|
|
1273
|
+
## Rooms
|
|
1274
|
+
|
|
1275
|
+
### `Rooms.list(): Promise<RoomsListResult | null>`
|
|
1276
|
+
|
|
1277
|
+
This deck's public multiplayer rooms and how many players are in each, for a
|
|
1278
|
+
lobby, a room picker or a "12 playing now" line. No room has to write its own
|
|
1279
|
+
count to `Store` for a menu to read.
|
|
1280
|
+
|
|
1281
|
+
```js
|
|
1282
|
+
import { Rooms } from "castle-web-sdk";
|
|
1283
|
+
|
|
1284
|
+
const list = await Rooms.list();
|
|
1285
|
+
if (list) {
|
|
1286
|
+
label.textContent = `${list.total} playing now`;
|
|
1287
|
+
for (const room of list.rooms) {
|
|
1288
|
+
// { sessionId, routeId?, slot?, players, maxPlayers }
|
|
1289
|
+
}
|
|
1290
|
+
}
|
|
1291
|
+
```
|
|
1292
|
+
|
|
1293
|
+
- `total` is the players across every listed room; `rooms` is one entry per
|
|
1294
|
+
room, with `routeId` and `slot` as the deck passed them to
|
|
1295
|
+
`Multiplayer.joinDestination` (absent for a room `Multiplayer.join`
|
|
1296
|
+
opened).
|
|
1297
|
+
- It resolves `null` when Castle will not list the deck's rooms for this
|
|
1298
|
+
player. The deck's owner and Castle admins always get a list; whether
|
|
1299
|
+
other players do depends on how far Castle has rolled presence out, so
|
|
1300
|
+
handle `null` for any player. A player under 13, or one Castle keeps out
|
|
1301
|
+
of multiplayer, gets `null` even on their own deck. Treat `null` as "not available", never as "no
|
|
1302
|
+
rooms": a deck nobody is playing answers `{ total: 0, rooms: [] }`.
|
|
1303
|
+
- An app built before the call also resolves `null` rather than throwing
|
|
1304
|
+
`UNKNOWN_COMMAND`. An unsaved deck throws `MISSING_DECK_ID`.
|
|
1305
|
+
- Counts come from a rollup Castle refreshes about every 10 seconds, so a
|
|
1306
|
+
player who joined or left in the last few seconds may not show yet. Poll it
|
|
1307
|
+
no more than every 10 seconds; there is no event.
|
|
1308
|
+
- Only public rooms are listed. Private, party and named rooms are not.
|
|
1309
|
+
- A local `castle-web serve` lists the saved deck's rooms on Castle, not the
|
|
1310
|
+
rooms of the local serve.
|
|
1311
|
+
|
|
1250
1312
|
## Party
|
|
1251
1313
|
|
|
1252
1314
|
`Party` creates and drives Castle parties with the signed-in player's account.
|
|
@@ -1951,8 +2013,10 @@ load its assets through the bundler instead.
|
|
|
1951
2013
|
A multiplayer socket closed before its first hello reports its WebSocket close
|
|
1952
2014
|
code in `error.extensions.closeCode` when available. Code `4404` means the
|
|
1953
2015
|
play proxy could not route the session (`not_running`); it does not prove the
|
|
1954
|
-
runtime ended. A
|
|
1955
|
-
a
|
|
2016
|
+
runtime ended. A hub join refused this way tries the same handoff again for a
|
|
2017
|
+
few seconds, since a session ghost has just started can briefly be unroutable;
|
|
2018
|
+
the error is reported only when those tries run out. A failed hub join cancels
|
|
2019
|
+
its handoff, so retrying a door after that requires a fresh `Hub.go` acquisition.
|
|
1956
2020
|
|
|
1957
2021
|
Every error the SDK throws is a `CastleError`. Check `code` to tell
|
|
1958
2022
|
the kinds apart.
|
package/dist/castle.d.ts
CHANGED
|
@@ -14,6 +14,8 @@ export { Haptics } from "./haptics";
|
|
|
14
14
|
export type { CastleHapticsApi, HapticsResult, HapticsStatus, HapticStyle } from "./haptics";
|
|
15
15
|
export { Hub } from "./hub";
|
|
16
16
|
export type { CastleHubApi, HubBackResult, HubCancelResult, HubCancelStatus, HubChatMessage, HubChatResult, HubDoor, HubDoorsResult, HubFriend, HubFriendsResult, HubInviteResult, HubCanInviteResult, HubInviteArrivalResult, HubHeartsResult, HubGoParams, HubGoRequest, HubSignInParams, HubSignInResult, HubGoResult, HubHandoffResult, HubHandoffStatus, HubJumpResult, HubPlacementKind, HubReportResult, HubSayResult, } from "./hub";
|
|
17
|
+
export { Rooms } from "./rooms";
|
|
18
|
+
export type { CastleRoomsApi, RoomSummary, RoomsListResult } from "./rooms";
|
|
17
19
|
export { Social } from "./social";
|
|
18
20
|
export type { CastleSocialApi, SocialFriend, SocialPresence } from "./social";
|
|
19
21
|
export { Party } from "./party";
|
|
@@ -46,7 +48,7 @@ export { LocalCache } from "./localCache";
|
|
|
46
48
|
export type { LocalCacheApi } from "./localCache";
|
|
47
49
|
export { SharedStorage, Storage } from "./storage";
|
|
48
50
|
export { Store } from "./store";
|
|
49
|
-
export type { CastleStoreApi, StoreBoardApi, StoreBoardScore, StoreListEntry, StoreListOptions, StoreListPage, StoreAllowance, StoreScopeApi, StoreUsage, } from "./store";
|
|
51
|
+
export type { CastleStoreApi, StoreBoardApi, StoreBoardScore, StoreListEntry, StoreListOptions, StoreListPage, StoreAllowance, StoreRateBudget, StoreRateUsage, StoreScopeApi, StoreUsage, } from "./store";
|
|
50
52
|
export { Time } from "./time";
|
|
51
53
|
export type { CastleClockZone, CastleDateParts, CastleTimeApi } from "./time";
|
|
52
54
|
export type { Json } from "./types";
|
package/dist/castle.js
CHANGED
|
@@ -9,6 +9,7 @@ export { experiment, experiments, experimentsReady } from "./experiments";
|
|
|
9
9
|
export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckFile, } from "./files";
|
|
10
10
|
export { Haptics } from "./haptics";
|
|
11
11
|
export { Hub } from "./hub";
|
|
12
|
+
export { Rooms } from "./rooms";
|
|
12
13
|
export { Social } from "./social";
|
|
13
14
|
export { Party } from "./party";
|
|
14
15
|
export { Leaderboard } from "./leaderboard";
|
package/dist/commands.d.ts
CHANGED
|
@@ -19,9 +19,25 @@ export interface StoreAllowance {
|
|
|
19
19
|
byteCount: number;
|
|
20
20
|
byteLimit: number;
|
|
21
21
|
}
|
|
22
|
+
/** One storage rate window: what was spent in the current second, and its limits. */
|
|
23
|
+
export interface StoreRateBudget {
|
|
24
|
+
opsUsed: number;
|
|
25
|
+
opsLimit: number;
|
|
26
|
+
bytesUsed: number;
|
|
27
|
+
bytesLimit: number;
|
|
28
|
+
}
|
|
29
|
+
/** The storage rate windows a call is charged against. */
|
|
30
|
+
export interface StoreRateUsage {
|
|
31
|
+
/** Which caller bucket answered: "client", "server", "session" or "town-layer". */
|
|
32
|
+
callerClass: string;
|
|
33
|
+
caller: StoreRateBudget;
|
|
34
|
+
deck: StoreRateBudget;
|
|
35
|
+
}
|
|
22
36
|
export interface StoreAllowances {
|
|
23
37
|
player: StoreAllowance;
|
|
24
38
|
shared: StoreAllowance;
|
|
39
|
+
/** Absent from a host older than the rate field. */
|
|
40
|
+
rate?: StoreRateUsage;
|
|
25
41
|
}
|
|
26
42
|
export interface StoreBoardEntry {
|
|
27
43
|
subject: string;
|
|
@@ -96,6 +112,19 @@ export interface SocialPresence extends SocialFriend {
|
|
|
96
112
|
slot?: string;
|
|
97
113
|
updatedAt: string;
|
|
98
114
|
}
|
|
115
|
+
/** One public room of the current deck, as Castle last counted it. */
|
|
116
|
+
export interface RoomSummary {
|
|
117
|
+
sessionId: string;
|
|
118
|
+
routeId?: string;
|
|
119
|
+
slot?: string;
|
|
120
|
+
players: number;
|
|
121
|
+
maxPlayers: number;
|
|
122
|
+
}
|
|
123
|
+
export interface RoomsListResult {
|
|
124
|
+
/** Players across every room listed. */
|
|
125
|
+
total: number;
|
|
126
|
+
rooms: RoomSummary[];
|
|
127
|
+
}
|
|
99
128
|
export type PartyStatus = "invited" | "joined" | "rejected" | "left" | "party_closed" | "banned";
|
|
100
129
|
export interface PartySummary {
|
|
101
130
|
partyId: string;
|
|
@@ -799,6 +828,7 @@ export interface CommandParams {
|
|
|
799
828
|
subject?: string | null;
|
|
800
829
|
};
|
|
801
830
|
"cauldronStorage.usage": Record<string, never>;
|
|
831
|
+
"rooms.list": Record<string, never>;
|
|
802
832
|
"lifecycle.restoreState": Record<string, never>;
|
|
803
833
|
"localCache.get": {
|
|
804
834
|
key: string;
|
|
@@ -956,6 +986,7 @@ export interface CommandResult {
|
|
|
956
986
|
"cauldronStorage.usage": {
|
|
957
987
|
usage: StoreAllowances;
|
|
958
988
|
};
|
|
989
|
+
"rooms.list": RoomsListResult | null;
|
|
959
990
|
"lifecycle.restoreState": LifecycleRestoreStateResult;
|
|
960
991
|
"localCache.get": {
|
|
961
992
|
value: ArrayBuffer | string | null;
|
package/dist/multiplayer.js
CHANGED
|
@@ -75,6 +75,9 @@ async function join(options) {
|
|
|
75
75
|
// The host answers `unavailable` while ghost is busy with this player; the
|
|
76
76
|
// trip stays pending there, so asking again is safe.
|
|
77
77
|
const HUB_COMMIT_RETRY_MS = [1_000, 2_000, 4_000, 8_000];
|
|
78
|
+
// A hub join's tries of the same nonce while the proxy cannot route the new
|
|
79
|
+
// session yet (`openHubSocket`), well inside the nonce's unconsumed life.
|
|
80
|
+
const HUB_UNROUTED_RETRY_MS = [500, 1_000, 2_000];
|
|
78
81
|
async function commitHubTrip(nonce, sessionId) {
|
|
79
82
|
for (let attempt = 0;; attempt++) {
|
|
80
83
|
let status;
|
|
@@ -458,8 +461,35 @@ class MultiplayerConnectionImpl {
|
|
|
458
461
|
if (savedToken && await this.restoreDevReconnect(savedToken))
|
|
459
462
|
return;
|
|
460
463
|
this.assertOpen();
|
|
464
|
+
if (this.request.command === "hub") {
|
|
465
|
+
await this.openHubSocket(result.nonce);
|
|
466
|
+
return;
|
|
467
|
+
}
|
|
461
468
|
await this.openSocket("nonce", result.nonce);
|
|
462
469
|
}
|
|
470
|
+
// A hub session ghost has just started can be refused by the play proxy
|
|
471
|
+
// before its route is readable there (4404, before any hello). The proxy
|
|
472
|
+
// refuses before the session sees the nonce, so the nonce is still good:
|
|
473
|
+
// try it again for a few seconds before the trip is given back.
|
|
474
|
+
async openHubSocket(nonce) {
|
|
475
|
+
for (let attempt = 0;; attempt++) {
|
|
476
|
+
try {
|
|
477
|
+
await this.openSocket("nonce", nonce);
|
|
478
|
+
return;
|
|
479
|
+
}
|
|
480
|
+
catch (error) {
|
|
481
|
+
const delay = HUB_UNROUTED_RETRY_MS[attempt];
|
|
482
|
+
if (!(error instanceof SocketClosedError) ||
|
|
483
|
+
error.code !== PROXY_SESSION_ENDED_CLOSE_CODE ||
|
|
484
|
+
delay === undefined) {
|
|
485
|
+
throw error;
|
|
486
|
+
}
|
|
487
|
+
this.assertOpen();
|
|
488
|
+
await pause(delay);
|
|
489
|
+
this.assertOpen();
|
|
490
|
+
}
|
|
491
|
+
}
|
|
492
|
+
}
|
|
463
493
|
async restoreDevReconnect(token) {
|
|
464
494
|
this.assertOpen();
|
|
465
495
|
const budget = this.reconnectBudget = new ReconnectBudget();
|
package/dist/rooms.d.ts
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import type { RoomsListResult } from "./commands";
|
|
2
|
+
export type { RoomSummary, RoomsListResult } from "./commands";
|
|
3
|
+
export interface CastleRoomsApi {
|
|
4
|
+
/**
|
|
5
|
+
* This deck's public rooms with their player counts, or null when Castle
|
|
6
|
+
* will not list them for this player or the app running the deck predates
|
|
7
|
+
* the call. Null is "not available", never "no rooms".
|
|
8
|
+
*/
|
|
9
|
+
list(): Promise<RoomsListResult | null>;
|
|
10
|
+
}
|
|
11
|
+
export declare const Rooms: CastleRoomsApi;
|
package/dist/rooms.js
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
// Rooms — the current deck's public multiplayer rooms and how many players are
|
|
2
|
+
// in each, for a lobby or a "players online" line. Castle always lists them
|
|
3
|
+
// to the deck's owner and Castle admins, to other players only as far as its
|
|
4
|
+
// presence rollout reaches, and never to a player under 13 or kept out of
|
|
5
|
+
// multiplayer; anyone it will not list them for gets null.
|
|
6
|
+
//
|
|
7
|
+
// Counts come from a rollup Castle refreshes about every 10 seconds, so a
|
|
8
|
+
// player who just joined or left may not show yet. Private, party and named
|
|
9
|
+
// rooms are not listed.
|
|
10
|
+
import { CastleError } from "./errors";
|
|
11
|
+
import { hostRequest } from "./transport";
|
|
12
|
+
async function list() {
|
|
13
|
+
try {
|
|
14
|
+
return await hostRequest("rooms.list", {});
|
|
15
|
+
}
|
|
16
|
+
catch (error) {
|
|
17
|
+
if (error instanceof CastleError && error.code === "UNKNOWN_COMMAND")
|
|
18
|
+
return null;
|
|
19
|
+
throw error;
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
export const Rooms = Object.freeze({ list });
|
package/dist/store.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { StoreAllowance } from "./commands";
|
|
1
|
+
import type { StoreAllowance, StoreRateBudget, StoreRateUsage } from "./commands";
|
|
2
2
|
import type { Json } from "./types";
|
|
3
3
|
import { type SaveApi, type SaveBucketApi } from "./save";
|
|
4
4
|
export interface StoreListOptions {
|
|
@@ -54,7 +54,7 @@ export interface StoreBoardApi {
|
|
|
54
54
|
/** One player's score, defaulting to the current player. Null if unset. */
|
|
55
55
|
get(userId?: string): Promise<StoreBoardScore | null>;
|
|
56
56
|
}
|
|
57
|
-
export type { StoreAllowance };
|
|
57
|
+
export type { StoreAllowance, StoreRateBudget, StoreRateUsage };
|
|
58
58
|
export interface StoreUsage {
|
|
59
59
|
/**
|
|
60
60
|
* The current player's own data in this deck: their `Store.me` and
|
|
@@ -63,6 +63,12 @@ export interface StoreUsage {
|
|
|
63
63
|
player: StoreAllowance;
|
|
64
64
|
/** `Store.deck`: one allowance shared by every player of the deck. */
|
|
65
65
|
shared: StoreAllowance;
|
|
66
|
+
/**
|
|
67
|
+
* How much of the current second's call and byte rate limits is spent, for
|
|
68
|
+
* the current player (`caller`) and for every player of the deck together
|
|
69
|
+
* (`deck`). Counts this usage call. Absent when the app is too old to report it.
|
|
70
|
+
*/
|
|
71
|
+
rate?: StoreRateUsage;
|
|
66
72
|
}
|
|
67
73
|
export interface CastleStoreApi extends SaveApi {
|
|
68
74
|
/** Shared by everyone playing the deck. */
|
package/dist/store.js
CHANGED
|
@@ -309,7 +309,11 @@ async function usage() {
|
|
|
309
309
|
// caller.
|
|
310
310
|
await Promise.all(Array.from(buckets.values(), (bucket) => flushBucket(bucket, false)));
|
|
311
311
|
const { usage: allowances } = await hostRequest("cauldronStorage.usage", {});
|
|
312
|
-
|
|
312
|
+
const result = { player: allowances.player, shared: allowances.shared };
|
|
313
|
+
// An app built before the rate field answers without it.
|
|
314
|
+
if (allowances.rate)
|
|
315
|
+
result.rate = allowances.rate;
|
|
316
|
+
return result;
|
|
313
317
|
}
|
|
314
318
|
// Saves skip the write coalescing above: each is one request, sent at once.
|
|
315
319
|
const saveApi = createSaveApi((verb, input) => hostRequest(`cauldronStorage.${verb}`, input));
|