winzik/docs/externals.md
David Nurdin f11a8da9f1 Externals extension (jumphp/externals): game data streamed by blocks from the playground
- Externals service: list / search / stat / open the folders the playground's
  administrator shares with a game (server externals/ folder)
- RemoteFile: read(offset, length), readNow(), prefetch(), readAll() with
  progress; only the 64 KB blocks read are downloaded (HTTP Range),
  consecutive blocks share a request, `parallel` requests at a time
- BlockCache: memory LRU + persistent blocks in var/ (IndexedDB)
- HttpTransport (the playground's ~list / ~search / ~stat / Range protocol),
  LocalTransport (folders of the computer for desktop and tests)
- samples (browse, search, read), games/externals-demo (file browser),
  game and unit tests, doc/index.md, tutorial, docs/externals.md, AGENTS.md

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-11-14 15:51:55 +01:00

58 lines
3.1 KiB
Markdown

# Externals : de grosses données de jeu, lues par blocs depuis le serveur
Certains jeux ont besoin de données qui ne peuvent pas être dans leur dépôt public ni être téléchargées au lancement :
la version CD d'un jeu (ALIS), des collections de niveaux (dmmotor), des films. Les **externals** sont ces fichiers.
## Côté serveur (le playground)
- Sur la machine de production, le dossier des externals (variable `EXTERNALS_HOST_DIR` du déploiement) est monté
**en lecture seule** dans le conteneur du playground (`/app/var/externals`, variable `EXTERNALS_DIR`).
- On y range les données par jeu, avec des sous-dossiers : `externals/dmmotor/wads/…`, `externals/alis/…`.
- **Seul l'administrateur** donne l'accès : page Administration → *Externals*, un dossier partagé avec un ou plusieurs
projets (table `external_grant`). Un projet ne voit que les dossiers qui lui sont partagés (et leurs sous-dossiers).
- Les fichiers et dossiers dont le nom commence par un point ne sont jamais montrés ; un lien symbolique qui sort du
dossier est refusé.
- Détails, protocole et tests : `docs/externals.md` du dépôt jumphp-playground.
## Le protocole HTTP
Sur l'hôte du jeu, à côté de ses fichiers (`/<slug>/play/`) :
| Requête | Réponse |
|---|---|
| `GET /<slug>/play/externals/~list?dir=<chemin>&recursive=0\|1` | `{"dir", "entries": [{"path", "type": "file"\|"dir", "size", "mtime"}]}` ; `dir` vide = les dossiers partagés |
| `GET /<slug>/play/externals/~search?q=<texte ou motif>&dir=<chemin>` | idem, fichiers seulement (500 au plus) |
| `GET /<slug>/play/externals/~stat?path=<chemin>` | `{"path", "type", "size", "mtime", "etag"}` |
| `GET /<slug>/play/externals/<chemin>` avec `Range: bytes=a-b` | `206` et ces octets (`Accept-Ranges: bytes`) |
Non partagé : 403 ; absent : 404. Les chemins partent de la racine des externals (`dmmotor/wads/x.wad`).
Comme les fichiers du jeu, un fichier partagé se télécharge avec son adresse : ne partager que ce qui peut l'être.
## Côté jeu : l'extension `jumphp/externals`
```bash
bin/jumphp composer <jeu> require jumphp/externals
```
```php
public function __construct(private \JumPHP\Externals\Externals $externals) {}
$this->externals->list('dmmotor/wads', recursive: true)->then(fn (array $entries) => ...);
$this->externals->search('*.wad')->then(...);
$this->externals->open('dmmotor/wads/mod.wad')->then(fn ($f) => $f->read(0, 12)->then(fn ($bytes) => ...));
```
Un fichier se lit comme un disque : `read($offset, $longueur)` ne télécharge que les blocs de 64 Ko concernés (requête
HTTP Range ; les blocs qui se suivent partagent une requête), `readNow()` répond tout de suite quand c'est en cache (sinon
null, et le bloc est demandé), `readAll()` lit tout avec sa progression. Les blocs restent en cache en mémoire et dans
le stockage du joueur (IndexedDB) : un fichier lu une fois ne se retélécharge pas.
En local (bureau, tests), `project.yaml` fait correspondre des dossiers du jeu aux chemins du serveur :
```yaml
externals:
local: { "dmmotor/wads": "wads" }
```
Documentation complète, exemples et jeu de démonstration : `extensions/externals/` (`doc/index.md`, `doc/samples/`,
`games/externals-demo`).