arcadible.functions
Your game's function: the server code Arcadible runs for it, beside its build, named in arcadible.toml's [function] table. It's in the Arcadible SDK, the package and the hosted script alike. How to use one: Live Play.
interface Functions {
readonly url: string | null | undefined;
fetch(path: string, init?: RequestInit): Promise<Response>;
}
Members
| Member | Description |
|---|---|
functions.url | Where your game's function is, or null for no function |
functions.fetch(path, init) | A request to it, with the game's ticket |
functions.url
readonly url: string | null | undefined
Where your game's function is: your build's own origin, with /arcadible/function, such as https://5b1f6f0a.arcadible.io/arcadible/function, with no slash at the end.
undefinedbeforeinit()settles, then fixed for the run: the play page says it as your game starts, and it never changes while it runs.nullfor no function: a build with none, or a play page from before functions. Off Arcadible it'snulltoo, as every fact is;arcadible.buildsays whether there's a page.- A request of your own goes under it, with a ticket for it from
tickets.get(url), asfetchdoes for you.
functions.fetch(path, init)
fetch(path: string, init?: RequestInit): Promise<Response>
A request to your game's function, as the browser's fetch makes one: path from the function's root, such as "/score", and init as fetch takes it.
const res = await arcadible.functions.fetch("/move", {
method: "POST",
body: JSON.stringify({ match, move: cell }),
});
if (!res.ok) {
// … the function's own answer: its status and body are yours …
}
const board = await res.json();
- It carries the game's ticket, in
Authorization, which says the game, the build, and the player, so the function knows who's asking. The play page keeps the ticket while it's good, and gets another when it isn't. - A ticket Arcadible didn't take (a
401: it ran out on its way, or was refused) is sent once more, with a new one, and the call doesn't see it. A body that can't be read twice, a stream, isn't sent twice: it fails asunavailableinstead. - Waits for the run's facts, so a call made before they're known goes once the address is known.
- Resolves with the function's
Response, whatever its status: a404or a500your function answers is theResponse, never an error. - Rejects only with Arcadible's own refusal, a request that never reached your function, with its code and its
retryas Arcadible said them (Codes). A request your game aborts rejects with itsAbortError, asfetchdoes.
A request of your own
fetch is a request with a ticket. To make one yourself, with a WebSocket's address or a library's client, take the address from url, and a ticket for it from tickets.get(url):
const { url } = arcadible.functions;
const ticket = await arcadible.tickets.get(url);
const res = await fetch(`${url}/score`, {
headers: { Authorization: `Bearer ${ticket}` },
});
Arcadible's refusals then come as answers, not errors: each carries its code in the x-arcadible-refusal header, which a function's own answers never do, and whether to try again in x-arcadible-retry (yes, later, or no), with { code, retry } as JSON. A 401 is a ticket Arcadible didn't take. tickets.get gives the same ticket until it's about to run out, so a request of your own can't cure one: fetch sends once more with a new ticket by itself, so use it where you can.
Codes
A call that fails rejects with an ArcadibleError: act on its code, and on its retry for a code you don't handle.
| Code | Means | retry | What to do |
|---|---|---|---|
invalid | A path that doesn't start with /, or a body Arcadible couldn't read | no | Pass a path from the function's root |
no_function | On a play page, this build has no function | no | Play on without it |
too_large | A body over 1 MB | no | Send less, or keep it in values |
busy | Too many requests in a minute, or too many tickets | yes | Try again after a moment |
paused | The function is paused, by its owner or by Arcadible | later | Say so; it runs again when it's resumed |
limit_reached | The function's allowance is spent until its day or month renews | later | Say so, and play on without it |
retired | A newer build took this one's place over a day ago | no | Ask the player to reload |
function_failed | The function threw, or went past what it may use | later | Say so, as for a server's own error; fix the code |
unavailable | Offline, a ticket Arcadible didn't take twice, or Arcadible not answering | yes | Say so, and try again |
unsupported | Off Arcadible, or on a play page from before functions | no | Play on without it |
New codes may be added, each with its retry.
Under arc serve
arc serve runs your function on your own machine, as Arcadible would.
urlis the same path on the local game's origin, such ashttp://127.0.0.1:4100/arcadible/function, andfetchreaches it the same way, with a ticket ofarc serve's.- Its refusals are Arcadible's, with the same codes, but for what's never counted locally:
busy,paused,limit_reached, andretireddon't happen there. - A project with no
[function]answersno_function, as a build with none does on Arcadible.