discovery-media-player 0.1.57 → 0.1.58

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, "manquant": [] }
 }
 ```
 
@@ -39,6 +40,18 @@ 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.
+
+⚠️ **`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.
+
 ⚠️ **`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.58",
   "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." });
               }
@@ -3824,6 +3821,14 @@ 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: 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,34 @@
 // 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",
+  },
+};
+
 let PLAYER = null;
 /**
  * Une question posée une fois, retenue pour le processus.
@@ -28,9 +56,59 @@ 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 });
+  return {
+    attendues: Object.keys(ATTENDUES).length,
+    sondees: reponses.size,
+    // ⚠️ 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 +145,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 +153,18 @@ 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;
   }
 }
 
+/** 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 +178,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, oublier, ATTENDUES };