discovery-media-player 0.1.138 → 0.1.139

package/bin/serve.js

@@ -185,13 +185,69 @@ function lireCorpsJson(req, maxOctets = 1_000_000) {
   });
 }
 
+/**
+ * ⚠️ AUCUN SIGNAL N'ÉTAIT ÉCOUTÉ, ET LE CHOIX ÉTAIT ENTRE LENT ET BRUTAL. Sans gestionnaire, Node
+ * PID 1 IGNORE `SIGTERM` (le noyau ne délivre pas à PID 1 un signal sans gestionnaire) : `docker
+ * stop` attend dix secondes puis tue. C'est ce que `dumb-init` corrige — il est PID 1, Node est son
+ * ENFANT, donc le signal relayé y déclenche l'action par défaut : terminaison IMMÉDIATE. Rapide,
+ * mais net : un document en cours de relais, une lecture de présentation, un battement — tranchés
+ * au milieu, à CHAQUE déploiement. La troisième voie n'avait jamais été posée.
+ *
+ * Ici : on cesse d'accepter, on laisse finir ce qui est en vol, on sort. Avec ou sans `dumb-init`.
+ *
+ * ⚠️ PREMIER PIÈGE — `close()` SEUL N'ARRIVE JAMAIS AU BOUT. Il attend que TOUTES les connexions se
+ * ferment, or le keep-alive en garde d'oisives ouvertes plusieurs secondes après leur dernière
+ * requête. Un arrêt qui attend ces sockets-là dépasse le délai de l'orchestrateur et se fait tuer :
+ * on aurait remplacé un arrêt brutal par un arrêt brutal PLUS LENT. `closeIdleConnections()` ferme
+ * ce qui ne sert plus, sans toucher à ce qui travaille.
+ *
+ * ⚠️ SECOND PIÈGE — SANS ÉCHÉANCE, UNE SEULE REQUÊTE BLOQUÉE TIENT TOUT. Un relais vers un stockage
+ * qui ne répond plus n'a aucune raison de finir. Le délai est donc BORNÉ, et volontairement sous le
+ * défaut de `docker stop` (dix secondes) : une échéance qui tombe après le couperet ne sert à rien.
+ * Passé le délai on coupe ce qui reste — c'est exactement l'ancien comportement, mais seulement pour
+ * ce qui n'a pas su finir, et après l'avoir DIT.
+ *
+ * ⚠️ Le minuteur est `unref()` : un compte à rebours qui empêcherait le processus de sortir
+ * retiendrait précisément l'arrêt qu'il surveille.
+ */
+const DELAI_ARRET_MS = Math.max(0, Number(process.env.PLAYER_SHUTDOWN_GRACE_MS) || 0) || 8000;
+
+function arreterProprement(signal) {
+  // ⚠️ UN SECOND SIGNAL SORT TOUT DE SUITE. Qui appuie deux fois sur Ctrl-C demande l'arrêt, pas
+  // une explication — et un gestionnaire qui insiste après un second ordre est un processus qu'on
+  // finit par tuer à la main.
+  if (arreterProprement.enCours) { process.exit(130); return; }
+  arreterProprement.enCours = true;
+  console.log(`${signal} reçu — arrêt : plus de nouvelle connexion, ${DELAI_ARRET_MS} ms pour finir ce qui est en vol`);
+
+  const couperet = setTimeout(() => {
+    console.warn(`arrêt : délai de ${DELAI_ARRET_MS} ms dépassé, les requêtes encore en vol sont coupées`);
+    serveur.closeAllConnections();
+    process.exit(1);
+  }, DELAI_ARRET_MS);
+  couperet.unref();
+
+  serveur.close(() => { clearTimeout(couperet); console.log("arrêt : tout est fini, sortie propre"); process.exit(0); });
+  serveur.closeIdleConnections();
+}
+
 // N'écoute QUE lorsqu'on lance ce fichier. Sans cette garde, un test qui l'importe ouvrirait un
