@zaisma/game-server 1.10.0 → 1.12.0

package/bin/fast-lane.js

@@ -0,0 +1,212 @@
+// The fast lane to your own server: WebTransport (HTTP/3 over UDP) beside the WebSocket, for games that join
+// with transport: "webtransport". Latest-only sends go as datagrams, so a late one is dropped instead of holding
+// up what comes after it; everything else rides one stream, framed as the wire comment in src/room.ts says
+// (above ServerMessage). @fails-components/webtransport serves it: an optional peer dependency, which developers
+// who use the fast lane install themselves, loaded only when the runner is given one, so nobody else installs or loads it.
+import { EventEmitter } from "node:events";
+import { randomBytes } from "node:crypto";
+import { GameServerError } from "../src/internal.js";
+
+const FAST_LANE_PACKAGES = ["@fails-components/webtransport", "@fails-components/webtransport-transport-http3-quiche"];
+const TEXT_KIND_NUMBER = 0;
+const BYTES_KIND_NUMBER = 1;
+/** A stream frame's header: its payload's length (4 bytes, big-endian), then its kind. */
+const FRAME_HEADER_SIZE_BYTES = 5;
+/** A session's datagram size when it doesn't say: under the 1200 bytes every QUIC path carries, less QUIC's and HTTP/3's own. */
+const DEFAULT_MAXIMUM_DATAGRAM_SIZE_BYTES = 1100;
+/** A closing session waits this long for what it sent before it to go out, then closes anyway. */
+const CLOSE_WAIT_MS = 2000;
+const ROOM_PATH = /^\/v1\/rooms\//;
+
+const ignore = () => {};
+
+/** The error for a fast lane whose package isn't there: the runner exits with it, and startServer's fastLaneReady rejects with it. */
+function notInstalled() {
+  return new GameServerError("bad_option", "webtransportPort", `The fast lane needs ${FAST_LANE_PACKAGES.join(" and ")}, which aren't installed.`, `Install them (npm install ${FAST_LANE_PACKAGES.join(" ")}) for --webtransport-port, or leave the fast lane out.`);
+}
+
+/**
+ * Listen for WebTransport sessions on a UDP port, with the server's certificate (PEM). Each session at
+ * /v1/rooms/... whose client opens its stream within helloMs goes to onConnection(socket, path, origin),
+ * where socket has the surface the runner uses on a ws WebSocket. Answers { sockets, close() } once it listens.
+ */
+export async function startFastLane({ port, certificatePem, keyPem, helloMs, maximumFrameSizeBytes, onConnection }) {
+  let webtransport;
+  try {
+    webtransport = await import(FAST_LANE_PACKAGES[0]);
+    // The HTTP/3 binary comes in a package of its own, which the first loads only when a server starts.
+    await webtransport.quicheLoaded;
+  } catch {
+    throw notInstalled();
+  }
+  const listen = async (host) => {
+    const server = new webtransport.Http3Server({ port, host, secret: randomBytes(32).toString("hex"), cert: certificatePem, privKey: keyPem });
+    server.startServer();
+    await server.ready;
+    return server;
+  };
+  // IPv6 and IPv4 together where the machine has IPv6, else IPv4 alone.
+  const server = await listen("::").catch(() => listen("0.0.0.0"));
+  const sockets = new Set();
+  // Every room address goes to one stream of sessions, carrying its own path; the room checks it as for the WebSocket.
+  server.setRequestCallback(async ({ header }) => {
+    const path = String(header[":path"] ?? "");
+    if (!ROOM_PATH.test(path)) return { header, path, status: 404 };
+    return { header: { ...header, ":path": "/v1/rooms" }, path: "/v1/rooms", userData: { path }, status: 200 };
+  });
+  const sessions = server.sessionStream("/v1/rooms").getReader();
+  void (async () => {
+    for (;;) {
+      const { value: session, done } = await sessions.read();
+      if (done) return;
+      take(session).catch(ignore);
+    }
+  })();
+
+  async function take(session) {
+    await session.ready;
+    // The client opens its stream first, with its hello: a session that doesn't is closed.
+    const streams = session.incomingBidirectionalStreams.getReader();
+    let timer;
+    const stream = await Promise.race([streams.read().then((read) => read.value), new Promise((resolve) => (timer = setTimeout(resolve, helloMs)))]);
+    clearTimeout(timer);
+    if (!stream) return void session.close({ closeCode: 4001, reason: "no_hello" });
+    // One stream is all a player has; any other is turned away.
+    void (async () => {
+      for (;;) {
+        const { value: other, done } = await streams.read().catch(() => ({ done: true }));
+        if (done) return;
+        other.readable.cancel().catch(ignore);
+        other.writable.abort().catch(ignore);
+      }
+    })();
+    const socket = new FastLaneSocket(session, stream, maximumFrameSizeBytes);
+    sockets.add(socket);
+    socket.once("close", () => sockets.delete(socket));
+    onConnection(socket, session.userData?.path ?? "", typeof session.header?.origin === "string" ? session.header.origin : undefined);
+    socket.start();
+  }
+
+  return {
+    sockets,
+    close() {
+      try {
+        server.stopServer();
+      } catch {}
+    },
+  };
+}
+
+/**
+ * One player's fast-lane session, with what the runner uses on a ws WebSocket: send(message, { binary, delivery }),
+ * close(code, reason), terminate(), bufferedAmount, and "message" (payload, isBinary, isDatagram) and "close" (code) events.
+ */
+class FastLaneSocket extends EventEmitter {
+  constructor(session, stream, maximumFrameSizeBytes) {
+    super();
+    this.session = session;
+    this.stream = stream;
+    this.maximumFrameSizeBytes = maximumFrameSizeBytes;
+    this.writer = stream.writable.getWriter();
+    const datagrams = session.datagrams;
+    this.datagramWriter = (typeof datagrams.createWritable === "function" ? datagrams.createWritable() : datagrams.writable).getWriter();
+    /** Bytes handed to the stream and not yet taken by it, as a WebSocket's bufferedAmount. */
+    this.bufferedAmount = 0;
+    this.isOpen = true;
+    this.isClosed = false;
+  }
+
+  /** Read the stream and the datagrams, and hear the session close: after onConnection has its listeners on. */
+  start() {
+    this.session.closed.then((closeInfo) => this.end(closeInfo?.closeCode ?? 1005), () => this.end(1006));
+    this.readStream().catch(() => this.terminate());
+    this.readDatagrams().catch(ignore);
+  }
+
+  async readStream() {
+    const reader = this.stream.readable.getReader();
+    let buffered = Buffer.alloc(0);
+    for (;;) {
+      const { value: chunk, done } = await reader.read();
+      if (done) return;
+      buffered = buffered.length ? Buffer.concat([buffered, chunk]) : Buffer.from(chunk);
+      while (buffered.length >= FRAME_HEADER_SIZE_BYTES) {
+        const payloadSizeBytes = buffered.readUInt32BE(0);
+        const kindNumber = buffered[4];
+        // Over the limit, or of a kind the wire doesn't have: this connection ends, as a WebSocket's does.
+        if (payloadSizeBytes > this.maximumFrameSizeBytes || (kindNumber !== TEXT_KIND_NUMBER && kindNumber !== BYTES_KIND_NUMBER)) return this.terminate();
+        if (buffered.length < FRAME_HEADER_SIZE_BYTES + payloadSizeBytes) break;
+        const payload = Buffer.from(buffered.subarray(FRAME_HEADER_SIZE_BYTES, FRAME_HEADER_SIZE_BYTES + payloadSizeBytes));
+        buffered = buffered.subarray(FRAME_HEADER_SIZE_BYTES + payloadSizeBytes);
+        if (!this.isClosed) this.emit("message", payload, kindNumber === BYTES_KIND_NUMBER, false);
+      }
+    }
+  }
+
+  async readDatagrams() {
+    const reader = this.session.datagrams.readable.getReader();
+    for (;;) {
+      const { value: datagram, done } = await reader.read();
+      if (done || this.isClosed) return;
+      const kindNumber = datagram[0];
+      // A datagram that isn't one of the wire's is dropped, as a lost one would be.
+      if (datagram.length < 1 || (kindNumber !== TEXT_KIND_NUMBER && kindNumber !== BYTES_KIND_NUMBER)) continue;
+      this.emit("message", Buffer.from(datagram.subarray(1)), kindNumber === BYTES_KIND_NUMBER, true);
+    }
+  }
+
+  /** The most a datagram carries on this session. */
+  maximumDatagramSizeBytes() {
+    const maximumSizeBytes = this.session.datagrams.maxDatagramSize;
+    return typeof maximumSizeBytes === "number" && maximumSizeBytes > 0 ? maximumSizeBytes : DEFAULT_MAXIMUM_DATAGRAM_SIZE_BYTES;
+  }
+
+  /** A text, or a binary frame with { binary: true }. A latest-only one goes as a datagram when it fits; the rest on the stream, in order. */
+  send(message, options = {}) {
+    if (!this.isOpen) return;
+    const kindNumber = options.binary ? BYTES_KIND_NUMBER : TEXT_KIND_NUMBER;
+    const payload = typeof message === "string" ? Buffer.from(message, "utf8") : message;
+    if (options.delivery === "latest_only" && 1 + payload.length <= this.maximumDatagramSizeBytes()) {
+      const datagram = new Uint8Array(1 + payload.length);
+      datagram[0] = kindNumber;
+      datagram.set(payload, 1);
+      this.datagramWriter.write(datagram).catch(ignore);
+      return;
+    }
+    const frame = Buffer.alloc(FRAME_HEADER_SIZE_BYTES + payload.length);
+    frame.writeUInt32BE(payload.length, 0);
+    frame[4] = kindNumber;
+    frame.set(payload, FRAME_HEADER_SIZE_BYTES);
+    this.bufferedAmount += frame.length;
+    this.writer.write(frame).then(() => (this.bufferedAmount -= frame.length), ignore);
+  }
+
+  /** Close with a code and reason, after what was sent before goes out (as a WebSocket's close frame waits behind it). */
+  close(closeCode = 1000, reason = "") {
+    if (!this.isOpen) return;
+    this.isOpen = false;
+    let timer;
+    Promise.race([this.writer.close(), new Promise((resolve) => (timer = setTimeout(resolve, CLOSE_WAIT_MS)))])
+      .catch(ignore)
+      .finally(() => {
+        clearTimeout(timer);
+        this.end(closeCode, reason);
+      });
+  }
+
+  /** Close now, dropping what hasn't gone out. */
+  terminate() {
+    this.isOpen = false;
+    this.end(1006, "");
+  }
+
+  end(closeCode, reason = "") {
+    if (this.isClosed) return;
+    this.isOpen = false;
+    this.isClosed = true;
+    try {
+      this.session.close({ closeCode, reason });
+    } catch {}
+    this.emit("close", closeCode);
+  }
+}

