NL

Les externals : des fichiers du serveur pour les jeux

Les externals sont un dossier du serveur de production, /mimichatPROD/jumphp/externals/, monté en lecture seule dans le conteneur app du playground (/app/var/externals). L'administrateur en partage des sous-dossiers avec des projets choisis (jeux ou applications) : leurs jeux en lisent les fichiers depuis le navigateur, par blocs (requêtes HTTP Range), jamais en entier d'un coup. Pour les gros fichiers qui n'ont rien à faire dans un dépôt ni dans les fichiers privés (1 Go par jeu) : des WAD, des images disque, des jeux de données.

Seul l'administrateur donne un accès. Le playground n'écrit jamais dans ce dossier : on y dépose les fichiers directement sur le serveur.

Le dossier et le montage

  • Sur le serveur : /mimichatPROD/jumphp/externals/ (variable EXTERNALS_HOST_DIR de deploy/.env pour un autre emplacement).
  • deploy/compose.yaml, service app (le seul qui sert l'origine des jeux, PLAY_HOST) : ${EXTERNALS_HOST_DIR:-/mimichatPROD/jumphp/externals}:/app/var/externals:ro, et EXTERNALS_DIR=/app/var/externals (le paramètre app.externals_dir de Symfony ; par défaut <projet>/var/externals).
  • En développement (compose.yaml à la racine) : ./var/externals (ignoré par git), monté de la même façon en lecture seule ; mkdir -p var/externals avant docker compose up.
  • Les fichiers doivent être lisibles par l'utilisateur du conteneur (droits o+r sur les fichiers, o+rx sur les dossiers).

L'administration

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

  • les partages en cours : dossier → identifiant du projet, date, qui l'a donné ; bouton Retirer ;
  • un formulaire pour partager : un dossier trouvé (liste) ou un chemin tapé (dmmotor/wads), et l'identifiant du projet ;
  • les dossiers trouvés (3 niveaux au plus), avec le nombre et la taille des fichiers qu'ils contiennent directement.

Un partage vaut pour le dossier et tout ce qu'il contient. Le dossier doit exister (un lien symbolique vers un dossier n'est pas partageable : partagez sa cible). Un projet supprimé emporte ses partages.

Le protocole HTTP

Sur l'origine des jeux (PLAY_URL, https://play.jumphp.net), à côté de /<slug>/play/private/…, pour un projet publié seulement. Tous les chemins sont relatifs à la racine des externals (dmmotor/wads/doom.wad), sans / au début. Le jeu les appelle sur sa propre origine (pas de CORS).

Lister un dossier

GET /<slug>/play/externals/~list?dir=<chemin>&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}
  • dir vide (ou absent) : les dossiers partagés avec le projet, en entrées de type dir.
  • recursive=1 : tout ce qu'il y a dessous (les liens symboliques vers des dossiers sont listés mais pas parcourus).
  • Entrées triées par nom, 5000 au plus : au-delà, "truncated": true.
  • Un dossier a une size de 0.

Chercher des fichiers

GET /<slug>/play/externals/~search?q=<texte>&dir=<chemin>

Même réponse (dir, entries, truncated), fichiers seulement, 500 au plus. q : une partie du nom, sans tenir compte de la casse ; un motif (glob) quand il a * ou ? (*.wad, map??.lmp), appliqué au nom du fichier, ou au chemin entier s'il contient un /. dir vide : dans tous les dossiers partagés. q vide : 400.

Une entrée

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

etag = <taille en hexadécimal>-<mtime en hexadécimal>, le même que l'en-tête ETag du fichier (entre guillemets).

Lire un fichier, par blocs

GET /<slug>/play/externals/<chemin>
Range: bytes=0-65535
  • Range (une seule plage) → 206 avec Content-Range: bytes 0-65535/12408292 ; sans Range → 200 et le fichier entier (à éviter pour un gros fichier) ; plage impossible → 416.
  • Accept-Ranges: bytes, ETag: "<taille hex>-<mtime hex>", Last-Modified ; If-None-Match / If-Modified-Since → 304 ; If-Range respecté.
  • Content-Type : celui de l'extension pour les images, les sons, le JSON, le texte… ; application/octet-stream sinon, et toujours pour ce qu'un navigateur exécuterait ou afficherait comme une page (HTML, JavaScript, CSS, SVG, XML).
  • Cache-Control: private, max-age=300, no-transform (no-transform : aucun proxy ne compresse le corps, un bloc 206 reste exactement les octets demandés). Pas de 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());
}

Les erreurs

Réponses JSON {"error": "…"} :

Statut Quand
400 paramètre invalide (q vide)
403 chemin refusé ou pas sous un dossier partagé avec le projet
404 projet inconnu ou non publié, entrée absente, dossier attendu mais fichier (~list, ~search), dossier demandé comme fichier

Les réponses JSON ont Cache-Control: no-store.

Les règles de sécurité

  • Lecture seule : le montage est :ro, le playground n'a aucune route qui écrit.
  • Seul l'administrateur partage ou retire (jeton CSRF, compte administrateur) ; un jeu ne voit que les dossiers partagés avec son projet, et seulement tant qu'il est publié.
  • Chemins : refusés s'ils commencent par /, contiennent .., ., un segment vide, une barre oblique inverse, un caractère NUL ou de contrôle, ou un segment qui commence par un point.
  • Fichiers cachés (nom commençant par .) : jamais listés, cherchés ni servis.
  • Liens symboliques : le chemin réel (realpath) doit rester dans la racine et sous un dossier partagé avec le projet ; sinon l'entrée n'est pas listée et sa lecture est refusée (403).
  • Pas de fichier exécutable par le navigateur sur l'origine des jeux : HTML, JavaScript, CSS, SVG, XML sont servis en application/octet-stream (avec X-Content-Type-Options: nosniff).
  • Limites : 5000 entrées par liste, 500 résultats et 200 000 entrées parcourues par recherche.