@aurabase/realtime 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { ChannelConfig, PostgresChangesFilter, RealtimeEvent, BroadcastFilter, PresenceFilter, SubscribeCallback, BroadcastPayload, PresenceState, ServerMessage, RealtimeListenType, AuraClientLike, AuraResponse } from '@aurabase/core';
+import { ChannelConfig, PostgresChangesFilter, RealtimeEvent, BroadcastFilter, PresenceFilter, PresenceState, SubscribeCallback, BroadcastPayload, BroadcastSendStatus, ServerMessage, RealtimeListenType, AuraClientLike, AuraResponse } from '@aurabase/core';
 
 type ListenerCallback = (payload: RealtimeEvent | Record<string, unknown>) => void;
 type ListenerEntry = {
@@ -6,7 +6,15 @@ type ListenerEntry = {
     filter: PostgresChangesFilter | BroadcastFilter | PresenceFilter;
     callback: ListenerCallback;
 };
-type SendFn = (data: string) => void;
+/**
+ * Fonction d'émission fournie par `RealtimeService`.
+ *
+ * Retourne `false` lorsque le message n'a **pas** été remis à la socket (socket absente
+ * ou non-OPEN — `RealtimeService._send` jette silencieusement ce qu'il ne peut pas
+ * émettre). Tout autre retour (`true`, `undefined`…) vaut « remis au transport » : les
+ * transports de test qui ne retournent rien restent valides.
+ */
+type SendFn = (data: string) => boolean | void;
 /**
  * Délai par défaut d'attente de la confirmation `subscribed` avant d'émettre
  * `TIMED_OUT`. Aligné sur `DEFAULT_TIMEOUT` de `@supabase/realtime-js`
@@ -35,7 +43,7 @@ declare const DEFAULT_SUBSCRIBE_TIMEOUT_MS = 10000;
  */
 declare class AuraChannel {
     readonly name: string;
-    private readonly _projectId;
+    private readonly _projectPrefix;
     private readonly _listeners;
     private _subscribed;
     private _sendFn;
@@ -51,8 +59,18 @@ declare class AuraChannel {
     private _refCounter;
     /** Dernier event ID recu — utilise pour since_id au reconnect */
     private _lastEventId;
-    /** Pending ACK callbacks : ref_id → resolve */
+    /** Pending ACK callbacks : ref_id → solde la promesse de `send()` avec un statut. */
     private _pendingAcks;
+    /**
+     * Abonnement vu par le SERVEUR — à ne pas confondre avec `_subscribed`, qui n'est que
+     * l'INTENTION de l'appelant (et pilote le re-subscribe après reconnexion).
+     *
+     * C18 (rejeu) : `_subscribed` était posé optimistement par `subscribe()` et n'était
+     * jamais infirmé quand le serveur REFUSAIT l'abonnement. `send({ ack })` armait alors un
+     * compte à rebours de 5 s pour un accusé structurellement impossible — mesuré sur le banc
+     * à 5 065 ms, alors que le serveur avait répondu en 6 ms « Non abonné au canal … ».
+     */
+    private _serverState;
     /**
      * Timer d'attente de la confirmation `subscribed`. Armé à l'ENVOI effectif du
      * message subscribe (parité phoenix : `Push#startTimeout` ne démarre qu'au
@@ -63,7 +81,14 @@ declare class AuraChannel {
     private _subscribeTimeoutMs;
     /** `CLOSED` n'est émis qu'une fois par cycle de vie du canal (unsubscribe idempotent). */
     private _closedEmitted;
-    constructor(name: string, projectId: string, options?: ChannelConfig);
+    /**
+     * @param projectPrefix Préfixe de projet du canal sur le fil (`"<project_id>:"`, ou `""`
+     *   s'il est inconnu), résolu PARESSEUSEMENT : le SDK ne connaît le projet qu'à travers
+     *   le token de session, qui peut arriver après la création du canal (connexion
+     *   différée). Une valeur figée à la construction serait alors périmée pour toujours,
+     *   le canal étant mémorisé par `RealtimeService`.
+     */
+    constructor(name: string, projectPrefix: () => string, options?: ChannelConfig);
     /** Génère un ref_id unique pour la corrélation request/response. */
     private _nextRef;
     /** Full channel name with project prefix (for server protocol) */
@@ -74,7 +99,7 @@ declare class AuraChannel {
      */
     on(type: 'postgres_changes', filter: PostgresChangesFilter, callback: (payload: RealtimeEvent) => void): this;
     on(type: 'broadcast', filter: BroadcastFilter, callback: (payload: RealtimeEvent) => void): this;
-    on(type: 'presence', filter: PresenceFilter, callback: (payload: any) => void): this;
+    on(type: 'presence', filter: PresenceFilter, callback: (payload: PresenceState | RealtimeEvent | Record<string, unknown>) => void): this;
     /**
      * Subscribe to the channel. Sends the Subscribe message to the server
      * with the full config (postgres_changes, broadcast, presence).
@@ -95,6 +120,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;
@@ -111,19 +156,36 @@ declare class AuraChannel {
     /** Unsubscribe from the channel. */
     unsubscribe(): void;
     /**
-     * Send a broadcast message to the channel.
-     * If broadcast.ack=true, returns a Promise that resolves when the server ACKs.
+     * Envoie un message broadcast sur le canal.
+     *
+     * Avec `broadcast: { ack: true }`, la promesse ne se résout qu'à l'accusé de réception du
+     * serveur (`broadcast_ack`) ; sans `ack`, elle se résout dès la remise au transport.
+     *
+     * Le statut rendu nomme sa CAUSE — voir {@link BroadcastSendStatus} :
+     * `'ok'`, `'timeout'`, `'not_connected'`, `'requires_subscription'`, `'error'`.
+     *
+     * **`'requires_subscription'`** signifie que le serveur n'a pas d'abonnement pour ce canal
+     * — soit `.subscribe()` n'a jamais été appelé, soit le serveur l'a REFUSÉ (RLS,
+     * `private_only`, quota) ou révoqué depuis. Rien n'est émis dans ce cas : le serveur
+     * rejetterait l'écriture (`Non abonné au canal '…' — Subscribe requis avant Broadcast`).
      *
      * @example
      * ```ts
-     * // Without ACK (fire & forget)
+     * // Sans ACK (fire & forget)
      * channel.send({ type: 'broadcast', event: 'cursor-pos', payload: { x: 100, y: 200 } })
      *
-     * // With ACK (wait for server confirmation)
-     * await channel.send({ type: 'broadcast', event: 'cursor-pos', payload: { x: 100 } })
+     * // Avec ACK — le modèle est celui de Supabase : on écrit APRÈS SUBSCRIBED.
+     * channel.subscribe(async (statut) => {
+     *   if (statut !== 'SUBSCRIBED') return // CHANNEL_ERROR = le serveur a refusé ce canal
+     *   const status = await channel.send({ type: 'broadcast', event: 'cursor-pos', payload: { x: 100 } })
+     *   if (status === 'requires_subscription') {
+     *     // l'abonnement a été refusé ou révoqué entre-temps ; la cause a été remontée en
+     *     // CHANNEL_ERROR à ce même callback.
+     *   }
+     * })
      * ```
      */
-    send(message: BroadcastPayload): Promise<'ok' | 'timeout' | 'error'>;
+    send(message: BroadcastPayload): Promise<BroadcastSendStatus>;
     /**
      * Track presence state for this client.
      * Returns a Promise that resolves with 'ok' once tracked (compatible Supabase).
@@ -134,12 +196,20 @@ declare class AuraChannel {
      * ```
      */
     track(state: Record<string, unknown>): Promise<'ok' | 'error'>;
-    /** Stop tracking presence. */
+    /** Stop tracking presence. Même contrat que `track()`. */
     untrack(): Promise<'ok' | 'error'>;
     /** Get the current presence state for this channel. */
     presenceState(): PresenceState;
     /** Called by RealtimeService when a server message arrives for this channel. */
     _onMessage(msg: ServerMessage): void;
+    /**
+     * Solde TOUS les accusés en attente de ce canal avec un statut donné.
+     *
+     * Le protocole ne corrèle pas l'erreur serveur au `ref_id` de l'écriture refusée : quand
+     * le serveur déclare n'avoir aucun abonnement pour ce canal, AUCUN accusé en vol ne peut
+     * plus aboutir — les solder tous est donc exact, pas approximatif.
+     */
+    private _settlePendingAcks;
     /** Dispatch a RealtimeEvent to matching listeners. */
     private _dispatchEvent;
     /** Whether this channel has been subscribed. */
@@ -189,6 +259,73 @@ declare class RealtimeConnectionError extends Error {
     });
 }
 
+/**
+ * HeartbeatManager — pings périodiques pour maintenir la connexion WS.
+ *
+ * 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;
+}
+
 /** Connection state machine */
 type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
 /**
@@ -211,7 +348,7 @@ declare const HEARTBEAT_INTERVAL_MS = 25000;
  *
  * @example
  * ```ts
- * const aura = createClient('http://localhost:8080', 'my-project')
+ * const aura = createClient('https://mon-projet.aurabase.cloud', 'aura_anon_xxx')
  *
  * const channel = aura.realtime.channel('room-1')
  *   .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'messages' }, (payload) => {
@@ -251,6 +388,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);
@@ -289,6 +437,17 @@ declare class RealtimeService {
      * la diffusion ni la boucle de reconnexion.
      */
     private _emitError;
+    /**
+     * Préfixe `"<project_id>:"` des noms de canaux sur le fil, `""` s'il est inconnu.
+     *
+     * `aura-realtime` exige que tout canal commence par le `project_id` du TOKEN
+     * (`handlers/websocket.rs`, `expected_prefix` ; idem pour le broadcast HTTP,
+     * `handlers/broadcast.rs`). Le SDK ne porte plus d'identifiant de projet — le projet est
+     * celui de l'URL — mais le token de session, lui, porte ce claim : on le lit là, dans le
+     * même jeton que celui envoyé au serveur. Sans token (pas encore connecté), il n'y a rien
+     * à préfixer ; la connexion WS échouerait de toute façon, le serveur exigeant un JWT.
+     */
+    private _projectPrefix;
     private get _wsUrl();
     /** Ensure the WebSocket connection is open. */
     connect(): void;
@@ -298,6 +457,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.
      *
@@ -318,7 +508,15 @@ declare class RealtimeService {
      * puis on relance le cycle de reconnexion nous-mêmes.
      */
     private _handleDeadConnection;
-    /** Send raw data through the WebSocket. */
+    /**
+     * Send raw data through the WebSocket.
+     *
+     * @returns `true` si le message a été remis à la socket, `false` s'il a été **jeté**
+     * (socket absente ou non-OPEN). Ce retour n'est pas cosmétique : sans lui,
+     * `AuraChannel.send()`/`track()` rendaient `'ok'` pour un message qui n'avait jamais
+     * quitté le process — la seule branche de `send()` capable de rendre `'error'` était
+     * une exception que ce `_send` ne lève jamais (C18/N24).
+     */
     private _send;
     /** Refresh the JWT token on an existing connection (no disconnect). */
     refreshToken(token: string): void;
@@ -347,18 +545,46 @@ declare class RealtimeService {
      * Envoie un broadcast par HTTP (REST), sans connexion WebSocket ouverte
      * (parité `@supabase/realtime-js`). Utile côté serveur/edge.
      *
-     * POST `/v1/realtime/{projectId}/broadcast` avec le contrat du handler backend
+     * POST `/v1/realtime/broadcast` avec le contrat du handler backend
      * (`broadcast.rs`) : `{ channel, payload }`, `channel` préfixé par le projet,
      * `event` replié dans `payload` (aligné sur le broadcast WS).
      *
-     * @param channel Nom du canal (préfixé projet automatiquement si absent).
+     * ### Le canal DOIT porter le projet — y compris hors session (K2)
+     *
+     * Le handler exige `channel.starts_with("{project_id}:")` et répond sinon
+     * `403 « Le canal n'appartient pas à ce projet »`
+     * (`services/aura-realtime/src/handlers/broadcast.rs`, fonction `broadcast`).
+     *
+     * Avec une session, ce préfixe est ajouté ici même : il est lu dans le claim
+     * `project_id` du jeton (voir {@link _projectPrefix}).
+     *
+     * **Sans session — le cas d'usage serveur/edge de cette méthode** — le SDK n'a AUCUN
+     * identifiant de projet : l'URL est la seule désignation du tenant côté client, et rien
+     * ne la traduit en `project_id` (c'est la passerelle qui fait cette résolution, à partir
+     * de l'hôte). L'authentification, elle, passe : pour le realtime, la passerelle forge un
+     * JWT interne à partir des claims de la clé API et écrase l'`Authorization`
+     * (`aura-gateway/src/proxy/sse_proxy.rs::do_http_proxy`). Émettre un canal nu produisait
+     * donc un `403` dont le message ne nomme jamais la forme attendue.
+     *
+     * Cette méthode **refuse** désormais ce cas, sans appel réseau
+     * (`error.code === 'realtime_channel_non_qualifie'`) : passez le canal déjà qualifié,
+     * `"<project_id>:<canal>"`. Cette forme est acceptée dans les deux situations — avec une
+     * session, elle n'est pas préfixée une seconde fois.
+     *
+     * @param channel Nom du canal. Avec une session : nom nu ou déjà qualifié. Sans session :
+     *                OBLIGATOIREMENT `"<project_id>:<canal>"`.
      * @param event   Nom de l'événement broadcast.
      * @param payload Données de l'événement.
-     * @returns `AuraResponse<null>` — `error` non nul en cas de 4xx/rate-limit.
+     * @returns `AuraResponse<null>` — `error` non nul en cas de 4xx/rate-limit, ou de canal
+     *          non qualifiable (refus local, aucun appel réseau).
      *
      * @example
      * ```ts
+     * // Navigateur, utilisateur connecté : le projet vient du jeton de session.
      * await aura.realtime.httpBroadcast('room-1', 'cursor', { x: 10, y: 20 })
+     *
+     * // Serveur / edge (clé service_role, aucune session) : qualifier le canal.
+     * await aura.realtime.httpBroadcast(`${PROJECT_ID}:room-1`, 'cursor', { x: 10, y: 20 })
      * ```
      */
     httpBroadcast(channel: string, event: string, payload?: Record<string, unknown>): Promise<AuraResponse<null>>;
@@ -391,29 +617,6 @@ declare class RealtimeService {
     removeAllChannels(): void;
     /** Route incoming server messages to the correct channel. */
     private _dispatch;
-    /**
-     * Simple callback-based subscription (legacy API).
-     * Prefer using `.channel().on().subscribe()` instead.
-     *
-     * @deprecated Use `channel().on().subscribe()` instead.
-     */
-    on<T = Record<string, unknown>>(channelName: string, callback: (event: any) => void): {
-        unsubscribe: () => void;
-    };
-}
-
-/**
- * HeartbeatManager — pings périodiques pour maintenir la connexion WS.
- * Utilise un Worker dédié (anti-throttle des onglets en arrière-plan) ; fallback setInterval.
- */
-declare class HeartbeatManager {
-    private _worker;
-    private _workerUrl;
-    private _interval;
-    private _sendFn;
-    start(sendPing: () => void, intervalMs?: number): void;
-    stop(): void;
-    get isActive(): boolean;
 }
 
 export { AuraChannel, type ConnectionState, DEFAULT_SUBSCRIBE_TIMEOUT_MS, HEARTBEAT_INTERVAL_MS, HeartbeatManager, RealtimeConnectionError, type RealtimeErrorPhase, RealtimeService };