-// port — et deux tests en parallèle s'attraperaient sur le même.
-if (require.main === module) serveur.listen(PORT, HOST, () => {
-  const racine = process.env.PLAYER_LOCAL_ROOT;
-  console.log(`Discovery Media Player — http://localhost:${PORT}`);
-  console.log(racine ? `  documents : ${racine}` : "  documents : aucun dossier local (PLAYER_LOCAL_ROOT)");
-  console.log(`  état      : http://localhost:${PORT}/api/doc?contract=1`);
-});
+// port — et deux tests en parallèle s'attraperaient sur le même. Les signaux suivent la même règle,
+// et pour une raison de plus : un gestionnaire posé par un IMPORT vit dans le processus de qui
+// importe, et détournerait le Ctrl-C d'un banc qui ne demandait qu'à lire une fonction.
+if (require.main === module) {
+  for (const signal of ["SIGTERM", "SIGINT"]) process.on(signal, () => arreterProprement(signal));
+  serveur.listen(PORT, HOST, () => {
+    const racine = process.env.PLAYER_LOCAL_ROOT;
+    // ⚠️ LE PORT OBTENU, PAS LE PORT DEMANDÉ. `PORT=0` demande à l'OS d'en choisir un libre — la
+    // ligne affichait alors « localhost:0 », une adresse qui ne mène nulle part, au moment précis
+    // où l'on a besoin de savoir où frapper. Une trace de démarrage qui n'aide pas à joindre le
+    // serveur ne sert à rien.
+    const ouvert = (serveur.address() || {}).port || PORT;
+    console.log(`Discovery Media Player — http://localhost:${ouvert}`);
+    console.log(racine ? `  documents : ${racine}` : "  documents : aucun dossier local (PLAYER_LOCAL_ROOT)");
+    console.log(`  état      : http://localhost:${ouvert}/api/doc?contract=1`);
+  });
+}
 
-module.exports = { serveur, versParametres, pageAccueil };
+module.exports = { serveur, versParametres, pageAccueil, __arreterProprement: arreterProprement, DELAI_ARRET_MS };

package/docs/HOST-CONTRACT.md

@@ -40,6 +40,7 @@ need.
   "presenceJetons": true,
   "presenceDurcissement": "inconnu",
   "presenceFusion": "inconnu",
+  "lectureSaturee": { "total": 0, "fenetreS": 0, "derniereIlYaS": null },
   "retentionSweep": false,
   "hostShare": true,
   "hostMail": true,
@@ -91,6 +92,29 @@ The three `presence*` fields report what the host has **observed**, not what it
 | `presenceDurcissement` | `actif` (a hardened call came back), `degrade` (migration 0018 is missing), `inconnu` (nothing attempted in this process — **not** a green light, and process-local: another instance may have seen otherwise) |
 | `presenceFusion` | `actif` (a heartbeat used the fused contract — one round trip instead of two), `degrade` (migration 0019 is missing: heartbeats cost 3 round trips instead of 2, nothing breaks), `inconnu` (no heartbeat served in this process). Same three states, same trap, same reading rule as the row above |
 
+### `lectureSaturee` — what this instance actually refused
+
+The read cache groups concurrent requests for the same presentation state and admits a bounded
+number of them in flight. Past that ceiling it answers **`503` with `Retry-After: 1`** — a refusal,
+not a failure, and deliberately distinguishable from a `500`. That ceiling has existed for a long
+time; **nothing counted how often it was reached**, so the question *"do we actually saturate?"* had
+no observable answer.
+
+| key | meaning |
+|---|---|
+| `total` | refusals since this process started |
+| `fenetreS` | how long this process has been running, in seconds — **the window `total` was counted over** |
+| `derniereIlYaS` | seconds since the most recent refusal, or `null` if there has been none |
+
+⚠️ **`total` and `fenetreS` only mean anything together.** `total: 0` does not say *we do not
+saturate*; on a process that started four seconds ago it says *nobody has looked yet*. That is the
+same trap as `inconnu` in the two rows above, and the reason the three keys are returned as one
+object rather than as separate fields you could read apart.
+
+⚠️ **It is process-local.** Behind a load balancer this is the count of the instance that answered,
+not of your deployment. Aggregating is your job — and letting you believe otherwise would be worse
+than returning nothing.
+
 ⚠️ **Before you upgrade, do not read `presenceDurcissement` or `presenceFusion`.** They are *reports
 of execution*: on an instance where nothing is running they say `inconnu`, which means *nobody
 looked* — not *the migration is there*. A pre-flight check built on one of them silently passes on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discovery-media-player",
