@aurabase/aurabase-js 0.3.0 → 0.4.0

package/packages/realtime/src/AuraChannel.ts

@@ -1,485 +0,0 @@
-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

@@ -1,73 +0,0 @@
-/**
- * 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
-  }
-}