# 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
```

```json
{"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>
```

```json
{"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`.

```js
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.
