@aurabase/aurabase-js 0.3.0

package/packages/realtime/src/columnFilter.ts

@@ -0,0 +1,301 @@
+/**
+ * Fallback client (second rideau) du filtre colonne `postgres_changes`.
+ *
+ * Le serveur `aura-realtime` est **autoritaire** : il filtre déjà les events CDC
+ * par colonne avant de les envoyer (`services/aura-realtime/src/protocol.rs`).
+ * Ce module reproduit fidèlement la même sémantique côté client, en defense-in-depth :
+ * il ne peut que sur-filtrer (jamais laisser passer un event que le serveur aurait dû
+ * exclure).
+ *
+ * Sémantique portée depuis le backend Rust (parité stricte) :
+ * - Opérateurs : eq, neq, lt, lte, gt, gte, in, like, ilike, is, match, imatch, isdistinct.
+ * - Syntaxe : `column=operator.value`, négation `column=not.operator.value`.
+ * - AND par virgules : `a=eq.1,b=gt.2` (les virgules internes d'un `in.(a,b,c)` ne
+ *   séparent PAS les conditions — split respectant la profondeur des parenthèses).
+ * - **Fail-CLOSED** : toute condition non parsable (syntaxe invalide, opérateur inconnu,
+ *   regex invalide, trop de valeurs `in`, pattern `match`/`imatch` trop long) => `false`,
+ *   jamais laissé passer.
+ * - Champ absent du record => résultat non évaluable => exclusion ferme, **jamais
+ *   inversée** par `not.` (sémantique SQL : `NOT (col = x)` avec `col` NULL/absent
+ *   => NULL => exclu). Seul un résultat sémantique évaluable est inversé par `not.`.
+ */
+
+type FilterOp =
+  | 'eq'
+  | 'neq'
+  | 'lt'
+  | 'lte'
+  | 'gt'
+  | 'gte'
+  | 'in'
+  | 'like'
+  | 'ilike'
+  | 'is'
+  | 'match'
+  | 'imatch'
+  | 'isdistinct'
+
+const VALID_OPS: ReadonlySet<string> = new Set([
+  'eq',
+  'neq',
+  'lt',
+  'lte',
+  'gt',
+  'gte',
+  'in',
+  'like',
+  'ilike',
+  'is',
+  'match',
+  'imatch',
+  'isdistinct',
+])
+
+/** Longueur max d'un pattern `match`/`imatch` — borne anti-ReDoS (parité backend). */
+const MAX_REGEX_PATTERN_LEN = 512
+
+/** Nombre max de valeurs dans un `in.(...)` — parité backend/PostgREST. */
+const MAX_IN_VALUES = 100
+
+interface ParsedColumnFilter {
+  column: string
+  op: FilterOp
+  value: string
+  /** `true` si le filtre était préfixé par `not.` — le résultat sémantique est inversé. */
+  negated: boolean
+}
+
+/**
+ * Parse une condition unique "column=op.value" ou "column=not.op.value".
+ * Retourne `null` si non parsable (fail-closed — voir `matchesColumnFilter`).
+ */
+function parseColumnFilter(filterStr: string): ParsedColumnFilter | null {
+  const eqIdx = filterStr.indexOf('=')
+  if (eqIdx === -1) return null
+  const column = filterStr.slice(0, eqIdx)
+  if (!column) return null
+  let rest = filterStr.slice(eqIdx + 1)
+
+  let negated = false
+  if (rest.startsWith('not.')) {
+    negated = true
+    rest = rest.slice(4)
+  }
+
+  const dotIdx = rest.indexOf('.')
+  if (dotIdx === -1) return null
+  const opStr = rest.slice(0, dotIdx)
+  let value = rest.slice(dotIdx + 1)
+
+  if (!VALID_OPS.has(opStr)) return null
+  const op = opStr as FilterOp
+
+  if (op === 'in') {
+    const stripped = value.replace(/^\(+/, '').replace(/\)+$/, '')
+    if (stripped.split(',').length > MAX_IN_VALUES) return null
+    value = stripped
+  } else if (op === 'is') {
+    // `is` n'accepte que null/true/false (parité PostgREST) : toute autre valeur est
+    // rejetée DÈS LE PARSE. Sinon `is.<garbage>` serait accepté et `matchesRaw`
+    // renverrait `false` (défaut) — un `not.is.<garbage>` inverserait ce `false` en
+    // `true` => fail-OPEN (matche tout). On refuse ce filtre en amont (parité Rust).
+    if (value !== 'null' && value !== 'true' && value !== 'false') return null
+  } else if (op === 'match' || op === 'imatch') {
+    if (value.length > MAX_REGEX_PATTERN_LEN) return null
+    // Compiler la regex DÈS LE PARSE : un pattern invalide => filtre rejeté (null).
+    // Sinon un `not.match.(invalide` verrait son échec de compilation transformé
+    // en un `true` inversé => fail-OPEN. On refuse ce filtre en amont (parité Rust).
+    try {
+      // eslint-disable-next-line no-new
+      new RegExp(value, op === 'imatch' ? 'i' : undefined)
+    } catch {
+      return null
+    }
+  }
+
+  return { column, op, value, negated }
+}
+
+/**
+ * Découpe un ensemble de conditions AND ("a=eq.1,b=in.(x,y)") en conditions
+ * individuelles, en respectant les virgules internes d'un `in.(...)` (profondeur
+ * de parenthèses). Ne fait PAS de parsing ici — juste le split structurel.
+ */
+function splitTopLevel(s: string): string[] {
+  const parts: string[] = []
+  let depth = 0
+  let start = 0
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i]
+    if (c === '(') depth += 1
+    else if (c === ')') depth = Math.max(0, depth - 1)
+    else if (c === ',' && depth === 0) {
+      parts.push(s.slice(start, i))
+      start = i + 1
+    }
+  }
+  parts.push(s.slice(start))
+  return parts
+}
+
+/**
+ * Découpe puis parse un ensemble de conditions AND. **Fail-closed** : retourne
+ * `null` dès qu'UNE condition est invalide (propage l'échec, n'ignore jamais
+ * silencieusement une condition malformée).
+ */
+function parseFilterSet(s: string): ParsedColumnFilter[] | null {
+  const parts = splitTopLevel(s)
+  const out: ParsedColumnFilter[] = []
+  for (const part of parts) {
+    const cf = parseColumnFilter(part.trim())
+    if (!cf) return null
+    out.push(cf)
+  }
+  return out
+}
+
+/** Convertit une valeur JSON en sa représentation string (comparaison textuelle/numérique). */
+function jsonValueToString(field: unknown): string {
+  if (typeof field === 'string') return field
+  if (typeof field === 'number' || typeof field === 'boolean') return String(field)
+  if (field === null) return 'null'
+  try {
+    return JSON.stringify(field) ?? ''
+  } catch {
+    return ''
+  }
+}
+
+/** Parse une valeur en `number` strict (rejette les chaînes vides/non-numériques). */
+function parseStrictNumber(s: string): number | null {
+  if (s.trim() === '') return null
+  const n = Number(s)
+  return Number.isFinite(n) ? n : null
+}
+
+function compareNumeric(a: string, b: string, cmp: (a: number, b: number) => boolean): boolean {
+  const an = parseStrictNumber(a)
+  const bn = parseStrictNumber(b)
+  if (an === null || bn === null) return false // types incompatibles => fail-closed
+  return cmp(an, bn)
+}
+
+/** Convertit un motif SQL like/ilike (`%`→sous-chaîne, `_`→1 caractère) en RegExp ancrée. */
+function likeToRegExp(pattern: string, caseInsensitive: boolean): RegExp | null {
+  let re = '^'
+  for (const ch of pattern) {
+    if (ch === '%') re += '.*'
+    else if (ch === '_') re += '.'
+    else re += ch.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  }
+  re += '$'
+  try {
+    return new RegExp(re, caseInsensitive ? 'i' : undefined)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Évalue le prédicat brut (sans tenir compte de `negated`).
+ * Retourne `null` si non évaluable (champ absent, regex invalide) — distinct
+ * d'un `false` qui est un « faux » sémantique (inversable par `not.`).
+ */
+function matchesRaw(cf: ParsedColumnFilter, record: Record<string, unknown>): boolean | null {
+  // `is` compare la valeur JSON réelle (null/true/false) — toujours évaluable.
+  if (cf.op === 'is') {
+    const field = record[cf.column]
+    switch (cf.value) {
+      case 'null':
+        return field === undefined || field === null
+      case 'true':
+        return field === true
+      case 'false':
+        return field === false
+      default:
+        // Invariant garanti par `parseColumnFilter` : `is.<autre>` est rejeté au parse
+        // (null), ce bras est donc défensif uniquement (jamais atteint en pratique).
+        return false
+    }
+  }
+
+  // `isdistinct` : NULL est distinct de toute valeur non-NULL — toujours évaluable.
+  if (cf.op === 'isdistinct') {
+    const field = record[cf.column]
+    const fieldIsNull = field === undefined || field === null
+    if (fieldIsNull) return true
+    return jsonValueToString(field) !== cf.value
+  }
+
+  // Champ absent => non évaluable (null), JAMAIS un false inversable.
+  if (!(cf.column in record) || record[cf.column] === undefined) return null
+  const field = record[cf.column]
+  const fieldStr = jsonValueToString(field)
+
+  switch (cf.op) {
+    case 'eq':
+      return fieldStr === cf.value
+    case 'neq':
+      return fieldStr !== cf.value
+    case 'lt':
+      return compareNumeric(fieldStr, cf.value, (a, b) => a < b)
+    case 'lte':
+      return compareNumeric(fieldStr, cf.value, (a, b) => a <= b)
+    case 'gt':
+      return compareNumeric(fieldStr, cf.value, (a, b) => a > b)
+    case 'gte':
+      return compareNumeric(fieldStr, cf.value, (a, b) => a >= b)
+    case 'in':
+      return cf.value
+        .split(',')
+        .map((v) => v.trim())
+        .some((v) => v === fieldStr)
+    case 'like': {
+      const re = likeToRegExp(cf.value, false)
+      return re ? re.test(fieldStr) : null
+    }
+    case 'ilike': {
+      const re = likeToRegExp(cf.value, true)
+      return re ? re.test(fieldStr) : null
+    }
+    case 'match': {
+      try {
+        return new RegExp(cf.value).test(fieldStr)
+      } catch {
+        return null
+      }
+    }
+    case 'imatch': {
+      try {
+        return new RegExp(cf.value, 'i').test(fieldStr)
+      } catch {
+        return null
+      }
+    }
+    default:
+      return null
+  }
+}
+
+/** Applique la négation UNIQUEMENT au résultat sémantique évaluable (jamais à `null`). */
+function matchesSingle(cf: ParsedColumnFilter, record: Record<string, unknown>): boolean {
+  const raw = matchesRaw(cf, record)
+  if (raw === null) return false // non évaluable => exclusion ferme, pas d'inversion
+  return cf.negated ? !raw : raw
+}
+
+/**
+ * Vérifie si `record` matche le filtre colonne `filter` (syntaxe Supabase/PostgREST) :
+ * `column=operator.value`, négation `not.`, conditions AND séparées par virgules.
+ *
+ * **Fail-CLOSED** : si `filter` n'est pas parsable dans son ensemble (une seule
+ * condition invalide suffit), retourne `false` — jamais un match par défaut.
+ *
+ * Ce helper est un second rideau client (defense-in-depth) : le serveur
+ * `aura-realtime` a déjà filtré l'event de façon autoritaire.
+ */
+export function matchesColumnFilter(filter: string, record: Record<string, unknown>): boolean {
+  const set = parseFilterSet(filter)
+  if (!set) return false
+  return set.every((cf) => matchesSingle(cf, record))
+}

package/packages/realtime/src/index.ts

@@ -0,0 +1,4 @@
+export { RealtimeService } from './RealtimeService'
+export type { ConnectionState } from './RealtimeService'
+export { AuraChannel } from './AuraChannel'
+export { HeartbeatManager } from './HeartbeatManager'

package/packages/realtime/tests/ack-routing.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect, vi } from 'vitest'
+import { RealtimeService } from '../src/RealtimeService'
+import { AuraChannel } from '../src/AuraChannel'
+import { BaseAuthStore } from '@aurabase/core'
+import type { AuraClientLike } from '@aurabase/core'
+
+function client(): AuraClientLike {
+  return {
+    baseUrl: 'http://x',
+    projectId: 'proj',
+    apiKey: 'k',
+    authStore: new BaseAuthStore(),
+    fetchFn: (async () => new Response('{}')) as unknown as typeof globalThis.fetch,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    auth: { refreshSession: async () => ({ data: null, error: null }) as any },
+  }
+}
+
+function seedChannels(rt: RealtimeService, names: string[]): Map<string, AuraChannel> {
+  const map = (rt as unknown as { _channels: Map<string, AuraChannel> })._channels
+  for (const n of names) map.set(n, new AuraChannel(n, 'proj'))
+  return map
+}
+
+function dispatch(rt: RealtimeService, msg: unknown): void {
+  ;(rt as unknown as { _dispatch: (m: unknown) => void })._dispatch(msg)
+}
+
+describe('RealtimeService._dispatch — routage broadcast_ack par ref_id', () => {
+  it("un broadcast_ack n'est dispatché qu'au channel émetteur (extrait du préfixe ref_id)", () => {
+    const rt = new RealtimeService(client())
+    const map = seedChannels(rt, ['room-1', 'room-2'])
+    const spy1 = vi.spyOn(map.get('room-1')!, '_onMessage').mockImplementation(() => {})
+    const spy2 = vi.spyOn(map.get('room-2')!, '_onMessage').mockImplementation(() => {})
+
+    dispatch(rt, { type: 'broadcast_ack', message_id: 'm1', ref_id: 'proj:room-1:r3' })
+
+    expect(spy1).toHaveBeenCalledTimes(1)
+    expect(spy2).not.toHaveBeenCalled()
+  })
+
+  it('résout par message_id absent de ref_id ? — fallback dispatch à tous si ref_id non résoluble', () => {
+    const rt = new RealtimeService(client())
+    const map = seedChannels(rt, ['room-1', 'room-2'])
+    const spy1 = vi.spyOn(map.get('room-1')!, '_onMessage').mockImplementation(() => {})
+    const spy2 = vi.spyOn(map.get('room-2')!, '_onMessage').mockImplementation(() => {})
+
+    // Pas de ref_id (message_id brut, aucun ':r') → non résoluble → fallback à tous.
+    dispatch(rt, { type: 'broadcast_ack', message_id: 'uuid-sans-prefixe' })
+
+    expect(spy1).toHaveBeenCalledTimes(1)
+    expect(spy2).toHaveBeenCalledTimes(1)
+  })
+
+  it("la promesse channel.send(ack:true) se résout 'ok' sur réception de l'ACK routé", async () => {
+    const rt = new RealtimeService(client())
+    const map = (rt as unknown as { _channels: Map<string, AuraChannel> })._channels
+    const ch = new AuraChannel('room-1', 'proj', { broadcast: { ack: true } })
+    const sent: string[] = []
+    ch._bindSend((d) => sent.push(d))
+    map.set('room-1', ch)
+
+    const p = ch.send({ type: 'broadcast', event: 'ping', payload: { a: 1 } })
+
+    // Récupérer le ref_id réellement émis par le channel.
+    const outbound = JSON.parse(sent[0]!) as { ref_id: string }
+    dispatch(rt, { type: 'broadcast_ack', message_id: 'm', ref_id: outbound.ref_id })
+
+    await expect(p).resolves.toBe('ok')
+  })
+
+  it('nom de channel contenant ":r" — lastIndexOf isole bien le suffixe :r{n}', () => {
+    const rt = new RealtimeService(client())
+    const map = seedChannels(rt, ['weird:r-name'])
+    const spy = vi.spyOn(map.get('weird:r-name')!, '_onMessage').mockImplementation(() => {})
+
+    dispatch(rt, { type: 'broadcast_ack', message_id: 'm', ref_id: 'proj:weird:r-name:r7' })
+
+    expect(spy).toHaveBeenCalledTimes(1)
+  })
+})

package/packages/realtime/tests/column-filter.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect } from 'vitest'
+import { matchesColumnFilter } from '../src/columnFilter'
+
+// Ces tests portent la même sémantique que le backend Rust
+// (services/aura-realtime/src/protocol.rs) : eq/neq/lt/lte/gt/gte/in/like/ilike/
+// is/match/imatch/isdistinct, négation `not.`, AND par virgules (hors `in.(...)`),
+// fail-closed sur filtre non parsable, champ absent = exclusion ferme (jamais inversée).
+
+describe('matchesColumnFilter — opérateurs de base', () => {
+  it('eq', () => {
+    expect(matchesColumnFilter('room_id=eq.42', { room_id: 42 })).toBe(true)
+    expect(matchesColumnFilter('room_id=eq.42', { room_id: 7 })).toBe(false)
+  })
+
+  it('neq', () => {
+    expect(matchesColumnFilter('status=neq.deleted', { status: 'active' })).toBe(true)
+    expect(matchesColumnFilter('status=neq.deleted', { status: 'deleted' })).toBe(false)
+  })
+
+  it('lt/lte/gt/gte numérique', () => {
+    expect(matchesColumnFilter('age=lt.18', { age: 10 })).toBe(true)
+    expect(matchesColumnFilter('age=lt.18', { age: 18 })).toBe(false)
+    expect(matchesColumnFilter('age=lte.18', { age: 18 })).toBe(true)
+    expect(matchesColumnFilter('qty=gt.5', { qty: 10 })).toBe(true)
+    expect(matchesColumnFilter('qty=gt.5', { qty: 5 })).toBe(false)
+    expect(matchesColumnFilter('score=gte.50', { score: 50 })).toBe(true)
+    expect(matchesColumnFilter('score=gte.50', { score: 49 })).toBe(false)
+  })
+
+  it('lt/gt sur types incompatibles => false (fail-closed)', () => {
+    expect(matchesColumnFilter('name=gt.100', { name: 'hello' })).toBe(false)
+  })
+
+  it('in — respecte les parenthèses et les espaces', () => {
+    expect(matchesColumnFilter('status=in.(a,b)', { status: 'b' })).toBe(true)
+    expect(matchesColumnFilter('status=in.(a,b)', { status: 'c' })).toBe(false)
+    expect(matchesColumnFilter('status=in.(active, pending, done)', { status: 'pending' })).toBe(true)
+  })
+
+  it('like / ilike', () => {
+    expect(matchesColumnFilter('name=like.jo%', { name: 'john' })).toBe(true)
+    expect(matchesColumnFilter('name=like.jo%', { name: 'alice' })).toBe(false)
+    expect(matchesColumnFilter('name=ilike.JO%', { name: 'john' })).toBe(true)
+    expect(matchesColumnFilter('name=ilike.JO%', { name: 'JOHN' })).toBe(true)
+    expect(matchesColumnFilter('name=ilike.JO%', { name: 'alice' })).toBe(false)
+  })
+
+  it('is — null/true/false sur la valeur réelle', () => {
+    expect(matchesColumnFilter('deleted_at=is.null', { deleted_at: null })).toBe(true)
+    expect(matchesColumnFilter('deleted_at=is.null', { deleted_at: '2026' })).toBe(false)
+    expect(matchesColumnFilter('active=is.true', { active: true })).toBe(true)
+    expect(matchesColumnFilter('active=is.true', { active: false })).toBe(false)
+    expect(matchesColumnFilter('active=is.false', { active: false })).toBe(true)
+    expect(matchesColumnFilter('active=is.false', { active: true })).toBe(false)
+  })
+
+  it('match / imatch — RegExp', () => {
+    expect(matchesColumnFilter('email=match.^[a-z]+@example\\.com$', { email: 'alice@example.com' })).toBe(true)
+    expect(matchesColumnFilter('email=match.^[a-z]+@example\\.com$', { email: 'ALICE@example.com' })).toBe(false)
+    expect(matchesColumnFilter('email=imatch.^[a-z]+@example\\.com$', { email: 'ALICE@example.com' })).toBe(true)
+  })
+
+  it('isdistinct — NULL distinct de toute valeur non-NULL', () => {
+    expect(matchesColumnFilter('status=isdistinct.done', { status: 'open' })).toBe(true)
+    expect(matchesColumnFilter('status=isdistinct.done', { status: 'done' })).toBe(false)
+    expect(matchesColumnFilter('status=isdistinct.done', { status: null })).toBe(true)
+  })
+})
+
+describe('matchesColumnFilter — négation not.', () => {
+  it('inverse le résultat sémantique', () => {
+    expect(matchesColumnFilter('status=not.eq.done', { status: 'open' })).toBe(true)
+    expect(matchesColumnFilter('status=not.eq.done', { status: 'done' })).toBe(false)
+  })
+
+  it('ne fail-open jamais sur champ absent (non évaluable => exclusion ferme)', () => {
+    // Sémantique SQL : NOT (col = x) avec col NULL/absent => NULL => exclu, pas inversé en true.
+    expect(matchesColumnFilter('status=not.eq.done', { id: 1 })).toBe(false)
+  })
+})
+
+describe('matchesColumnFilter — AND (virgules)', () => {
+  it('toutes les conditions doivent matcher', () => {
+    expect(matchesColumnFilter('room_id=eq.42,qty=gt.5', { room_id: 42, qty: 9 })).toBe(true)
+    expect(matchesColumnFilter('room_id=eq.42,qty=gt.5', { room_id: 42, qty: 1 })).toBe(false)
+  })
+
+  it("respecte les virgules internes d'un in.(...)", () => {
+    expect(matchesColumnFilter('status=in.(a,b),qty=gt.5', { status: 'b', qty: 9 })).toBe(true)
+    expect(matchesColumnFilter('status=in.(a,b),qty=gt.5', { status: 'c', qty: 9 })).toBe(false)
+  })
+})
+
+describe('matchesColumnFilter — fail-closed', () => {
+  it('filtre non parsable (syntaxe invalide) => false', () => {
+    expect(matchesColumnFilter('garbage', { a: 1 })).toBe(false)
+  })
+
+  it('opérateur inconnu => false', () => {
+    expect(matchesColumnFilter('col=unknown.val', { col: 'val' })).toBe(false)
+  })
+
+  it('une condition AND invalide invalide tout le set => false', () => {
+    expect(matchesColumnFilter('room_id=eq.42,garbage', { room_id: 42 })).toBe(false)
+  })
+
+  it('regex match/imatch invalide => filtre rejeté (false), jamais inversé par not.', () => {
+    expect(matchesColumnFilter('name=match.(unclosed', { name: 'anything' })).toBe(false)
+    expect(matchesColumnFilter('name=not.match.(unclosed', { name: 'anything' })).toBe(false)
+  })
+
+  it('pattern match trop long (>512) => rejeté', () => {
+    const longPattern = 'a'.repeat(513)
+    expect(matchesColumnFilter(`name=match.${longPattern}`, { name: 'a'.repeat(513) })).toBe(false)
+  })
+
+  it('in avec plus de 100 valeurs => rejeté', () => {
+    const values = Array.from({ length: 101 }, (_, i) => String(i + 1)).join(',')
+    expect(matchesColumnFilter(`id=in.(${values})`, { id: 1 })).toBe(false)
+  })
+
+  it('is.<valeur invalide> => rejeté au parse (pas null/true/false)', () => {
+    expect(matchesColumnFilter('active=is.garbage', { active: true })).toBe(false)
+    expect(matchesColumnFilter('active=is.garbage', { active: false })).toBe(false)
+  })
+
+  it('not.is.<valeur invalide> ne fail-open jamais (recoin fermé)', () => {
+    // Avant le fix : is.garbage était accepté au parse, matchesRaw renvoyait false,
+    // et `not.` inversait ce false en true => le filtre matchait tout event.
+    expect(matchesColumnFilter('active=not.is.garbage', { active: true })).toBe(false)
+    expect(matchesColumnFilter('active=not.is.garbage', { active: false })).toBe(false)
+  })
+})
+
+describe('matchesColumnFilter — champ absent', () => {
+  it('champ absent => exclusion ferme (jamais un match)', () => {
+    expect(matchesColumnFilter('xyz=eq.1', { other: 1 })).toBe(false)
+  })
+
+  it('champ null (présent) sur eq => comparaison textuelle "null", pas une exclusion', () => {
+    expect(matchesColumnFilter('name=eq.test', { name: null })).toBe(false)
+    expect(matchesColumnFilter('name=eq.null', { name: null })).toBe(true)
+  })
+})