arcadible 0.1.47 → 0.1.49

package/src/serve/files.js

@@ -0,0 +1,61 @@
+"use strict";
+// a game's files, read as Arcadible reads them from storage: by exact path,
+// letter case included, even on a disk that ignores it, such as a Mac's. The
+// server reads through `find`, so another source, such as a packed game,
+// can stand in for a folder.
+
+// [import]
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+// [use]
+
+const createReadStream = fs.createReadStream;
+const join = path.join;
+const readdir = fs.promises.readdir;
+const stat = fs.promises.stat;
+
+// [function]
+
+// whether every segment of `segments` is named exactly so in `root`.
+const exactCase = async function (root, segments) {
+  const found = await Promise.all(
+    segments.map((segment, i) =>
+      readdir(join(root, ...segments.slice(0, i))).then((names) =>
+        names.includes(segment),
+      ),
+    ),
+  );
+  return found.every(Boolean);
+};
+
+// [function]
+
+// the files in `root`. `find(segments)` resolves with the file at that path,
+// as `{ size, mtime, open({ start, end }) }`, or null when there's none, or
+// it's a folder.
+const dirFiles = function (root) {
+  return {
+    async find(segments) {
+      const file = join(root, ...segments);
+      try {
+        const info = await stat(file);
+        if (!info.isFile() || !(await exactCase(root, segments))) {
+          return null;
+        }
+        return {
+          mtime: info.mtime,
+          open: (range) => createReadStream(file, range),
+          size: info.size,
+        };
+      } catch (ex) {
+        return null;
+      }
+    },
+  };
+};
+
+// [export]
+
+module.exports = { dirFiles };

package/src/serve/game.js

@@ -0,0 +1,185 @@
+"use strict";
+// the game's origin, as Arcadible's router and storage answer it
+// (app/src/cloudfront/io-arcadible-router): a path ending in / gets its
+// index.html, a path is found only with its exact letter case, /arcadible/
+// holds only Arcadible's own files, and each file has the type the release
+// pipeline gives it. The headers are the build origin's, but nothing is
+// cached, so a change shows on reload.
+
+// [import]
+
+const http = require("node:http");
+const path = require("node:path");
+
+// [import]
+
+const mime = require("mime-types");
+const parseRange = require("range-parser");
+
+// [use]
+
+const extname = path.extname;
+
+// [declare]
+
+const RESERVED = "arcadible";
+
+// [function]
+
+// the path's segments, decoded, or null for one that can't be a file's:
+// undecodable, or `.`, `..`, or holding a separator.
+const segmentsOf = function (pathname) {
+  const segments = pathname.slice(1).split("/");
+  try {
+    const decoded = segments.map(decodeURIComponent);
+    const unsafe = decoded.some(
+      (s, i) =>
+        s === "." ||
+        s === ".." ||
+        /[/\\\0]/u.test(s) ||
+        (s === "" && i < decoded.length - 1),
+    );
+    return unsafe ? null : decoded;
+  } catch (ex) {
+    return null;
+  }
+};
+
+// [function]
+
+const plain = function (res, status, headers = {}) {
+  res.writeHead(status, {
+    "content-type": "text/plain; charset=utf-8",
+    ...headers,
+  });
+  res.end(`${http.STATUS_CODES[status]}\n`);
+};
+
+// [function]
+
+// the headers every response from the game's origin has, as Arcadible's: the
+// game is cross-origin isolated, and only the play page can frame it.
+const baseHeaders = function (page) {
+  return {
+    "cache-control": "no-store",
+    "content-security-policy": `frame-ancestors ${page};`,
+    "cross-origin-embedder-policy": "require-corp",
+    "cross-origin-resource-policy": "cross-origin",
+    "referrer-policy": "strict-origin-when-cross-origin",
+  };
+};
+
+// [function]
+
+// a file from `files`, whole or the one range asked for. A range that can't be
+// satisfied is a 416; several ranges, or a malformed one, get the whole file.
+const sendFile = function (req, res, file, headers) {
+  const size = file.size;
+  const ranges = req.headers.range ? parseRange(size, req.headers.range) : -2;
+  if (ranges === -1) {
+    res.writeHead(416, { ...headers, "content-range": `bytes */${size}` });
+    res.end();
+    return;
+  }
+  const single =
+    Array.isArray(ranges) && ranges.length === 1 ? ranges[0] : null;
+  const range = single ?? { end: size - 1, start: 0 };
+  const length = size ? range.end - range.start + 1 : 0;
+  res.writeHead(single ? 206 : 200, {
+    ...headers,
+    "accept-ranges": "bytes",
+    "content-length": length,
+    "last-modified": file.mtime.toUTCString(),
+    ...(single
+      ? { "content-range": `bytes ${range.start}-${range.end}/${size}` }
+      : {}),
+  });
+  if (req.method === "HEAD" || !length) {
+    res.end();
+    return;
+  }
+  file.open(range).pipe(res);
+};
+
+// [function]
+
+// ends the response with `body`, or with none for a HEAD request.
+const endWith = function (req, res, body) {
+  if (req.method === "HEAD") {
+    res.end();
+    return;
+  }
+  res.end(body);
+};
+
+// [function]
+
+// one of Arcadible's files under /arcadible/, from `remote`. `onRemote` hears
+// of each, to say when it's a kept copy or can't be had.
+const sendRemote = function (req, res, { headers, name, onRemote, remote }) {
+  return remote
+    .get(name)
+    .then((file) => {
+      onRemote(name, file);
+      if (!file) {
+        plain(res, 404, headers);
+        return;
+      }
+      res.writeHead(200, {
+        ...headers,
+        "content-length": file.body.length,
+        "content-type": file.type,
+      });
+      endWith(req, res, file.body);
+    })
+    .catch((ex) => {
+      onRemote(name, null, ex);
+      plain(res, 502, headers);
+    });
+};
+
+// [function]
+
+// the request handler for the game's origin. `page` is the play page's
+// origin, the only one that may frame the game.
+const gameHandler = function ({ files, onRemote = () => null, page, remote }) {
+  return function (req, res) {
+    const headers = baseHeaders(page);
+    if (req.method !== "GET" && req.method !== "HEAD") {
+      plain(res, 405, { ...headers, allow: "GET, HEAD" });
+      return Promise.resolve();
+    }
+    const segments = segmentsOf(new URL(req.url, "http://game").pathname);
+    if (!segments) {
+      plain(res, 404, headers);
+      return Promise.resolve();
+    }
+    // /arcadible/, in any letter case, is Arcadible's: only its exact path
+    // reaches Arcadible's files.
+    if (segments[0].toLowerCase() === RESERVED && segments.length > 1) {
+      if (segments[0] !== RESERVED) {
+        plain(res, 404, headers);
+        return Promise.resolve();
+      }
+      const name = segments.slice(1).join("/");
+      return sendRemote(req, res, { headers, name, onRemote, remote });
+    }
+    if (segments.at(-1) === "") {
+      segments[segments.length - 1] = "index.html";
+    }
+    return files.find(segments).then((file) => {
+      if (!file) {
+        plain(res, 404, headers);
+        return;
+      }
+      const type =
+        mime.contentType(extname(segments.at(-1))) ||
+        "application/octet-stream";
+      sendFile(req, res, file, { ...headers, "content-type": type });
+    });
+  };
+};
+
+// [export]
+
+module.exports = { endWith, gameHandler };

