Skip to main content

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​

MemberDescription
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 invalid outside a function; unauthorized over a minute after its request came; busy when the game has opened too many in a minute; and unavailable when 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 });
  • wire is anything with a wire's id: what open() gave, or a { id } made from one your function kept. An id alone isn't taken.
  • data is anything JSON, up to 1 KB, by JSON's own rules: what's sent is what JSON.stringify makes of it, and only what it can't make text of at all fails with invalid. 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 invalid for a wire that isn't one, or isn't this game's on this channel, and for data that isn't JSON; too_large over 1 KB, as the wire says; unauthorized over a minute after its request came; busy past a function's sends in a minute; and unavailable when Arcadible couldn't be reached.
  • A send that fails with unavailable may 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​

LimitValueWhen you reach itWhat to do
A message1 KB, as JSONThe send fails as too_largeSend what changed; keep the rest in values
A function's sends600 a minute, for a game on a channelThe send fails as busySend once for each change, to the whole wire
Wires a game opens600 a minute, for a game on a channelopen() fails as busyOpen 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.