Skip to main content

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​

MemberDescription
functions.urlWhere 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.

  • undefined before init() settles, then fixed for the run: the play page says it as your game starts, and it never changes while it runs.
  • null for no function: a build with none, or a play page from before functions. Off Arcadible it's null too, as every fact is; arcadible.build says whether there's a page.
  • A request of your own goes under it, with a ticket for it from tickets.get(url), as fetch does 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 as unavailable instead.
  • 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: a 404 or a 500 your function answers is the Response, never an error.
  • Rejects only with Arcadible's own refusal, a request that never reached your function, with its code and its retry as Arcadible said them (Codes). A request your game aborts rejects with its AbortError, as fetch does.

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.

CodeMeansretryWhat to do
invalidA path that doesn't start with /, or a body Arcadible couldn't readnoPass a path from the function's root
no_functionOn a play page, this build has no functionnoPlay on without it
too_largeA body over 1 MBnoSend less, or keep it in values
busyToo many requests in a minute, or too many ticketsyesTry again after a moment
pausedThe function is paused, by its owner or by ArcadiblelaterSay so; it runs again when it's resumed
limit_reachedThe function's allowance is spent until its day or month renewslaterSay so, and play on without it
retiredA newer build took this one's place over a day agonoAsk the player to reload
function_failedThe function threw, or went past what it may uselaterSay so, as for a server's own error; fix the code
unavailableOffline, a ticket Arcadible didn't take twice, or Arcadible not answeringyesSay so, and try again
unsupportedOff Arcadible, or on a play page from before functionsnoPlay 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.

  • url is the same path on the local game's origin, such as http://127.0.0.1:4100/arcadible/function, and fetch reaches it the same way, with a ticket of arc serve's.
  • Its refusals are Arcadible's, with the same codes, but for what's never counted locally: busy, paused, limit_reached, and retired don't happen there.
  • A project with no [function] answers no_function, as a build with none does on Arcadible.