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

3.1 KiB

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

bin/jumphp composer <jeu> require jumphp/externals
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 :

externals:
  local: { "dmmotor/wads": "wads" }

Documentation complète, exemples et jeu de démonstration : extensions/externals/ (doc/index.md, doc/samples/, games/externals-demo).