@aurabase/aurabase-js 0.3.0

package/packages/realtime/src/RealtimeService.ts

@@ -0,0 +1,505 @@
+import type { AuraClientLike, AuraResponse } from '@aurabase/core'
+import type { ServerMessage, ChannelConfig, BroadcastAckMessage } from '@aurabase/core'
+import { fetchWithAuth } from '@aurabase/core'
+import { AuraChannel } from './AuraChannel'
+import { HeartbeatManager } from './HeartbeatManager'
+
+/** Connection state machine */
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting'
+
+/**
+ * Realtime service — manages a single WebSocket connection and multiplexes
+ * channels on top of it. Supabase-compatible API.
+ *
+ * @example
+ * ```ts
+ * const aura = createClient('http://localhost:8080', 'my-project')
+ *
+ * const channel = aura.realtime.channel('room-1')
+ *   .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'messages' }, (payload) => {
+ *     console.log('New message:', payload)
+ *   })
+ *   .on('broadcast', { event: 'cursor-pos' }, (payload) => {
+ *     console.log('Cursor:', payload)
+ *   })
+ *   .subscribe((status) => {
+ *     if (status === 'SUBSCRIBED') {
+ *       channel.send({ type: 'broadcast', event: 'cursor-pos', payload: { x: 100, y: 200 } })
+ *     }
+ *   })
+ * ```
+ */
+export class RealtimeService {
+  private readonly client: AuraClientLike
+  private _ws: WebSocket | null = null
+  private _channels = new Map<string, AuraChannel>()
+  private _state: ConnectionState = 'disconnected'
+  private _stateListeners = new Set<(state: ConnectionState) => void>()
+
+  // ─── Reconnection state ──────────────────────────────────────────────
+  private _autoReconnect = true
+  private _reconnectAttempts = 0
+  private _maxReconnectAttempts = Infinity
+  private _reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  private _intentionalClose = false
+  private _heartbeat = new HeartbeatManager()
+  private _tokenRefreshTimer: ReturnType<typeof setTimeout> | null = null
+  /** Dernier access_token propagé au serveur — évite les pushs redondants (propagation différentielle). */
+  private _lastSentToken: string | null = null
+
+  /** Backoff delays in ms: 1s, 2s, 4s, 8s, 16s, 30s (cap) */
+  private static readonly BACKOFF_MS = [1000, 2000, 4000, 8000, 16000, 30000]
+
+  constructor(client: AuraClientLike) {
+    this.client = client
+  }
+
+  /** Current connection state. */
+  get connectionState(): ConnectionState {
+    return this._state
+  }
+
+  /** Listen for connection state changes. */
+  onStateChange(callback: (state: ConnectionState) => void): () => void {
+    this._stateListeners.add(callback)
+    return () => this._stateListeners.delete(callback)
+  }
+
+  private _setState(state: ConnectionState): void {
+    this._state = state
+    for (const cb of this._stateListeners) {
+      try { cb(state) } catch { /* ignore */ }
+    }
+  }
+
+  // ─── WebSocket URL ──────────────────────────────────────────────────────
+
+  private get _wsUrl(): string {
+    const base = this.client.baseUrl.replace(/^http/, 'ws')
+    return `${base}/v1/realtime/ws`
+  }
+
+  // ─── Connection management ──────────────────────────────────────────────
+
+  /** Ensure the WebSocket connection is open. */
+  connect(): void {
+    if (this._ws && (this._ws.readyState === WebSocket.OPEN || this._ws.readyState === WebSocket.CONNECTING)) {
+      return
+    }
+
+    // Toute nouvelle tentative de connexion repart d'un état « non-intentionnel » :
+    // évite qu'un flag `_intentionalClose` laissé à true (car le onclose de
+    // l'ancien socket est désormais court-circuité par la garde anti-race) ne
+    // fasse traiter une future coupure inattendue comme volontaire.
+    this._intentionalClose = false
+
+    this._setState('connecting')
+
+    const token = this.client.authStore.token
+    const params = new URLSearchParams()
+    if (token) params.set('token', token)
+    // Clé API en query param (les navigateurs ne permettent pas de headers custom sur WebSocket)
+    if (this.client.apiKey) params.set('apikey', this.client.apiKey)
+
+    const url = `${this._wsUrl}?${params.toString()}`
+    // On capture `ws` dans les closures des handlers : un ancien socket dont
+    // l'événement `onclose`/`onopen` se déclenche de façon asynchrone APRÈS
+    // qu'un nouveau socket ait été créé ne doit pas écraser la connexion
+    // courante (race « stale onclose »). Chaque handler se garde donc par
+    // `if (ws !== this._ws) return`.
+    const ws = new WebSocket(url)
+    this._ws = ws
+
+    ws.onopen = () => {
+      // Socket périmé (superseded par un connect()/reconnexion) ⇒ on le ferme
+      // proprement et on n'active rien dessus.
+      if (ws !== this._ws) {
+        try { ws.close() } catch { /* ignore */ }
+        return
+      }
+      this._reconnectAttempts = 0
+      this._setState('connected')
+
+      // Démarrer le heartbeat proactif (anti-throttle navigateur)
+      this._heartbeat.start(() => this._send(JSON.stringify({ type: 'ping' })), 25000)
+
+      // Planifier le refresh proactif du token (à 80% du TTL)
+      this._scheduleTokenRefresh()
+
+      // Bind send function and re-subscribe all pending channels
+      for (const channel of this._channels.values()) {
+        channel._bindSend((data) => this._send(data))
+        if (channel.isSubscribed) {
+          channel._doSubscribe()
+        }
+      }
+    }
+
+    ws.onmessage = (evt) => {
+      // Ignore les messages d'un socket périmé.
+      if (ws !== this._ws) return
+      try {
+        const raw = typeof evt.data === 'string' ? evt.data : ''
+        const msg: ServerMessage = JSON.parse(raw)
+        this._dispatch(msg)
+      } catch (e) {
+        if (typeof console !== 'undefined') {
+          console.warn('[aura-realtime] Failed to parse WS message:', evt.data, e)
+        }
+      }
+    }
+
+    ws.onclose = () => {
+      // Garde anti-race : si ce socket n'est plus le socket courant (une
+      // nouvelle connexion l'a remplacé, ou disconnect() a déjà nettoyé),
+      // son `onclose` tardif ne doit PAS toucher l'état partagé.
+      if (ws !== this._ws) return
+      this._ws = null
+      // Nouvelle connexion (après reconnexion auto) ⇒ le token devra être renvoyé.
+      this._lastSentToken = null
+      this._heartbeat.stop()
+      if (this._intentionalClose) {
+        this._setState('disconnected')
+        this._intentionalClose = false
+      } else if (this._autoReconnect) {
+        this._scheduleReconnect()
+      } else {
+        this._setState('disconnected')
+      }
+    }
+
+    ws.onerror = (evt) => {
+      if (ws !== this._ws) return
+      if (typeof console !== 'undefined') {
+        console.warn('[aura-realtime] WebSocket error', evt)
+      }
+    }
+  }
+
+  /** Send raw data through the WebSocket. */
+  private _send(data: string): void {
+    if (this._ws && this._ws.readyState === WebSocket.OPEN) {
+      this._ws.send(data)
+    }
+  }
+
+  /** Refresh the JWT token on an existing connection (no disconnect). */
+  refreshToken(token: string): void {
+    if (token === this._lastSentToken) {
+      this._scheduleTokenRefresh()
+      return
+    }
+    this._lastSentToken = token
+    this._send(JSON.stringify({ type: 'access_token', token }))
+    this._scheduleTokenRefresh()
+  }
+
+  /**
+   * Définit/rafraîchit explicitement le token utilisé pour l'autorisation des
+   * canaux privés et broadcast (parité `@supabase/realtime-js` `setAuth`).
+   *
+   * - Avec `token` : utilise ce token. Sinon, reprend `client.authStore.token`.
+   * - Propage via le pipeline existant `refreshToken` (push
+   *   `{ type:'access_token', token }` sur une connexion ouverte, dédupliqué via
+   *   `_lastSentToken`). N'ouvre ni ne ferme aucune connexion WS.
+   * - Hors-ligne : `connect()` lit `client.authStore.token` au moment de l'open,
+   *   donc `setAuth()` doit être appelé avec un token présent dans le store (ou
+   *   après authentification) pour prendre effet sur une future connexion.
+   *
+   * À appeler AVANT de s'abonner à un canal privé (`channel(name,{private:true})`).
+   *
+   * @example
+   * ```ts
+   * aura.realtime.setAuth(session.access_token)
+   * const ch = aura.realtime.channel('secret', { private: true }).subscribe()
+   * ```
+   */
+  setAuth(token?: string): void {
+    const resolved = token ?? this.client.authStore.token
+    if (resolved == null) return
+    this.refreshToken(resolved)
+  }
+
+  /**
+   * 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
+   * (`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).
+   * @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.
+   *
+   * @example
+   * ```ts
+   * await aura.realtime.httpBroadcast('room-1', 'cursor', { x: 10, y: 20 })
+   * ```
+   */
+  httpBroadcast(
+    channel: string,
+    event: string,
+    payload: Record<string, unknown> = {},
+  ): Promise<AuraResponse<null>> {
+    const prefix = `${this.client.projectId}:`
+    const fullChannel = channel.startsWith(prefix) ? channel : `${prefix}${channel}`
+    const body = {
+      channel: fullChannel,
+      payload: { event, ...payload },
+    }
+    return fetchWithAuth<null>(
+      `${this.client.baseUrl}/v1/realtime/${this.client.projectId}/broadcast`,
+      { method: 'POST', body },
+      this.client,
+    )
+  }
+
+  /**
+   * Schedule proactive token refresh at 80% of the JWT TTL.
+   * Prevents token expiration during an active WebSocket session.
+   */
+  private _scheduleTokenRefresh(): void {
+    if (this._tokenRefreshTimer) {
+      clearTimeout(this._tokenRefreshTimer)
+      this._tokenRefreshTimer = null
+    }
+    const token = this.client.authStore.token
+    if (!token) return
+    try {
+      const payload = JSON.parse(atob(token.split('.')[1]))
+      const exp = payload.exp * 1000
+      const ttl = exp - Date.now()
+      if (ttl <= 0) return
+      // Refresh at 80% of the remaining TTL
+      const refreshIn = ttl * 0.8
+      this._tokenRefreshTimer = setTimeout(async () => {
+        this._tokenRefreshTimer = null
+        try {
+          const res = await this.client.auth.refreshSession()
+          if (res.data) {
+            this.refreshToken(res.data.access_token)
+          }
+        } catch {
+          // Refresh failed — the server will eventually disconnect on token expiry
+        }
+      }, refreshIn)
+    } catch {
+      // JWT decode failed — skip proactive refresh
+    }
+  }
+
+  /** Schedule a reconnection attempt with exponential backoff + jitter. */
+  private _scheduleReconnect(): void {
+    // Clear any existing timer to avoid double-reconnect
+    if (this._reconnectTimer) {
+      clearTimeout(this._reconnectTimer)
+      this._reconnectTimer = null
+    }
+
+    if (this._reconnectAttempts >= this._maxReconnectAttempts) {
+      this._setState('disconnected')
+      return
+    }
+
+    this._reconnectAttempts++
+    this._setState('reconnecting')
+
+    const idx = Math.min(this._reconnectAttempts - 1, RealtimeService.BACKOFF_MS.length - 1)
+    const baseDelay = RealtimeService.BACKOFF_MS[idx]
+    const jitter = Math.random() * baseDelay * 0.25
+    const delay = baseDelay + jitter
+
+    this._reconnectTimer = setTimeout(() => {
+      this._reconnectTimer = null
+      this.connect()
+    }, delay)
+  }
+
+  /** Enable/disable auto-reconnect (enabled by default). */
+  setAutoReconnect(enabled: boolean, maxAttempts?: number): void {
+    this._autoReconnect = enabled
+    if (maxAttempts !== undefined) this._maxReconnectAttempts = maxAttempts
+  }
+
+  /** Disconnect the WebSocket and clean up all channels. */
+  disconnect(): void {
+    this._intentionalClose = true
+    this._heartbeat.stop()
+    if (this._tokenRefreshTimer) {
+      clearTimeout(this._tokenRefreshTimer)
+      this._tokenRefreshTimer = null
+    }
+    if (this._reconnectTimer) {
+      clearTimeout(this._reconnectTimer)
+      this._reconnectTimer = null
+    }
+    this._reconnectAttempts = 0
+    for (const channel of this._channels.values()) {
+      channel.unsubscribe()
+    }
+    this._channels.clear()
+    if (this._ws) {
+      this._ws.close()
+      this._ws = null
+    }
+    this._setState('disconnected')
+    this._lastSentToken = null
+  }
+
+  // ─── Channel factory ────────────────────────────────────────────────────
+
+  /**
+   * Create or retrieve a channel by name.
+   * Returns an `AuraChannel` with chainable `.on()` / `.subscribe()` API.
+   *
+   * @example
+   * ```ts
+   * const channel = aura.realtime.channel('room-1')
+   * ```
+   */
+  channel(name: string, options?: ChannelConfig): AuraChannel {
+    const existing = this._channels.get(name)
+    if (existing) return existing
+
+    const ch = new AuraChannel(name, this.client.projectId, options)
+    this._channels.set(name, ch)
+
+    // Établit la connexion WS si nécessaire (idempotent — connect() vérifie
+    // déjà readyState avant d'ouvrir un nouveau socket).
+    this.connect()
+
+    // If already connected, bind immediately
+    if (this._ws && this._ws.readyState === WebSocket.OPEN) {
+      ch._bindSend((data) => this._send(data))
+    }
+
+    return ch
+  }
+
+  /** Remove a channel. */
+  removeChannel(name: string): void {
+    const ch = this._channels.get(name)
+    if (ch) {
+      ch.unsubscribe()
+      this._channels.delete(name)
+    }
+  }
+
+  /** List active channels. */
+  getChannels(): AuraChannel[] {
+    return Array.from(this._channels.values())
+  }
+
+  /** Remove all channels and subscriptions. */
+  removeAllChannels(): void {
+    for (const ch of this._channels.values()) {
+      ch.unsubscribe()
+    }
+    this._channels.clear()
+  }
+
+  // ─── Message dispatch ───────────────────────────────────────────────────
+
+  /** Route incoming server messages to the correct channel. */
+  private _dispatch(msg: ServerMessage): void {
+    // Extract channel name — present in subscribed, presence_state, OR topic in event messages
+    // ServerMessage::Event uses 'topic' (serde flatten de RealtimeEvent), pas 'channel'
+    const channelFull = 'channel' in msg
+      ? (msg as { channel?: string }).channel
+      : 'topic' in msg
+        ? (msg as { topic?: string }).topic
+        : undefined
+
+    if (channelFull) {
+      // Strip project prefix to find channel
+      const prefix = `${this.client.projectId}:`
+      const name = channelFull.startsWith(prefix) ? channelFull.slice(prefix.length) : channelFull
+      const ch = this._channels.get(name)
+      if (ch) {
+        ch._onMessage(msg)
+        return
+      }
+
+      // Try matching by full name (for CDC channels like proj:db:schema.table)
+      // The channel might have been created with a short name but CDC sends full topic
+      for (const [, channel] of this._channels) {
+        if (channel.fullName === channelFull || channelFull.startsWith(channel.fullName + ':')) {
+          channel._onMessage(msg)
+          return
+        }
+      }
+    }
+
+    // Messages without channel (pong, token_refreshed, global errors)
+    if (msg.type === 'token_refreshed') {
+      // Global token refresh ACK — no action needed
+      return
+    }
+
+    if (msg.type === 'pong') {
+      // Keepalive — no action needed
+      return
+    }
+
+    if (msg.type === 'broadcast_ack') {
+      // Router l'ACK vers le SEUL channel émetteur. Le `ref_id` est préfixé par
+      // le `fullName` du channel (`{fullName}:r{n}`, cf. AuraChannel._nextRef) :
+      // on récupère le suffixe `:r{n}` via lastIndexOf (robuste à un nom de
+      // channel contenant lui-même « :r ») et on résout par `fullName`.
+      const ack = msg as BroadcastAckMessage
+      const refId = ack.ref_id ?? ack.message_id
+      if (refId) {
+        const marker = refId.lastIndexOf(':r')
+        if (marker > 0) {
+          const fullName = refId.slice(0, marker)
+          for (const ch of this._channels.values()) {
+            if (ch.fullName === fullName) {
+              ch._onMessage(msg)
+              return
+            }
+          }
+        }
+      }
+      // Fallback prudent : `ref_id` non résoluble (préfixe inattendu ou
+      // `message_id` brut sans « :r ») → dispatch à tous pour ne pas perdre
+      // l'ACK. Chaque channel n'agit que sur un `ref_id`/`message_id` présent
+      // dans ses `_pendingAcks`, donc aucun faux positif.
+      for (const ch of this._channels.values()) {
+        ch._onMessage(msg)
+      }
+      return
+    }
+
+    // Broadcast to all channels for unroutable messages
+    if (msg.type === 'error') {
+      for (const ch of this._channels.values()) {
+        ch._onMessage(msg)
+      }
+    }
+  }
+
+  // ─── Backward compatibility ─────────────────────────────────────────────
+
+  /**
+   * 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 } {
+    this.connect()
+
+    const ch = this.channel(channelName)
+    ch.on('postgres_changes', { event: '*' }, callback)
+    ch.subscribe()
+
+    return {
+      unsubscribe: () => this.removeChannel(channelName),
+    }
+  }
+}