-  "version": "0.1.138",
+  "version": "0.1.139",
   "description": "Self-hosted document viewer: per-recipient tracked links, reading analytics, live presentation. The core knows nothing about the application hosting it — everything it borrows arrives through an injected context.",
   "keywords": [
     "pdf-viewer",

package/server/cache.js

@@ -75,6 +75,12 @@ function creerCache(options) {
   // résultat en mémoire.
   const maxEnVol = Math.max(1, Number(options && options.maxEnVol) || 128);
   const now = (options && options.now) || (() => Date.now());
+  // ⚠️ CE QUI EST REFUSÉ NE LAISSAIT AUCUNE TRACE. Le plafond d'admission existe depuis longtemps
+  // et il rend un 503 propre — mais rien ne comptait combien de fois il avait servi. La question
+  // « sature-t-on, en vrai ? » n'avait donc AUCUNE réponse observable, et c'est précisément celle
+  // dont dépend la décision d'optimiser ou non le chemin chaud. Optimiser sans elle, c'est deviner.
+  let nSatures = 0;
+  let dernierSature = null;
   /** @type {Map<string, { echeance: number, promesse: Promise<unknown>, poids: number, enVol: boolean, rendrePlace?: () => void }>} */
   const entrees = new Map();
   let poidsTotal = 0;
@@ -123,7 +129,11 @@ function creerCache(options) {
       // existe pour absorber. On ne refuse que ce qui coûterait une requête DE PLUS.
       if (vue && (vue.enVol || vue.echeance > t)) return vue.promesse;
 
-      if (nEnVol >= maxEnVol) throw erreurSaturation(maxEnVol);
+      if (nEnVol >= maxEnVol) {
+        nSatures += 1;
+        dernierSature = t;
+        throw erreurSaturation(maxEnVol);
+      }
 
       const promesse = Promise.resolve().then(produire);
       // ⚠️ UN DÉCOMPTE IDEMPOTENT PAR PROMESSE. Deux chemins libèrent la place (résolution, et
@@ -172,6 +182,16 @@ function creerCache(options) {
     poids: () => poidsTotal,
     /** Demandes actuellement en vol — ce que le plafond d'admission borne. */
     enVol: () => nEnVol,
+    /**
+     * Ce que le plafond a refusé depuis le démarrage de ce processus.
+     *
+     * ⚠️ UN TOTAL SEUL MENT PAR OMISSION, et c'est pour ça que `dernier` l'accompagne. « 0 refus »
+     * ne veut pas dire « on ne sature pas » : ça peut vouloir dire « ce processus vient de
+     * démarrer ». La même règle que `presenceFusion` dans la carte — un rapport d'exécution n'est
+     * pas un inventaire, et une absence d'observation n'est pas une preuve. Celui qui LIT reste
+     * responsable de savoir depuis quand ce processus regarde ; la carte, elle, le lui dit.
+     */
+    satures: () => ({ total: nSatures, dernier: dernierSature }),
   };
 }
 

package/server/handler.js

@@ -694,6 +694,30 @@ async function handler(req, res) {
             return typeof signer === "function" && !!signer("carte-sonde", "carte-sonde", 60);
           } catch { return false; }
         })(),
+        // ⚠️ CE QUE LE PLAFOND D'ADMISSION A REFUSÉ — la seule question dont dépend la décision
+        // d'optimiser le chemin chaud, et elle n'avait aucune réponse observable. Le cache de
+        // lecture refuse une demande de trop par un 503 réessayable depuis longtemps ; rien ne
+        // comptait combien de fois. « Faut-il fusionner les opérations du battement ? » se
+        // tranchait donc au flair (audit CODEX 5.6, §2 — qui disait lui-même d'attendre une mesure).
+        //
+        // ⚠️ ET `fenetreS` N'EST PAS UN ORNEMENT : SANS ELLE LE TOTAL MENT PAR OMISSION. « 0 refus »
+        // ne veut pas dire « on ne sature pas » — ça peut vouloir dire « ce processus a démarré il y
+        // a quatre secondes ». Le total et la fenêtre qui l'a produit ne se lisent QUE ensemble,
+        // exactement comme `presenceFusion` ne se lit pas sans savoir que `inconnu` veut dire
+        // « personne n'a regardé ». On les rend donc dans le même objet, jamais séparés.
+        //
+        // ⚠️ PROCESSUS-LOCAL, comme les champs de présence. Une instance qui répond n'est pas
+        // toutes les instances : derrière un répartiteur, ce compte est celui de CELLE qui a
+        // répondu. Agréger est le travail de l'hôte, et lui laisser croire l'inverse serait pire
+        // que de ne rien rendre.
+        lectureSaturee: (() => {
+          const { total, dernier } = cacheLecture.satures();
+          return {
+            total,
+            fenetreS: Math.round(process.uptime()),
+            derniereIlYaS: dernier == null ? null : Math.max(0, Math.round((Date.now() - dernier) / 1000)),
+          };
+        })(),
         // ⚠️ LE BALAYAGE DE RÉTENTION EST-IL ARMÉ ? La capacité `retention` dit que l'instance PEUT
         // purger ; ce booléen dit si le balayage automatique TOURNE (`config.retention.balayage`).
         // Sans lui, une instance armée est indiscernable d'une instance éteinte — et une purge qui