@aurabase/realtime 0.4.1 → 0.5.1

package/README.md

@@ -23,7 +23,7 @@ npm i @aurabase/realtime
 ```ts
 import { createClient } from '@aurabase/aurabase-js'
 
-const aura = createClient('http://localhost:8080', 'my-project', 'aura_anon_xxx')
+const aura = createClient('https://mon-projet.aurabase.cloud', 'aura_anon_xxx')
 ```
 
 ### Connexion
@@ -162,21 +162,108 @@ room
   })
   .subscribe()
 
-// 'ok' | 'timeout' | 'error' — résout à l'ACK serveur si broadcast.ack est activé sur le channel.
+// Résout à l'ACK serveur si broadcast.ack est activé ET le canal abonné (voir ci-dessous).
 const status = await room.send({ type: 'broadcast', event: 'cursor-pos', payload: { x: 100, y: 200 } })
 ```
 
+##### Statuts rendus par `send()`
+
+| Statut | Signification | Le message est-il parti ? |
+| --- | --- | --- |
+| `'ok'` | Sans `ack` : remis au transport. Avec `ack` : le serveur a répondu `broadcast_ack`. | oui |
+| `'timeout'` | `ack` demandé sur un canal abonné, aucun accusé reçu en 5 s : l'accusé s'est **perdu** (lien coupé, serveur saturé). | oui |
+| `'not_connected'` | Aucun transport lié, ou socket non-OPEN — le message a été **jeté**. | **non** |
+| `'requires_subscription'` | Le serveur n'a **pas d'abonnement** pour ce canal : jamais souscrit, souscription **refusée** (RLS, `private_only`, quota) ou **révoquée** depuis (voir ci-dessous). | **non** |
+| `'error'` | L'envoi a levé (sérialisation, transport en erreur). | non |
+
+Avant la remédiation C18/N24, ces trois derniers cas rendaient tous `'error'` (et le
+message jeté sur une socket fermée rendait même `'ok'`) : l'appelant ne pouvait ni les
+distinguer, ni savoir si son message était parti.
+
+##### Toute écriture exige un canal ABONNÉ
+
+`.subscribe()` d'abord, `.send()` / `.track()` ensuite. Le serveur refuse un broadcast émis
+sur un canal auquel la connexion n'est pas abonnée
+(`Non abonné au canal '…' — Subscribe requis avant Broadcast`), et le SDK ne l'émet donc
+même pas :
+
+```ts
+const room = aura.realtime.channel('room-1', { broadcast: { ack: true } })
+
+await room.send({ type: 'broadcast', event: 'x', payload: {} })
+// → 'requires_subscription' (immédiat) : rien n'est parti.
+
+room.subscribe()
+await room.send({ type: 'broadcast', event: 'x', payload: {} }) // → 'ok'
+```
+
+Le même statut est rendu quand le SERVEUR **refuse** l'abonnement (canal privé sans droit
+RLS, projet `private_only`, quota de canaux) ou le **révoque** ensuite (ré-évaluation RLS au
+refresh de token) : le canal a alors reçu `CHANNEL_ERROR`, et toute écriture ultérieure rend
+`'requires_subscription'` immédiatement — elle n'attend pas les 5 s d'un accusé que le
+serveur n'émettra jamais. Écrivez donc depuis le callback de statut, comme chez Supabase :
+
+```ts
+room.subscribe(async (statut) => {
+  if (statut !== 'SUBSCRIBED') return // CHANNEL_ERROR : le serveur a refusé ce canal
+  await room.send({ type: 'broadcast', event: 'x', payload: {} }) // → 'ok'
+})
+```
+
+Ce n'est pas une limitation arbitraire, c'est la condition d'un contrôle d'accès qui tienne :
+les policies RLS d'un canal privé sont calculées **à l'abonnement** et mises en cache dans la
+subscription de la connexion. Sans abonnement, le serveur n'a aucune policy à consulter — et
+laisser passer reviendrait à n'appliquer le contrôle qu'aux clients qui s'abonnent (c'était
+le défaut N28 : un client jamais abonné diffusait sur un canal privé). C'est aussi le modèle
+de `@supabase/realtime-js` : phoenix exige le `join` avant tout `push`, et `send()` bascule
+sur l'endpoint HTTP quand le canal n'est pas rejoint. Le pendant Aurabase de cet endpoint est
+`httpBroadcast()`, ci-dessous — lui aussi soumis à la RLS sur les projets `private_only`.
+
+##### `private_only` — l'autorité sur la privauté est au SERVEUR
+
+`{ private: true }` est une DEMANDE du client : elle déclenche le contrôle RLS pour *cette*
+connexion. Elle ne rend pas le canal privé pour les autres — un client qui s'abonne au même
+canal sans `private` reste, par défaut, un abonné public. Pour que la privauté soit imposée
+à tous, activez le réglage de projet (table `realtime_config` du schéma `_platform`, hors de
+portée des rôles `anon`/`authenticated`) :
+
+```sql
+INSERT INTO "project_<id>_platform".realtime_config (key, value)
+VALUES ('private_only', 'true')
+ON CONFLICT (key) DO UPDATE SET value = excluded.value;
+```
+
+Tout abonnement public est alors refusé (`Canal public refusé : ce projet est configuré en
+private_only`), et les chemins REST (`httpBroadcast`, roster de présence) ainsi que le flux
+SSE passent par la même policy RLS. Même modèle que le réglage `private_only` de Supabase
+Realtime (`PrivateOnly`).
+
 #### Broadcast HTTP (sans WebSocket)
 
 Émet un broadcast via REST, sans connexion WebSocket ouverte — utile côté serveur/edge.
 
 ```ts
-// POST /v1/realtime/{projectId}/broadcast — pas besoin de connect().
+// POST /v1/realtime/broadcast — pas besoin de connect().
 const { error } = await aura.realtime.httpBroadcast('room-1', 'cursor-pos', { x: 10, y: 20 })
 if (error) console.error(error) // 4xx / rate-limit surfacés proprement
 ```
 
-Le nom de canal est préfixé par le projet automatiquement s'il ne l'est pas déjà.
+**Le canal doit porter le projet.** Le serveur exige `channel` préfixé par
+`"<project_id>:"` et répond sinon `403 « Le canal n'appartient pas à ce projet »`
+(`handlers/broadcast.rs`).
+
+- **Avec une session** : le préfixe est ajouté ici, lu dans le claim `project_id` du jeton.
+  Un canal déjà qualifié n'est pas préfixé deux fois.
+- **Sans session — le cas serveur/edge** : le SDK n'a aucun identifiant de projet (l'URL est
+  la seule désignation du tenant côté client), et il ne peut donc rien préfixer.
+  `httpBroadcast` **refuse** alors localement, sans appel réseau
+  (`error.code === 'realtime_channel_non_qualifie'`), plutôt que d'aller chercher un `403`
+  dont le message ne nomme pas la forme attendue. Qualifiez le canal vous-même :
+
+```ts
+// Serveur / edge : clé service_role, aucune session utilisateur.
+await aura.realtime.httpBroadcast(`${PROJECT_ID}:room-1`, 'cursor-pos', { x: 10, y: 20 })
+```
 
 ### Canaux privés (`setAuth`)