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_DIRindeploy/.envfor another place). deploy/compose.yaml, serviceapp(the only one serving the games' origin,PLAY_HOST):${EXTERNALS_HOST_DIR:-/mimichatPROD/jumphp/externals}:/app/var/externals:ro, andEXTERNALS_DIR=/app/var/externals(Symfony parameterapp.externals_dir; default<project>/var/externals).- In development (
compose.yamlat the root):./var/externals(ignored by git), mounted read-only the same way;mkdir -p var/externalsbeforedocker compose up. - Files must be readable by the container's user (
o+ron files,o+rxon 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 typedir. 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
sizeof 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 withContent-Range: bytes 0-65535/12408292; noRange→ 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-Rangehonoured.Content-Type: the extension's one for images, sounds, JSON, text…;application/octet-streamotherwise, 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). NoContent-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(withX-Content-Type-Options: nosniff). - Limits: 5000 entries per listing, 500 results and 200,000 entries walked per search.