package/bin/local-play-certificate.js

@@ -20,9 +20,12 @@ const explicit = (tagNumber, content) => der(0xa0 + tagNumber, content);
 const octets = (bytes) => der(0x04, bytes);
 const bits = (bytes) => der(0x03, Buffer.concat([Buffer.from([0]), bytes]));
 const utf8 = (text) => der(0x0c, Buffer.from(text, "utf8"));
-function integer(bytes) {
-  // A positive integer: a leading zero byte when the first bit is set.
-  return der(0x02, bytes[0] & 0x80 ? Buffer.concat([Buffer.from([0]), bytes]) : bytes);
+/** A positive integer, in the fewest bytes DER allows: leading zero bytes dropped, then one back when the first bit is set. */
+export function integer(bytes) {
+  let zeroByteCount = 0;
+  while (zeroByteCount < bytes.length - 1 && bytes[zeroByteCount] === 0) zeroByteCount += 1;
+  const minimal = bytes.subarray(zeroByteCount);
+  return der(0x02, minimal[0] & 0x80 ? Buffer.concat([Buffer.from([0]), minimal]) : minimal);
 }
 function objectId(dotted) {
   const [first, second, ...rest] = dotted.split(".").map(Number);
@@ -56,8 +59,10 @@ function addressBytes(address) {
 /**
  * A self-signed certificate for these names and addresses ("localhost", "192.168.1.20"), with its key, as PEM text:
  * { certificatePem, keyPem }. ECDSA P-256 and SHA-256, for server authentication, as phones ask of a server's certificate.
+ * The serial is 16 random bytes unless serialBytes is given (a test's way to try the serials that are hard to write).
+ * It lasts durationDays from now (and a day before, for clocks a little behind).
  */
-export function makeCertificate(names, nowMs = Date.now()) {
+export function makeCertificate(names, nowMs = Date.now(), serialBytes = randomBytes(16), durationDays = CERTIFICATE_DURATION_DAYS) {
   const { privateKey, publicKey } = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
   const name = sequence(set(sequence(objectId("2.5.4.3"), utf8("Zaisma test bench"))));
   const signatureAlgorithm = sequence(objectId("1.2.840.10045.4.3.2"));
@@ -69,14 +74,14 @@ export function makeCertificate(names, nowMs = Date.now()) {
     // Basic constraints: not a certificate authority.
     sequence(objectId("2.5.29.19"), octets(sequence())),
   ));
-  const serial = randomBytes(16);
+  const serial = Buffer.from(serialBytes);
   serial[0] &= 0x7f;
   const toBeSigned = sequence(
     explicit(0, integer(Buffer.from([2]))),
     integer(serial),
     signatureAlgorithm,
     name,
-    sequence(utcTime(nowMs - DAY_MS), utcTime(nowMs + CERTIFICATE_DURATION_DAYS * DAY_MS)),
+    sequence(utcTime(nowMs - DAY_MS), utcTime(nowMs + durationDays * DAY_MS)),
     name,
     publicKey.export({ type: "spki", format: "der" }),
     extensions,

package/bin/node-parts.js

@@ -289,7 +289,7 @@ export function secretsFromEnvironment() {
   return Object.freeze(Object.fromEntries(Object.entries(process.env).filter(([, environmentValue]) => typeof environmentValue === "string")));
 }
 
-const OPTION_NAMES = ["gameServer", "gameSlug", "port", "origins", "issuerUrl", "loadPassKeys", "loadReceiptKeys", "loadProfile", "database", "secrets", "webhookSigningSecret", "roomStateFile", "zaismaKey", "developerApiUrl"];
+const OPTION_NAMES = ["gameServer", "gameSlug", "port", "origins", "issuerUrl", "loadPassKeys", "loadReceiptKeys", "loadProfile", "database", "secrets", "webhookSigningSecret", "roomStateFile", "zaismaKey", "developerApiUrl", "webtransportPort", "certificatePath", "certificateKeyPath"];
 
 /**
  * Check what startServer was given: unknown options and options of the wrong kind are a GameServerError,
@@ -325,5 +325,13 @@ export function checkedStartServerOptions(given, issuerUrlDefault) {
   if (options.roomStateFile !== undefined && options.roomStateFile !== null && !isText(options.roomStateFile)) throw bad("roomStateFile", "a file path", "Give a file path as text, like \"zaisma-room-states.sqlite\", or null to keep no states.");
   if (options.zaismaKey !== undefined && !isText(options.zaismaKey)) throw bad("zaismaKey", "an API key", "Give an API key with purchase_access write for this game as text, or leave it out to use ZAISMA_KEY.");
   if (options.developerApiUrl !== undefined && (!isText(options.developerApiUrl) || !URL.canParse(options.developerApiUrl))) throw bad("developerApiUrl", "a URL", 'Give the address of Zaisma\'s developer API, like "https://zaisma.com/api/dev".');
+  // The fast lane (WebTransport): its UDP port and the certificate it holds itself, all three or none.
+  const fastLaneFields = ["webtransportPort", "certificatePath", "certificateKeyPath"];
+  const missingFastLaneFields = fastLaneFields.filter((field) => options[field] === undefined);
+  if (missingFastLaneFields.length && missingFastLaneFields.length < fastLaneFields.length) throw fail("bad_option", missingFastLaneFields[0], `The fast lane needs ${missingFastLaneFields.join(" and ")} too.`, `Give ${fastLaneFields.join(", ")} together, or none of them.`);
+  if (options.webtransportPort !== undefined && !(Number.isInteger(options.webtransportPort) && options.webtransportPort >= 0 && options.webtransportPort <= 65535)) throw bad("webtransportPort", "a port number", "Give the UDP port for the fast lane, a whole number from 0 to 65535 (0 picks a free one), like 443.");
+  for (const field of ["certificatePath", "certificateKeyPath"]) {
+    if (options[field] !== undefined && !isText(options[field])) throw bad(field, "a file path", `Give the path of a PEM file as text, like "${field === "certificatePath" ? "fullchain.pem" : "privkey.pem"}".`);
+  }
   return options;
 }

package/bin/node.d.ts

@@ -31,6 +31,16 @@ export interface StartServerOptions {
   zaismaKey?: string;
   /** Zaisma's developer API, which marks purchases handled. Default: https://zaisma.com/api/dev. */
   developerApiUrl?: string;
+  /**
+   * The fast lane: the UDP port where WebTransport sessions come, for games that join with transport: "webtransport".
+   * Give it with certificatePath and certificateKeyPath, or none of the three. It needs the optional packages
+   * @fails-components/webtransport and @fails-components/webtransport-transport-http3-quiche.
+   */
+  webtransportPort?: number;
+  /** The fast lane's certificate for the server's name, a PEM file (Let's Encrypt's fullchain.pem): WebTransport can't sit behind a TLS proxy, so the runner holds it. */
+  certificatePath?: string;
+  /** The fast lane's certificate key, a PEM file (Let's Encrypt's privkey.pem). */
+  certificateKeyPath?: string;
 }
 
 export interface RunningServer {
@@ -38,6 +48,8 @@ export interface RunningServer {
   close(): Promise<void>;
   /** The HTTP server, for its address (httpServer.address()). */
   httpServer: Server;
+  /** Settles once the fast lane listens (at once without one), or rejects with a GameServerError saying why it can't start. */
+  fastLaneReady: Promise<void>;
 }
 
 /**

package/bin/node.js

@@ -17,13 +17,16 @@
 // Its rooms' states are another, --room-state-file, so a restarted server brings its matches back (onRestored).
 // Its secrets (room.secrets, server.secrets) are this process's environment variables, and it calls
 // other servers with plain fetch(), with no list: on your own server nothing stands in between.
+// With --webtransport-port, --certificate-path and --certificate-key-path, it also serves the fast lane:
+// WebTransport on that UDP port, for games that join with transport: "webtransport" (bin/fast-lane.js).
 import { WebSocketServer } from "ws";
 import { createServer } from "node:http";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { resolve } from "node:path";
-import { realpathSync } from "node:fs";
+import { readFileSync, realpathSync } from "node:fs";
 import { BUSY_CLOSE_CODE, ENDED_CLOSE_CODE, ERROR_TEXT, NO_ANSWER_CLOSE_CODE, PASS_ISSUER_URL, PassError, ReceiptError, REMOVED_CLOSE_CODE, REQUEST_ERROR_HTTP_STATUS, REQUEST_LIMITS, ROOM_LIMITS, ROOM_TUNING, WEBHOOK_LIMITS, GameServerError, RoomCore, chatSettingsOf, checkChat, readChatMessage, restoreInfoOf, passesAreFriends, passesHaveBlockBetween, answerRequest, startSchedules, checkRoomData, clientIdle, defineGameServer, errorMessage, isRoomCode, readRequestBody, relay, requestError, runWebhook, tidyRoomInfo, verifyPass, verifyReceipt, verifyWebhook } from "../src/internal.js";
 import { OutsideCallError } from "../src/outside-calls.js";
+import { startFastLane } from "./fast-lane.js";
 import { checkedStartServerOptions, localDatabase, localRoomStates, passKeysFrom, profilesFrom, receiptKeysFrom, secretsFromEnvironment } from "./node-parts.js";
 
 // Code that names OutsideCallError, as Zaisma's sandbox lets it, moves unchanged: nothing here refuses a call, so instanceof is simply false.
@@ -69,16 +72,28 @@ const CATCH_UP_MS = 50;
  * rooms save their states, so a restart brings matches back; by default zaisma-room-states.sqlite, null to keep none),
  * zaismaKey (an API key with purchase_access write for this game, which onPurchase and onRefund need; by default
  * the ZAISMA_KEY environment variable) and developerApiUrl (Zaisma's developer API; by default https://zaisma.com/api/dev).
- * Answers { close(), httpServer }: close() saves every room first and finishes once the server has stopped.
+ * webtransportPort (a UDP port), certificatePath and certificateKeyPath (the server's certificate and its key,
+ * PEM files), all three or none, also serve the fast lane (WebTransport) beside the WebSocket.
+ * Answers { close(), httpServer, fastLaneReady }: close() saves every room first and finishes once the server
+ * has stopped; fastLaneReady settles once the fast lane listens (at once without one), or rejects saying why it can't.
  */
 export function startServer(options) {
-  const { gameServer, gameSlug, port: portNumber, origins, issuerUrl, loadPassKeys = passKeysFrom(`${issuerUrl}/.well-known/jwks.json`), loadReceiptKeys = receiptKeysFrom(`${issuerUrl}/.well-known/receipt-jwks.json`), loadProfile = profilesFrom(issuerUrl), database = localDatabase("zaisma-database.sqlite"), secrets = secretsFromEnvironment(), webhookSigningSecret = process.env.ZAISMA_WEBHOOK_SIGNING_SECRET, roomStateFile = "zaisma-room-states.sqlite", zaismaKey = process.env.ZAISMA_KEY, developerApiUrl = "https://zaisma.com/api/dev" } = checkedStartServerOptions(options, PASS_ISSUER_URL);
+  const { gameServer, gameSlug, port: portNumber, origins, issuerUrl, loadPassKeys = passKeysFrom(`${issuerUrl}/.well-known/jwks.json`), loadReceiptKeys = receiptKeysFrom(`${issuerUrl}/.well-known/receipt-jwks.json`), loadProfile = profilesFrom(issuerUrl), database = localDatabase("zaisma-database.sqlite"), secrets = secretsFromEnvironment(), webhookSigningSecret = process.env.ZAISMA_WEBHOOK_SIGNING_SECRET, roomStateFile = "zaisma-room-states.sqlite", zaismaKey = process.env.ZAISMA_KEY, developerApiUrl = "https://zaisma.com/api/dev", webtransportPort, certificatePath, certificateKeyPath } = checkedStartServerOptions(options, PASS_ISSUER_URL);
   const definition = defineGameServer(gameServer);
   // Exactly once needs Zaisma's record of what's handled: without a key, purchases would come twice, so it doesn't start.
   if ((definition.onPurchase || definition.onRefund) && !zaismaKey) {
     const hook = definition.onPurchase ? "onPurchase" : "onRefund";
     throw new GameServerError("bad_option", "zaismaKey", `${hook} needs zaismaKey, so each purchase is delivered once.`, "Give an API key with purchase_access write for this game as zaismaKey, or set ZAISMA_KEY.");
   }
+  // The fast lane's certificate, read before anything listens, so a wrong path says so at once.
+  const readPem = (path, field) => {
+    try {
+      return readFileSync(path, "utf8");
+    } catch (error) {
+      throw new GameServerError("bad_option", field, `${field} ${path} couldn't be read (${error.code ?? error.message}).`, "Give the path of a PEM file this process can read, like the fullchain.pem and privkey.pem Let's Encrypt makes.");
+    }
+  };
+  const fastLaneCertificate = webtransportPort === undefined ? null : { certificatePem: readPem(certificatePath, "certificatePath"), keyPem: readPem(certificateKeyPath, "certificateKeyPath") };
   const purchaseHandling = definition.onPurchase || definition.onRefund ? ownServerPurchaseHandling(gameSlug, zaismaKey, developerApiUrl) : undefined;
   const roomStates = roomStateFile === null ? null : localRoomStates(roomStateFile);
   const stateSaveIntervalMs = (definition.stateSaveIntervalSec ?? ROOM_LIMITS.defaultStateSaveIntervalSec) * 1000;
@@ -88,6 +103,9 @@ export function startServer(options) {
   const httpServer = createServer((request, response) => answerHttp(request, response));
   const wss = new WebSocketServer({ server: httpServer, maxPayload: MAXIMUM_SOCKET_MESSAGE_SIZE_BYTES });
   httpServer.listen(portNumber);
+  // The fast lane's players come in the same way as the WebSocket's (connected), on a socket with the same surface.
+  const fastLaneReady = fastLaneCertificate ? startFastLane({ port: webtransportPort, ...fastLaneCertificate, helloMs: HELLO_MS, maximumFrameSizeBytes: MAXIMUM_SOCKET_MESSAGE_SIZE_BYTES, onConnection: connected }) : Promise.resolve(null);
+  fastLaneReady.catch(() => {});
 
   /** room.verifyReceipt and server.verifyReceipt: a receipt for this game from Zaisma's receipt issuer, checked against its keys (fetched again once when its key is new). */
   async function receiptClaims(receipt) {
@@ -256,8 +274,9 @@ export function startServer(options) {
         secrets,
         verifyReceipt: receiptClaims,
         purchaseHandling,
-        send: (id, text) => sockets.get(id)?.send(text),
-        sendBytes: (id, frame) => sockets.get(id)?.send(frame, { binary: true }),
+        // delivery reaches a fast-lane socket, which sends latest-only ones as datagrams; ws doesn't read it.
+        send: (id, text, delivery) => sockets.get(id)?.send(text, { delivery }),
+        sendBytes: (id, frame, delivery) => sockets.get(id)?.send(frame, { binary: true, delivery }),
         isBackedUp: (id) => (sockets.get(id)?.bufferedAmount ?? 0) >= BACKED_UP_SIZE_BYTES,
         close: (id, code, reason) => {
           const ws = sockets.get(id);
@@ -485,8 +504,11 @@ export function startServer(options) {
   }, CATCH_UP_MS);
   catcher.unref?.();
 
-  wss.on("connection", (ws, request) => {
-    const address = /^\/v1\/rooms\/([a-z0-9-]{1,40})\/([A-Z0-9]{6})$/.exec(request.url ?? "");
+  wss.on("connection", (ws, request) => connected(ws, request.url ?? "", request.headers.origin));
+
+  /** A player's connection to /v1/rooms/<game>/<code>: a ws WebSocket, or a fast-lane socket with the same surface. */
+  function connected(ws, url, origin) {
+    const address = /^\/v1\/rooms\/([a-z0-9-]{1,40})\/([A-Z0-9]{6})$/.exec(url);
     const refuse = (code, message) => {
       ws.send(errorMessage(code, message));
       // Busy is a try-again (1013); every other refusal is final (4001).
@@ -494,14 +516,16 @@ export function startServer(options) {
     };
     // Refused before the hello too, with a code the SDK reads: a browser never sees why a socket closed otherwise.
     if (!address || address[1] !== gameSlug || !isRoomCode(address[2])) return refuse("game_unavailable");
-    if (origins.length && !origins.includes(request.headers.origin)) return refuse("bad_origin");
+    if (origins.length && !origins.includes(origin)) return refuse("bad_origin");
     if (typeof definition.setup !== "function") return refuse("game_unavailable", "This game server has no setup(), so it runs no rooms: it only answers requests, runs on schedules or takes webhooks.");
     const code = address[2];
     let playerId = null;
     const helloTimer = setTimeout(() => playerId || refuse("no_hello"), HELLO_MS);
     ws.zaismaSeenAtMs = Date.now();
 
-    const onMessage = async (received, isBinary) => {
+    const onMessage = async (received, isBinary, isDatagram) => {
+      // Datagrams carry only latest-only sends, from a player already in.
+      if (isDatagram && !playerId) return;
       const text = isBinary ? null : received.toString();
       ws.zaismaSeenAtMs = Date.now();
       // Games ping every 25 seconds or so, so a connection that stops answering can be dropped.
@@ -587,8 +611,8 @@ export function startServer(options) {
       pace(code, room);
     };
     // Whatever a message hits, it ends that connection or that message, never the process and the matches on it.
-    ws.on("message", (received, isBinary) => {
-      onMessage(received, isBinary).catch((error) => {
+    ws.on("message", (received, isBinary, isDatagram = false) => {
+      onMessage(received, isBinary, isDatagram).catch((error) => {
         console.error("Couldn't handle a message:", error);
         if (!playerId) refuse("busy");
       });
@@ -608,7 +632,7 @@ export function startServer(options) {
       pace(code, room);
       closeIfEmpty(code, room);
     });
-  });
+  }
 
   // Every room saves as the server stops, so a clean restart loses nothing.
   const close = () =>
@@ -625,10 +649,15 @@ export function startServer(options) {
       setTimeout(() => {
         for (const ws of wss.clients) ws.terminate();
       }, 2000).unref?.();
+      void fastLaneReady.then((fastLane) => {
+        if (!fastLane) return;
+        for (const socket of fastLane.sockets) socket.close(1012, "Server restarting");
+        setTimeout(() => fastLane.close(), 2000).unref?.();
+      }, () => {});
       wss.close(() => httpServer.close(() => done()));
       httpServer.closeAllConnections?.();
     });
-  return { close, httpServer };
+  return { close, httpServer, fastLaneReady: fastLaneReady.then(() => undefined) };
 }
 
 /** A saved state's key: its JSON, who was in the match and whether the room is kept, since any of them changing is worth a save. */
@@ -720,8 +749,10 @@ function binaryBytes(received) {
   return new Uint8Array(received.buffer.slice(received.byteOffset, received.byteOffset + received.byteLength));
 }
 
-const USAGE = "Usage: zaisma-game-server <server.ts | relay> --game <slug> [--port 8080] [--origin <url>,<url>] [--issuer-url https://rooms.zaisma.com] [--database-file zaisma-database.sqlite] [--room-state-file zaisma-room-states.sqlite]\n   or: zaisma-game-server play-locally [folder] [--port 4800] [--game <slug>] [--on-network] [--no-open] [--json]";
-const FLAGS = ["game", "port", "origin", "issuer-url", "database-file", "room-state-file"];
+const USAGE = "Usage: zaisma-game-server <server.ts | relay> --game <slug> [--port 8080] [--origin <url>,<url>] [--issuer-url https://rooms.zaisma.com] [--database-file zaisma-database.sqlite] [--room-state-file zaisma-room-states.sqlite] [--webtransport-port 443 --certificate-path fullchain.pem --certificate-key-path privkey.pem]\n   or: zaisma-game-server play-locally [folder] [--port 4800] [--game <slug>] [--on-network] [--no-open] [--json]";
+const FLAGS = ["game", "port", "origin", "issuer-url", "database-file", "room-state-file", "webtransport-port", "certificate-path", "certificate-key-path"];
+/** The fast lane's flags: all three or none. */
+const FAST_LANE_FLAGS = ["webtransport-port", "certificate-path", "certificate-key-path"];
 
 /** The command line's flags by name, or null for one this runner doesn't take (or one missing its value). */
 function flagsFrom(argumentList) {
@@ -807,6 +838,11 @@ async function runCommand() {
     console.log(USAGE);
     process.exit(1);
   }
+  const missingFastLaneFlags = FAST_LANE_FLAGS.filter((name) => flags[name] === undefined);
+  if (missingFastLaneFlags.length && missingFastLaneFlags.length < FAST_LANE_FLAGS.length) {
+    console.log(`The fast lane needs ${missingFastLaneFlags.map((name) => `--${name}`).join(" and ")} too: give all three of ${FAST_LANE_FLAGS.map((name) => `--${name}`).join(", ")}, or none.\n${USAGE}`);
+    process.exit(1);
+  }
   const gameServer = file === "relay" ? relay : (await import(pathToFileURL(resolve(file)).href)).default;
   const portNumber = Number(flags.port ?? "8080");
   let running;
@@ -819,6 +855,7 @@ async function runCommand() {
       ...(flags["issuer-url"] !== undefined ? { issuerUrl: flags["issuer-url"] } : {}),
       ...(flags["database-file"] !== undefined ? { database: localDatabase(resolve(flags["database-file"])) } : {}),
       roomStateFile: resolve(flags["room-state-file"] ?? "zaisma-room-states.sqlite"),
+      ...(flags["webtransport-port"] !== undefined ? { webtransportPort: Number(flags["webtransport-port"]), certificatePath: resolve(flags["certificate-path"]), certificateKeyPath: resolve(flags["certificate-key-path"]) } : {}),
     });
   } catch (error) {
     // A bad flag, or an option the runner refuses: said plainly, before anything listens.
@@ -829,6 +866,13 @@ async function runCommand() {
   for (const signal of ["SIGTERM", "SIGINT"]) process.once(signal, () => running.close().then(() => process.exit(0)));
   const scheduleNames = (gameServer.schedules ?? []).map((schedule) => `${schedule.name} (${schedule.cron})`);
   const webhookNote = ` Webhooks come to POST /v1/webhooks${process.env.ZAISMA_WEBHOOK_SIGNING_SECRET ? "" : " once ZAISMA_WEBHOOK_SIGNING_SECRET is set"}${typeof gameServer.onWebhook === "function" ? "" : " (account_deleted only: it erases the player from the database)"}.`;
+  running.fastLaneReady.then(
+    () => flags["webtransport-port"] !== undefined && console.log(`Fast lane (WebTransport) on UDP port ${flags["webtransport-port"]}, for games that join with transport: "webtransport".`),
+    (error) => {
+      console.error(error instanceof GameServerError ? error.message : error);
+      process.exit(1);
+    },
+  );
   console.log(`Game server for "${flags.game}" on port ${portNumber}. Players connect to /v1/rooms/${flags.game}/<code>; requests come to POST /v1/requests/${flags.game}.${scheduleNames.length ? ` Schedules, in UTC: ${scheduleNames.join(", ")}.` : ""}${webhookNote}`);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaisma/game-server",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "description": "Run your Zaisma game server: the same rooms on Zaisma or on your own server.",
   "license": "MIT",
   "homepage": "https://zaisma.com",
@@ -38,5 +38,17 @@
   },
   "dependencies": {
     "ws": "8.21.3"
+  },
+  "peerDependencies": {
+    "@fails-components/webtransport": "1.6.11",
+    "@fails-components/webtransport-transport-http3-quiche": "1.6.11"
+  },
+  "peerDependenciesMeta": {
+    "@fails-components/webtransport": {
+      "optional": true
+    },
+    "@fails-components/webtransport-transport-http3-quiche": {
+      "optional": true
+    }
   }
 }

package/sdk/zaisma.d.ts

@@ -140,7 +140,7 @@ declare namespace Zaisma {
    * refused (the game server's canJoin said no; the message is its refusalMessage), hosting_paused (the
    * game's hosting is paused this month: its free allowance or its developer's budget or credit is used). No player pass: unchecked, or account_needed for a
    * guest when the game needs accounts (see Zaisma.player.getPass()). The
-   * call is set up wrong: unknown_option, bad_room_code, bad_server_url, not_on_zaisma (the game isn't hosted
+   * call is set up wrong: unknown_option, bad_room_code, bad_server_url, bad_transport, not_on_zaisma (the game isn't hosted
    * on Zaisma, serverUrl or not; serverUrl points a game hosted on Zaisma at your own server). Or connection_closed (the connection closed first, say the game left or the player
    * joined from another tab) and request_failed (Zaisma didn't answer). {@link ErrorCode} has them all.
    *
@@ -566,6 +566,32 @@ declare namespace Zaisma {
    */
   const versions: Versions;
 
+  /**
+   * Whether Zaisma's page covers the game right now, so a game can pause or hold the player's input while it does.
+   * coveredBy is "sheet" while one of Zaisma's sheets is open over the game (buying, Players, Report: the player is
+   * busy with it), "card" while one of its cards is over the game's corner (Still there?, Keep your progress; the
+   * game stays in view and playable), and null otherwise. Always null outside Zaisma's page (your own site, a
+   * local test). Listen for "coveredBy" to hear each change.
+   * @example
+   * Zaisma.page.on("coveredBy", (coveredBy) => {
+   *   if (coveredBy === "sheet") pauseGame();
+   *   else resumeGame();
+   * });
+   */
+  const page: Page;
+
+  /** Whether Zaisma's page covers the game ({@link page}). */
+  interface Page {
+    /** "sheet", "card" or null: what of Zaisma's is over the game now. Read-only. */
+    readonly coveredBy: CoveredBy;
+    /** Listen for "coveredBy": called with the new value each time it changes. A wrong name fails with error.code "unknown_event". */
+    on(event: "coveredBy", listener: (coveredBy: CoveredBy) => void): Page;
+    off(event: "coveredBy", listener: (coveredBy: CoveredBy) => void): Page;
+  }
+
+  /** What of Zaisma's covers the game ({@link page}): one of its sheets, one of its cards, or nothing. */
+  type CoveredBy = "sheet" | "card" | null;
+
   /** A version published "now" ({@link versions}). */
   interface Versions {
     /** Listen for "update". A wrong name fails with error.code "unknown_event". */
@@ -797,6 +823,18 @@ declare namespace Zaisma {
      * is allowed to connect to it.
      */
     serverUrl?: string;
+    /**
+     * How to reach a room on your own server (serverUrl, wss:// or https://): "websocket" (the default), or
+     * "webtransport", the fast lane: WebTransport, where sends with delivery "latest_only" go as datagrams, so a
+     * late one is dropped instead of holding up what comes after it, as PC shooters play. Your server has to
+     * serve it (the Node runner's --webtransport-port). Where WebTransport isn't there or doesn't connect in
+     * 3 seconds (a network that blocks UDP), the room uses the WebSocket by itself; {@link Room.transport} says
+     * which. Zaisma rooms use the WebSocket either way. Anything else is refused with error.code "bad_transport".
+     *
+     * @example
+     * const room = await Zaisma.joinRoom({ serverUrl: "wss://play.example.com", transport: "webtransport" });
+     */
+    transport?: "websocket" | "webtransport";
     /**
      * true: a new room that shows in room lists, for others to find. By default false: a room only its
      * code and link reach, like a private match ({@link Rooms.quickJoin} lists its new rooms unless given
@@ -852,10 +890,10 @@ declare namespace Zaisma {
   type Region = "AF" | "AN" | "AS" | "EU" | "NA" | "OC" | "SA";
 
   /**
-   * What {@link Rooms.quickJoin} takes: joinRoom's options but roomCode, isSpectator and serverUrl (it
-   * finds Zaisma rooms), and region.
+   * What {@link Rooms.quickJoin} takes: joinRoom's options but roomCode, isSpectator, serverUrl and transport
+   * (it finds Zaisma rooms), and region.
    */
-  interface QuickJoinOptions extends Omit<JoinOptions, "roomCode" | "isSpectator" | "serverUrl"> {
+  interface QuickJoinOptions extends Omit<JoinOptions, "roomCode" | "isSpectator" | "serverUrl" | "transport"> {
     /** Look for a room in this region only, like "EU", as in {@link RoomList.regions}. */
     region?: Region;
     /** Look for a room with these labels, like { Mode: "Classic" }; a new room gets them. */
@@ -870,8 +908,8 @@ declare namespace Zaisma {
     labels?: Record<string, string>;
   }
 
-  /** What {@link Move.join} takes: joinRoom's options but roomCode and serverUrl, which are the move's own, and isSpectator (moves are for players). */
-  interface MoveJoinOptions extends Omit<JoinOptions, "roomCode" | "serverUrl" | "isSpectator"> {}
+  /** What {@link Move.join} takes: joinRoom's options but roomCode, serverUrl and transport, which are the move's own, and isSpectator (moves are for players). */
+  interface MoveJoinOptions extends Omit<JoinOptions, "roomCode" | "serverUrl" | "transport" | "isSpectator"> {}
 
   /** What {@link Room.kick} takes. */
   interface KickOptions {
@@ -960,7 +998,8 @@ declare namespace Zaisma {
     /**
      * "reliable" (the default) reaches the game server in order. "latest_only" may be dropped: while
      * this player's connection is backed up, a newer send with the same latestKey replaces it, and the
-     * newest goes once it catches up. For input sent every frame, like where the player aims. Anything
+     * newest goes once it catches up. For input sent every frame, like where the player aims. On the fast
+     * lane to your own server ({@link JoinOptions.transport}), it goes as a datagram when it fits one. Anything
      * else throws error.code "bad_send_option".
      */
     delivery?: "reliable" | "latest_only";
@@ -1005,6 +1044,11 @@ declare namespace Zaisma {
     readonly spectatorCount: number;
     /** Where the socket stands; the "connectionStatus" event says when it changes. Away is awayReason, not this. */
     readonly connectionStatus: ConnectionStatus;
+    /**
+     * What this connection uses now: "webtransport" on the fast lane to your own server
+     * ({@link JoinOptions.transport}), else "websocket", including when the fast lane didn't connect.
+     */
+    readonly transport: "websocket" | "webtransport";
     /**
      * Why this player is out of the match: "idle" (no input until the "Still there?" ran out) or "hidden"
      * (the game hidden too long), from the "away" event until "back"; null while they play.
@@ -1662,6 +1706,7 @@ declare namespace Zaisma {
    * - bad_delay: {@link Room.smoothedState}'s delayMs isn't from 0 to 1000.
    * - bad_region: a region that isn't a continent code ({@link Region}).
    * - bad_idle_timeout: an idleTimeoutSec that isn't from 30 to 86400.
+   * - bad_transport: a transport that isn't "websocket" or "webtransport".
    * - request_failed: Zaisma didn't answer (no connection, or a problem on Zaisma's side); try again.
    * - no_game: {@link Items.buy} named a game that isn't open to play here.
    * - chat_stopped, chat_not_allowed, chat_empty, chat_too_long, chat_too_fast, chat_not_here: {@link Room.chat} didn't send ({@link ChatErrorCode}).
@@ -1700,6 +1745,7 @@ declare namespace Zaisma {
     | "bad_delay"
     | "bad_region"
     | "bad_idle_timeout"
+    | "bad_transport"
     | "bad_server_url"
     | "unlisted_server"
     | "unknown_link"