@zaisma/game-server 1.4.0 → 1.5.0

package/bin/node.js

@@ -691,7 +691,7 @@ 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]";
+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"];
 
 /** The command line's flags by name, or null for one this runner doesn't take (or one missing its value). */
@@ -705,8 +705,73 @@ function flagsFrom(argumentList) {
   return flags;
 }
 
+/** play-locally's flags: whether each takes a value. */
+const PLAY_LOCALLY_FLAGS = { port: true, game: true, "on-network": false, "no-open": false, json: false };
+
+/** play-locally [folder] and its flags, or null with the refusal printed: said plainly, before anything listens. */
+function playLocallyArguments(argumentList) {
+  const refuse = (message, fix) => {
+    console.error(`${message} ${fix} (bad_option)`);
+    return null;
+  };
+  const flags = {};
+  let folder = null;
+  for (let i = 0; i < argumentList.length; i++) {
+    const given = argumentList[i];
+    if (!given.startsWith("--")) {
+      if (folder !== null) return refuse(`play-locally takes one folder, and got ${folder} and ${given}.`, "Give the folder of your game, the one with index.html at the top.");
+      folder = given;
+      continue;
+    }
+    const name = given.slice(2);
+    if (!(name in PLAY_LOCALLY_FLAGS)) return refuse(`${given} isn't a play-locally flag.`, `play-locally takes: ${Object.keys(PLAY_LOCALLY_FLAGS).map((each) => `--${each}`).join(", ")}.`);
+    if (!PLAY_LOCALLY_FLAGS[name]) {
+      flags[name] = true;
+      continue;
+    }
+    const flagValue = argumentList[++i];
+    if (flagValue === undefined || flagValue.startsWith("--")) return refuse(`${given} needs a value.`, name === "port" ? "Give the first of four ports, like --port 4800." : "Give your game's slug, like --game sky-hopper.");
+    flags[name] = flagValue;
+  }
+  const portNumber = flags.port === undefined ? 4800 : Number(flags.port);
+  if (!Number.isInteger(portNumber) || portNumber < 1 || portNumber > 65532) return refuse("--port isn't a whole number from 1 to 65532.", "Give the first of four ports, like --port 4800: the bench, the game's site, the stand-in rooms and your game server take it and the next three.");
+  if (flags.game !== undefined && !/^[a-z0-9-]{1,40}$/.test(flags.game)) return refuse("--game isn't a game's slug.", "A slug is 1 to 40 lowercase letters, digits or hyphens, like sky-hopper.");
+  return { folder: folder ?? ".", portNumber, gameSlug: flags.game ?? null, isOnNetwork: flags["on-network"] === true, isOpening: flags["no-open"] !== true, isJson: flags.json === true };
+}
+
+/** zaisma-game-server play-locally: your game and its game server on this computer, with a test bench (bin/local-play.js). */
+async function playLocally(argumentList) {
+  const given = playLocallyArguments(argumentList);
+  if (!given) process.exit(1);
+  const { startLocalPlay, terminalQr } = await import("./local-play.js");
+  const say = given.isJson ? (line) => console.error(line) : (line) => console.log(line);
+  let running;
+  try {
+    running = await startLocalPlay({ gameFolder: given.folder, port: given.portNumber, isOnNetwork: given.isOnNetwork, gameSlug: given.gameSlug, log: say });
+  } catch (error) {
+    console.error(error instanceof GameServerError ? `${error.message} ${error.fix ?? ""} (${error.code})` : error);
+    process.exit(1);
+  }
+  for (const signal of ["SIGTERM", "SIGINT"]) process.once(signal, () => running.close().then(() => process.exit(0)));
+  if (given.isJson) console.log(JSON.stringify({ bench_url: running.benchUrl, game_site_url: running.gameSiteUrl, rooms_url: running.roomsUrl, network_url: running.networkUrl }));
+  say(`Playing ${given.gameSlug ?? "your game"} on this computer. The test bench is at ${running.benchUrl}`);
+  say("Each player plays on Zaisma's own game page. Add a player in the dev bar to play with yourself in another tab. A change to a game file reloads the game, and a change to the game server starts it again with its rooms kept.");
+  say("Nothing here talks to Zaisma. What the bench keeps is in .zaisma-local/ in the game's folder: add it to your .gitignore. Press Ctrl-C to stop.");
+  if (running.networkUrl) {
+    say(`On a phone on the same Wi-Fi: ${running.networkUrl}`);
+    say(terminalQr(running.networkUrl));
+    say("Your phone will say the connection isn't private, because the bench signs its own certificate. Continue to the site.");
+  }
+  if (given.isOpening) {
+    const { spawn } = await import("node:child_process");
+    const opener = process.platform === "darwin" ? ["open", [running.benchUrl]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", running.benchUrl]] : ["xdg-open", [running.benchUrl]];
+    spawn(opener[0], opener[1], { stdio: "ignore", detached: true }).on("error", () => {}).unref();
+  }
+}
+
 // Run as a command. An npm bin is a symlink to this file, so both sides are resolved before they're compared.
 async function runCommand() {
+  if (process.argv[2] === "play-locally") return playLocally(process.argv.slice(3));
   const file = process.argv[2];
   const flags = file ? flagsFrom(process.argv.slice(3)) : null;
   if (!file || file.startsWith("--") || !flags?.game) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaisma/game-server",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Run your Zaisma game server: the same rooms on Zaisma or on your own server.",
   "license": "MIT",
   "homepage": "https://zaisma.com",

package/sdk/picture.js

@@ -0,0 +1,97 @@
+/*
+ * Report pictures. Zaisma adds this to every game page. When a player opens Report on the Zaisma
+ * game page, the page asks for one picture of the game as it is right now: the game's biggest
+ * canvas, copied straight after the game draws a frame (so WebGL games work too), shrunk and
+ * handed back (unless it's all one color). Nothing is taken unless the Zaisma page asks, and nothing leaves the player's
+ * browser unless they send the report with the picture. Games that don't draw on a canvas give
+ * no picture. Plain JavaScript, no dependencies, MIT licensed.
+ */
+(function () {
+  "use strict";
+  var site = typeof __ZAISMA_PICTURE__ === "object" && __ZAISMA_PICTURE__ ? __ZAISMA_PICTURE__.site : "";
+  if (!site || window.parent === window) return;
+  var MAXIMUM_SIDE_PIXEL_COUNT = 1280;
+  var waiting = [];
+
+  function biggestCanvas() {
+    var best = null;
+    var bestPixelCount = 0;
+    var all = document.getElementsByTagName("canvas");
+    for (var i = 0; i < all.length; i++) {
+      var pixelCount = all[i].width * all[i].height;
+      if (pixelCount > bestPixelCount && all[i].getClientRects().length) {
+        best = all[i];
+        bestPixelCount = pixelCount;
+      }
+    }
+    return best;
+  }
+
+  // A canvas that's all one color (a title screen drawn in HTML over it, a game still loading) shows nothing worth sending.
+  function blank(canvas) {
+    var small = document.createElement("canvas");
+    small.width = 32;
+    small.height = 18;
+    var canvasContext = small.getContext("2d");
+    canvasContext.drawImage(canvas, 0, 0, 32, 18);
+    var pixelBytes = canvasContext.getImageData(0, 0, 32, 18).data;
+    var darkestByte = 255, lightestByte = 0;
+    for (var i = 0; i < pixelBytes.length; i += 4) {
+      var lightnessByte = (pixelBytes[i] * 3 + pixelBytes[i + 1] * 6 + pixelBytes[i + 2]) / 10;
+      if (lightnessByte < darkestByte) darkestByte = lightnessByte;
+      if (lightnessByte > lightestByte) lightestByte = lightnessByte;
+    }
+    return lightestByte - darkestByte < 10;
+  }
+
+  function picture() {
+    try {
+      var from = biggestCanvas();
+      if (!from) return null;
+      var longestSidePixelCount = Math.max(from.width, from.height);
+      var shrunkSidePixelCount = Math.min(longestSidePixelCount, MAXIMUM_SIDE_PIXEL_COUNT);
+      var to = document.createElement("canvas");
+      to.width = Math.max(1, Math.round((from.width * shrunkSidePixelCount) / longestSidePixelCount));
+      to.height = Math.max(1, Math.round((from.height * shrunkSidePixelCount) / longestSidePixelCount));
+      var canvasContext = to.getContext("2d");
+      canvasContext.fillStyle = "#000";
+      canvasContext.fillRect(0, 0, to.width, to.height);
+      canvasContext.drawImage(from, 0, 0, to.width, to.height);
+      return blank(to) ? null : to.toDataURL("image/jpeg", 0.8);
+    } catch (error) {
+      return null; // A canvas showing pictures from another site can't be copied.
+    }
+  }
+
+  function answer() {
+    if (!waiting.length) return;
+    var pictureUrl = picture();
+    waiting.splice(0).forEach(function (id) {
+      window.parent.postMessage({ type: "zaisma:picture", id: id, picture: pictureUrl }, site);
+    });
+  }
+
+  // Copy inside the game's own frame callback: after it has drawn, before the browser clears a WebGL canvas.
+  var nativeFrame = window.requestAnimationFrame;
+  if (nativeFrame) {
+    window.requestAnimationFrame = function (callback) {
+      return nativeFrame.call(window, function (frameTimeMs) {
+        try {
+          callback(frameTimeMs);
+        } finally {
+          answer();
+        }
+      });
+    };
+  }
+
+  window.addEventListener("message", function (event) {
+    if (event.origin !== site || event.source !== window.parent || !event.data || event.data.type !== "zaisma:picture-request") return;
+    var id = String(event.data.id);
+    waiting.push(id);
+    // A game that isn't drawing right now (paused, between turns) is copied straight away.
+    setTimeout(function () {
+      if (waiting.indexOf(id) !== -1) answer();
+    }, 200);
+  });
+})();

package/sdk/relay.js

@@ -0,0 +1,269 @@
+/*
+ * Zaisma's relay. Zaisma adds this first to every game page. A connection between two players'
+ * browsers (WebRTC, what PeerJS and Godot use) would show each the other's internet address, so
+ * every one goes through Cloudflare's relay (TURN) instead: players only ever see Cloudflare's
+ * address, and connections also get through school and office networks where direct ones fail.
+ * The game's own WebRTC code works unchanged: this wraps RTCPeerConnection so each connection uses
+ * only the relay, with Zaisma's relay servers, whatever servers the game asks for (the game's own
+ * relay stays when it's one of the game's listed servers). Plain JavaScript, no dependencies, MIT licensed.
+ */
+(function (window) {
+  "use strict";
+  var config = typeof __ZAISMA_RELAY__ === "object" && __ZAISMA_RELAY__ ? __ZAISMA_RELAY__ : {};
+  var NAMES = ["RTCPeerConnection", "webkitRTCPeerConnection"];
+  var ownRelayHosts = (config.ownRelayHosts || []).map(function (host) { return String(host).toLowerCase(); });
+  /** Ask again this long after the relay couldn't be had, not on every connection. */
+  var RETRY_AFTER_MS = 60 * 1000;
+  /** Credentials with less left than this are fetched anew. */
+  var RENEW_BEFORE_MS = 10 * 60 * 1000;
+  var storageKey = "zaisma:relay:" + config.game;
+
+  /** What this window wrapped: our getters (so nothing is wrapped twice), and each original's wrapper. */
+  var getters = new WeakSet();
+  var wrappers = new WeakMap();
+  /** The configuration the game asked each connection for, and the relay servers it was given. */
+  var askedConfigurations = new WeakMap();
+  var givenServers = new WeakMap();
+
+  // ---- Zaisma's relay servers for this tab ----
+
+  var kept = null; // { iceServers, expiresAtMs }
+  var fetching = null;
+  var failedAtMs = 0;
+  var hasWarned = false;
+
+  function warn(message) {
+    if (hasWarned) return;
+    hasWarned = true;
+    window.console.warn("Zaisma: connections between players go only through Zaisma's relay, so they don't connect right now. " + message);
+  }
+
+  function isFresh(credentials) {
+    return Boolean(credentials && credentials.iceServers && credentials.expiresAtMs - Date.now() > RENEW_BEFORE_MS);
+  }
+
+  function storedCredentials() {
+    try {
+      var stored = JSON.parse(window.sessionStorage.getItem(storageKey) || "null");
+      return isFresh(stored) ? stored : null;
+    } catch (error) {
+      return null; // storage off: fetch new ones
+    }
+  }
+
+  /** The game page's key to player passes, which also gives relay credentials (the SDK asks for it the same way). */
+  function roomKey() {
+    return new Promise(function (resolve, reject) {
+      if (!config.site || !config.rooms || window.parent === window) return reject(new Error("Connections between players work when the game is played on Zaisma."));
+      var timerNumber = window.setTimeout(function () {
+        window.removeEventListener("message", onMessage);
+        reject(new Error("Zaisma couldn't check this browser. Reload the game to try again."));
+      }, 30000);
+      function onMessage(event) {
+        if (event.origin !== config.site || event.source !== window.parent || !event.data || event.data.type !== "zaisma:room-key") return;
+        window.removeEventListener("message", onMessage);
+        window.clearTimeout(timerNumber);
+        if (typeof event.data.key === "string") resolve(event.data.key);
+        else reject(new Error("Zaisma couldn't check this browser, or this game doesn't use online play. Reload the game to try again."));
+      }
+      window.addEventListener("message", onMessage);
+      window.parent.postMessage({ type: "zaisma:room-key" }, config.site);
+    });
+  }
+
+  /** Zaisma's relay servers, as iceServers: [] when there are none to be had (connections then don't connect, rather than go direct). */
+  function relayServers() {
+    if (isFresh(kept)) return Promise.resolve(kept.iceServers);
+    var stored = storedCredentials();
+    if (stored) {
+      kept = stored;
+      return Promise.resolve(kept.iceServers);
+    }
+    if (Date.now() - failedAtMs < RETRY_AFTER_MS) return Promise.resolve([]);
+    if (!fetching) {
+      fetching = roomKey()
+        .then(function (key) {
+          // text/plain keeps this a simple request, so the browser needs no preflight.
+          return window.fetch(config.rooms + "/v1/relay", { method: "POST", headers: { "Content-Type": "text/plain" }, body: JSON.stringify({ gameSlug: config.game, roomKey: key }) });
+        })
+        .then(function (response) {
+          return response.json().then(function (answer) {
+            if (!response.ok || !answer || !Array.isArray(answer.iceServers)) throw new Error((answer && answer.error && answer.error.message) || "Zaisma's relay didn't answer.");
+            return answer;
+          });
+        })
+        .then(
+          function (answer) {
+            fetching = null;
+            kept = { iceServers: answer.iceServers, expiresAtMs: Date.parse(answer.expiresAt) };
+            try { window.sessionStorage.setItem(storageKey, JSON.stringify(kept)); } catch (error) { /* fine */ }
+            return kept.iceServers;
+          },
+          function (error) {
+            fetching = null;
+            failedAtMs = Date.now();
+            warn(error && error.message ? error.message : "");
+            return [];
+          },
+        );
+    }
+    return fetching;
+  }
+
+  // ---- What each connection is given ----
+
+  /** The game's own relay servers among its listed servers: turn: and turns: addresses on those hosts, nothing else. */
+  function ownRelays(iceServers) {
+    var out = [];
+    (Array.isArray(iceServers) ? iceServers : []).forEach(function (server) {
+      if (!server || typeof server !== "object") return;
+      var urls = [].concat(server.urls !== undefined ? server.urls : server.url !== undefined ? server.url : []).filter(function (address) {
+        var host = /^turns?:(\[[^\]]+\]|[^:?\/]+)/i.exec(String(address));
+        return host !== null && ownRelayHosts.indexOf(host[1].toLowerCase()) !== -1;
+      });
+      if (urls.length) out.push({ urls: urls, username: server.username, credential: server.credential });
+    });
+    return out;
+  }
+
+  /** A configuration from base that only relays, through Zaisma's servers and the game's own relay. */
+  function relayedConfiguration(base, asked, servers) {
+    var out = {};
+    for (var name in base) if (Object.prototype.hasOwnProperty.call(base, name)) out[name] = base[name];
+    out.iceTransportPolicy = "relay";
+    out.iceServers = servers.concat(ownRelays(asked.iceServers));
+    // Gathering ahead of time waits until there are servers to gather from.
+    if (!servers.length) out.iceCandidatePoolSize = 0;
+    else if (asked.iceCandidatePoolSize !== undefined) out.iceCandidatePoolSize = asked.iceCandidatePoolSize;
+    return out;
+  }
+
+  function define(target, name, method) {
+    Object.defineProperty(target, name, { value: method, writable: true, configurable: true, enumerable: false });
+  }
+
+  /** The wrapper for one window's RTCPeerConnection, and its prototype's calls made to relay first. */
+  function wrap(Native) {
+    var proto = Native.prototype;
+    var nativeSetConfiguration = proto.setConfiguration;
+    var nativeGetConfiguration = proto.getConfiguration;
+
+    function RTCPeerConnection(configuration) {
+      if (!new.target) throw new TypeError("Failed to construct 'RTCPeerConnection': Please use the 'new' operator.");
+      var asked = configuration && typeof configuration === "object" ? configuration : {};
+      var servers = isFresh(kept) ? kept.iceServers : [];
+      var parts = Array.prototype.slice.call(arguments);
+      parts[0] = relayedConfiguration(asked, asked, servers);
+      var connection = Reflect.construct(Native, parts, new.target);
+      askedConfigurations.set(connection, asked);
+      if (servers.length) givenServers.set(connection, servers);
+      // Fetched now, so they're there by the game's first offer or answer.
+      if (!servers.length) relayServers();
+      return connection;
+    }
+    RTCPeerConnection.prototype = proto;
+    Object.setPrototypeOf(RTCPeerConnection, Native);
+    define(proto, "constructor", RTCPeerConnection);
+
+    /**
+     * Before a connection gathers addresses (its first offer or answer): Zaisma's relay servers, and
+     * a check that it only relays. Covers every connection in this window, however it was made.
+     */
+    function relayFirst(connection) {
+      return relayServers().then(function (servers) {
+        if (connection.signalingState === "closed") return; // the call itself says so
+        var current = nativeGetConfiguration.call(connection);
+        // Servers it already has stay when new ones couldn't be had.
+        var use = servers.length ? servers : givenServers.get(connection) || [];
+        if (givenServers.get(connection) !== use || current.iceTransportPolicy !== "relay") {
+          try {
+            nativeSetConfiguration.call(connection, relayedConfiguration(current, askedConfigurations.get(connection) || current, use));
+            givenServers.set(connection, use);
+          } catch (error) {
+            /* checked just below */
+          }
+        }
+        if (nativeGetConfiguration.call(connection).iceTransportPolicy !== "relay") {
+          throw new DOMException("On Zaisma, connections between players go only through Zaisma's relay, and this one couldn't be set to.", "InvalidStateError");
+        }
+      });
+    }
+    ["createOffer", "createAnswer", "setLocalDescription"].forEach(function (name) {
+      var native = proto[name];
+      if (typeof native !== "function") return;
+      define(proto, name, function () {
+        var connection = this;
+        var parts = arguments;
+        return relayFirst(connection).then(function () { return native.apply(connection, parts); });
+      });
+    });
+    if (typeof nativeSetConfiguration === "function") {
+      // A game changing its servers keeps Zaisma's relay.
+      define(proto, "setConfiguration", function (configuration) {
+        var asked = configuration && typeof configuration === "object" ? configuration : {};
+        askedConfigurations.set(this, asked);
+        var servers = givenServers.get(this) || [];
+        return nativeSetConfiguration.call(this, relayedConfiguration(asked, asked, servers));
+      });
+    }
+    wrappers.set(Native, RTCPeerConnection);
+    return RTCPeerConnection;
+  }
+
+  // ---- Every window the game can reach ----
+
+  function install(target) {
+    try {
+      if (!target) return;
+      NAMES.forEach(function (name) {
+        var descriptor = Object.getOwnPropertyDescriptor(target, name);
+        if (!descriptor || (descriptor.get && getters.has(descriptor.get))) return;
+        var Native = target[name];
+        if (typeof Native !== "function") return;
+        var Relayed = wrappers.get(Native) || wrap(Native);
+        var current = Relayed;
+        var get = function () { return current; };
+        getters.add(get);
+        // Libraries like webrtc-adapter put their own wrapper around this one; nothing puts the original back.
+        Object.defineProperty(target, name, { configurable: true, enumerable: false, get: get, set: function (assigned) { current = assigned === Native ? Relayed : assigned; } });
+      });
+      watchFrames(target);
+    } catch (error) {
+      /* another site's window: nothing of it is reachable from here */
+    }
+  }
+
+  /** A frame the game makes has its own RTCPeerConnection: it's wrapped the moment the game reaches into the frame. */
+  function watchFrames(target) {
+    ["HTMLIFrameElement", "HTMLFrameElement", "HTMLObjectElement"].forEach(function (name) {
+      var Element = target[name];
+      if (typeof Element !== "function") return;
+      ["contentWindow", "contentDocument"].forEach(function (property) {
+        var descriptor = Object.getOwnPropertyDescriptor(Element.prototype, property);
+        if (!descriptor || !descriptor.get || getters.has(descriptor.get)) return;
+        var nativeGet = descriptor.get;
+        var get = function () {
+          var reached = nativeGet.call(this);
+          if (reached) install(property === "contentDocument" ? reached.defaultView : reached);
+          return reached;
+        };
+        getters.add(get);
+        Object.defineProperty(Element.prototype, property, { configurable: true, enumerable: descriptor.enumerable, get: get });
+      });
+    });
+    var nativeOpen = target.open;
+    if (typeof nativeOpen === "function" && !getters.has(nativeOpen)) {
+      var open = function () {
+        var opened = nativeOpen.apply(this, arguments);
+        install(opened);
+        return opened;
+      };
+      getters.add(open);
+      target.open = open;
+    }
+  }
+
+  install(window);
+  // A game that plays online gets its relay servers while it loads, so its first connection doesn't wait.
+  if (config.fetchEarly && NAMES.some(function (name) { return typeof window[name] === "function"; })) relayServers();
+})(window);