@aurabase/aurabase-js 0.3.0

package/packages/realtime/src/AuraChannel.ts

@@ -0,0 +1,485 @@
+import type {
+  RealtimeEvent,
+  RealtimeListenType,
+  PostgresChangesFilter,
+  BroadcastFilter,
+  PresenceFilter,
+  SubscribeCallback,
+  BroadcastPayload,
+  PresenceState,
+  PresenceInfo,
+  ServerMessage,
+  ServerSubscribedMsg,
+  ServerEventMsg,
+  ServerPresenceStateMsg,
+  ServerErrorMsg,
+  ChannelConfig,
+} from '@aurabase/core'
+import { matchesColumnFilter } from './columnFilter'
+
+// ─── Internal types ─────────────────────────────────────────────────────────
+
+type ListenerCallback = (payload: RealtimeEvent | Record<string, unknown>) => void
+
+type ListenerEntry = {
+  type: RealtimeListenType
+  filter: PostgresChangesFilter | BroadcastFilter | PresenceFilter
+  callback: ListenerCallback
+}
+
+type SendFn = (data: string) => void
+
+// ─── AuraChannel ────────────────────────────────────────────────────────────
+
+/**
+ * A realtime channel with Supabase-compatible chainable API.
+ *
+ * @example
+ * ```ts
+ * const channel = aura.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)
+ *   })
+ *   .on('presence', { event: 'sync' }, () => {
+ *     console.log('Presence synced:', channel.presenceState())
+ *   })
+ *   .subscribe((status) => {
+ *     if (status === 'SUBSCRIBED') console.log('Connected!')
+ *   })
+ * ```
+ */
+export class AuraChannel {
+  readonly name: string
+  private readonly _projectId: string
+  private readonly _listeners: ListenerEntry[] = []
+  private _subscribed = false
+  private _sendFn: SendFn | null = null
+  private _subscribeCallback: SubscribeCallback | null = null
+  private _presenceState: PresenceState = {}
+  private _isPrivate = false
+  private _broadcastAck = false
+  private _broadcastSelf = false
+  private _presenceKey = ''
+  /** ID de subscription retourné par le serveur (utilisé pour le filtre RLS allowed_sub_ids) */
+  private _subscriptionId: string | null = null
+  /** Compteur pour générer des ref_id uniques par connexion */
+  private _refCounter = 0
+  /** Dernier event ID recu — utilise pour since_id au reconnect */
+  private _lastEventId: string | null = null
+  /** Pending ACK callbacks : ref_id → resolve */
+  private _pendingAcks = new Map<string, () => void>()
+
+  constructor(name: string, projectId: string, options?: ChannelConfig) {
+    this.name = name
+    this._projectId = projectId
+    this._isPrivate = options?.private ?? false
+    this._broadcastAck = options?.broadcast?.ack ?? false
+    this._broadcastSelf = options?.broadcast?.self ?? false
+    this._presenceKey = options?.config?.presence?.key ?? ''
+  }
+
+  /** Génère un ref_id unique pour la corrélation request/response. */
+  private _nextRef(): string {
+    return `${this.fullName}:r${++this._refCounter}`
+  }
+
+  /** Full channel name with project prefix (for server protocol) */
+  get fullName(): string {
+    return `${this._projectId}:${this.name}`
+  }
+
+  // ─── Chainable .on() ────────────────────────────────────────────────────
+
+  /**
+   * Register a listener for a specific event type.
+   * Returns `this` for chaining.
+   */
+  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: RealtimeListenType,
+    filter: PostgresChangesFilter | BroadcastFilter | PresenceFilter,
+    callback: (payload: any) => void,
+  ): this {
+    this._listeners.push({ type, filter, callback })
+    return this
+  }
+
+  // ─── Subscribe ──────────────────────────────────────────────────────────
+
+  /**
+   * Subscribe to the channel. Sends the Subscribe message to the server
+   * with the full config (postgres_changes, broadcast, presence).
+   */
+  subscribe(callback?: SubscribeCallback): this {
+    this._subscribeCallback = callback ?? null
+    this._subscribed = true
+
+    // Si le WS est déjà connecté (canal créé après une connexion existante),
+    // s'abonner immédiatement. Sinon, RealtimeService appellera _bindSend()
+    // puis _doSubscribe() depuis son handler ws.onopen une fois connecté.
+    if (this._sendFn) {
+      this._doSubscribe()
+    }
+
+    return this
+  }
+
+  /** Called by RealtimeService once the WS connection is ready. */
+  _bindSend(sendFn: SendFn): void {
+    this._sendFn = sendFn
+  }
+
+  /** Send the subscribe message to the server. */
+  _doSubscribe(): void {
+    if (!this._sendFn) return
+
+    // Build postgres_changes config from listeners
+    const pgFilters = this._listeners
+      .filter((l) => l.type === 'postgres_changes')
+      .map((l) => l.filter as PostgresChangesFilter)
+
+    const msg = {
+      type: 'subscribe',
+      channel: this.fullName,
+      ref_id: this._nextRef(),
+      since_id: this._lastEventId ?? undefined,
+      config: {
+        postgres_changes: pgFilters,
+        broadcast: {
+          self_broadcast: this._broadcastSelf,  // ← depuis les options du channel
+          ack: this._broadcastAck,              // ← depuis les options du channel
+        },
+        presence: { key: this._presenceKey },   // ← depuis les options du channel
+        private: this._isPrivate,
+      },
+    }
+
+    this._sendFn(JSON.stringify(msg))
+  }
+
+  /** Unsubscribe from the channel. */
+  unsubscribe(): void {
+    if (this._sendFn) {
+      this._sendFn(JSON.stringify({ type: 'unsubscribe', channel: this.fullName }))
+    }
+    this._subscribed = false
+    this._listeners.length = 0
+    this._presenceState = {}
+  }
+
+  // ─── Broadcast ──────────────────────────────────────────────────────────
+
+  /**
+   * Send a broadcast message to the channel.
+   * If broadcast.ack=true, returns a Promise that resolves when the server ACKs.
+   *
+   * @example
+   * ```ts
+   * // Without 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 } })
+   * ```
+   */
+  send(message: BroadcastPayload): Promise<'ok' | 'timeout' | 'error'> {
+    return new Promise((resolve) => {
+      if (!this._sendFn) {
+        resolve('error')
+        return
+      }
+      const ref_id = message.ref_id ?? this._nextRef()
+
+      // Si ack demandé, enregistrer un callback en attente
+      if (this._broadcastAck) {
+        const timer = setTimeout(() => {
+          this._pendingAcks.delete(ref_id)
+          resolve('timeout')
+        }, 5000)
+
+        this._pendingAcks.set(ref_id, () => {
+          clearTimeout(timer)
+          resolve('ok')
+        })
+      } else {
+        resolve('ok')
+      }
+
+      this._sendFn(
+        JSON.stringify({
+          type: 'broadcast',
+          channel: this.fullName,
+          ref_id,
+          payload: { event: message.event, ...message.payload },
+        }),
+      )
+    })
+  }
+
+  // ─── Presence ───────────────────────────────────────────────────────────
+
+  /**
+   * Track presence state for this client.
+   * Returns a Promise that resolves with 'ok' once tracked (compatible Supabase).
+   *
+   * @example
+   * ```ts
+   * await channel.track({ user: 'user-1', online_at: new Date().toISOString() })
+   * ```
+   */
+  async track(state: Record<string, unknown>): Promise<'ok' | 'error'> {
+    if (!this._sendFn) return 'error'
+    this._sendFn(
+      JSON.stringify({
+        type: 'presence_update',
+        channel: this.fullName,
+        meta: state,
+      }),
+    )
+    return 'ok'
+  }
+
+  /** Stop tracking presence. */
+  async untrack(): Promise<'ok' | 'error'> {
+    return this.track({})
+  }
+
+  /** Get the current presence state for this channel. */
+  presenceState(): PresenceState {
+    return { ...this._presenceState }
+  }
+
+  // ─── Internal: dispatch server messages ──────────────────────────────────
+
+  /** Called by RealtimeService when a server message arrives for this channel. */
+  _onMessage(msg: ServerMessage): void {
+    switch (msg.type) {
+      case 'subscribed': {
+        const subMsg = msg as ServerSubscribedMsg
+        if (subMsg.subscription_id) this._subscriptionId = subMsg.subscription_id
+        this._subscribeCallback?.('SUBSCRIBED')
+        break
+      }
+
+      case 'event': {
+        // Serde flatten : les champs de RealtimeEvent sont au top-level du JSON
+        // ServerEventMsg a les champs id, event, topic, payload, timestamp directement
+        const evtMsg = msg as ServerEventMsg
+        if (evtMsg.id) {
+          const event: RealtimeEvent = {
+            id: evtMsg.id,
+            event: evtMsg.event as RealtimeEvent['event'],
+            topic: evtMsg.topic,
+            payload: evtMsg.payload,
+            timestamp: evtMsg.timestamp,
+            allowed_sub_ids: evtMsg.allowed_sub_ids,
+          }
+          this._dispatchEvent(event)
+        }
+        break
+      }
+
+      case 'presence_state': {
+        const presMsg = msg as ServerPresenceStateMsg
+        if (presMsg.presences) {
+          this._presenceState = {}
+          for (const p of presMsg.presences) {
+            const key = p.user_id || p.client_id
+            if (!this._presenceState[key]) this._presenceState[key] = []
+            this._presenceState[key].push(p)
+          }
+          for (const l of this._listeners) {
+            if (l.type === 'presence' && (l.filter as PresenceFilter).event === 'sync') {
+              l.callback(this._presenceState)
+            }
+          }
+        }
+        break
+      }
+
+      case 'error': {
+        const errMsg = msg as ServerErrorMsg
+        this._subscribeCallback?.('CHANNEL_ERROR', new Error(errMsg.message ?? 'Unknown error'))
+        break
+      }
+
+      case 'token_refreshed':
+        break
+
+      case 'broadcast_ack': {
+        // Résoudre le pending ACK si ref_id présent
+        const ackMsg = msg as { type: 'broadcast_ack'; ref_id?: string; message_id?: string }
+        const refId = ackMsg.ref_id ?? ackMsg.message_id
+        if (refId) {
+          const resolve = this._pendingAcks.get(refId)
+          if (resolve) {
+            this._pendingAcks.delete(refId)
+            resolve()
+          }
+        }
+        break
+      }
+    }
+  }
+
+  /** Dispatch a RealtimeEvent to matching listeners. */
+  private _dispatchEvent(event: RealtimeEvent): void {
+    if (!event) return
+
+    // Tracker le dernier event ID pour since_id au reconnect
+    if (event.id) this._lastEventId = event.id
+
+    // Filtre RLS : si l'event a une liste allowed_sub_ids et que notre subscription_id
+    // n'y figure pas, ne pas dispatcher (defense-in-depth côté client)
+    const allowed = event.allowed_sub_ids
+    if (allowed && this._subscriptionId && !allowed.includes(this._subscriptionId)) {
+      return
+    }
+
+    const eventType = event.event // 'insert', 'update', 'delete', 'broadcast', 'presence'
+
+    // Mettre à jour l'état de présence local avant de notifier les écouteurs
+    if (eventType === 'presence') {
+      const payload = event.payload as Record<string, unknown>
+      const action = payload.action as string
+      const key = (payload.user_id || payload.client_id) as string
+
+      if (action === 'join') {
+        if (!this._presenceState[key]) this._presenceState[key] = []
+        if (!this._presenceState[key].some(p => p.client_id === payload.client_id)) {
+          const presenceInfo: PresenceInfo = {
+            client_id: payload.client_id as string,
+            user_id: (payload.user_id as string) ?? undefined,
+            metadata: (payload.metadata ?? payload.meta ?? {}) as Record<string, unknown>,
+            joined_at: new Date().toISOString(),
+            last_seen: new Date().toISOString(),
+          }
+          this._presenceState[key].push(presenceInfo)
+        }
+      } else if (action === 'leave') {
+        const arr = this._presenceState[key]
+        if (arr) {
+          const idx = arr.findIndex((p) => p.client_id === payload.client_id)
+          if (idx >= 0) arr.splice(idx, 1)
+          if (arr.length === 0) delete this._presenceState[key]
+        }
+      } else if (action === 'update') {
+        const arr = this._presenceState[key]
+        if (arr) {
+          const idx = arr.findIndex((p) => p.client_id === payload.client_id)
+          if (idx >= 0) {
+            arr[idx].metadata = (payload.metadata ?? payload.meta ?? {}) as Record<string, unknown>
+            arr[idx].last_seen = new Date().toISOString()
+          } else {
+            const presenceInfo: PresenceInfo = {
+              client_id: payload.client_id as string,
+              user_id: (payload.user_id as string) ?? undefined,
+              metadata: (payload.metadata ?? payload.meta ?? {}) as Record<string, unknown>,
+              joined_at: new Date().toISOString(),
+              last_seen: new Date().toISOString(),
+            }
+            this._presenceState[key].push(presenceInfo)
+          }
+        } else {
+          this._presenceState[key] = [{
+            client_id: payload.client_id as string,
+            user_id: (payload.user_id as string) ?? undefined,
+            metadata: (payload.metadata ?? payload.meta ?? {}) as Record<string, unknown>,
+            joined_at: new Date().toISOString(),
+            last_seen: new Date().toISOString(),
+          }]
+        }
+      }
+    }
+
+    for (const listener of this._listeners) {
+      if (listener.type === 'postgres_changes') {
+        const filter = listener.filter as PostgresChangesFilter
+        if (
+          eventType === 'insert' ||
+          eventType === 'update' ||
+          eventType === 'delete'
+        ) {
+          const filterEvent = filter.event.toLowerCase()
+          if (filterEvent === '*' || filterEvent === eventType) {
+            // Check schema/table if specified
+            const payload = event.payload as Record<string, unknown>
+            if (filter.schema && payload.schema !== filter.schema) continue
+            if (filter.table && payload.table !== filter.table) continue
+
+            // Second rideau client (defense-in-depth) : le serveur a déjà filtré
+            // par colonne de façon autoritaire. DELETE -> old_record (record CDC
+            // vide) ; INSERT/UPDATE -> record. Si la cible est absente/non-objet,
+            // ne pas filtrer (éviter un faux négatif sur un payload sans record).
+            if (filter.filter) {
+              const target = eventType === 'delete' ? payload.old_record : payload.record
+              if (target && typeof target === 'object') {
+                if (!matchesColumnFilter(filter.filter, target as Record<string, unknown>)) {
+                  continue
+                }
+              }
+            }
+
+            listener.callback(event)
+          }
+        }
+      } else if (listener.type === 'broadcast') {
+        if (eventType === 'broadcast') {
+          const filter = listener.filter as BroadcastFilter
+          const payload = event.payload as Record<string, unknown>
+          // Match broadcast event name if specified
+          if (!filter.event || payload.event === filter.event) {
+            listener.callback(event)
+          }
+        }
+      } else if (listener.type === 'presence') {
+        if (eventType === 'presence') {
+          const filter = listener.filter as PresenceFilter
+          const payload = event.payload as Record<string, unknown>
+          const action = payload.action as string
+
+          if (filter.event === 'join' && action === 'join') {
+            listener.callback({
+              key: payload.user_id || payload.client_id,
+              newPresences: [payload],
+            })
+          } else if (filter.event === 'leave' && action === 'leave') {
+            listener.callback({
+              key: payload.user_id || payload.client_id,
+              leftPresences: [payload],
+            })
+          } else if (filter.event === 'sync') {
+            listener.callback(this.presenceState())
+          }
+        }
+      }
+    }
+  }
+
+  /** Whether this channel has been subscribed. */
+  get isSubscribed(): boolean {
+    return this._subscribed
+  }
+
+  /** Get listeners (for re-subscribe after reconnect). */
+  _getListeners(): ListenerEntry[] {
+    return this._listeners
+  }
+}

