discovery-media-player 0.1.57 → 0.1.59

package/docs/HOST-CONTRACT.md

@@ -31,7 +31,8 @@ need.
   "separateIssuer": true,
   "hostShare": true,
   "hostMail": true,
-  "plugins": { "bot": false, "visitors": false, "brandIntro": false, "botBrowser": false, "providerQuotas": false }
+  "plugins": { "bot": false, "visitors": false, "brandIntro": false, "botBrowser": false, "providerQuotas": false },
+  "schema": { "attendues": 3, "sondees": 1, "verdict": "partiel", "manquant": [] }
 }
 ```
 
@@ -39,6 +40,42 @@ need.
 never by order. `plugins` lets you refuse to start when you depend on an optional module this
 instance does not have.
 
+⚠️ **`schema` tells you which migrations this instance is still waiting for.** The player never
+applies migrations — it cannot, it only speaks PostgREST — so it *detects* instead, and a missing
+column makes the feature that needs it **degrade silently**, by design, so as not to break a host
+mid-migration. That silence is the point: an operator whose write ordering and message idempotency
+are both switched off sees an instance that looks perfectly healthy. Each entry names the file to
+apply and the feature that is asleep.
+
+⚠️ **`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
 the host sees a silence indistinguishable from an unreachable instance. Check that your domain is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discovery-media-player",
-  "version": "0.1.57",
+  "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

