@splattervault/server 0.1.0 → 0.1.1
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/CHANGELOG.md +30 -1
- package/README.md +24 -8
- package/dist/index.cjs +14 -4
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1251 -141
- package/dist/index.d.ts +1251 -141
- package/dist/index.js +1 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -4,7 +4,36 @@ All notable changes to `@splattervault/server` are listed here. The format follo
|
|
|
4
4
|
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the package uses [semantic versioning](https://semver.org/);
|
|
5
5
|
while it is 0.x, a minor version may change the API.
|
|
6
6
|
|
|
7
|
-
## [0.1.
|
|
7
|
+
## [0.1.1] - 2026-11-15
|
|
8
|
+
|
|
9
|
+
Follows the corrected Studio API description (API main c002ca7f, https://splattervault.com/docs/studio/swagger.json).
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- `poolClaimConflict(err)`: tells a `serverPools.claim` 409 apart by the API's message: `"no_warm_server"` (none idle:
|
|
14
|
+
start a session instead) or `"busy"` (the "— retry" messages: contention; trying the claim again shortly is safe;
|
|
15
|
+
nothing was claimed). The SDK still never retries a claim itself (it starts servers). The README and
|
|
16
|
+
`examples/match-server.ts` show the fallback.
|
|
17
|
+
|
|
18
|
+
### Changed (types, from the API description)
|
|
19
|
+
|
|
20
|
+
- `CreditBalance`: `createdAt` and `updatedAt` are now `string | null` (an organization API key's answer has null
|
|
21
|
+
dates); new fields `availableBalance`, `graceExpiresAt` (`string | null`) and `user` (an object, or null; null for
|
|
22
|
+
an organization key). Code that assigned `createdAt` to a non-null `string` must now handle null. The SDK itself
|
|
23
|
+
never reads these fields.
|
|
24
|
+
- Every GET operation's parameters now list an optional `If-None-Match` header, and its answers `ETag`, `304` and
|
|
25
|
+
`x-request-id` headers (`components["headers"]["RequestId"]`); `serverPools.claim` lists its `409` answer. Request
|
|
26
|
+
and answer bodies are unchanged apart from `CreditBalance`.
|
|
27
|
+
|
|
28
|
+
### Documentation
|
|
29
|
+
|
|
30
|
+
- The game-server session and billing routes never answer 429 (the API sets no rate limit on them): said so in the
|
|
31
|
+
README and on `Sessions` / `Billing`; only the studio routes answer `429 rate_limited`.
|
|
32
|
+
- Conditional requests: every GET documents ETags, but the SDK never sends `If-None-Match` itself, so it never meets
|
|
33
|
+
a 304; if you send one in `headers`, it adds `Cache-Control: max-age=0` and a 304 rejects with status 304 (as in
|
|
34
|
+
0.1.0). The contract test now checks exactly that instead of "no operation documents ETags".
|
|
35
|
+
|
|
36
|
+
## [0.1.0] - 2026-11-15 (preview)
|
|
8
37
|
|
|
9
38
|
The first release: the Studio API's server operations (organization API key) for Node.js 18 and later.
|
|
10
39
|
|
package/README.md
CHANGED
|
@@ -60,17 +60,24 @@ Claim a warm server from one of your pools (it is already running: seconds), or
|
|
|
60
60
|
minute):
|
|
61
61
|
|
|
62
62
|
```ts
|
|
63
|
-
import {
|
|
63
|
+
import { poolClaimConflict, SplatterVault } from "@splattervault/server";
|
|
64
64
|
|
|
65
65
|
const sv = new SplatterVault();
|
|
66
66
|
|
|
67
67
|
async function serverForMatch(matchId: string) {
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
68
|
+
for (let attempt = 1; attempt <= 2; attempt++) {
|
|
69
|
+
try {
|
|
70
|
+
const claim = await sv.serverPools.claim(12, { friendlyName: `Match ${matchId}`, mode: "Ranked" });
|
|
71
|
+
return claim; // { sessionId, serverInstanceId, connection: { host, primaryPort, code, ... } | null }
|
|
72
|
+
} catch (err) {
|
|
73
|
+
const conflict = poolClaimConflict(err); // a 409 claimed nothing; null for any other error
|
|
74
|
+
if (conflict === "busy" && attempt === 1) {
|
|
75
|
+
await new Promise((r) => setTimeout(r, 1000)); // contention: one more try shortly
|
|
76
|
+
continue;
|
|
77
|
+
}
|
|
78
|
+
if (conflict === null) throw err;
|
|
79
|
+
break; // "no_warm_server" (or still busy): start a new one instead
|
|
80
|
+
}
|
|
74
81
|
}
|
|
75
82
|
const session = await sv.sessions.create({
|
|
76
83
|
gameTypeConfigKey: "my-game",
|
|
@@ -96,6 +103,11 @@ says it is ready (`ready: true`; a game with no ready signal is returned once it
|
|
|
96
103
|
Creating a session, stopping one and claiming a pool server are **never retried by the SDK** (a repeat could start or
|
|
97
104
|
claim a second server). After a network error, look for the session with `sv.sessions.list()` before trying again.
|
|
98
105
|
|
|
106
|
+
A claim's `409` claims nothing, and the API tells its kinds apart only by the message: `poolClaimConflict(err)`
|
|
107
|
+
answers `"no_warm_server"` ("No warm server available in this pool": start a session instead) or `"busy"` (the
|
|
108
|
+
messages ending in "— retry": another claim was running, or the idle server could not take the session; trying the
|
|
109
|
+
claim again shortly is safe), and null for any other error.
|
|
110
|
+
|
|
99
111
|
### Verify a player's token on your game server
|
|
100
112
|
|
|
101
113
|
The game client sends its player token when it connects; your server checks it **offline** against SplatterVault's
|
|
@@ -239,6 +251,10 @@ try {
|
|
|
239
251
|
`err.is("rate_limited")`, `err.isTransient` (408, 429, 500, 502, 503, 504 or no answer) and `err.isNetworkError` help too. Each
|
|
240
252
|
operation's codes are listed in the [Studio API reference](https://splattervault.com/docs/studio).
|
|
241
253
|
|
|
254
|
+
Rate limits: the studio routes (player sign-in, player data, the store) answer `429 rate_limited` with `Retry-After`
|
|
255
|
+
when a key or a player sends too much. The game-server session and billing routes set no rate limit of their own:
|
|
256
|
+
they never answer 429 (their transient failures are 500, 502, 503, 504 or no answer).
|
|
257
|
+
|
|
242
258
|
## Retries, timeouts and cancellation
|
|
243
259
|
|
|
244
260
|
The SDK sends a request again by itself only when that is **safe**, and only after a transient failure: no answer
|
|
@@ -311,7 +327,7 @@ claiming match's; `mode`, `serverName` and `friendlyName` are from when the pool
|
|
|
311
327
|
| `sv.playerData` | `resolve`, `get`, `update`, `clear`, `getMany`, `writeMany`, `getGameData`, `updateGameData`, `import`, `listErasedPlayers`, `erasedPlayerPages` |
|
|
312
328
|
| `sv.store` | `getCatalog`, `getPlayer`, `getHistory`, `historyPages`, `grant`, `consume`, `purchase`, `updateItem`, `reverse`, `syncMetaPurchases`, `importCatalog`, `importHoldings` |
|
|
313
329
|
| `sv` | `verifyPlayerToken` |
|
|
314
|
-
| functions | `verifyPlayerToken`, `createPlayerTokenVerifier`, `readSessionEnvironment`, `newIdempotencyKey` |
|
|
330
|
+
| functions | `verifyPlayerToken`, `createPlayerTokenVerifier`, `readSessionEnvironment`, `newIdempotencyKey`, `poolClaimConflict` |
|
|
315
331
|
|
|
316
332
|
Each method's documentation names its API operation (`@see POST /store/studio/players/{player}/grants`). Request and
|
|
317
333
|
answer types (`ServerSession`, `StoreTxnResult`, `DataOp`, …) are exported, generated from the API's OpenAPI
|
package/dist/index.cjs
CHANGED
|
@@ -519,7 +519,7 @@ var HttpClient = class {
|
|
|
519
519
|
};
|
|
520
520
|
|
|
521
521
|
// src/version.ts
|
|
522
|
-
var SDK_VERSION = "0.1.
|
|
522
|
+
var SDK_VERSION = "0.1.1";
|
|
523
523
|
var KID_RE = /^[0-9a-f]{16}$/;
|
|
524
524
|
var MIN_KEYS_LIFETIME_MS = 6e4;
|
|
525
525
|
var MAX_KEYS_LIFETIME_MS = 36e5;
|
|
@@ -833,7 +833,7 @@ var Billing = class {
|
|
|
833
833
|
http;
|
|
834
834
|
/**
|
|
835
835
|
* The credit balance: the organization's for an organization API key (split into subscription and purchased
|
|
836
|
-
* credits).
|
|
836
|
+
* credits). For an organization key `id` is 0 and `createdAt`, `updatedAt` and `user` are null.
|
|
837
837
|
* @see GET /credits (`billing.getCredits`)
|
|
838
838
|
*/
|
|
839
839
|
getCredits(options) {
|
|
@@ -1274,6 +1274,12 @@ var Sessions = class {
|
|
|
1274
1274
|
return this.http.call("sessions.cancelScheduledCredit", { path: { sessionId }, options });
|
|
1275
1275
|
}
|
|
1276
1276
|
};
|
|
1277
|
+
function poolClaimConflict(err) {
|
|
1278
|
+
if (!(err instanceof SplatterVaultError) || err.status !== 409 || err.operationId !== "serverPools.claim") return null;
|
|
1279
|
+
const body = err.body;
|
|
1280
|
+
const message = typeof body?.message === "string" ? body.message : "";
|
|
1281
|
+
return /\bretry\s*[.!]?\s*$/i.test(message) ? "busy" : "no_warm_server";
|
|
1282
|
+
}
|
|
1277
1283
|
var ServerPools = class {
|
|
1278
1284
|
/** @internal */
|
|
1279
1285
|
constructor(http) {
|
|
@@ -1282,8 +1288,11 @@ var ServerPools = class {
|
|
|
1282
1288
|
http;
|
|
1283
1289
|
/**
|
|
1284
1290
|
* Claims a warm server from pool `poolId` for a match: answers the new session's id, the pool instance and its
|
|
1285
|
-
* `connection` (null until reachable). Needs a key holding org:manage_pools
|
|
1286
|
-
*
|
|
1291
|
+
* `connection` (null until reachable). Needs a key holding org:manage_pools (with an organization API key).
|
|
1292
|
+
*
|
|
1293
|
+
* Never retried by the SDK: a repeat after a lost answer could claim a second server. A `409` claimed nothing:
|
|
1294
|
+
* {@link poolClaimConflict} says whether no server is idle (`"no_warm_server"`: start a session instead) or the
|
|
1295
|
+
* claim met contention (`"busy"`: you may try again shortly). Like every session route it never answers 429.
|
|
1287
1296
|
* @see POST /server-pools/{id}/claim (`serverPools.claim`)
|
|
1288
1297
|
*/
|
|
1289
1298
|
claim(poolId, body, options) {
|
|
@@ -1578,6 +1587,7 @@ exports.TRANSIENT_STATUSES = TRANSIENT_STATUSES;
|
|
|
1578
1587
|
exports.createPlayerTokenVerifier = createPlayerTokenVerifier;
|
|
1579
1588
|
exports.isBrowserLike = isBrowserLike;
|
|
1580
1589
|
exports.newIdempotencyKey = newIdempotencyKey;
|
|
1590
|
+
exports.poolClaimConflict = poolClaimConflict;
|
|
1581
1591
|
exports.readSessionEnvironment = readSessionEnvironment;
|
|
1582
1592
|
exports.verifyPlayerToken = verifyPlayerToken;
|
|
1583
1593
|
//# sourceMappingURL=index.cjs.map
|