@arcadible/server-sdk 0.0.0-stage → 0.4.0-next.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 +176 -0
- package/README.md +118 -2
- package/dist/server/api.d.ts +11 -0
- package/dist/server/api.js +75 -0
- package/dist/server/index.d.ts +27 -0
- package/dist/server/index.js +35 -0
- package/dist/server/issuer.d.ts +17 -0
- package/dist/server/issuer.js +46 -0
- package/dist/server/keys.d.ts +11 -0
- package/dist/server/keys.js +87 -0
- package/dist/server/players.d.ts +25 -0
- package/dist/server/players.js +30 -0
- package/dist/server/tickets.d.ts +54 -0
- package/dist/server/tickets.js +176 -0
- package/dist/shared/api.d.ts +16 -0
- package/dist/shared/api.js +75 -0
- package/dist/shared/error.d.ts +17 -0
- package/dist/shared/error.js +38 -0
- package/dist/shared/players.d.ts +18 -0
- package/dist/shared/players.js +52 -0
- package/dist/shared/values.d.ts +99 -0
- package/dist/shared/values.js +203 -0
- package/package.json +30 -4
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
// Players, for a server of the developer's own: their names, and who
|
|
2
|
+
// deleted their account, read on a schedule.
|
|
3
|
+
import { isObject, readPlayers, unreadable, } from "../shared/players.js";
|
|
4
|
+
// [function]
|
|
5
|
+
export function createPlayers(api) {
|
|
6
|
+
return {
|
|
7
|
+
read: readPlayers(api),
|
|
8
|
+
async deleted(options = {}) {
|
|
9
|
+
const since = options.since;
|
|
10
|
+
if (since !== undefined && Number.isNaN(Date.parse(since))) {
|
|
11
|
+
throw new TypeError("players.deleted's `since` is an ISO time, such as 2026-11-10T00:00:00Z.");
|
|
12
|
+
}
|
|
13
|
+
const query = since === undefined ? "" : `?since=${encodeURIComponent(since)}`;
|
|
14
|
+
const data = await api().request(`/deleted_players${query}`);
|
|
15
|
+
if (!Array.isArray(data))
|
|
16
|
+
throw unreadable();
|
|
17
|
+
return data.map((entry) => {
|
|
18
|
+
if (!isObject(entry) ||
|
|
19
|
+
typeof entry["id"] !== "string" ||
|
|
20
|
+
typeof entry["deleted_at"] !== "string") {
|
|
21
|
+
throw unreadable();
|
|
22
|
+
}
|
|
23
|
+
return {
|
|
24
|
+
deletedAt: new Date(entry["deleted_at"]).toISOString(),
|
|
25
|
+
id: entry["id"],
|
|
26
|
+
};
|
|
27
|
+
});
|
|
28
|
+
},
|
|
29
|
+
};
|
|
30
|
+
}
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
export type Channel = "production" | "staging" | "local";
|
|
2
|
+
/** What a checked ticket says. */
|
|
3
|
+
export type Ticket = {
|
|
4
|
+
/** Unique to this ticket: keep it until `expiresAt` to refuse one sent twice. */
|
|
5
|
+
id: string;
|
|
6
|
+
/** The game's id. */
|
|
7
|
+
game: string;
|
|
8
|
+
/** The build's site. */
|
|
9
|
+
site: string;
|
|
10
|
+
/** The build's version. */
|
|
11
|
+
version: string;
|
|
12
|
+
/** The build's channel. */
|
|
13
|
+
channel: Channel;
|
|
14
|
+
/** The player's id in this game, the same every time; `null` for a guest. */
|
|
15
|
+
player: string | null;
|
|
16
|
+
/** When it stops being good, as an ISO time. */
|
|
17
|
+
expiresAt: string;
|
|
18
|
+
};
|
|
19
|
+
export type CheckOptions = {
|
|
20
|
+
/** This server's own address, as the game declared it: any URL of it. */
|
|
21
|
+
server: string;
|
|
22
|
+
/** The game's id, from its `arcadible.toml`. */
|
|
23
|
+
game: string;
|
|
24
|
+
/**
|
|
25
|
+
* The channel to take tickets from, or several: a production server
|
|
26
|
+
* passes `"production"`, a staging one `"staging"`, and one for both
|
|
27
|
+
* `["production", "staging"]`. Under `ARCADIBLE_SERVE`, `arc serve`'s
|
|
28
|
+
* tickets (`local`) are taken whatever it names.
|
|
29
|
+
*/
|
|
30
|
+
channel: Channel | readonly Channel[];
|
|
31
|
+
};
|
|
32
|
+
export interface Tickets {
|
|
33
|
+
/**
|
|
34
|
+
* Checks a ticket a game sent, and resolves with what it says. Rejects
|
|
35
|
+
* with an `ArcadibleError`: `invalid` (not a ticket, or not one for this
|
|
36
|
+
* server, game, and channel: refuse it), `expired` (ask the game for
|
|
37
|
+
* another), or `unavailable` (the keys couldn't be read: try again).
|
|
38
|
+
*/
|
|
39
|
+
check(ticket: string, options: CheckOptions): Promise<Ticket>;
|
|
40
|
+
}
|
|
41
|
+
export type TicketsOptions = {
|
|
42
|
+
env?: Record<string, string | undefined>;
|
|
43
|
+
fetch?: (url: string, init: {
|
|
44
|
+
signal: AbortSignal;
|
|
45
|
+
}) => Promise<Response>;
|
|
46
|
+
now?: () => number;
|
|
47
|
+
warn?: (message: string) => void;
|
|
48
|
+
};
|
|
49
|
+
/**
|
|
50
|
+
* Tickets for one process. Its issuer is read from the environment once, as
|
|
51
|
+
* it's made: a value that isn't allowed throws here, so a server stops as it
|
|
52
|
+
* starts, not at its first ticket.
|
|
53
|
+
*/
|
|
54
|
+
export declare function createTickets(options?: TicketsOptions): Tickets;
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
// Tickets: a game's proof, signed by Arcadible, of which game it is, which
|
|
2
|
+
// build, and who's playing. A game sends one as it connects; the server
|
|
3
|
+
// checks it here, then keeps its own session.
|
|
4
|
+
// [import]
|
|
5
|
+
import { ArcadibleError, Codes } from "../shared/error.js";
|
|
6
|
+
import { issuerOf } from "./issuer.js";
|
|
7
|
+
import { createKeys } from "./keys.js";
|
|
8
|
+
const TYPE = "arcadible-ticket+jwt";
|
|
9
|
+
// what a check's `channel` may name.
|
|
10
|
+
const CHANNELS = ["production", "staging", "local"];
|
|
11
|
+
// The largest ticket read: one is a few hundred bytes.
|
|
12
|
+
const MAX_TICKET = 4096;
|
|
13
|
+
// How far a server's clock may be from Arcadible's, either way.
|
|
14
|
+
const SKEW = 30;
|
|
15
|
+
const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
|
|
16
|
+
// [function]
|
|
17
|
+
function invalid(why) {
|
|
18
|
+
return new ArcadibleError(Codes.Invalid, `Not a ticket for this: ${why}.`);
|
|
19
|
+
}
|
|
20
|
+
// [function]
|
|
21
|
+
function isObject(value) {
|
|
22
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
23
|
+
}
|
|
24
|
+
// [function]
|
|
25
|
+
// a base64url part's bytes, or null.
|
|
26
|
+
function bytes(part) {
|
|
27
|
+
if (!/^[\w-]+$/u.test(part))
|
|
28
|
+
return null;
|
|
29
|
+
try {
|
|
30
|
+
const text = atob(part.replace(/-/gu, "+").replace(/_/gu, "/"));
|
|
31
|
+
const out = new Uint8Array(new ArrayBuffer(text.length));
|
|
32
|
+
for (let at = 0; at < text.length; at += 1)
|
|
33
|
+
out[at] = text.charCodeAt(at);
|
|
34
|
+
return out;
|
|
35
|
+
}
|
|
36
|
+
catch {
|
|
37
|
+
return null;
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
// [function]
|
|
41
|
+
// a base64url part's JSON object, or null.
|
|
42
|
+
function json(part) {
|
|
43
|
+
const raw = bytes(part);
|
|
44
|
+
if (!raw)
|
|
45
|
+
return null;
|
|
46
|
+
try {
|
|
47
|
+
const value = JSON.parse(new TextDecoder().decode(raw));
|
|
48
|
+
return isObject(value) ? value : null;
|
|
49
|
+
}
|
|
50
|
+
catch {
|
|
51
|
+
return null;
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
// [function]
|
|
55
|
+
// the origin of a server from any address of it. An option that isn't an
|
|
56
|
+
// address is the server's own mistake, so it throws as one.
|
|
57
|
+
function originOf(server) {
|
|
58
|
+
try {
|
|
59
|
+
const url = new URL(server);
|
|
60
|
+
if (url.protocol === "https:" || url.protocol === "http:") {
|
|
61
|
+
return url.origin;
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
catch {
|
|
65
|
+
// refused below.
|
|
66
|
+
}
|
|
67
|
+
throw new TypeError("tickets.check needs `server`: this server's own address, such as https://api.example.com.");
|
|
68
|
+
}
|
|
69
|
+
// [function]
|
|
70
|
+
// the channels a check takes, of those its issuer signs for. Which is the
|
|
71
|
+
// server's own to say, so one that names none, or names what isn't one,
|
|
72
|
+
// throws as a mistake in its code. Under `arc serve`, its tickets are taken
|
|
73
|
+
// whatever the server names, so the same code runs unchanged there.
|
|
74
|
+
function channelsOf(given, issuer) {
|
|
75
|
+
const asked = typeof given === "string" ? [given] : Array.isArray(given) ? given : [];
|
|
76
|
+
if (asked.length === 0 ||
|
|
77
|
+
!asked.every((channel) => CHANNELS.includes(channel))) {
|
|
78
|
+
throw new TypeError('tickets.check needs `channel`: the channel this server takes tickets from, "production" or "staging", or both as a list.');
|
|
79
|
+
}
|
|
80
|
+
if (issuer.local)
|
|
81
|
+
return issuer.channels;
|
|
82
|
+
return asked.filter((channel) => issuer.channels.includes(channel));
|
|
83
|
+
}
|
|
84
|
+
// [function]
|
|
85
|
+
/**
|
|
86
|
+
* Tickets for one process. Its issuer is read from the environment once, as
|
|
87
|
+
* it's made: a value that isn't allowed throws here, so a server stops as it
|
|
88
|
+
* starts, not at its first ticket.
|
|
89
|
+
*/
|
|
90
|
+
export function createTickets(options = {}) {
|
|
91
|
+
const env = options.env ??
|
|
92
|
+
globalThis
|
|
93
|
+
.process?.env ??
|
|
94
|
+
{};
|
|
95
|
+
const now = options.now ?? (() => Date.now());
|
|
96
|
+
const issuer = issuerOf(env);
|
|
97
|
+
if (issuer.local) {
|
|
98
|
+
(options.warn ?? ((message) => console.warn(message)))(`Arcadible: checking tickets against arc serve at ${issuer.name}, not Arcadible. For development only.`);
|
|
99
|
+
}
|
|
100
|
+
const keys = createKeys({
|
|
101
|
+
fetch: options.fetch ?? ((url, init) => fetch(url, init)),
|
|
102
|
+
now,
|
|
103
|
+
url: issuer.keys,
|
|
104
|
+
});
|
|
105
|
+
return {
|
|
106
|
+
async check(ticket, given) {
|
|
107
|
+
if (!isObject(given) ||
|
|
108
|
+
typeof given.game !== "string" ||
|
|
109
|
+
!UUID.test(given.game)) {
|
|
110
|
+
throw new TypeError("tickets.check needs `game`: the game's id, from its arcadible.toml.");
|
|
111
|
+
}
|
|
112
|
+
const server = originOf(given.server);
|
|
113
|
+
const channels = channelsOf(given.channel, issuer);
|
|
114
|
+
if (typeof ticket !== "string" || ticket.length > MAX_TICKET) {
|
|
115
|
+
throw invalid("it isn't a ticket");
|
|
116
|
+
}
|
|
117
|
+
const parts = ticket.split(".");
|
|
118
|
+
if (parts.length !== 3)
|
|
119
|
+
throw invalid("it isn't a ticket");
|
|
120
|
+
const [head, body, mark] = parts;
|
|
121
|
+
const header = json(head);
|
|
122
|
+
const claims = json(body);
|
|
123
|
+
const signature = bytes(mark);
|
|
124
|
+
if (!header || !claims || !signature)
|
|
125
|
+
throw invalid("it isn't a ticket");
|
|
126
|
+
// only what Arcadible signs: one algorithm, one type, a named key.
|
|
127
|
+
if (header["alg"] !== "EdDSA" || header["typ"] !== TYPE) {
|
|
128
|
+
throw invalid("it isn't a ticket");
|
|
129
|
+
}
|
|
130
|
+
if (typeof header["kid"] !== "string")
|
|
131
|
+
throw invalid("it names no key");
|
|
132
|
+
const key = await keys.find(header["kid"]);
|
|
133
|
+
if (!key)
|
|
134
|
+
throw invalid("its key isn't one of the issuer's");
|
|
135
|
+
const signed = new TextEncoder().encode(`${head}.${body}`);
|
|
136
|
+
if (!(await crypto.subtle.verify({ name: "Ed25519" }, key, signature, signed))) {
|
|
137
|
+
throw invalid("its signature doesn't hold");
|
|
138
|
+
}
|
|
139
|
+
// from here it's the issuer's word; what's left is whether it's for
|
|
140
|
+
// this server, this game, and now.
|
|
141
|
+
const { aud, channel, exp, game, iat, iss, jti, site, sub, version } = claims;
|
|
142
|
+
if (iss !== issuer.name)
|
|
143
|
+
throw invalid("it's from another issuer");
|
|
144
|
+
if (aud !== server)
|
|
145
|
+
throw invalid("it's for another server");
|
|
146
|
+
if (game !== given.game)
|
|
147
|
+
throw invalid("it's for another game");
|
|
148
|
+
if (typeof channel !== "string" || !channels.includes(channel)) {
|
|
149
|
+
throw invalid("it's from a channel this server doesn't take");
|
|
150
|
+
}
|
|
151
|
+
if (typeof exp !== "number" ||
|
|
152
|
+
typeof iat !== "number" ||
|
|
153
|
+
typeof jti !== "string" ||
|
|
154
|
+
typeof site !== "string" ||
|
|
155
|
+
typeof version !== "string" ||
|
|
156
|
+
(sub !== undefined && typeof sub !== "string")) {
|
|
157
|
+
throw invalid("it's missing what a ticket says");
|
|
158
|
+
}
|
|
159
|
+
const seconds = now() / 1000;
|
|
160
|
+
if (iat > seconds + SKEW)
|
|
161
|
+
throw invalid("it's from the future");
|
|
162
|
+
if (exp <= seconds - SKEW) {
|
|
163
|
+
throw new ArcadibleError(Codes.Expired, "The ticket has expired. Ask the game for another.");
|
|
164
|
+
}
|
|
165
|
+
return {
|
|
166
|
+
channel: channel,
|
|
167
|
+
expiresAt: new Date(exp * 1000).toISOString(),
|
|
168
|
+
game: given.game,
|
|
169
|
+
id: jti,
|
|
170
|
+
player: sub ?? null,
|
|
171
|
+
site,
|
|
172
|
+
version,
|
|
173
|
+
};
|
|
174
|
+
},
|
|
175
|
+
};
|
|
176
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { ArcadibleError } from "./error.js";
|
|
2
|
+
export type Api = {
|
|
3
|
+
request(path: string, body?: unknown): Promise<unknown>;
|
|
4
|
+
};
|
|
5
|
+
export declare const TIMEOUT: number;
|
|
6
|
+
export declare function initOf(body: unknown): {
|
|
7
|
+
body?: string;
|
|
8
|
+
headers: Record<string, string>;
|
|
9
|
+
method: "GET" | "POST";
|
|
10
|
+
};
|
|
11
|
+
export declare function unreachable(): ArcadibleError;
|
|
12
|
+
/**
|
|
13
|
+
* An answer's `data`, or the error its status says. `unauthorized` is what
|
|
14
|
+
* a `401` means to the caller: its key, or its claim, wasn't taken.
|
|
15
|
+
*/
|
|
16
|
+
export declare function dataOf(res: Response, unauthorized: string): Promise<unknown>;
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
// Arcadible's server API, as both packages read it: what a call sends, and
|
|
2
|
+
// what an answer means. How a request gets there is each package's own: a
|
|
3
|
+
// server's with its key (../server/api.ts), a function's through Arcadible's
|
|
4
|
+
// entry, with its claim (../function/api.ts).
|
|
5
|
+
// [import]
|
|
6
|
+
import { ArcadibleError, Codes } from "./error.js";
|
|
7
|
+
// How long a call waits for Arcadible.
|
|
8
|
+
export const TIMEOUT = 15 * 1000;
|
|
9
|
+
// what Arcadible says of a game's values (values.ts), by status.
|
|
10
|
+
const REFUSED = {
|
|
11
|
+
403: ["Denied", "Arcadible doesn't allow that to a game's server."],
|
|
12
|
+
409: [
|
|
13
|
+
"Conflict",
|
|
14
|
+
"The value was written since the revision named. Read it again.",
|
|
15
|
+
],
|
|
16
|
+
413: ["TooLarge", "A value, or the call's values together, is too large."],
|
|
17
|
+
507: ["Full", "The scope's storage is used up."],
|
|
18
|
+
};
|
|
19
|
+
// [function]
|
|
20
|
+
function isObject(value) {
|
|
21
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
22
|
+
}
|
|
23
|
+
// [function]
|
|
24
|
+
// what a call sends: the method, lowercase headers, and its body as JSON.
|
|
25
|
+
export function initOf(body) {
|
|
26
|
+
return body === undefined
|
|
27
|
+
? { headers: { accept: "application/json" }, method: "GET" }
|
|
28
|
+
: {
|
|
29
|
+
body: JSON.stringify(body),
|
|
30
|
+
headers: {
|
|
31
|
+
"accept": "application/json",
|
|
32
|
+
"content-type": "application/json",
|
|
33
|
+
},
|
|
34
|
+
method: "POST",
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
// [function]
|
|
38
|
+
// Arcadible couldn't be reached.
|
|
39
|
+
export function unreachable() {
|
|
40
|
+
return new ArcadibleError(Codes.Unavailable, "Arcadible couldn't be reached. Try again.");
|
|
41
|
+
}
|
|
42
|
+
// [function]
|
|
43
|
+
/**
|
|
44
|
+
* An answer's `data`, or the error its status says. `unauthorized` is what
|
|
45
|
+
* a `401` means to the caller: its key, or its claim, wasn't taken.
|
|
46
|
+
*/
|
|
47
|
+
export async function dataOf(res, unauthorized) {
|
|
48
|
+
if (res.status === 429) {
|
|
49
|
+
throw new ArcadibleError(Codes.Busy, "Too many requests. Slow down, and try again.");
|
|
50
|
+
}
|
|
51
|
+
if (res.status === 401) {
|
|
52
|
+
throw new ArcadibleError(Codes.Invalid, unauthorized);
|
|
53
|
+
}
|
|
54
|
+
const refusal = REFUSED[res.status];
|
|
55
|
+
if (refusal) {
|
|
56
|
+
throw new ArcadibleError(Codes[refusal[0]], refusal[1]);
|
|
57
|
+
}
|
|
58
|
+
if (res.status >= 500) {
|
|
59
|
+
throw new ArcadibleError(Codes.Unavailable, "Arcadible couldn't answer. Try again.");
|
|
60
|
+
}
|
|
61
|
+
if (!res.ok) {
|
|
62
|
+
throw new ArcadibleError(Codes.Invalid, "Arcadible didn't take the request.");
|
|
63
|
+
}
|
|
64
|
+
let answer;
|
|
65
|
+
try {
|
|
66
|
+
answer = await res.json();
|
|
67
|
+
}
|
|
68
|
+
catch {
|
|
69
|
+
answer = null;
|
|
70
|
+
}
|
|
71
|
+
if (!isObject(answer) || !("data" in answer)) {
|
|
72
|
+
throw new ArcadibleError(Codes.Unavailable, "Arcadible's answer couldn't be read. Try again.");
|
|
73
|
+
}
|
|
74
|
+
return answer["data"];
|
|
75
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
export declare const Codes: {
|
|
2
|
+
readonly Busy: "busy";
|
|
3
|
+
readonly Conflict: "conflict";
|
|
4
|
+
readonly Denied: "denied";
|
|
5
|
+
readonly Expired: "expired";
|
|
6
|
+
readonly Full: "full";
|
|
7
|
+
readonly Invalid: "invalid";
|
|
8
|
+
readonly TooLarge: "too_large";
|
|
9
|
+
readonly TooMany: "too_many";
|
|
10
|
+
readonly Unavailable: "unavailable";
|
|
11
|
+
};
|
|
12
|
+
export type Code = (typeof Codes)[keyof typeof Codes];
|
|
13
|
+
/** A failure with a code: `err.code` says what to do about it. */
|
|
14
|
+
export declare class ArcadibleError extends Error {
|
|
15
|
+
readonly code: Code;
|
|
16
|
+
constructor(code: Code, message: string);
|
|
17
|
+
}
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
// Why a call failed: a code a server branches on, and a message for its
|
|
2
|
+
// logs. The codes are the Arcadible SDK's, where the two share one. One
|
|
3
|
+
// class for both packages; each exports the codes it makes (the Function
|
|
4
|
+
// SDK's have no `expired`, since it checks no tickets).
|
|
5
|
+
// [declare]
|
|
6
|
+
export const Codes = {
|
|
7
|
+
// too many requests: slow down, and try again.
|
|
8
|
+
Busy: "busy",
|
|
9
|
+
// a value was written since the revision a write named: read it again.
|
|
10
|
+
Conflict: "conflict",
|
|
11
|
+
// Arcadible won't do this for a server: writing the developer's values,
|
|
12
|
+
// or a player who isn't the game's.
|
|
13
|
+
Denied: "denied",
|
|
14
|
+
// a ticket that was good, and isn't any more: ask the game for another.
|
|
15
|
+
// The Server SDK's alone.
|
|
16
|
+
Expired: "expired",
|
|
17
|
+
// the scope's storage is used up: remove something first.
|
|
18
|
+
Full: "full",
|
|
19
|
+
// not a ticket, or not one for this server and game: refuse it. Or a
|
|
20
|
+
// request Arcadible won't take: no key, a revoked one, or a bad argument.
|
|
21
|
+
Invalid: "invalid",
|
|
22
|
+
// a value, or a call's values together, past what one may be.
|
|
23
|
+
TooLarge: "too_large",
|
|
24
|
+
// more items in a call than one takes.
|
|
25
|
+
TooMany: "too_many",
|
|
26
|
+
// Arcadible couldn't be reached: worth trying again.
|
|
27
|
+
Unavailable: "unavailable",
|
|
28
|
+
};
|
|
29
|
+
// [class]
|
|
30
|
+
/** A failure with a code: `err.code` says what to do about it. */
|
|
31
|
+
export class ArcadibleError extends Error {
|
|
32
|
+
code;
|
|
33
|
+
constructor(code, message) {
|
|
34
|
+
super(message);
|
|
35
|
+
this.name = "ArcadibleError";
|
|
36
|
+
this.code = code;
|
|
37
|
+
}
|
|
38
|
+
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import type { Api } from "./api.js";
|
|
2
|
+
import { ArcadibleError } from "./error.js";
|
|
3
|
+
/** A player, as a game's server sees one. */
|
|
4
|
+
export type Player = {
|
|
5
|
+
/** Their id in this game, the one a ticket names. */
|
|
6
|
+
id: string;
|
|
7
|
+
/** Their profile's name, as players see it; `null` with none. */
|
|
8
|
+
name: string | null;
|
|
9
|
+
};
|
|
10
|
+
export declare const MAX_PLAYERS = 50;
|
|
11
|
+
export declare const UUID: RegExp;
|
|
12
|
+
export declare function isObject(value: unknown): value is Record<string, unknown>;
|
|
13
|
+
export declare function unreadable(): ArcadibleError;
|
|
14
|
+
/**
|
|
15
|
+
* `players.read`: each player, in the order given, their id and name, or
|
|
16
|
+
* `null` for one who's gone, never was, or is a guest. Up to 50 ids.
|
|
17
|
+
*/
|
|
18
|
+
export declare function readPlayers(api: () => Api): (ids: readonly string[]) => Promise<(Player | null)[]>;
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
// Players: what a game's server, or its function, may ask Arcadible about
|
|
2
|
+
// the players it knows by their ids: their names. Each package adds its own
|
|
3
|
+
// (the server's `deleted`, the function's `primary`).
|
|
4
|
+
import { ArcadibleError, Codes } from "./error.js";
|
|
5
|
+
// The most ids one read takes.
|
|
6
|
+
export const MAX_PLAYERS = 50;
|
|
7
|
+
export const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
|
|
8
|
+
// [function]
|
|
9
|
+
export function isObject(value) {
|
|
10
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
11
|
+
}
|
|
12
|
+
// [function]
|
|
13
|
+
// an answer that isn't the shape a server relies on.
|
|
14
|
+
export function unreadable() {
|
|
15
|
+
return new ArcadibleError(Codes.Unavailable, "Arcadible's answer couldn't be read. Try again.");
|
|
16
|
+
}
|
|
17
|
+
// [function]
|
|
18
|
+
/**
|
|
19
|
+
* `players.read`: each player, in the order given, their id and name, or
|
|
20
|
+
* `null` for one who's gone, never was, or is a guest. Up to 50 ids.
|
|
21
|
+
*/
|
|
22
|
+
export function readPlayers(api) {
|
|
23
|
+
return async (ids) => {
|
|
24
|
+
if (!Array.isArray(ids) ||
|
|
25
|
+
ids.length > MAX_PLAYERS ||
|
|
26
|
+
!ids.every((id) => typeof id === "string" && UUID.test(id))) {
|
|
27
|
+
throw new TypeError(`players.read takes up to ${MAX_PLAYERS} ids, each a player's id in the game.`);
|
|
28
|
+
}
|
|
29
|
+
if (ids.length === 0)
|
|
30
|
+
return [];
|
|
31
|
+
// each id once, then every place it was asked for
|
|
32
|
+
const asked = [...new Set(ids)];
|
|
33
|
+
const data = await api().request(`/players/${asked.join(",")}`);
|
|
34
|
+
if (!Array.isArray(data) || data.length !== asked.length) {
|
|
35
|
+
throw unreadable();
|
|
36
|
+
}
|
|
37
|
+
const found = new Map();
|
|
38
|
+
for (const entry of data) {
|
|
39
|
+
if (entry === null)
|
|
40
|
+
continue;
|
|
41
|
+
if (!isObject(entry) || typeof entry["id"] !== "string") {
|
|
42
|
+
throw unreadable();
|
|
43
|
+
}
|
|
44
|
+
const name = entry["name"];
|
|
45
|
+
found.set(entry["id"], {
|
|
46
|
+
id: entry["id"],
|
|
47
|
+
name: typeof name === "string" && name !== "" ? name : null,
|
|
48
|
+
});
|
|
49
|
+
}
|
|
50
|
+
return ids.map((id) => found.get(id) ?? null);
|
|
51
|
+
};
|
|
52
|
+
}
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
import type { Api } from "./api.js";
|
|
2
|
+
/**
|
|
3
|
+
* Whose the values are: `"developer"`, what the developer publishes, to
|
|
4
|
+
* read; `"game"`, what every player reads and only the game's server writes;
|
|
5
|
+
* `"server"`, the server's alone; or a player, by their id in the game:
|
|
6
|
+
* `{ id }`, as `players.primary(request)` or a ticket gives it.
|
|
7
|
+
*/
|
|
8
|
+
export type Scope = "developer" | WritableScope;
|
|
9
|
+
/** A scope a server writes: every one but the developer's. */
|
|
10
|
+
export type WritableScope = "game" | "server" | {
|
|
11
|
+
id: string;
|
|
12
|
+
};
|
|
13
|
+
/** A value, with the revision a write may name to replace it. */
|
|
14
|
+
export type Value = {
|
|
15
|
+
scope: Scope;
|
|
16
|
+
key: string;
|
|
17
|
+
value: unknown;
|
|
18
|
+
revision: number;
|
|
19
|
+
/** When it was written, as an ISO time. */
|
|
20
|
+
updatedAt: string;
|
|
21
|
+
};
|
|
22
|
+
/** A value a read named with `since`, still at that revision: nothing more to read. */
|
|
23
|
+
export type Unchanged = {
|
|
24
|
+
scope: Scope;
|
|
25
|
+
key: string;
|
|
26
|
+
revision: number;
|
|
27
|
+
unchanged: true;
|
|
28
|
+
};
|
|
29
|
+
/** What a write left: the value's new revision. */
|
|
30
|
+
export type Written = {
|
|
31
|
+
scope: Scope;
|
|
32
|
+
key: string;
|
|
33
|
+
revision: number;
|
|
34
|
+
updatedAt: string;
|
|
35
|
+
};
|
|
36
|
+
/** A key in a list, without its value: its size is the value's, in bytes. */
|
|
37
|
+
export type Entry = {
|
|
38
|
+
key: string;
|
|
39
|
+
revision: number;
|
|
40
|
+
updatedAt: string;
|
|
41
|
+
size: number;
|
|
42
|
+
};
|
|
43
|
+
/** A value to read: its scope and key, and, with `since`, the revision the caller has. */
|
|
44
|
+
export type ReadItem = {
|
|
45
|
+
scope: Scope;
|
|
46
|
+
key: string;
|
|
47
|
+
since?: number;
|
|
48
|
+
};
|
|
49
|
+
/** A value to write: with `revision`, only if it's the value's now (`0`: only if there's none). */
|
|
50
|
+
export type WriteItem = {
|
|
51
|
+
scope: WritableScope;
|
|
52
|
+
key: string;
|
|
53
|
+
value: unknown;
|
|
54
|
+
revision?: number;
|
|
55
|
+
};
|
|
56
|
+
/** A value to remove: with `revision`, only if it's the value's now. */
|
|
57
|
+
export type RemoveItem = {
|
|
58
|
+
scope: WritableScope;
|
|
59
|
+
key: string;
|
|
60
|
+
revision?: number;
|
|
61
|
+
};
|
|
62
|
+
/** What a list takes: a prefix, the key to go on after, and how many. */
|
|
63
|
+
export type ListOptions = {
|
|
64
|
+
prefix?: string;
|
|
65
|
+
after?: string;
|
|
66
|
+
limit?: number;
|
|
67
|
+
};
|
|
68
|
+
/** A list's page: `next` is the key to pass as `after`, or `null` at the end. */
|
|
69
|
+
export type Listed = {
|
|
70
|
+
entries: Entry[];
|
|
71
|
+
next: string | null;
|
|
72
|
+
};
|
|
73
|
+
export interface Values {
|
|
74
|
+
/**
|
|
75
|
+
* The values of the items, in their order, in one call and one snapshot,
|
|
76
|
+
* across scopes: each with its revision, `Unchanged` for an item whose
|
|
77
|
+
* `since` is still its revision, or `null` for a key with none. Up to 32.
|
|
78
|
+
*/
|
|
79
|
+
read(items: readonly ReadItem[]): Promise<(Value | Unchanged | null)[]>;
|
|
80
|
+
/**
|
|
81
|
+
* Replaces each item's value, whole, all of them or none, across scopes.
|
|
82
|
+
* With `revision`, only if it's the value's now (`0`: only if there's
|
|
83
|
+
* none); otherwise the call rejects with `conflict`, and nothing is
|
|
84
|
+
* written.
|
|
85
|
+
*/
|
|
86
|
+
write(items: readonly WriteItem[]): Promise<Written[]>;
|
|
87
|
+
/** Removes what each item holds, all of them or none: with `revision`, only if it's the value's now. */
|
|
88
|
+
remove(items: readonly RemoveItem[]): Promise<void>;
|
|
89
|
+
/**
|
|
90
|
+
* A scope's keys in order, by byte, each with its revision, time, and
|
|
91
|
+
* size: those that start with `prefix`, after the key `after`, 50 by
|
|
92
|
+
* default and 100 at most. `next` is the key to pass as `after` for the
|
|
93
|
+
* following page, or `null` at the end.
|
|
94
|
+
*/
|
|
95
|
+
list(scope: Scope, options?: ListOptions): Promise<Listed>;
|
|
96
|
+
}
|
|
97
|
+
export declare const MAX_KEYS = 32;
|
|
98
|
+
export declare const MAX_LIST = 100;
|
|
99
|
+
export declare function createValues(api: () => Api): Values;
|