wires
Live messages between your game's players, as your function reaches them: it opens a wire, and sends on one as the server. The package is the Arcadible Function SDK. A game is on a wire with the Arcadible SDK's wires, which says what a wire is. How to use both: Live Play.
import { wires } from "@arcadible/function-sdk";
interface Wires {
open(): Promise<{ id: string }>;
send(wire: { readonly id: string }, data: unknown): Promise<void>;
}
Members
| Member | Description |
|---|---|
open() | A new wire, with no one on it yet |
send(wire, data) | Sends a message to everyone on a wire, as the server |
A function on a wire
- A function sends, and never listens. It runs for a request and holds no connection, so there's nothing in it to listen with. What players need your function to know, they ask it, as any request.
- What it sends is marked as the server's: every game on the wire gets it with
server: true, which nothing a player sends can be. So a game can believe it. - Send only what your function has checked. Check who's asking (
players.primary(request)), that they may, and that the move is theirs to make, before you announce anything. Never pass a player's input along as the server's. - A wire is this game's, on this channel. A function sends only on its own game's wires.
- A wire is as private as its id. Keep one in
"server"values, which only your function reads, and hand it to a player only in the answer to a request you've checked. Never in"game"values, which every player can read and list. - Secrets don't go on a wire. Everyone on it gets every message. A dealt hand or a hidden word stays in your function and its
"server"values, and a player gets their own in the answer to their own request.
wires.open()
open(): Promise<{ id: string }>
A new wire, with no one on it yet.
const wire = await wires.open();
await values.write([{ scope: "server", key: `match/${match}`, value: { seats: [me.id], wire: wire.id }, revision: 0 }]);
return Response.json({ match, wire: wire.id });
- Resolves with the wire,
{ id }: its id is Arcadible's, opaque, and never expires. A wire with no one on it simply waits. - Players join it with what it gave, passed through your function's answer as it is, to the Arcadible SDK's
wires.join(wire). - Fails with
invalidoutside a function;unauthorizedover a minute after its request came;busywhen the game has opened too many in a minute; andunavailablewhen Arcadible couldn't be reached.
wires.send(wire, data)
send(wire: { readonly id: string }, data: unknown): Promise<void>
Sends a message to everyone on a wire, as the server.
const { wire } = record.value as { wire: string };
await wires.send({ id: wire }, { board: next, revision: written.revision });
wireis anything with a wire'sid: whatopen()gave, or a{ id }made from one your function kept. An id alone isn't taken.datais anything JSON, up to 1 KB, by JSON's own rules: what's sent is whatJSON.stringifymakes of it, and only what it can't make text of at all fails withinvalid. Send what changed, with the value's revision, and keep the state itself in values: a wire keeps nothing, and a player who was off it reads the value.- Resolves once the wire has passed it on, to whoever's on it. With no one on, it's passed to no one, and still resolves.
- It's never dropped for a wire's own rate, as players' messages are when a wire is too busy.
- Fails with
invalidfor a wire that isn't one, or isn't this game's on this channel, and fordatathat isn't JSON;too_largeover 1 KB, as the wire says;unauthorizedover a minute after its request came;busypast a function's sends in a minute; andunavailablewhen Arcadible couldn't be reached. - A send that fails with
unavailablemay still have been sent, since the wire may have passed it on before the answer was lost: carry the value's revision, so a game that hears it twice draws it once.
Limits
| Limit | Value | When you reach it | What to do |
|---|---|---|---|
| A message | 1 KB, as JSON | The send fails as too_large | Send what changed; keep the rest in values |
| A function's sends | 600 a minute, for a game on a channel | The send fails as busy | Send once for each change, to the whole wire |
| Wires a game opens | 600 a minute, for a game on a channel | open() fails as busy | Open a wire for a match, not for a message |
Every limit is also in Limits.
Under arc serve
arc serve runs wires itself, and nothing reaches Arcadible. A wire's id made in an earlier run still works, and neither rate is counted, so a call is never busy there.