tickcli-js 0.0.0-stage → 0.1.0

package/src/serve.ts

@@ -0,0 +1,224 @@
+// tickcli-js/serve: a complete game server in one call. Point it at a folder of .html games; every game gets live rooms, an invite link and
+// anonymous players (a pass cookie names their seat). Plain Node (node:http + ws), no framework, no accounts.
+//
+//   import { createGameServer } from "tickcli-js/serve";
+//   const app = createGameServer({ games: "./games", saves: "./saves" });
+//   await app.listen(8080);            // http://localhost:8080/ lists the games
+//
+// A game page loads the libraries with any of: <script src="room.js">, <script src="lib:room">, <script src="tickcli/room.js"> (same for game.js
+// and game3d.js). Engines installed next to tickcli load the same way: <script src="lib:three"></script> (global THREE, made from three's own
+// ES module build at the first request, no bundler), lib:phaser (Phaser), lib:pixi (PIXI);
+// the server points them at its own copies and runs the relay in the same window (the game is the top page, not a sandboxed frame).
+// For signed-in players, your own routes or a sandboxed frame, build on RoomHub + tickcli-js/node instead (see the README, "Hosting it").
+import crypto from "node:crypto";
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { WebSocketServer } from "ws";
+import { RoomHub, type Limits, type SavePort } from "./hub.ts";
+import { GuestPasses, Heartbeat, WS_OPTIONS, attach, clientAddress, fileSaves, gameHash, sameSite } from "./node.ts";
+
+export interface GameServerOptions {
+  /** Folder of games, one .html file each (names: letters, digits, "-" and "_"). Default: the current folder. */
+  games?: string;
+  /** Where saved profiles and worlds go: a folder (file saves) or your own SavePort. Default: none, a restart forgets them. */
+  saves?: string | SavePort;
+  /** Signs the players' pass cookies. Keep it the same across restarts so players keep their seats and saves. Default: random per process. */
+  secret?: string | Buffer;
+  /** Room limits (players, rooms, sizes, rates); see DEFAULT_LIMITS. */
+  limits?: Partial<Limits>;
+  /** Mark the pass cookie Secure (set this when the site is served over https). */
+  secure?: boolean;
+  /** Heading of the game list page. */
+  title?: string;
+  /** Behind a proxy on this machine or a private network (Caddy, nginx): take each player's address from X-Forwarded-For, so the
+   *  per-address limits count players, not the proxy. Only believed from private or loopback peers. */
+  trustProxy?: boolean;
+}
+
+export interface GameServer {
+  server: http.Server;
+  hub: RoomHub;
+  /** Starts listening; resolves with the address to open. */
+  listen(port?: number, host?: string): Promise<string>;
+  /** Stops the server; resolves once every save has been written. */
+  close(): Promise<void>;
+}
+
+const CLIENT = fileURLToPath(new URL("../client/", import.meta.url));
+const PASS = "cw_pass";
+const SCOPE = "play";
+const NAME_RE = /^[\w-]{1,60}\.html$/;
+/** <script src="..."> forms a game may use for the two page libraries. */
+const LIB_TAG = /<script\s+src=["'](?:lib:|(?:\.\/)?(?:tickcli(?:-js)?\/(?:client\/)?)?)(room|game|game3d)(?:\.js)?["']\s*>\s*<\/script>/gi;
+/** Game engines a page may load with <script src="lib:NAME"></script> when their package is installed: package, its browser build (one classic
+ *  script that sets a global; three.js has none, so it is made from its ES module build). */
+const ENGINES: Record<string, { pkg: string; files: string[] }> = {
+  three: { pkg: "three", files: [] },
+  phaser: { pkg: "phaser", files: ["dist/phaser.min.js"] },
+  // PixiJS compiles its shaders with new Function unless its unsafe-eval add-on is there; game pages run under a CSP without eval
+  pixi: { pkg: "pixi.js", files: ["dist/pixi.min.js", "dist/packages/unsafe-eval.min.js"] },
+};
+const ENGINE_TAG = /<script\s+src=["']lib:(three|phaser|pixi)(?:\.js)?["']\s*>\s*<\/script>/gi;
+/** An installed package's own folder (from this package or the folder the server runs in), or null. */
+function pkgDir(name: string): string | null {
+  for (const from of [import.meta.url, path.join(process.cwd(), "x.js")]) {
+    let main: string;
+    try { main = createRequire(from).resolve(name); } catch { continue; }
+    for (let d = path.dirname(main); d !== path.dirname(d); d = path.dirname(d)) {
+      try { if (JSON.parse(fs.readFileSync(path.join(d, "package.json"), "utf8")).name === name) return d; } catch { /* keep looking up */ }
+    }
+  }
+  return null;
+}
+/** The browser build of an engine, or null when it is not installed (or three.js has an unknown shape). Read once. */
+const engineCache = new Map<string, string | null>();
+function engineSource(name: string): string | null {
+  if (!engineCache.has(name)) {
+    const e = ENGINES[name], dir = e ? pkgDir(e.pkg) : null;
+    let src: string | null = null;
+    if (dir) src = name === "three" ? threeGlobal(path.join(dir, "build"))
+      : e.files.every((f) => fs.existsSync(path.join(dir, f))) ? e.files.map((f) => fs.readFileSync(path.join(dir, f), "utf8").replace(/^\/\/# sourceMappingURL=.*$/gm, "")).join("\n;\n") : null;
+    engineCache.set(name, src);
+  }
+  return engineCache.get(name)!;
+}
+/** "A, B as C" from an export or import list: [[local name, exported name]]. */
+function names(list: string): [string, string][] {
+  return list.split(",").map((x) => x.trim()).filter(Boolean).map((x) => { const m = /^(\S+)\s+as\s+(\S+)$/.exec(x); return m ? [m[1], m[2]] : [x, x]; });
+}
+/** three.js as one classic script that sets the global THREE, made from its ES module build (three.core.js + three.module.js: one export list,
+ *  one import and one re-export from the core). Any other shape (a future three.js): null, so the page gets a clear 404 instead of a broken build. */
+export function threeGlobal(dir: string): string | null {
+  const read = (f: string) => { try { return fs.readFileSync(path.join(dir, f), "utf8"); } catch { return null; } };
+  let core = read("three.core.js"), mod = read("three.module.js");
+  if (core === null || mod === null) return null;
+  const CORE = "['\"]\\./three\\.core\\.js['\"]";
+  const coreExp = new RegExp("^export \\{([^}]*)\\};?[ \\t]*$", "m").exec(core);
+  if (!coreExp) return null;
+  core = core.replace(coreExp[0], "");
+  const imp = new RegExp(`^import \\{([^}]*)\\} from ${CORE};?[ \\t]*$`, "m").exec(mod);
+  const reExp = new RegExp(`^export \\{([^}]*)\\} from ${CORE};?[ \\t]*$`, "m").exec(mod);
+  if (!imp || !reExp) return null;
+  mod = mod.replace(imp[0], "").replace(reExp[0], "");
+  const ownExp = new RegExp("^export \\{([^}]*)\\};?[ \\t]*$", "m").exec(mod);
+  if (!ownExp) return null;
+  mod = mod.replace(ownExp[0], "");
+  if (/^\s*(import|export)\b/m.test(core) || /^\s*(import|export)\b/m.test(mod) || /\bimport\.meta\b|\bimport\s*\(/.test(core + mod)) return null;
+  const obj = (pairs: [string, string][], from: (local: string) => string) => pairs.map(([l, e]) => `${JSON.stringify(e)}: ${from(l)}`).join(",\n");
+  return `/* three.js (MIT, three.js authors) as the global THREE: its ES module build wrapped by tickcli, nothing changed inside */\n` +
+    `var THREE = (function () {\n"use strict";\nvar __core = (function () {\n${core}\nreturn {\n${obj(names(coreExp[1]), (l) => l)}\n};\n})();\n` +
+    `return (function () {\nvar {${names(imp[1]).map(([l, e]) => `${JSON.stringify(l)}: ${e}`).join(", ")}} = __core;\n${mod}\n` +
+    `return Object.freeze({\n${obj(names(reExp[1]), (l) => `__core[${JSON.stringify(l)}]`)},\n${obj(names(ownExp[1]), (l) => l)}\n});\n})();\n})();\n`;
+}
+
+/** The page's own socket address for its CSP (connect-src): only this server, as ws: and wss:. Plain 'self' covers same-origin sockets only in
+ *  newer browsers, and "ws: wss:" alone allowed any host. A Host header that is not a plain host[:port] adds nothing. */
+const wsOrigins = (req: http.IncomingMessage) => {
+  const h = String(req.headers.host || "");
+  return /^[a-z0-9.-]{1,253}(:\d{1,5})?$/i.test(h) || /^\[[0-9a-f:.]{2,45}\](:\d{1,5})?$/i.test(h) ? ` ws://${h} wss://${h}` : "";
+};
+const esc = (s: string) => s.replace(/[&<>"]/g, (c) => `&#${c.charCodeAt(0)};`);
+const cookie = (req: http.IncomingMessage, name: string) => (req.headers.cookie || "").split(/;\s*/).map((p) => p.split("=")).find(([k]) => k === name)?.[1];
+
+/** A game page as a visitor gets it: its library tags pointed at /client/*.js and the relay running in the same window. */
+export function playPage(html: string, game: string, roomPath = "/room"): string {
+  const boot = `<script src="/client/relay.js"></script><script>tickcliRelay({frame:function(){return{contentWindow:window}},guest:true,` +
+    `name:function(){try{return localStorage.getItem("tickcli.name")||localStorage.getItem("hr.name")||""}catch(e){return ""}},onName:function(n){try{localStorage.setItem("tickcli.name",n);localStorage.removeItem("hr.name")}catch(e){}},` +
+    `connect:function(){return Promise.resolve({url:${JSON.stringify(`${roomPath}?game=${encodeURIComponent(game)}`)}})}})</script>`;
+  const out = html.replace(LIB_TAG, (_m, n: string) => `<script src="/client/${n.toLowerCase()}.js"></script>`).replace(ENGINE_TAG, (_m, n: string) => `<script src="/vendor/${n.toLowerCase()}.js"></script>`);
+  if (/<head[^>]*>/i.test(out)) return out.replace(/<head[^>]*>/i, (h) => h + boot);
+  // no <head>: right after the doctype, so the page stays in standards mode
+  return /^\s*<!doctype[^>]*>/i.test(out) ? out.replace(/^\s*<!doctype[^>]*>/i, (d) => d + boot) : boot + out;
+}
+
+/**
+ * A complete game server: every .html file in `games` gets live rooms, an invite link and anonymous players. Plain node:http + ws.
+ *
+ * ```ts
+ * import { createGameServer } from "tickcli-js/serve";
+ * const app = createGameServer({ games: "./games", saves: "./saves" });
+ * await app.listen(8080);   // http://localhost:8080/ lists the games
+ * ```
+ */
+export function createGameServer(o: GameServerOptions = {}): GameServer {
+  const secret = o.secret === undefined ? crypto.randomBytes(32) : Buffer.from(o.secret);
+  const games = path.resolve(o.games ?? ".");
+  if (!fs.existsSync(games) || !fs.statSync(games).isDirectory()) throw new Error(`tickcli: no games folder at ${games}`);
+  const saves = typeof o.saves === "string" ? fileSaves(path.resolve(o.saves)) : o.saves;
+  const hub = new RoomHub({ secret: secret.toString("base64url"), limits: o.limits, saves });
+  hub.start();
+  const passes = new GuestPasses(secret);
+  const heartbeat = new Heartbeat();
+  const wss = new WebSocketServer({ ...WS_OPTIONS });
+  // A game is read and hashed once per version of its file (mtime + size), not on every page load and socket: after a restart every player
+  // reconnects within seconds, and a big game read and hashed 2,000 times would hold up the event loop.
+  const cache = new Map<string, { at: string; html: string; hash: string }>();
+  const read = (name: string) => {
+    if (!NAME_RE.test(name)) return null;
+    const file = path.join(games, name);
+    let st: fs.Stats;
+    try { st = fs.statSync(file); } catch { cache.delete(name); return null; }
+    if (!st.isFile()) return null;
+    const at = `${st.mtimeMs}|${st.size}`;
+    const hit = cache.get(name);
+    if (hit && hit.at === at) return hit;
+    const html = fs.readFileSync(file, "utf8");
+    const got = { at, html, hash: gameHash(html) };
+    cache.set(name, got);
+    return got;
+  };
+  const title = o.title ?? "tickcli games";
+
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url || "/", "http://localhost");
+    const send = (code: number, type: string, body: string, headers: Record<string, string> = {}) => { res.writeHead(code, { "Content-Type": type, "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff", ...headers }); res.end(body); };
+    if (req.method !== "GET" && req.method !== "HEAD") return send(405, "text/plain", "method not allowed");
+    if (url.pathname === "/") {
+      const list = fs.readdirSync(games).filter((f) => NAME_RE.test(f)).sort().map((f) => `<li><a href="/play/${f}">${esc(f.replace(/\.html$/, ""))}</a></li>`).join("");
+      return send(200, "text/html; charset=utf-8", `<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${esc(title)}</title><h1>${esc(title)}</h1><ul>${list || "<li>No .html games in this folder yet.</li>"}</ul><p>Open a game in two windows (or send the link) to play together.</p>`);
+    }
+    const c = /^\/client\/(room|relay|game|game3d)\.js$/.exec(url.pathname);
+    if (c) return send(200, "text/javascript; charset=utf-8", fs.readFileSync(path.join(CLIENT, `${c[1]}.js`), "utf8"));
+    const v = /^\/vendor\/(three|phaser|pixi)\.js$/.exec(url.pathname);
+    if (v) {
+      const src = engineSource(v[1]);
+      if (!src) return send(404, "text/javascript; charset=utf-8", `console.error(${JSON.stringify(`lib:${v[1]}: install it next to tickcli (npm install ${ENGINES[v[1]].pkg})`)})`);
+      return send(200, "text/javascript; charset=utf-8", src, { "Cache-Control": "public, max-age=3600" });
+    }
+    const g = /^\/play\/([^/]+)$/.exec(url.pathname);
+    const html = g ? read(g[1])?.html : null;
+    if (!html) return send(404, "text/plain", "not found");
+    // An anonymous pass on first visit (scripts cannot read it; it only names a seat, it proves nothing about a person).
+    const headers: Record<string, string> = { "Content-Security-Policy": `default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:; connect-src 'self'${wsOrigins(req)}; frame-ancestors 'none'` };
+    if (!passes.check(SCOPE, cookie(req, PASS))) headers["Set-Cookie"] = GuestPasses.cookie(PASS, passes.issue(SCOPE), "/", !!o.secure);
+    return send(200, "text/html; charset=utf-8", playPage(html, g![1]), headers);
+  });
+
+  server.on("upgrade", (req, socket, head) => {
+    const url = new URL(req.url || "/", "http://localhost");
+    const refuse = (code: number) => { socket.end(`HTTP/1.1 ${code} ${http.STATUS_CODES[code]}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`); };
+    if (url.pathname !== "/room") return refuse(404);
+    if (!sameSite((n) => req.headers[n] as string | undefined)) return refuse(403);
+    const pass = passes.check(SCOPE, cookie(req, PASS));
+    if (!pass) return refuse(403);
+    const name = url.searchParams.get("game") || "";
+    const game = read(name);
+    if (!game) return refuse(404);
+    const identity = { scope: `${SCOPE}:${name}`, game: game.hash, slot: name, who: { seat: `g:${pass}`, name: GuestPasses.defaultName(pass), guest: true } };
+    wss.handleUpgrade(req, socket, head, (ws) => attach(ws, { hub, heartbeat, address: clientAddress(req, !!o.trustProxy), identity }));
+  });
+
+  const listen = (port = 8080, host?: string) => new Promise<string>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, () => {
+      const a = server.address();
+      const p = typeof a === "object" && a ? a.port : port;
+      resolve(`http://${!host || host === "0.0.0.0" || host === "::" ? "localhost" : host}:${p}/`);
+    });
+  });
+  const close = async () => { const done = hub.shutdown(); heartbeat.stop(); wss.close(); server.close(); await done; };
+  return { server, hub, listen, close };
+}