EN

Externals: server files for the games

The externals are a folder of the production server, /mimichatPROD/jumphp/externals/, mounted read-only into the playground's app container (/app/var/externals). The administrator shares sub-folders of it with chosen projects (games or applications): their games read the files from the browser, in blocks (HTTP Range requests), never all at once. Meant for big files that belong neither in a repository nor in the private files (1 GB per game): WADs, disk images, data sets.

Only the administrator grants access. The playground never writes into this folder: files are put there directly on the server.

The folder and the mount

  • On the server: /mimichatPROD/jumphp/externals/ (EXTERNALS_HOST_DIR in deploy/.env for another place).
  • deploy/compose.yaml, service app (the only one serving the games' origin, PLAY_HOST): ${EXTERNALS_HOST_DIR:-/mimichatPROD/jumphp/externals}:/app/var/externals:ro, and EXTERNALS_DIR=/app/var/externals (Symfony parameter app.externals_dir; default <project>/var/externals).
  • In development (compose.yaml at the root): ./var/externals (ignored by git), mounted read-only the same way; mkdir -p var/externals before docker compose up.
  • Files must be readable by the container's user (o+r on files, o+rx on folders).

Administration

Administration (/studio/admin) → Externals block (#externals):

  • the current grants: folder → project slug, date, who granted it; Remove button;
  • a form to share: a folder found (list) or a typed path (dmmotor/wads), and the project's slug;
  • the folders found (3 levels at most), with the number and size of the files directly in them.

A grant covers the folder and everything under it. The folder must exist (a symbolic link to a folder cannot be shared: share its target). A deleted project takes its grants with it.

The HTTP protocol

On the games' origin (PLAY_URL, https://play.jumphp.net), next to /<slug>/play/private/…, for a published project only. All paths are relative to the externals' root (dmmotor/wads/doom.wad), without a leading /. The game calls them on its own origin (no CORS).

List a folder

GET /<slug>/play/externals/~list?dir=<path>&recursive=0|1
{"dir": "dmmotor/wads", "entries": [
  {"path": "dmmotor/wads/doom.wad", "type": "file", "size": 12408292, "mtime": 1731564000},
  {"path": "dmmotor/wads/maps", "type": "dir", "size": 0, "mtime": 1731564000}
], "truncated": false}
  • empty (or missing) dir: the folders granted to the project, as entries of type dir.
  • recursive=1: everything under it (symbolic links to folders are listed, not walked into).
  • Entries sorted by name, 5000 at most: beyond, "truncated": true.
  • A folder has a size of 0.

Search files

GET /<slug>/play/externals/~search?q=<text>&dir=<path>

Same answer (dir, entries, truncated), files only, 500 at most. q: part of the name, case-insensitive; a glob when it has * or ? (*.wad, map??.lmp), matched against the file name, or the whole path when it contains a /. Empty dir: in every granted folder. Empty q: 400.

One entry

GET /<slug>/play/externals/~stat?path=<path>
{"path": "dmmotor/wads/doom.wad", "type": "file", "size": 12408292, "mtime": 1731564000, "etag": "bd55e4-673591e0"}

etag = <size in hex>-<mtime in hex>, the same as the file's ETag header (in quotes).

Read a file, in blocks

GET /<slug>/play/externals/<path>
Range: bytes=0-65535
  • Range (a single range) → 206 with Content-Range: bytes 0-65535/12408292; no Range → 200 and the whole file (avoid it for a big file); unsatisfiable range → 416.
  • Accept-Ranges: bytes, ETag: "<size hex>-<mtime hex>", Last-Modified; If-None-Match / If-Modified-Since → 304; If-Range honoured.
  • Content-Type: the extension's one for images, sounds, JSON, text…; application/octet-stream otherwise, and always for what a browser would run or render as a page (HTML, JavaScript, CSS, SVG, XML).
  • Cache-Control: private, max-age=300, no-transform (no-transform: no proxy compresses the body, a 206 block stays exactly the bytes asked for). No Content-Disposition.
async function readBlock(path, start, length) {
  const r = await fetch(`/${slug}/play/externals/${path}`, { headers: { Range: `bytes=${start}-${start + length - 1}` } });
  if (r.status !== 206 && r.status !== 200) throw new Error((await r.json()).error);
  return new Uint8Array(await r.arrayBuffer());
}

Errors

JSON answers {"error": "…"}:

Status When
400 invalid parameter (empty q)
403 path refused, or not under a folder granted to the project
404 unknown or unpublished project, missing entry, a file where a folder is expected (~list, ~search), a folder asked as a file

JSON answers carry Cache-Control: no-store.

Security rules

  • Read-only: the mount is :ro, the playground has no route that writes.
  • Only the administrator grants or revokes (CSRF token, administrator account); a game only sees the folders granted to its project, and only while it is published.
  • Paths: refused when they start with /, contain .., ., an empty segment, a backslash, a NUL or control character, or a segment starting with a dot.
  • Hidden files (name starting with .): never listed, searched nor served.
  • Symbolic links: the real path (realpath) must stay inside the root and under a folder granted to the project; otherwise the entry is not listed and reading it is refused (403).
  • Nothing the browser runs on the games' origin: HTML, JavaScript, CSS, SVG, XML are served as application/octet-stream (with X-Content-Type-Options: nosniff).
  • Limits: 5000 entries per listing, 500 results and 200,000 entries walked per search.