@aurabase/realtime 0.4.0 → 0.4.1

package/README.md

@@ -61,6 +61,21 @@ sur réseau mobile ou derrière un proxy, cas où aucun `close` n'est jamais ém
 alors la socket, notifie via `onError` (`phase: 'liveness'`) et `CHANNEL_ERROR` sur chaque canal,
 puis relance la reconnexion automatique (backoff exponentiel avec jitter).
 
+Trois filets couvrent les défaillances du Worker lui-même, car s'il se tait le client ne ping plus
+*et* ne détecte plus rien :
+
+| Défaillance | Détection | Réaction |
+| --- | --- | --- |
+| `Worker` indisponible, construction refusée | exception synchrone | fallback `setInterval` |
+| script refusé par la CSP (`worker-src` sans `blob:`) | événement `error` **asynchrone** — le constructeur ne lève pas | fallback `setInterval` |
+| Worker construit mais inerte | absence d'accusé `ready` sous 3 s | fallback `setInterval` |
+| Worker tué silencieusement en cours de route | filet de liveness du thread principal (90 s sans message serveur) | reconnexion |
+
+Le refresh proactif du token suit le cycle de vie de la connexion : maintenu pendant une
+reconnexion (le prochain handshake a besoin d'un token valide), **annulé** dès que l'état devient
+`disconnected` sans reconnexion prévue — un service arrêté ne doit pas continuer à faire tourner
+les jetons de la session en arrière-plan.
+
 ### Erreurs d'authentification à la connexion
 
 Un handshake refusé par le serveur (token JWT absent/expiré/invalide → HTTP 401) est signalé via

package/dist/index.cjs

@@ -300,6 +300,29 @@ var AuraChannel = class {
     this._sendFn(JSON.stringify(msg));
     this._armSubscribeTimeout();
   }
+  /**
+   * Notifie le callback de statut d'abonnement, sauf si le canal est fermé.
+   *
+   * Un canal sorti par `unsubscribe()` est **soldé** : son cycle de vie s'est
+   * terminé sur `CLOSED`. Rien ne doit plus le faire parler — ni une erreur
+   * serveur globale rediffusée à tous les canaux, ni une confirmation `subscribed`
+   * encore en vol au moment du désabonnement. Sans cette garde, l'appelant voyait
+   * un `CHANNEL_ERROR` ou un `SUBSCRIBED` APRÈS le `CLOSED` de son propre canal.
+   *
+   * Parité `@supabase/realtime-js` : un canal quitté est retiré de
+   * `socket.channels` (`RealtimeClient#_remove`) et échappe donc par construction
+   * à `Socket#triggerChanError` et au routage des réponses. Le SDK Aurabase garde
+   * l'instance dans sa Map (`unsubscribe()` ne la retire pas, seul
+   * `removeChannel()` le fait), la garde est donc portée par le canal lui-même.
+   *
+   * `CLOSED` est la seule exception : il est émis précisément au moment où
+   * `_subscribed` bascule à `false` — d'où son émission directe dans
+   * `unsubscribe()`.
+   */
+  _emitStatus(status, err) {
+    if (!this._subscribed) return;
+    this._subscribeCallback?.(status, err);
+  }
   /** (Re)arme le compte à rebours d'attente de la confirmation `subscribed`. */
   _armSubscribeTimeout() {
     this._clearSubscribeTimeout();
@@ -326,8 +349,7 @@ var AuraChannel = class {
    */
   _signalError(err) {
     this._clearSubscribeTimeout();
-    if (!this._subscribed) return;
-    this._subscribeCallback?.("CHANNEL_ERROR", err);
+    this._emitStatus("CHANNEL_ERROR", err);
   }
   /** Unsubscribe from the channel. */
   unsubscribe() {
@@ -423,7 +445,7 @@ var AuraChannel = class {
         const subMsg = msg;
         if (subMsg.subscription_id) this._subscriptionId = subMsg.subscription_id;
         this._clearSubscribeTimeout();
-        this._subscribeCallback?.("SUBSCRIBED");
+        this._emitStatus("SUBSCRIBED");
         break;
       }
       case "event": {
@@ -442,6 +464,7 @@ var AuraChannel = class {
         break;
       }
       case "presence_state": {
+        if (!this._subscribed) break;
         const presMsg = msg;
         if (presMsg.presences) {
           this._presenceState = {};
@@ -461,7 +484,7 @@ var AuraChannel = class {
       case "error": {
         const errMsg = msg;
         this._clearSubscribeTimeout();
-        this._subscribeCallback?.("CHANNEL_ERROR", new Error(errMsg.message ?? "Unknown error"));
+        this._emitStatus("CHANNEL_ERROR", new Error(errMsg.message ?? "Unknown error"));
         break;
       }
       case "token_refreshed":
@@ -601,44 +624,87 @@ var AuraChannel = class {
 };
 
 // src/HeartbeatManager.ts
-var HeartbeatManager = class {
+var HeartbeatManager = class _HeartbeatManager {
   _worker = null;
   _workerUrl = null;
   _interval = null;
   _sendFn = null;
+  /** Chien de garde de l'accusé `ready` du Worker (mode de défaillance 3). */
+  _watchdog = null;
+  /**
+   * Numéro du cycle start/stop courant. Un événement asynchrone (erreur de
+   * Worker, chien de garde) portant un numéro périmé appartient à un cycle déjà
+   * arrêté ou remplacé : il doit être ignoré, jamais ressusciter un heartbeat.
+   */
+  _generation = 0;
+  /**
+   * Délai accordé au Worker pour accuser réception du `start`.
+   *
+   * Volontairement **indépendant de l'intervalle de heartbeat** : c'est un temps
+   * de démarrage de thread, pas un multiple de la cadence. 3 s est très large
+   * pour un Worker sain (quelques millisecondes en pratique) tout en restant
+   * loin sous le `heartbeat_timeout` de 60 s du serveur.
+   */
+  static WORKER_READY_TIMEOUT_MS = 3e3;
   start(sendPing, intervalMs = 25e3) {
     this.stop();
+    const generation = ++this._generation;
     this._sendFn = sendPing;
     if (typeof Worker !== "undefined" && typeof URL !== "undefined" && typeof URL.createObjectURL === "function") {
       try {
-        const code = `let i=null;onmessage=(e)=>{if(e.data.type==='start'){if(i)clearInterval(i);i=setInterval(()=>postMessage('ping'),e.data.interval||25000);}else if(e.data.type==='stop'){if(i){clearInterval(i);i=null;}}};`;
+        const code = `let i=null;onmessage=(e)=>{if(e.data.type==='start'){if(i)clearInterval(i);postMessage('ready');i=setInterval(()=>postMessage('ping'),e.data.interval||25000);}else if(e.data.type==='stop'){if(i){clearInterval(i);i=null;}}};`;
         const blob = new Blob([code], { type: "application/javascript" });
         this._workerUrl = URL.createObjectURL(blob);
-        this._worker = new Worker(this._workerUrl);
-        this._worker.onmessage = () => {
+        const worker = new Worker(this._workerUrl);
+        this._worker = worker;
+        worker.onmessage = (evt) => {
+          if (generation !== this._generation) return;
+          this._clearWatchdog();
+          if (evt?.data === "ready") return;
           this._sendFn?.();
         };
-        this._worker.postMessage({ type: "start", interval: intervalMs });
+        worker.onerror = () => {
+          this._fallbackFromWorker(generation, intervalMs);
+        };
+        worker.postMessage({ type: "start", interval: intervalMs });
+        this._watchdog = setTimeout(
+          () => this._fallbackFromWorker(generation, intervalMs),
+          _HeartbeatManager.WORKER_READY_TIMEOUT_MS
+        );
         return;
       } catch {
-        this._worker = null;
-        if (this._workerUrl) {
-          try {
-            URL.revokeObjectURL(this._workerUrl);
-          } catch {
-          }
-          this._workerUrl = null;
-        }
+        this._disposeWorker();
       }
     }
+    this._startFallback(intervalMs);
+  }
+  /**
+   * Abandonne le Worker et reprend le battement avec un `setInterval`.
+   * Idempotent et insensible aux cycles périmés.
+   */
+  _fallbackFromWorker(generation, intervalMs) {
+    if (generation !== this._generation) return;
+    if (this._interval) return;
+    if (!this._sendFn) return;
+    this._clearWatchdog();
+    this._disposeWorker();
+    this._startFallback(intervalMs);
+  }
+  _startFallback(intervalMs) {
     this._interval = setInterval(() => {
       this._sendFn?.();
     }, intervalMs);
   }
-  stop() {
+  _clearWatchdog() {
+    if (this._watchdog) {
+      clearTimeout(this._watchdog);
+      this._watchdog = null;
+    }
+  }
+  /** Termine le Worker courant et libère l'URL d'objet associée. */
+  _disposeWorker() {
     if (this._worker) {
       try {
-        this._worker.postMessage({ type: "stop" });
         this._worker.terminate();
       } catch {
       }
@@ -651,6 +717,17 @@ var HeartbeatManager = class {
       }
       this._workerUrl = null;
     }
+  }
+  stop() {
+    this._generation++;
+    this._clearWatchdog();
+    if (this._worker) {
+      try {
+        this._worker.postMessage({ type: "stop" });
+      } catch {
+      }
+    }
+    this._disposeWorker();
     if (this._interval) {
       clearInterval(this._interval);
       this._interval = null;
@@ -711,6 +788,8 @@ var RealtimeConnectionError = class _RealtimeConnectionError extends Error {
 // src/RealtimeService.ts
 var HEARTBEAT_INTERVAL_MS = 25e3;
 var MAX_TIMEOUT_MS = 2147483647;
+var LIVENESS_GUARD_INTERVAL_MS = 3e4;
+var LIVENESS_MAX_SILENCE_MS = 9e4;
 var RealtimeService = class _RealtimeService {
   client;
   _ws = null;
@@ -736,6 +815,17 @@ var RealtimeService = class _RealtimeService {
    * 30 s et répond au ping : la connexion est morte (TCP à demi-fermé).
    */
   _awaitingPong = false;
+  /** Date du dernier message serveur reçu, pour le filet de liveness. */
+  _lastServerMessageAt = 0;
+  /**
+   * Filet de liveness, indépendant du `HeartbeatManager`.
+   *
+   * Sans lui, toute la détection de connexion morte reposait sur le tick du
+   * heartbeat — lui-même porté par un Worker. Un Worker tué silencieusement (par
+   * la pression mémoire d'un mobile, sans événement `error`) supprimait d'un coup
+   * le ping ET la détection : le heartbeat était un point unique de défaillance.
+   */
+  _livenessGuard = null;
   /** Backoff delays in ms: 1s, 2s, 4s, 8s, 16s, 30s (cap) */
   static BACKOFF_MS = [1e3, 2e3, 4e3, 8e3, 16e3, 3e4];
   constructor(client) {
@@ -840,7 +930,9 @@ var RealtimeService = class _RealtimeService {
       this._reconnectAttempts = 0;
       this._setState("connected");
       this._awaitingPong = false;
+      this._lastServerMessageAt = Date.now();
       this._heartbeat.start(() => this._heartbeatTick(ws), HEARTBEAT_INTERVAL_MS);
+      this._startLivenessGuard(ws);
       this._scheduleTokenRefresh();
       for (const channel of this._channels.values()) {
         channel._bindSend((data) => this._send(data));
@@ -852,6 +944,7 @@ var RealtimeService = class _RealtimeService {
     ws.onmessage = (evt) => {
       if (ws !== this._ws) return;
       this._awaitingPong = false;
+      this._lastServerMessageAt = Date.now();
       try {
         const raw = typeof evt.data === "string" ? evt.data : "";
         const msg = JSON.parse(raw);
@@ -880,12 +973,12 @@ var RealtimeService = class _RealtimeService {
         );
       }
       if (intentional || this._intentionalClose) {
-        this._setState("disconnected");
+        this._goDisconnected();
         this._intentionalClose = false;
       } else if (this._autoReconnect) {
         this._scheduleReconnect();
       } else {
-        this._setState("disconnected");
+        this._goDisconnected();
       }
     };
     ws.onerror = (evt) => {
@@ -905,6 +998,61 @@ var RealtimeService = class _RealtimeService {
     this._lastSentToken = null;
     this._awaitingPong = false;
     this._heartbeat.stop();
+    this._stopLivenessGuard();
+  }
+  /**
+   * Arme le filet de liveness pour `ws` : il ne juge que sur la date du dernier
+   * message reçu, donc il survit à la mort complète du heartbeat.
+   *
+   * Il vit sur le thread principal, qu'un navigateur throttle en arrière-plan :
+   * cela ne peut que le RETARDER, jamais provoquer un faux positif — le verdict
+   * porte sur une durée mesurée, pas sur le nombre de ticks écoulés.
+   */
+  _startLivenessGuard(ws) {
+    this._stopLivenessGuard();
+    this._livenessGuard = setInterval(() => {
+      if (ws !== this._ws) return;
+      const silence = Date.now() - this._lastServerMessageAt;
+      if (silence < LIVENESS_MAX_SILENCE_MS) return;
+      this._handleDeadConnection(
+        `Realtime : aucun message du serveur depuis ${Math.round(silence / 1e3)} s alors qu'il en pousse un toutes les 30 s \u2014 connexion consid\xE9r\xE9e morte. Reconnexion.`
+      );
+    }, LIVENESS_GUARD_INTERVAL_MS);
+  }
+  _stopLivenessGuard() {
+    if (this._livenessGuard) {
+      clearInterval(this._livenessGuard);
+      this._livenessGuard = null;
+    }
+  }
+  /** Annule le refresh proactif du token, s'il est armé. */
+  _cancelTokenRefresh() {
+    if (this._tokenRefreshTimer) {
+      clearTimeout(this._tokenRefreshTimer);
+      this._tokenRefreshTimer = null;
+    }
+  }
+  /**
+   * Bascule vers l'état terminal `disconnected` : plus aucune reconnexion n'est
+   * prévue, le service doit donc **cesser toute activité de fond**.
+   *
+   * Le point sensible est le refresh proactif du token. Le laisser courir n'est
+   * pas anodin : `auth.refreshSession()` frappe le backend, qui applique une
+   * ROTATION STRICTE — chaque refresh révoque l'ancien refresh token
+   * (`services/aura-auth/src/services/auth_service.rs`, « Rotation atomique (E2) »),
+   * et rejouer un token révoqué au-delà de la fenêtre de grâce déclenche
+   * `token_reuse_detected` → **révocation globale de toutes les sessions de
+   * l'utilisateur**. Comme `refreshToken()` replanifie systématiquement le timer,
+   * un service pourtant `disconnected` faisait tourner les jetons de la session à
+   * perpétuité, en tâche de fond, sans que personne ne l'ait demandé.
+   *
+   * En revanche le refresh est **conservé pendant une reconnexion** : le prochain
+   * handshake lit `authStore.token`, et un backoff un peu long laisserait sinon
+   * expirer le token — le ré-handshake partirait alors en 401.
+   */
+  _goDisconnected() {
+    this._cancelTokenRefresh();
+    this._setState("disconnected");
   }
   /**
    * Un tick de heartbeat : vérifie la liveness du lien puis émet un ping.
@@ -955,7 +1103,7 @@ var RealtimeService = class _RealtimeService {
       this._scheduleReconnect();
     } else {
       this._intentionalClose = false;
-      this._setState("disconnected");
+      this._goDisconnected();
     }
   }
   /** Send raw data through the WebSocket. */
@@ -1035,10 +1183,7 @@ var RealtimeService = class _RealtimeService {
    * Prevents token expiration during an active WebSocket session.
    */
   _scheduleTokenRefresh() {
-    if (this._tokenRefreshTimer) {
-      clearTimeout(this._tokenRefreshTimer);
-      this._tokenRefreshTimer = null;
-    }
+    this._cancelTokenRefresh();
     const token = this.client.authStore.token;
     if (!token) return;
     const exp = getTokenExpiryMs(token);
@@ -1071,7 +1216,7 @@ var RealtimeService = class _RealtimeService {
       this._reconnectTimer = null;
     }
     if (this._reconnectAttempts >= this._maxReconnectAttempts) {
-      this._setState("disconnected");
+      this._goDisconnected();
       return;
     }
     this._reconnectAttempts++;
@@ -1094,10 +1239,8 @@ var RealtimeService = class _RealtimeService {
   disconnect() {
     this._intentionalClose = true;
     this._heartbeat.stop();
-    if (this._tokenRefreshTimer) {
-      clearTimeout(this._tokenRefreshTimer);
-      this._tokenRefreshTimer = null;
-    }
+    this._stopLivenessGuard();
+    this._cancelTokenRefresh();
     if (this._reconnectTimer) {
       clearTimeout(this._reconnectTimer);
       this._reconnectTimer = null;

package/dist/index.d.cts

@@ -95,6 +95,26 @@ declare class AuraChannel {
     _bindSend(sendFn: SendFn): void;
     /** Send the subscribe message to the server. */
     _doSubscribe(): void;
+    /**
+     * Notifie le callback de statut d'abonnement, sauf si le canal est fermé.
+     *
+     * Un canal sorti par `unsubscribe()` est **soldé** : son cycle de vie s'est
+     * terminé sur `CLOSED`. Rien ne doit plus le faire parler — ni une erreur
+     * serveur globale rediffusée à tous les canaux, ni une confirmation `subscribed`
+     * encore en vol au moment du désabonnement. Sans cette garde, l'appelant voyait
+     * un `CHANNEL_ERROR` ou un `SUBSCRIBED` APRÈS le `CLOSED` de son propre canal.
+     *
+     * Parité `@supabase/realtime-js` : un canal quitté est retiré de
+     * `socket.channels` (`RealtimeClient#_remove`) et échappe donc par construction
+     * à `Socket#triggerChanError` et au routage des réponses. Le SDK Aurabase garde
+     * l'instance dans sa Map (`unsubscribe()` ne la retire pas, seul
+     * `removeChannel()` le fait), la garde est donc portée par le canal lui-même.
+     *
+     * `CLOSED` est la seule exception : il est émis précisément au moment où
+     * `_subscribed` bascule à `false` — d'où son émission directe dans
+     * `unsubscribe()`.
+     */
+    private _emitStatus;
     /** (Re)arme le compte à rebours d'attente de la confirmation `subscribed`. */
     private _armSubscribeTimeout;
     private _clearSubscribeTimeout;
@@ -251,6 +271,17 @@ declare class RealtimeService {
      * 30 s et répond au ping : la connexion est morte (TCP à demi-fermé).
      */
     private _awaitingPong;
+    /** Date du dernier message serveur reçu, pour le filet de liveness. */
+    private _lastServerMessageAt;
+    /**
+     * Filet de liveness, indépendant du `HeartbeatManager`.
+     *
+     * Sans lui, toute la détection de connexion morte reposait sur le tick du
+     * heartbeat — lui-même porté par un Worker. Un Worker tué silencieusement (par
+     * la pression mémoire d'un mobile, sans événement `error`) supprimait d'un coup
+     * le ping ET la détection : le heartbeat était un point unique de défaillance.
+     */
+    private _livenessGuard;
     /** Backoff delays in ms: 1s, 2s, 4s, 8s, 16s, 30s (cap) */
     private static readonly BACKOFF_MS;
     constructor(client: AuraClientLike);
@@ -298,6 +329,37 @@ declare class RealtimeService {
      * compter sur un `onclose` : une socket à demi-fermée n'en émet parfois jamais).
      */
     private _detachSocket;
+    /**
+     * Arme le filet de liveness pour `ws` : il ne juge que sur la date du dernier
+     * message reçu, donc il survit à la mort complète du heartbeat.
+     *
+     * Il vit sur le thread principal, qu'un navigateur throttle en arrière-plan :
+     * cela ne peut que le RETARDER, jamais provoquer un faux positif — le verdict
+     * porte sur une durée mesurée, pas sur le nombre de ticks écoulés.
+     */
+    private _startLivenessGuard;
+    private _stopLivenessGuard;
+    /** Annule le refresh proactif du token, s'il est armé. */
+    private _cancelTokenRefresh;
+    /**
+     * Bascule vers l'état terminal `disconnected` : plus aucune reconnexion n'est
+     * prévue, le service doit donc **cesser toute activité de fond**.
+     *
+     * Le point sensible est le refresh proactif du token. Le laisser courir n'est
+     * pas anodin : `auth.refreshSession()` frappe le backend, qui applique une
+     * ROTATION STRICTE — chaque refresh révoque l'ancien refresh token
+     * (`services/aura-auth/src/services/auth_service.rs`, « Rotation atomique (E2) »),
+     * et rejouer un token révoqué au-delà de la fenêtre de grâce déclenche
+     * `token_reuse_detected` → **révocation globale de toutes les sessions de
+     * l'utilisateur**. Comme `refreshToken()` replanifie systématiquement le timer,
+     * un service pourtant `disconnected` faisait tourner les jetons de la session à
+     * perpétuité, en tâche de fond, sans que personne ne l'ait demandé.
+     *
+     * En revanche le refresh est **conservé pendant une reconnexion** : le prochain
+     * handshake lit `authStore.token`, et un backoff un peu long laisserait sinon
+     * expirer le token — le ré-handshake partirait alors en 401.
+     */
+    private _goDisconnected;
     /**
      * Un tick de heartbeat : vérifie la liveness du lien puis émet un ping.
      *
@@ -404,14 +466,67 @@ declare class RealtimeService {
 
 /**
  * HeartbeatManager — pings périodiques pour maintenir la connexion WS.
- * Utilise un Worker dédié (anti-throttle des onglets en arrière-plan) ; fallback setInterval.
+ *
+ * Utilise un Worker dédié : les navigateurs throttlent agressivement les timers
+ * d'un onglet en arrière-plan (jusqu'à 1 tick/minute), ce qui ferait manquer le
+ * `heartbeat_timeout` de 60 s du serveur ; un Worker n'est pas soumis à ce
+ * throttling. Fallback `setInterval` quand le Worker est indisponible.
+ *
+ * ── Pourquoi trois filets et pas un ──────────────────────────────────────────
+ * Ce battement ne sert plus seulement à tenir la connexion ouverte : c'est aussi
+ * lui qui cadence la **détection de connexion morte** du `RealtimeService`. S'il
+ * se tait, le client ne ping plus (le serveur coupe à 60 s) *et* ne détecte plus
+ * rien. Les trois modes de défaillance d'un Worker sont donc couverts :
+ *
+ * 1. **Échec synchrone** (`new Worker` lève, `Worker` absent) → `try/catch`.
+ * 2. **Échec asynchrone** — le cas d'une CSP `worker-src` qui n'autorise pas
+ *    `blob:`. La spec HTML est explicite : quand le fetch du script échoue,
+ *    le constructeur **ne lève pas**, l'agent utilisateur déclenche un événement
+ *    `error` sur l'objet Worker. Un `try/catch` ne peut donc rien attraper →
+ *    `onerror` bascule sur le fallback.
+ * 3. **Worker inerte** — construit sans erreur mais qui ne poste jamais rien.
+ *    Aucun événement ne le signale : le Worker accuse donc réception du `start`
+ *    par un `ready` immédiat, et un chien de garde bascule si cet accusé
+ *    n'arrive pas.
+ *
+ * Le chien de garde porte sur le `ready`, PAS sur le premier battement : mesuré
+ * en Chromium réel, le démarrage d'un Worker peut dépasser 1,5 intervalle quand
+ * l'intervalle est court, ce qui faisait abandonner à tort un Worker
+ * parfaitement sain — et perdre silencieusement l'immunité au throttling, la
+ * seule raison d'être de ce Worker.
  */
 declare class HeartbeatManager {
     private _worker;
     private _workerUrl;
     private _interval;
     private _sendFn;
+    /** Chien de garde de l'accusé `ready` du Worker (mode de défaillance 3). */
+    private _watchdog;
+    /**
+     * Numéro du cycle start/stop courant. Un événement asynchrone (erreur de
+     * Worker, chien de garde) portant un numéro périmé appartient à un cycle déjà
+     * arrêté ou remplacé : il doit être ignoré, jamais ressusciter un heartbeat.
+     */
+    private _generation;
+    /**
+     * Délai accordé au Worker pour accuser réception du `start`.
+     *
+     * Volontairement **indépendant de l'intervalle de heartbeat** : c'est un temps
+     * de démarrage de thread, pas un multiple de la cadence. 3 s est très large
+     * pour un Worker sain (quelques millisecondes en pratique) tout en restant
+     * loin sous le `heartbeat_timeout` de 60 s du serveur.
+     */
+    private static readonly WORKER_READY_TIMEOUT_MS;
     start(sendPing: () => void, intervalMs?: number): void;
+    /**
+     * Abandonne le Worker et reprend le battement avec un `setInterval`.
+     * Idempotent et insensible aux cycles périmés.
+     */
+    private _fallbackFromWorker;
+    private _startFallback;
+    private _clearWatchdog;
+    /** Termine le Worker courant et libère l'URL d'objet associée. */
+    private _disposeWorker;
     stop(): void;
     get isActive(): boolean;
 }

package/dist/index.d.ts

@@ -95,6 +95,26 @@ declare class AuraChannel {
     _bindSend(sendFn: SendFn): void;
     /** Send the subscribe message to the server. */
     _doSubscribe(): void;
+    /**
+     * Notifie le callback de statut d'abonnement, sauf si le canal est fermé.
+     *
+     * Un canal sorti par `unsubscribe()` est **soldé** : son cycle de vie s'est
+     * terminé sur `CLOSED`. Rien ne doit plus le faire parler — ni une erreur
+     * serveur globale rediffusée à tous les canaux, ni une confirmation `subscribed`
+     * encore en vol au moment du désabonnement. Sans cette garde, l'appelant voyait
+     * un `CHANNEL_ERROR` ou un `SUBSCRIBED` APRÈS le `CLOSED` de son propre canal.
+     *
+     * Parité `@supabase/realtime-js` : un canal quitté est retiré de
+     * `socket.channels` (`RealtimeClient#_remove`) et échappe donc par construction
+     * à `Socket#triggerChanError` et au routage des réponses. Le SDK Aurabase garde
+     * l'instance dans sa Map (`unsubscribe()` ne la retire pas, seul
+     * `removeChannel()` le fait), la garde est donc portée par le canal lui-même.
+     *
+     * `CLOSED` est la seule exception : il est émis précisément au moment où
+     * `_subscribed` bascule à `false` — d'où son émission directe dans
+     * `unsubscribe()`.
+     */
+    private _emitStatus;
     /** (Re)arme le compte à rebours d'attente de la confirmation `subscribed`. */
     private _armSubscribeTimeout;
     private _clearSubscribeTimeout;
@@ -251,6 +271,17 @@ declare class RealtimeService {
      * 30 s et répond au ping : la connexion est morte (TCP à demi-fermé).
      */
     private _awaitingPong;
+    /** Date du dernier message serveur reçu, pour le filet de liveness. */
+    private _lastServerMessageAt;
+    /**
+     * Filet de liveness, indépendant du `HeartbeatManager`.
+     *
+     * Sans lui, toute la détection de connexion morte reposait sur le tick du
+     * heartbeat — lui-même porté par un Worker. Un Worker tué silencieusement (par
+     * la pression mémoire d'un mobile, sans événement `error`) supprimait d'un coup
+     * le ping ET la détection : le heartbeat était un point unique de défaillance.
+     */
+    private _livenessGuard;
     /** Backoff delays in ms: 1s, 2s, 4s, 8s, 16s, 30s (cap) */
     private static readonly BACKOFF_MS;
     constructor(client: AuraClientLike);
@@ -298,6 +329,37 @@ declare class RealtimeService {
      * compter sur un `onclose` : une socket à demi-fermée n'en émet parfois jamais).
      */
     private _detachSocket;
+    /**
+     * Arme le filet de liveness pour `ws` : il ne juge que sur la date du dernier
+     * message reçu, donc il survit à la mort complète du heartbeat.
+     *
+     * Il vit sur le thread principal, qu'un navigateur throttle en arrière-plan :
+     * cela ne peut que le RETARDER, jamais provoquer un faux positif — le verdict
+     * porte sur une durée mesurée, pas sur le nombre de ticks écoulés.
+     */
+    private _startLivenessGuard;
+    private _stopLivenessGuard;
+    /** Annule le refresh proactif du token, s'il est armé. */
+    private _cancelTokenRefresh;
+    /**
+     * Bascule vers l'état terminal `disconnected` : plus aucune reconnexion n'est
+     * prévue, le service doit donc **cesser toute activité de fond**.
+     *
+     * Le point sensible est le refresh proactif du token. Le laisser courir n'est
+     * pas anodin : `auth.refreshSession()` frappe le backend, qui applique une
+     * ROTATION STRICTE — chaque refresh révoque l'ancien refresh token
+     * (`services/aura-auth/src/services/auth_service.rs`, « Rotation atomique (E2) »),
+     * et rejouer un token révoqué au-delà de la fenêtre de grâce déclenche
+     * `token_reuse_detected` → **révocation globale de toutes les sessions de
+     * l'utilisateur**. Comme `refreshToken()` replanifie systématiquement le timer,
+     * un service pourtant `disconnected` faisait tourner les jetons de la session à
+     * perpétuité, en tâche de fond, sans que personne ne l'ait demandé.
+     *
+     * En revanche le refresh est **conservé pendant une reconnexion** : le prochain
+     * handshake lit `authStore.token`, et un backoff un peu long laisserait sinon
+     * expirer le token — le ré-handshake partirait alors en 401.
+     */
+    private _goDisconnected;
     /**
      * Un tick de heartbeat : vérifie la liveness du lien puis émet un ping.
      *
@@ -404,14 +466,67 @@ declare class RealtimeService {
 
 /**
  * HeartbeatManager — pings périodiques pour maintenir la connexion WS.
- * Utilise un Worker dédié (anti-throttle des onglets en arrière-plan) ; fallback setInterval.
+ *
+ * Utilise un Worker dédié : les navigateurs throttlent agressivement les timers
+ * d'un onglet en arrière-plan (jusqu'à 1 tick/minute), ce qui ferait manquer le
+ * `heartbeat_timeout` de 60 s du serveur ; un Worker n'est pas soumis à ce
+ * throttling. Fallback `setInterval` quand le Worker est indisponible.
+ *
+ * ── Pourquoi trois filets et pas un ──────────────────────────────────────────
+ * Ce battement ne sert plus seulement à tenir la connexion ouverte : c'est aussi
+ * lui qui cadence la **détection de connexion morte** du `RealtimeService`. S'il
+ * se tait, le client ne ping plus (le serveur coupe à 60 s) *et* ne détecte plus
+ * rien. Les trois modes de défaillance d'un Worker sont donc couverts :
+ *
+ * 1. **Échec synchrone** (`new Worker` lève, `Worker` absent) → `try/catch`.
+ * 2. **Échec asynchrone** — le cas d'une CSP `worker-src` qui n'autorise pas
+ *    `blob:`. La spec HTML est explicite : quand le fetch du script échoue,
+ *    le constructeur **ne lève pas**, l'agent utilisateur déclenche un événement
+ *    `error` sur l'objet Worker. Un `try/catch` ne peut donc rien attraper →
+ *    `onerror` bascule sur le fallback.
+ * 3. **Worker inerte** — construit sans erreur mais qui ne poste jamais rien.
+ *    Aucun événement ne le signale : le Worker accuse donc réception du `start`
+ *    par un `ready` immédiat, et un chien de garde bascule si cet accusé
+ *    n'arrive pas.
+ *
+ * Le chien de garde porte sur le `ready`, PAS sur le premier battement : mesuré
+ * en Chromium réel, le démarrage d'un Worker peut dépasser 1,5 intervalle quand
+ * l'intervalle est court, ce qui faisait abandonner à tort un Worker
+ * parfaitement sain — et perdre silencieusement l'immunité au throttling, la
+ * seule raison d'être de ce Worker.
  */
 declare class HeartbeatManager {
     private _worker;
     private _workerUrl;
     private _interval;
     private _sendFn;
+    /** Chien de garde de l'accusé `ready` du Worker (mode de défaillance 3). */
+    private _watchdog;
+    /**
+     * Numéro du cycle start/stop courant. Un événement asynchrone (erreur de
+     * Worker, chien de garde) portant un numéro périmé appartient à un cycle déjà
+     * arrêté ou remplacé : il doit être ignoré, jamais ressusciter un heartbeat.
+     */
+    private _generation;
+    /**
+     * Délai accordé au Worker pour accuser réception du `start`.
+     *
+     * Volontairement **indépendant de l'intervalle de heartbeat** : c'est un temps
+     * de démarrage de thread, pas un multiple de la cadence. 3 s est très large
+     * pour un Worker sain (quelques millisecondes en pratique) tout en restant
+     * loin sous le `heartbeat_timeout` de 60 s du serveur.
+     */
+    private static readonly WORKER_READY_TIMEOUT_MS;
     start(sendPing: () => void, intervalMs?: number): void;
+    /**
+     * Abandonne le Worker et reprend le battement avec un `setInterval`.
+     * Idempotent et insensible aux cycles périmés.
+     */
+    private _fallbackFromWorker;
+    private _startFallback;
+    private _clearWatchdog;
+    /** Termine le Worker courant et libère l'URL d'objet associée. */
+    private _disposeWorker;
     stop(): void;
     get isActive(): boolean;
 }

package/dist/index.js

@@ -298,6 +298,29 @@ var AuraChannel = class {
     this._sendFn(JSON.stringify(msg));
     this._armSubscribeTimeout();
   }
+  /**
+   * Notifie le callback de statut d'abonnement, sauf si le canal est fermé.
+   *
+   * Un canal sorti par `unsubscribe()` est **soldé** : son cycle de vie s'est
+   * terminé sur `CLOSED`. Rien ne doit plus le faire parler — ni une erreur
+   * serveur globale rediffusée à tous les canaux, ni une confirmation `subscribed`
+   * encore en vol au moment du désabonnement. Sans cette garde, l'appelant voyait
+   * un `CHANNEL_ERROR` ou un `SUBSCRIBED` APRÈS le `CLOSED` de son propre canal.
+   *
+   * Parité `@supabase/realtime-js` : un canal quitté est retiré de
+   * `socket.channels` (`RealtimeClient#_remove`) et échappe donc par construction
+   * à `Socket#triggerChanError` et au routage des réponses. Le SDK Aurabase garde
+   * l'instance dans sa Map (`unsubscribe()` ne la retire pas, seul
+   * `removeChannel()` le fait), la garde est donc portée par le canal lui-même.
+   *
+   * `CLOSED` est la seule exception : il est émis précisément au moment où
+   * `_subscribed` bascule à `false` — d'où son émission directe dans
+   * `unsubscribe()`.
+   */
+  _emitStatus(status, err) {
+    if (!this._subscribed) return;
+    this._subscribeCallback?.(status, err);
+  }
   /** (Re)arme le compte à rebours d'attente de la confirmation `subscribed`. */
   _armSubscribeTimeout() {
     this._clearSubscribeTimeout();
@@ -324,8 +347,7 @@ var AuraChannel = class {
    */
   _signalError(err) {
     this._clearSubscribeTimeout();
-    if (!this._subscribed) return;
-    this._subscribeCallback?.("CHANNEL_ERROR", err);
+    this._emitStatus("CHANNEL_ERROR", err);
   }
   /** Unsubscribe from the channel. */
   unsubscribe() {
@@ -421,7 +443,7 @@ var AuraChannel = class {
         const subMsg = msg;
         if (subMsg.subscription_id) this._subscriptionId = subMsg.subscription_id;
         this._clearSubscribeTimeout();
-        this._subscribeCallback?.("SUBSCRIBED");
+        this._emitStatus("SUBSCRIBED");
         break;
       }
       case "event": {
@@ -440,6 +462,7 @@ var AuraChannel = class {
         break;
       }
       case "presence_state": {
+        if (!this._subscribed) break;
         const presMsg = msg;
         if (presMsg.presences) {
           this._presenceState = {};
@@ -459,7 +482,7 @@ var AuraChannel = class {
       case "error": {
         const errMsg = msg;
         this._clearSubscribeTimeout();
-        this._subscribeCallback?.("CHANNEL_ERROR", new Error(errMsg.message ?? "Unknown error"));
+        this._emitStatus("CHANNEL_ERROR", new Error(errMsg.message ?? "Unknown error"));
         break;
       }
       case "token_refreshed":
@@ -599,44 +622,87 @@ var AuraChannel = class {
 };
 
 // src/HeartbeatManager.ts
-var HeartbeatManager = class {
+var HeartbeatManager = class _HeartbeatManager {
   _worker = null;
   _workerUrl = null;
   _interval = null;
   _sendFn = null;
+  /** Chien de garde de l'accusé `ready` du Worker (mode de défaillance 3). */
+  _watchdog = null;
+  /**
+   * Numéro du cycle start/stop courant. Un événement asynchrone (erreur de
+   * Worker, chien de garde) portant un numéro périmé appartient à un cycle déjà
+   * arrêté ou remplacé : il doit être ignoré, jamais ressusciter un heartbeat.
+   */
+  _generation = 0;
+  /**
+   * Délai accordé au Worker pour accuser réception du `start`.
+   *
+   * Volontairement **indépendant de l'intervalle de heartbeat** : c'est un temps
+   * de démarrage de thread, pas un multiple de la cadence. 3 s est très large
+   * pour un Worker sain (quelques millisecondes en pratique) tout en restant
+   * loin sous le `heartbeat_timeout` de 60 s du serveur.
+   */
+  static WORKER_READY_TIMEOUT_MS = 3e3;
   start(sendPing, intervalMs = 25e3) {
     this.stop();
+    const generation = ++this._generation;
     this._sendFn = sendPing;
     if (typeof Worker !== "undefined" && typeof URL !== "undefined" && typeof URL.createObjectURL === "function") {
       try {
-        const code = `let i=null;onmessage=(e)=>{if(e.data.type==='start'){if(i)clearInterval(i);i=setInterval(()=>postMessage('ping'),e.data.interval||25000);}else if(e.data.type==='stop'){if(i){clearInterval(i);i=null;}}};`;
+        const code = `let i=null;onmessage=(e)=>{if(e.data.type==='start'){if(i)clearInterval(i);postMessage('ready');i=setInterval(()=>postMessage('ping'),e.data.interval||25000);}else if(e.data.type==='stop'){if(i){clearInterval(i);i=null;}}};`;
         const blob = new Blob([code], { type: "application/javascript" });
         this._workerUrl = URL.createObjectURL(blob);
-        this._worker = new Worker(this._workerUrl);
-        this._worker.onmessage = () => {
+        const worker = new Worker(this._workerUrl);
+        this._worker = worker;
+        worker.onmessage = (evt) => {
+          if (generation !== this._generation) return;
+          this._clearWatchdog();
+          if (evt?.data === "ready") return;
           this._sendFn?.();
         };
-        this._worker.postMessage({ type: "start", interval: intervalMs });
+        worker.onerror = () => {
+          this._fallbackFromWorker(generation, intervalMs);
+        };
+        worker.postMessage({ type: "start", interval: intervalMs });
+        this._watchdog = setTimeout(
+          () => this._fallbackFromWorker(generation, intervalMs),
+          _HeartbeatManager.WORKER_READY_TIMEOUT_MS
+        );
         return;
       } catch {
-        this._worker = null;
-        if (this._workerUrl) {
-          try {
-            URL.revokeObjectURL(this._workerUrl);
-          } catch {
-          }
-          this._workerUrl = null;
-        }
+        this._disposeWorker();
       }
     }
+    this._startFallback(intervalMs);
+  }
+  /**
+   * Abandonne le Worker et reprend le battement avec un `setInterval`.
+   * Idempotent et insensible aux cycles périmés.
+   */
+  _fallbackFromWorker(generation, intervalMs) {
+    if (generation !== this._generation) return;
+    if (this._interval) return;
+    if (!this._sendFn) return;
+    this._clearWatchdog();
+    this._disposeWorker();
+    this._startFallback(intervalMs);
+  }
+  _startFallback(intervalMs) {
     this._interval = setInterval(() => {
       this._sendFn?.();
     }, intervalMs);
   }
-  stop() {
+  _clearWatchdog() {
+    if (this._watchdog) {
+      clearTimeout(this._watchdog);
+      this._watchdog = null;
+    }
+  }
+  /** Termine le Worker courant et libère l'URL d'objet associée. */
+  _disposeWorker() {
     if (this._worker) {
       try {
-        this._worker.postMessage({ type: "stop" });
         this._worker.terminate();
       } catch {
       }
@@ -649,6 +715,17 @@ var HeartbeatManager = class {
       }
       this._workerUrl = null;
     }
+  }
+  stop() {
+    this._generation++;
+    this._clearWatchdog();
+    if (this._worker) {
+      try {
+        this._worker.postMessage({ type: "stop" });
+      } catch {
+      }
+    }
+    this._disposeWorker();
     if (this._interval) {
       clearInterval(this._interval);
       this._interval = null;
@@ -709,6 +786,8 @@ var RealtimeConnectionError = class _RealtimeConnectionError extends Error {
 // src/RealtimeService.ts
 var HEARTBEAT_INTERVAL_MS = 25e3;
 var MAX_TIMEOUT_MS = 2147483647;
+var LIVENESS_GUARD_INTERVAL_MS = 3e4;
+var LIVENESS_MAX_SILENCE_MS = 9e4;
 var RealtimeService = class _RealtimeService {
   client;
   _ws = null;
@@ -734,6 +813,17 @@ var RealtimeService = class _RealtimeService {
    * 30 s et répond au ping : la connexion est morte (TCP à demi-fermé).
    */
   _awaitingPong = false;
+  /** Date du dernier message serveur reçu, pour le filet de liveness. */
+  _lastServerMessageAt = 0;
+  /**
+   * Filet de liveness, indépendant du `HeartbeatManager`.
+   *
+   * Sans lui, toute la détection de connexion morte reposait sur le tick du
+   * heartbeat — lui-même porté par un Worker. Un Worker tué silencieusement (par
+   * la pression mémoire d'un mobile, sans événement `error`) supprimait d'un coup
+   * le ping ET la détection : le heartbeat était un point unique de défaillance.
+   */
+  _livenessGuard = null;
   /** Backoff delays in ms: 1s, 2s, 4s, 8s, 16s, 30s (cap) */
   static BACKOFF_MS = [1e3, 2e3, 4e3, 8e3, 16e3, 3e4];
   constructor(client) {
@@ -838,7 +928,9 @@ var RealtimeService = class _RealtimeService {
       this._reconnectAttempts = 0;
       this._setState("connected");
       this._awaitingPong = false;
+      this._lastServerMessageAt = Date.now();
       this._heartbeat.start(() => this._heartbeatTick(ws), HEARTBEAT_INTERVAL_MS);
+      this._startLivenessGuard(ws);
       this._scheduleTokenRefresh();
       for (const channel of this._channels.values()) {
         channel._bindSend((data) => this._send(data));
@@ -850,6 +942,7 @@ var RealtimeService = class _RealtimeService {
     ws.onmessage = (evt) => {
       if (ws !== this._ws) return;
       this._awaitingPong = false;
+      this._lastServerMessageAt = Date.now();
       try {
         const raw = typeof evt.data === "string" ? evt.data : "";
         const msg = JSON.parse(raw);
@@ -878,12 +971,12 @@ var RealtimeService = class _RealtimeService {
         );
       }
       if (intentional || this._intentionalClose) {
-        this._setState("disconnected");
+        this._goDisconnected();
         this._intentionalClose = false;
       } else if (this._autoReconnect) {
         this._scheduleReconnect();
       } else {
-        this._setState("disconnected");
+        this._goDisconnected();
       }
     };
     ws.onerror = (evt) => {
@@ -903,6 +996,61 @@ var RealtimeService = class _RealtimeService {
     this._lastSentToken = null;
     this._awaitingPong = false;
     this._heartbeat.stop();
+    this._stopLivenessGuard();
+  }
+  /**
+   * Arme le filet de liveness pour `ws` : il ne juge que sur la date du dernier
+   * message reçu, donc il survit à la mort complète du heartbeat.
+   *
+   * Il vit sur le thread principal, qu'un navigateur throttle en arrière-plan :
+   * cela ne peut que le RETARDER, jamais provoquer un faux positif — le verdict
+   * porte sur une durée mesurée, pas sur le nombre de ticks écoulés.
+   */
+  _startLivenessGuard(ws) {
+    this._stopLivenessGuard();
+    this._livenessGuard = setInterval(() => {
+      if (ws !== this._ws) return;
+      const silence = Date.now() - this._lastServerMessageAt;
+      if (silence < LIVENESS_MAX_SILENCE_MS) return;
+      this._handleDeadConnection(
+        `Realtime : aucun message du serveur depuis ${Math.round(silence / 1e3)} s alors qu'il en pousse un toutes les 30 s \u2014 connexion consid\xE9r\xE9e morte. Reconnexion.`
+      );
+    }, LIVENESS_GUARD_INTERVAL_MS);
+  }
+  _stopLivenessGuard() {
+    if (this._livenessGuard) {
+      clearInterval(this._livenessGuard);
+      this._livenessGuard = null;
+    }
+  }
+  /** Annule le refresh proactif du token, s'il est armé. */
+  _cancelTokenRefresh() {
+    if (this._tokenRefreshTimer) {
+      clearTimeout(this._tokenRefreshTimer);
+      this._tokenRefreshTimer = null;
+    }
+  }
+  /**
+   * Bascule vers l'état terminal `disconnected` : plus aucune reconnexion n'est
+   * prévue, le service doit donc **cesser toute activité de fond**.
+   *
+   * Le point sensible est le refresh proactif du token. Le laisser courir n'est
+   * pas anodin : `auth.refreshSession()` frappe le backend, qui applique une
+   * ROTATION STRICTE — chaque refresh révoque l'ancien refresh token
+   * (`services/aura-auth/src/services/auth_service.rs`, « Rotation atomique (E2) »),
+   * et rejouer un token révoqué au-delà de la fenêtre de grâce déclenche
+   * `token_reuse_detected` → **révocation globale de toutes les sessions de
+   * l'utilisateur**. Comme `refreshToken()` replanifie systématiquement le timer,
+   * un service pourtant `disconnected` faisait tourner les jetons de la session à
+   * perpétuité, en tâche de fond, sans que personne ne l'ait demandé.
+   *
+   * En revanche le refresh est **conservé pendant une reconnexion** : le prochain
+   * handshake lit `authStore.token`, et un backoff un peu long laisserait sinon
+   * expirer le token — le ré-handshake partirait alors en 401.
+   */
+  _goDisconnected() {
+    this._cancelTokenRefresh();
+    this._setState("disconnected");
   }
   /**
    * Un tick de heartbeat : vérifie la liveness du lien puis émet un ping.
@@ -953,7 +1101,7 @@ var RealtimeService = class _RealtimeService {
       this._scheduleReconnect();
     } else {
       this._intentionalClose = false;
-      this._setState("disconnected");
+      this._goDisconnected();
     }
   }
   /** Send raw data through the WebSocket. */
@@ -1033,10 +1181,7 @@ var RealtimeService = class _RealtimeService {
    * Prevents token expiration during an active WebSocket session.
    */
   _scheduleTokenRefresh() {
-    if (this._tokenRefreshTimer) {
-      clearTimeout(this._tokenRefreshTimer);
-      this._tokenRefreshTimer = null;
-    }
+    this._cancelTokenRefresh();
     const token = this.client.authStore.token;
     if (!token) return;
     const exp = getTokenExpiryMs(token);
@@ -1069,7 +1214,7 @@ var RealtimeService = class _RealtimeService {
       this._reconnectTimer = null;
     }
     if (this._reconnectAttempts >= this._maxReconnectAttempts) {
-      this._setState("disconnected");
+      this._goDisconnected();
       return;
     }
     this._reconnectAttempts++;
@@ -1092,10 +1237,8 @@ var RealtimeService = class _RealtimeService {
   disconnect() {
     this._intentionalClose = true;
     this._heartbeat.stop();
-    if (this._tokenRefreshTimer) {
-      clearTimeout(this._tokenRefreshTimer);
-      this._tokenRefreshTimer = null;
-    }
+    this._stopLivenessGuard();
+    this._cancelTokenRefresh();
     if (this._reconnectTimer) {
       clearTimeout(this._reconnectTimer);
       this._reconnectTimer = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aurabase/realtime",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Service temps réel du SDK Aurabase (postgres_changes, broadcast, presence)",
   "type": "module",
   "main": "dist/index.cjs",
@@ -45,9 +45,10 @@
     "realtime"
   ],
   "dependencies": {
-    "@aurabase/core": "0.4.0"
+    "@aurabase/core": "0.4.1"
   },
   "devDependencies": {
+    "@types/node": "20.14.15",
     "tsup": "^8.0.0",
     "typescript": "^5.5.0",
     "vitest": "^4.1.6"
@@ -55,6 +56,7 @@
   "scripts": {
     "build": "tsup",
     "test": "vitest run --passWithNoTests",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "typecheck:tests": "tsc --noEmit -p tsconfig.test.json"
   }
 }