@aurabase/aurabase-js 0.3.0 → 0.4.0

package/packages/realtime/src/RealtimeService.ts

@@ -1,505 +0,0 @@
-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),
-    }
-  }
-}