package/packages/realtime/src/HeartbeatManager.ts

@@ -0,0 +1,73 @@
+/**
+ * HeartbeatManager — pings périodiques pour maintenir la connexion WS.
+ * Utilise un Worker dédié (anti-throttle des onglets en arrière-plan) ; fallback setInterval.
+ */
+export class HeartbeatManager {
+  private _worker: Worker | null = null
+  private _workerUrl: string | null = null
+  private _interval: ReturnType<typeof setInterval> | null = null
+  private _sendFn: (() => void) | null = null
+
+  start(sendPing: () => void, intervalMs = 25000): void {
+    this.stop()
+    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 blob = new Blob([code], { type: 'application/javascript' })
+        this._workerUrl = URL.createObjectURL(blob)
+        this._worker = new Worker(this._workerUrl)
+        this._worker.onmessage = () => {
+          this._sendFn?.()
+        }
+        this._worker.postMessage({ type: 'start', interval: intervalMs })
+        return
+      } catch {
+        // Worker indispo/CSP → fallback
+        this._worker = null
+        if (this._workerUrl) {
+          try {
+            URL.revokeObjectURL(this._workerUrl)
+          } catch {
+            /* ignore */
+          }
+          this._workerUrl = null
+        }
+      }
+    }
+
+    this._interval = setInterval(() => {
+      this._sendFn?.()
+    }, intervalMs)
+  }
+
+  stop(): void {
+    if (this._worker) {
+      try {
+        this._worker.postMessage({ type: 'stop' })
+        this._worker.terminate()
+      } catch {
+        /* ignore */
+      }
+      this._worker = null
+    }
+    if (this._workerUrl) {
+      try {
+        URL.revokeObjectURL(this._workerUrl)
+      } catch {
+        /* ignore */
+      }
+      this._workerUrl = null
+    }
+    if (this._interval) {
+      clearInterval(this._interval)
+      this._interval = null
+    }
+    this._sendFn = null
+  }
+
+  get isActive(): boolean {
+    return this._worker !== null || this._interval !== null
+  }
+}