package/src/serve/page.js

@@ -0,0 +1,176 @@
+"use strict";
+// the local play page: it frames the game as the play page does
+// (site/src/javascripts/arcadible/play/app/page.coffee), with the same
+// sandbox and permissions, and runs the play page's own host for the SDK,
+// so saves are kept by the page, across builds. It reloads the
+// game, and only the game, when told to.
+
+// [import]
+
+const serveGame = require("./game");
+
+// [use]
+
+const endWith = serveGame.endWith;
+
+// [declare]
+
+// the play page's iframe, word for word (test/unit/serve/page.test.js).
+const ALLOW =
+  "accelerometer; autoplay; cross-origin-isolated; fullscreen; gamepad; gyroscope; screen-wake-lock";
+const SANDBOX =
+  "allow-orientation-lock allow-pointer-lock allow-same-origin allow-scripts";
+// the page's own paths. Its origin isn't the game's, so they can't collide.
+const HOST = "/_arcadible/host.js";
+const RELOAD = "/_arcadible/reload";
+
+// [function]
+
+// `value` as JSON that's safe inside a <script>.
+const scriptJson = function (value) {
+  return JSON.stringify(value).replace(/</gu, "\\u003c");
+};
+
+// [function]
+
+const escapeHtml = function (text) {
+  return text.replace(
+    /[&<>"]/gu,
+    (c) => ({ '"': "&quot;", "&": "&amp;", "<": "&lt;", ">": "&gt;" })[c],
+  );
+};
+
+// [function]
+
+// the page for `game`: `{ id, channel, version, title, src }`, where `src` is
+// the game's URL, on its own origin.
+const html = function (game) {
+  const config = {
+    allow: ALLOW,
+    channel: game.channel,
+    game: game.id,
+    sandbox: SANDBOX,
+    src: game.src,
+    version: game.version,
+  };
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no, viewport-fit=cover">
+    <title>${escapeHtml(game.title)}</title>
+    <style>html,body{margin:0;height:100%;overflow:hidden;background:#000}iframe{display:block;width:100%;height:100%;border:0;visibility:hidden}</style>
+  </head>
+  <body>
+    <script src="${HOST}"></script>
+    <script>
+      const config = ${scriptJson(config)};
+      const frame = document.createElement("iframe");
+      frame.allow = config.allow;
+      frame.sandbox = config.sandbox;
+      frame.addEventListener("load", () => {
+        frame.style.visibility = "visible";
+        frame.focus();
+      });
+      // the host answers the game's hello, so it's created before the frame
+      // exists. Without it, the game stands alone, as off Arcadible.
+      const lib = window.arcadibleHost;
+      if (lib) {
+        try {
+          lib.createHost({
+            backend: lib.indexedDBBackend({ persist: true }),
+            channel: config.channel,
+            frame,
+            game: config.game,
+            origin: new URL(config.src).origin,
+            version: config.version,
+          });
+        } catch (err) {
+          console.error("arcadible: no host for the game:", err);
+        }
+      } else {
+        console.error("arcadible: no host for the game: the play page's host didn't load.");
+      }
+      frame.src = config.src;
+      document.body.prepend(frame);
+      new EventSource(${scriptJson(RELOAD)}).addEventListener("reload", () => {
+        frame.style.visibility = "hidden";
+        frame.src = config.src;
+      });
+    </script>
+  </body>
+</html>
+`;
+};
+
+// [function]
+
+// the headers of the page's responses, as the play page's: it's
+// cross-origin isolated, and nothing frames it.
+const HEADERS = {
+  "cache-control": "no-store",
+  "content-security-policy": "frame-ancestors 'none';",
+  "cross-origin-embedder-policy": "require-corp",
+  "cross-origin-opener-policy": "same-origin",
+};
+
+// [function]
+
+// the request handler for the page's origin. `reloads` keeps the pages
+// listening for a reload; `remote` has the host.
+const pageHandler = function ({
+  game,
+  onRemote = () => null,
+  reloads,
+  remote,
+}) {
+  return function (req, res) {
+    const pathname = new URL(req.url, "http://page").pathname;
+    if (req.method !== "GET" && req.method !== "HEAD") {
+      res.writeHead(405, { ...HEADERS, allow: "GET, HEAD" }).end();
+      return Promise.resolve();
+    }
+    if (pathname === "/") {
+      res.writeHead(200, {
+        ...HEADERS,
+        "content-type": "text/html; charset=utf-8",
+      });
+      endWith(req, res, html(game));
+      return Promise.resolve();
+    }
+    if (pathname === RELOAD) {
+      reloads.listen(res);
+      return Promise.resolve();
+    }
+    if (pathname === HOST) {
+      return remote
+        .get("host")
+        .then((file) => {
+          onRemote("host", file);
+          if (!file) {
+            res.writeHead(502, HEADERS).end();
+            return;
+          }
+          res.writeHead(200, {
+            ...HEADERS,
+            "content-type": "text/javascript; charset=utf-8",
+          });
+          endWith(req, res, file.body);
+        })
+        .catch((ex) => {
+          onRemote("host", null, ex);
+          res.writeHead(502, HEADERS).end();
+        });
+    }
+    res.writeHead(404, {
+      ...HEADERS,
+      "content-type": "text/plain; charset=utf-8",
+    });
+    res.end("Not Found\n");
+    return Promise.resolve();
+  };
+};
+
+// [export]
+
+module.exports = { ALLOW, SANDBOX, html, pageHandler };

package/src/serve/reload.js

@@ -0,0 +1,63 @@
+"use strict";
+// reloading the game when its files change: a watch on the folder served,
+// which waits for the changes to settle, so a build that writes many files
+// reloads once, and the pages listening, told over server-sent events.
+
+// [import]
+
+const fs = require("node:fs");
+
+// [declare]
+
+// how long the folder must be still before the game reloads, in ms.
+const SETTLE = 100;
+
+// [function]
+
+// the pages listening for a reload. `listen(res)` keeps a response open as
+// an event stream; `reload()` tells every one; `close()` ends them.
+const reloader = function () {
+  const listening = new Set();
+  return {
+    close() {
+      for (const res of listening) {
+        res.end();
+      }
+      listening.clear();
+    },
+    listen(res) {
+      res.writeHead(200, {
+        "cache-control": "no-store",
+        "content-type": "text/event-stream",
+      });
+      res.write(": listening\n\n");
+      listening.add(res);
+      res.on("close", () => listening.delete(res));
+    },
+    reload() {
+      for (const res of listening) {
+        res.write("event: reload\ndata: \n\n");
+      }
+    },
+  };
+};
+
+// [function]
+
+// calls `onChange` once `dir` has stopped changing for SETTLE ms. Returns a
+// function that stops watching.
+const watchDir = function (dir, onChange) {
+  let timer = null;
+  const watcher = fs.watch(dir, { recursive: true }, () => {
+    clearTimeout(timer);
+    timer = setTimeout(onChange, SETTLE);
+  });
+  return () => {
+    clearTimeout(timer);
+    watcher.close();
+  };
+};
+
+// [export]
+
+module.exports = { reloader, watchDir };

package/src/serve/remote.js

@@ -0,0 +1,119 @@
+"use strict";
+// the files Arcadible serves itself, fetched from where Arcadible serves
+// them, so a fix reaches `arc serve` without a new CLI: the SDK's hosted
+// script, as every game's origin serves it at /arcadible/sdk/, and the play
+// page's host, as the play page runs it. Each is fetched once a session, and
+// the last copy is kept on disk for when Arcadible can't be reached.
+
+// [import]
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+// [use]
+
+const join = path.join;
+const mkdir = fs.promises.mkdir;
+const readFile = fs.promises.readFile;
+const writeFile = fs.promises.writeFile;
+
+// [declare]
+
+// the play page's host, published with each web deploy beside the asset
+// site's other vendored files. Any number in /static/<n>/ is served, and each
+// is cached at Google's edge for a year, so a new one gets the current copy.
+const HOST_PATH = "/asset/arcadible/vnd/arcadible-sdk/host.min.js";
+// the files under /arcadible/ that Arcadible serves: the SDK's, such as
+// sdk/v1.js. Anything else there isn't found, as on Arcadible.
+const SDK_PATH = /^sdk\/[\w.-]+$/u;
+
+// [function]
+
+// a file kept from a fetch, or null.
+const readKept = async function (dir, name) {
+  try {
+    const [body, meta] = await Promise.all([
+      readFile(join(dir, name)),
+      readFile(join(dir, `${name}.json`), "utf8"),
+    ]);
+    return { ...JSON.parse(meta), body };
+  } catch (ex) {
+    return null;
+  }
+};
+
+// [function]
+
+// keeps `file` for later; a copy that can't be written is only skipped.
+const keep = async function (dir, name, { body, ...meta }) {
+  try {
+    await mkdir(dir, { recursive: true });
+    await Promise.all([
+      writeFile(join(dir, name), body),
+      writeFile(join(dir, `${name}.json`), JSON.stringify(meta)),
+    ]);
+  } catch (ex) {
+    // the copy is a convenience: serving goes on without it.
+  }
+};
+
+// [function]
+
+// the files from Arcadible. `asset` is the asset site's origin, `sdk` an
+// origin that serves /arcadible/sdk/, and `dir` where copies are kept.
+// `get(name)` resolves with `{ body, type, fetchedAt, kept }`, where `kept`
+// says the copy is from disk because Arcadible couldn't be reached, or null
+// when Arcadible has no such file; it rejects when Arcadible can't be reached
+// and there's no copy. `name` is `host`, or a path under /arcadible/.
+const remoteFiles = function ({ asset, dir, request = fetch, sdk }) {
+  const session = {};
+  const url = function (name) {
+    if (name === "host") {
+      return `${asset}/static/${Date.now()}${HOST_PATH}`;
+    }
+    return SDK_PATH.test(name) ? `${sdk}/arcadible/${name}` : null;
+  };
+  const load = async function (name) {
+    const target = url(name);
+    if (!target) {
+      return null;
+    }
+    const kept = name.replaceAll("/", "-");
+    try {
+      const res = await request(target);
+      if (res.status === 403 || res.status === 404) {
+        return null;
+      }
+      if (!res.ok) {
+        throw new Error(`${res.status}`);
+      }
+      const file = {
+        body: Buffer.from(await res.arrayBuffer()),
+        fetchedAt: new Date().toISOString(),
+        type: res.headers.get("content-type") ?? "text/javascript",
+      };
+      await keep(dir, kept, file);
+      return { ...file, kept: false };
+    } catch (ex) {
+      const file = await readKept(dir, kept);
+      if (!file) {
+        throw ex;
+      }
+      return { ...file, kept: true };
+    }
+  };
+  return {
+    get(name) {
+      if (!Object.hasOwn(session, name)) {
+        // a failure isn't kept, so the next request tries again.
+        session[name] = load(name);
+        session[name].catch(() => delete session[name]);
+      }
+      return session[name];
+    },
+  };
+};
+
+// [export]
+
+module.exports = { remoteFiles };