discovery-media-player 0.1.58 → 0.1.59

package/docs/HOST-CONTRACT.md

@@ -32,7 +32,7 @@ need.
   "hostShare": true,
   "hostMail": true,
   "plugins": { "bot": false, "visitors": false, "brandIntro": false, "botBrowser": false, "providerQuotas": false },
-  "schema": { "attendues": 3, "sondees": 1, "manquant": [] }
+  "schema": { "attendues": 3, "sondees": 1, "verdict": "partiel", "manquant": [] }
 }
 ```
 
@@ -47,10 +47,34 @@ mid-migration. That silence is the point: an operator whose write ordering and m
 are both switched off sees an instance that looks perfectly healthy. Each entry names the file to
 apply and the feature that is asleep.
 
-⚠️ **`sondees` is not decoration.** The card **reports** what this process has already asked; it
-never probes, because a diagnostic must answer when the database does not. A freshly started
-process therefore knows nothing, and `manquant: []` on `sondees: 0` means *no question asked yet*,
-not *nothing missing*. Compare `sondees` with `attendues` before you conclude.
+⚠️ **`manquant: []` has four meanings, so read `verdict`, not the array.** The card **reports**
+what this process has already asked; it never probes on its own, because a diagnostic must answer
+when the database does not — and on a serverless host that means it is usually empty. Ask a
+different question when you want a real answer:
+
+```
+GET /api/doc?contract=1&schema=1
+```
+
+That parameter **is** the one part of this card that needs the database, and only when you ask for
+it. `verdict` is then one of:
+
+| verdict | meaning |
+|---|---|
+| `non-sonde` | nothing asked yet — **not** *nothing missing* |
+| `partiel` | some expectations checked, none of them missing |
+| `complet` | all checked, all present |
+| `incomplet` | at least one is missing — `manquant` names the file and the sleeping feature |
+| `indetermine` | the database did not answer; this measurement did not happen |
+
+⚠️ **`incomplet` wins over `partiel`**: a missing column is a positive fact and settles the verdict
+on its own, even when the rest has not been checked.
+
+⚠️ **`indetermine` is not a failure of the card.** A control column — the primary key of the oldest
+table — is queried first. If *it* does not answer, nothing is missing: the database is. Without that
+control, an unreachable database would make all three probes fail and the card would announce three
+missing migrations **that exist**, sending you to apply what you already have. In that state nothing
+is cached either, so a passing outage does not switch features off for the life of the process.
 
 ⚠️ **`frameAncestors` matters more than it looks.** A host that is not listed will never see the
 viewer: the browser blocks the iframe **before any script runs**, so no message can be emitted and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discovery-media-player",
-  "version": "0.1.58",
+  "version": "0.1.59",
   "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/handler.js

@@ -3790,6 +3790,10 @@ async function handler(req, res) {
     // en booléens parce qu'un hôte doit pouvoir refuser de démarrer si le mur d'accès manque
     // alors qu'il compte dessus.
     if (String(q.contract || "") === "1") {
+      // ⚠️ `&schema=1` : la SEULE partie de cette carte qui demande la base, et seulement quand on
+      // la réclame. Sans le paramètre, la route garde sa propriété de répondre quand plus rien ne
+      // répond ; avec lui, l'appelant choisit d'en avoir besoin. Un échec ici ne fait pas échouer
+      // la carte — il devient le verdict « indetermine ».
       res.statusCode = 200;
       res.setHeader("Content-Type", "application/json; charset=utf-8");
       res.setHeader("Cache-Control", "no-store, max-age=0");
@@ -3828,7 +3832,9 @@ async function handler(req, res) {
         // carte est ce qu'un hôte interroge déjà pour épingler sa version ; c'est donc ici.
         // Elle RAPPORTE ce qui est connu, elle ne sonde pas : un diagnostic ne doit pas tomber en
         // même temps que ce qu'il diagnostique.
-        schema: require("./schema").etatDuSchema(),
+        schema: String(q.schema || "") === "1"
+          ? await require("./schema").sonderTout()
+          : require("./schema").etatDuSchema(),
         // « L'hôte peut-il créer un lien en son nom propre ? » — configuré, pas seulement
         // possible. Un hôte qui oublie le secret reçoit un 401 qui ressemble à un droit
         // manquant ; ce booléen le lui dit sans qu'il ait à essayer.

package/server/schema.js

@@ -44,6 +44,21 @@ const ATTENDUES = {
   },
 };
 
+/**
+ * LE TÉMOIN — une colonne dont l'absence est impossible.
+ *
+ * ⚠️ IL DISTINGUE « ABSENTE » DE « INJOIGNABLE » SANS LIRE UN MESSAGE D'ERREUR. La sonde ne fait
+ * pas cette différence, et c'est juste pour DÉCIDER (les deux mènent à ne pas écrire le champ).
+ * Pour RAPPORTER, les confondre serait faux dans les deux sens : une base momentanément muette
+ * ferait annoncer trois migrations manquantes qui existent — une fausse alerte qui envoie
+ * l'exploitant appliquer ce qu'il a déjà.
+ *
+ * Le témoin est la clé primaire de la plus ancienne table : si LUI ne répond pas, ce n'est pas une
+ * migration qui manque, c'est la base. Mesure différentielle, aucune dépendance au texte d'un
+ * service tiers — la raison même pour laquelle la sonde refusait de distinguer.
+ */
+const TEMOIN = { table: "doc_presentations", colonne: "slug" };
+
 let PLAYER = null;
 /**
  * Une question posée une fois, retenue pour le processus.
@@ -99,9 +114,15 @@ function attendue(nom) {
 function etatDuSchema() {
   const manquant = [];
   for (const [, r] of reponses) if (!r.present) manquant.push({ migration: r.migration, fonction: r.fonction });
+  const attendues = Object.keys(ATTENDUES).length;
   return {
-    attendues: Object.keys(ATTENDUES).length,
+    attendues,
     sondees: reponses.size,
+    // ⚠️ UN MOT, PAS UN TABLEAU VIDE À INTERPRÉTER. `manquant: []` a quatre sens selon ce qu'on
+    // sait par ailleurs — rien demandé, tout vérifié, vérifié en partie, base muette — et forcer
+    // le lecteur à les reconstituer en croisant deux champs, c'est lui laisser la faute. Le second
+    // hôte l'a posé comme condition à ce paramètre, et il avait raison avant même de le voir.
+    verdict: verdict(manquant.length, reponses.size, attendues),
     // ⚠️ ON NOMME LE FICHIER, alors que cette route est publique. Même raison que `frameAncestors`
     // juste au-dessus d'elle : l'exploitant n'a AUCUN autre moyen d'apprendre laquelle manque, et
     // un compte nu le laisserait deviner. Ce qu'on révèle en échange — qu'une fonction de
@@ -159,6 +180,45 @@ async function sonder(table, colonne, migration, cle) {
   }
 }
 
+function verdict(manque, sondees, attendues) {
+  if (manque) return "incomplet";          // un manque est un fait positif : il tranche seul
+  if (!sondees) return "non-sonde";
+  return sondees < attendues ? "partiel" : "complet";
+}
+
+/**
+ * SONDER TOUT, À LA DEMANDE — `?contract=1&schema=1`.
+ *
+ * ⚠️ LE COÛT EST SUR L'APPELANT QUI VEUT LA RÉPONSE. Sonder au démarrage mettrait un aller-retour
+ * base sur chaque démarrage à froid, donc sur le chemin critique de la première vraie requête,
+ * pour un diagnostic que presque personne ne lit — et ferait dépendre le contenu de la carte de ce
+ * que la base a répondu, c'est-à-dire déplacerait le couplage que sa doctrine interdit au lieu de
+ * le supprimer. Arbitrage tranché avec le second hôte, sur ses trois raisons.
+ *
+ * ⚠️ ET UN DIAGNOSTIC NE DOIT PAS ÉTEINDRE CE QU'IL DIAGNOSTIQUE. `aLaColonne` retient sa réponse
+ * pour la vie du processus : appelé pendant un hoquet de la base, ce paramètre aurait mis en cache
+ * « absente » pour les trois attentes — désactivant l'ordre des écritures et l'idempotence des
+ * messages jusqu'au prochain démarrage. Une route de contrôle qui casse la production. Si le
+ * témoin ne répond pas, on ne sonde RIEN et on ne retient RIEN.
+ */
+async function sonderTout() {
+  // ⚠️ LA PART ENCODÉE EST CALCULÉE À PART, comme dans `sonder()` dix lignes plus haut, et pour la
+  // même raison : la garde de portabilité traque une parenthèse après « select= », et un appel de
+  // fonction écrit dans le gabarit en produit une. J'ai reproduit ici le défaut dont le correctif
+  // était commenté juste au-dessus — la forme exacte de la migration 0004, où dix lignes
+  // expliquaient la prudence qu'un revoke six lignes plus haut n'appliquait pas.
+  const champTemoin = encodeURIComponent(TEMOIN.colonne);
+  try {
+    await PLAYER.db.request(`${TEMOIN.table}?select=${champTemoin}&limit=0`);
+  } catch {
+    // On rend ce qu'on savait déjà — un manque constaté plus tôt reste un fait — mais le verdict
+    // dit que cette mesure-ci n'a pas eu lieu. Taire l'un ou l'autre serait mentir d'un côté.
+    return { ...etatDuSchema(), verdict: "indetermine" };
+  }
+  for (const nom of Object.keys(ATTENDUES)) await attendue(nom);
+  return etatDuSchema();
+}
+
 /** La réponse, retenue pour qui la demandera — sans repasser par la base. */
 function noter(cle, present, migration) {
   const a = Object.values(ATTENDUES).find((x) => `${x.table}.${x.colonne}` === cle);
@@ -180,4 +240,4 @@ function signaler(cle, migration) {
 /** Pour les tests et l'exploitation : reposer la question. */
 function oublier() { connues.clear(); reponses.clear(); }
 
-module.exports = { init, aLaColonne, attendue, etatDuSchema, oublier, ATTENDUES };
+module.exports = { init, aLaColonne, attendue, etatDuSchema, sonderTout, oublier, ATTENDUES, TEMOIN };