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/(variableEXTERNALS_HOST_DIRdedeploy/.envpour un autre emplacement). deploy/compose.yaml, serviceapp(le seul qui sert l'origine des jeux,PLAY_HOST) :${EXTERNALS_HOST_DIR:-/mimichatPROD/jumphp/externals}:/app/var/externals:ro, etEXTERNALS_DIR=/app/var/externals(le paramètreapp.externals_dirde 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/externalsavantdocker compose up. - Les fichiers doivent être lisibles par l'utilisateur du conteneur (droits
o+rsur les fichiers,o+rxsur 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}
dirvide (ou absent) : les dossiers partagés avec le projet, en entrées de typedir.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
sizede 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 avecContent-Range: bytes 0-65535/12408292; sansRange→ 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-Rangerespecté.Content-Type: celui de l'extension pour les images, les sons, le JSON, le texte… ;application/octet-streamsinon, 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 deContent-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(avecX-Content-Type-Options: nosniff). - Limites : 5000 entrées par liste, 500 résultats et 200 000 entrées parcourues par recherche.