@@ -3476,10 +3476,7 @@ async function handler(req, res) {
             // capable d'expédier en son nom : le repli silencieux ouvrirait exactement la porte que
             // la séparation ferme. On nomme le fichier à appliquer et on s'arrête.
             if (atteste) {
-              const pret = await require("./schema").aLaColonne(
-                "commercial_doc_shares", "attested_recipient_email",
-                "supabase/migrations/0001-destinataire-atteste.sql",
-              );
+              const pret = await require("./schema").attendue("destinataireAtteste");
               if (!pret) {
                 return jd(409, { ok: false, error: "migration", message: "Destinataire attesté indisponible : appliquez supabase/migrations/0001-destinataire-atteste.sql." });
               }
@@ -3793,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");
@@ -3824,6 +3825,16 @@ async function handler(req, res) {
         // l'hôte connaît déjà son émetteur — il veut seulement savoir si l'instance le regarde.
         // Dire lequel n'aiderait personne et renseignerait qui sonde.
         separateIssuer: !!(PLAYER.config && PLAYER.config.separateIssuer),
+        // ⚠️ L'ÉTAT DU SCHÉMA, LÀ OÙ ON REGARDE. Une colonne absente était signalée par un
+        // `console.warn`, une fois par processus : sur une fonction serverless, une ligne perdue
+        // dans une sortie que personne n'ouvre tant que tout a l'air de marcher — et « tout a
+        // l'air de marcher » est exactement l'état d'un hôte dont trois protections dorment. Cette
+        // 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: 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/presentations.js

@@ -54,9 +54,7 @@ async function reclaimPresentation(slug, email) {
   // ⚠️ Et j'ai écrit ce champ sans condition en premier jet, ce qui est exactement le piège que
   // docs/MIGRATIONS.md décrit : PostgREST rejette le PATCH ENTIER si la colonne manque. La reprise
   // aurait cessé de fonctionner chez tout hôte non migré — pas la nouvelle garantie, la reprise.
-  const rangDispo = await require("./schema").aLaColonne(
-    "doc_presentations", "write_seq", "supabase/migrations/0002-ordre-des-ecritures.sql",
-  );
+  const rangDispo = await require("./schema").attendue("rangEcriture");
   await PLAYER.db.request(`doc_presentations?slug=eq.${enc(slug)}`, { method: "PATCH", headers: { Prefer: "return=minimal" }, body: { control_hash: sha(control), active: true, ...(rangDispo ? { write_seq: 0 } : {}), last_seen: new Date().toISOString(), updated_at: new Date().toISOString() } });
   return { ok: true, slug, control, page: row.current_page || 1, fileUrl: row.file_url, fileName: row.file_name, docTitle: row.doc_title, docId: row.doc_id };
 }
@@ -200,9 +198,7 @@ async function getPresentation(slug) {
 async function rangAccepte(row, seq) {
   const rang = Number(seq);
   if (!Number.isFinite(rang) || rang <= 0) return { controle: false };   // client plus ancien : pas de rang
-  const dispo = await require("./schema").aLaColonne(
-    "doc_presentations", "write_seq", "supabase/migrations/0002-ordre-des-ecritures.sql",
-  );
+  const dispo = await require("./schema").attendue("rangEcriture");
   if (!dispo) return { controle: false };
   if (rang <= Number(row.write_seq || 0)) return { controle: true, perime: true };
   // ⚠️ ON REND LE RANG, PAS UN OBJET TOUT FAIT. La première version rendait « { write_seq: rang } »,
@@ -428,8 +424,7 @@ async function addMessage(slug, { name, email, avatar, isPresenter, isMember, bo
   // colonne inconnue : chez un hôte non migré, ce n'est pas l'idempotence qu'on perdrait, c'est
   // l'envoi de messages. Même piège que le rang d'écriture, même sonde.
   const cle = String(clientKey || "").slice(0, 80);
-  if (cle && await require("./schema").aLaColonne(
-    "doc_presentation_messages", "client_key", "supabase/migrations/0005-envoi-unique.sql")) {
+  if (cle && await require("./schema").attendue("envoiUnique")) {
     row.client_key = cle;
   }
 

package/server/schema.js

@@ -16,6 +16,49 @@
 // chantiers ont été repoussés pour cette seule raison. Avec cette sonde, l'ordre de déploiement
 // cesse d'être un piège.
 
+/**
+ * CE QUE CE CODE ATTEND DE LA BASE — DÉCLARÉ UNE FOIS, ET C'EST LA SOURCE.
+ *
+ * ⚠️ UN INVENTAIRE QUI N'EST PAS LA SOURCE DÉRIVE. Ces couples vivaient recopiés sur quatre
+ * appels ; en tirer une simple liste « pour l'affichage » aurait refait, en plus petit, le défaut
+ * qui a vidé supabase/init.sql de ses cinq migrations : deux exemplaires du même fait, personne
+ * pour les confronter. Les appelants passent donc par `attendue(nom)` et ne nomment plus de
+ * colonne — il n'existe plus qu'un endroit où se tromper. Une étape de la forge vérifie en outre
+ * que chaque fichier nommé ici existe, et qu'aucun appel ne contourne cette table.
+ */
+const ATTENDUES = {
+  destinataireAtteste: {
+    table: "commercial_doc_shares", colonne: "attested_recipient_email",
+    migration: "supabase/migrations/0001-destinataire-atteste.sql",
+    fonction: "attribuer une lecture au destinataire attesté par l'hôte",
+  },
+  rangEcriture: {
+    table: "doc_presentations", colonne: "write_seq",
+    migration: "supabase/migrations/0002-ordre-des-ecritures.sql",
+    fonction: "refuser une écriture de pilotage doublée en vol",
+  },
+  envoiUnique: {
+    table: "doc_presentation_messages", colonne: "client_key",
+    migration: "supabase/migrations/0005-envoi-unique.sql",
+    fonction: "empêcher qu'un renvoi crée un second message",
+  },
+};
+
+/**
+ * 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.
@@ -28,9 +71,65 @@ let PLAYER = null;
  */
 const connues = new Map();
 
+/**
+ * Les réponses DÉJÀ OBTENUES, pour qui veut les lire — la carte d'identité, essentiellement.
+ *
+ * ⚠️ CE N'EST PAS UN DOUBLON DE `connues`. Celle-ci porte des promesses, dont on ne peut rien dire
+ * sans les attendre ; celle-là porte des réponses. La distinction compte parce que la carte
+ * d'identité ne doit RIEN demander à la base — elle doit répondre quand la base ne répond plus.
+ */
+const reponses = new Map();
+
 function init(ctx) {
   PLAYER = ctx;
   connues.clear();
+  reponses.clear();
+}
+
+/** La sonde d'une attente déclarée. C'est la seule forme d'appel que les appelants utilisent. */
+function attendue(nom) {
+  const a = ATTENDUES[nom];
+  // Un nom inconnu est une faute de frappe, pas une dégradation : la taire ferait passer la
+  // fonction pour « en attente de migration » alors qu'elle est simplement mal câblée.
+  if (!a) throw new Error(`attente de schéma inconnue : ${nom}`);
+  return aLaColonne(a.table, a.colonne, a.migration);
+}
+
+/**
+ * ⚠️ CE QUE LE JOURNAL NE DIRA JAMAIS À PERSONNE.
+ *
+ * La sonde signale une colonne absente par un `console.warn`, une fois par processus. Sur une
+ * fonction serverless, c'est une ligne perdue dans une sortie que personne n'ouvre quand tout a
+ * l'air de marcher — et « tout a l'air de marcher » est précisément l'état d'un hôte dont trois
+ * protections dorment. Remarque du second hôte, et elle est juste : la trace existait à l'endroit
+ * exact où on ne regarde pas.
+ *
+ * ⚠️ ON NE SONDE PAS ICI, ON RAPPORTE. La carte d'identité doit répondre quand la base ne répond
+ * plus ; sonder depuis elle en ferait un diagnostic qui tombe en même temps que ce qu'il diagnostique.
+ *
+ * ⚠️ D'OÙ TROIS ÉTATS, ET PAS DEUX. Un processus qui n'a encore rien demandé ne sait rien — et
+ * « rien de manquant » se lirait « tout va bien ». Une absence de résultat ressemble à un
+ * résultat ; `sondees` est là pour qu'on ne puisse pas les confondre.
+ */
+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,
+    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
+    // fiabilité est en attente, dans un dépôt dont les migrations sont publiques — n'ouvre aucun
+    // accès : il faut déjà détenir un jeton de pilotage pour tirer parti d'un rang absent.
+    manquant,
+  };
 }
 
 /**
@@ -67,6 +166,7 @@ async function sonder(table, colonne, migration, cle) {
     // portage a un fichier à réécrire, pas une habitude à retrouver partout.
     const champ = encodeURIComponent(colonne);
     await PLAYER.db.request(`${table}?select=${champ}&limit=0`);
+    noter(cle, true, migration);
     return true;
   } catch {
     // ⚠️ ON NE DISTINGUE PAS « COLONNE ABSENTE » DE « BASE INJOIGNABLE », ET C'EST VOULU. Les deux
@@ -74,11 +174,57 @@ async function sonder(table, colonne, migration, cle) {
     // message d'erreur, c'est-à-dire de dépendre du texte d'un service tiers. Ce qui change entre
     // les deux, c'est la durée : une base injoignable le redevient, et le processus suivant reposera
     // la question.
+    noter(cle, false, migration);
     signaler(cle, migration);
     return false;
   }
 }
 
+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);
+  reponses.set(cle, { present, migration, fonction: a ? a.fonction : "" });
+}
+
 /**
  * ⚠️ ON NOMME LE FICHIER, PAS L'ERREUR. « column does not exist » envoie l'exploitant lire du
  * PostgREST ; « appliquez supabase/migrations/0001-…sql » lui dit quoi faire. La différence entre
@@ -92,6 +238,6 @@ function signaler(cle, migration) {
 }
 
 /** Pour les tests et l'exploitation : reposer la question. */
-function oublier() { connues.clear(); }
+function oublier() { connues.clear(); reponses.clear(); }
 
-module.exports = { init, aLaColonne, oublier };
+module.exports = { init, aLaColonne, attendue, etatDuSchema, sonderTout, oublier, ATTENDUES, TEMOIN };