bunderstack 0.16.0 → 0.17.0-beta.2

package/src/realtime/redis.ts

@@ -1,219 +0,0 @@
-import type { RealtimeAction, RealtimeBroker } from './index'
-
-// packages/bunderstack/src/realtime-redis.ts
-//
-// Redis-backed realtime broker: cross-instance fan-out + persistent replay log.
-//
-// Fan-out model: every instance SUBSCRIBEs one channel. publish() INCRs a global
-// counter (monotonic eventId across instances/restarts), LPUSH+LTRIM a capped log
-// for replay, then PUBLISHes. Redis delivers the message to ALL subscribers
-// including the publisher, so local delivery happens uniformly inside the channel
-// listener — never directly in publish() — to avoid double-delivery.
-import {
-  checkAccessSync,
-  rowMatchesScope,
-  tableEntryForName,
-  type AccessUser,
-  type ResolvedAccess,
-} from '../access'
-
-export type RedisLike = {
-  incr(key: string): Promise<number>
-  publish(channel: string, message: string): Promise<unknown>
-  subscribe(
-    channel: string,
-    listener: (message: string) => void,
-  ): Promise<unknown>
-  lpush(key: string, value: string): Promise<unknown>
-  ltrim(key: string, start: number, stop: number): Promise<unknown>
-  lrange(key: string, start: number, stop: number): Promise<string[]>
-  close?(): void | Promise<void>
-}
-
-type Subscriber = {
-  id: string
-  send: (data: string) => void
-  user: AccessUser | null
-  activeOrganizationId: string | null
-  subscriptions: Set<string>
-}
-
-type WireEvent = {
-  eventId: number
-  table: string
-  action: RealtimeAction
-  record: Record<string, unknown>
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
-}
-
-function isRealtimeAction(value: unknown): value is RealtimeAction {
-  return value === 'create' || value === 'update' || value === 'delete'
-}
-
-function parseWireEvent(raw: string): WireEvent | null {
-  try {
-    const value = JSON.parse(raw)
-    if (
-      !isRecord(value) ||
-      typeof value.eventId !== 'number' ||
-      typeof value.table !== 'string' ||
-      !isRealtimeAction(value.action) ||
-      !isRecord(value.record)
-    ) {
-      return null
-    }
-    return {
-      eventId: value.eventId,
-      table: value.table,
-      action: value.action,
-      record: value.record,
-    }
-  } catch {
-    return null
-  }
-}
-
-export function createRedisRealtimeBroker(opts: {
-  access: ResolvedAccess
-  /** A factory keeps Redis completely cold until SSE or a publish needs it. */
-  redis: RedisLike | (() => RedisLike)
-  bufferSize?: number
-  channel?: string
-}): RealtimeBroker {
-  const subscribers = new Map<string, Subscriber>()
-  const bufferSize = opts.bufferSize ?? 1000
-  const channel = opts.channel ?? 'bunderstack:realtime'
-  const logKey = `${channel}:log`
-  const counterKey = `${channel}:seq`
-  let redis: RedisLike | undefined
-
-  const getRedis = () => {
-    redis ??= typeof opts.redis === 'function' ? opts.redis() : opts.redis
-    return redis
-  }
-
-  function deliverable(
-    s: Subscriber,
-    table: string,
-    record: Record<string, unknown>,
-  ): boolean {
-    const entry = tableEntryForName(opts.access, table)
-    if (!entry) return false
-    const id = record['id']
-    const topicMatch =
-      s.subscriptions.has(table) ||
-      (id != null && s.subscriptions.has(`${table}/${String(id)}`))
-    if (!topicMatch) return false
-    const ctx = {
-      user: s.user,
-      request: new Request('http://realtime.local'),
-      row: record,
-      session: { activeOrganizationId: s.activeOrganizationId },
-    }
-    if (typeof entry.get === 'function') return false
-    if (!checkAccessSync(entry.get, ctx, entry.ownerColumn).allowed)
-      return false
-    if (entry.readScope && !rowMatchesScope(record, entry.readScope(ctx)))
-      return false
-    return true
-  }
-
-  function fanOut(evt: WireEvent) {
-    const payload = JSON.stringify(evt)
-    for (const s of subscribers.values()) {
-      if (deliverable(s, evt.table, evt.record)) s.send(payload)
-    }
-  }
-
-  let started: Promise<void> | undefined
-  let closed = false
-
-  const start = () => {
-    if (closed)
-      return Promise.reject(
-        new Error('[bunderstack] realtime broker is closed'),
-      )
-    started ??= getRedis()
-      .subscribe(channel, (message) => {
-        const evt = parseWireEvent(message)
-        if (evt) fanOut(evt)
-      })
-      .then(() => undefined)
-    return started
-  }
-
-  return {
-    start,
-    async close() {
-      closed = true
-      subscribers.clear()
-      await redis?.close?.()
-    },
-    register(send) {
-      const id = crypto.randomUUID()
-      subscribers.set(id, {
-        id,
-        send,
-        user: null,
-        activeOrganizationId: null,
-        subscriptions: new Set(),
-      })
-      return { id }
-    },
-    async setContext(id, ctx) {
-      const s = subscribers.get(id)
-      if (!s) return { gap: false }
-      s.user = ctx.user
-      s.activeOrganizationId = ctx.activeOrganizationId
-      s.subscriptions = ctx.subscriptions
-
-      const since = ctx.since ?? null
-      if (since == null) return { gap: false }
-
-      // Log is LPUSH-ed (newest first); read newest->oldest, filter id>since.
-      // If redis is unavailable, return { gap: true } so the client falls back
-      // to a full refetch rather than 500-ing the POST handler.
-      let raw: string[]
-      try {
-        raw = await getRedis().lrange(logKey, 0, bufferSize - 1)
-      } catch {
-        return { gap: true }
-      }
-      const events = raw
-        .map(parseWireEvent)
-        .filter((e) => e !== null)
-        .filter((e) => e.eventId > since)
-        .sort((a, b) => a.eventId - b.eventId)
-
-      const oldestInLog = events.length ? events[0]!.eventId : since + 1
-      const gap = oldestInLog > since + 1
-      for (const e of events) {
-        if (deliverable(s, e.table, e.record)) s.send(JSON.stringify(e))
-      }
-      return { gap }
-    },
-    unregister(id) {
-      subscribers.delete(id)
-    },
-    async publish(table, action, record) {
-      if (!tableEntryForName(opts.access, table)) return
-      try {
-        const client = getRedis()
-        const eventId = await client.incr(counterKey)
-        const evt: WireEvent = { eventId, table, action, record }
-        const msg = JSON.stringify(evt)
-        await client.lpush(logKey, msg)
-        await client.ltrim(logKey, 0, bufferSize - 1)
-        await client.publish(channel, msg)
-      } catch {
-        // Broadcast is best-effort: a redis blip must not reject the floating
-        // promise (callers use `void broker?.publish(...)` with no .catch).
-        // Correctness self-heals: reconnecting clients use the since/gap replay
-        // path which issues a full refetch when events were missed.
-      }
-    },
-  }
-}

package/src/routes.ts

@@ -1,137 +0,0 @@
-// src/routes.ts — mounting user-supplied Hono routes inside the app.
-
-/** A route as Hono reports it on `app.routes`. */
-export type DeclaredRoute = { method: string; path: string }
-
-const RESERVED_EXACT = ['/health', '/api/health', '/api/realtime'] as const
-
-const RESERVED_PREFIXES = [
-  '/api/auth/',
-  '/api/trpc/',
-  '/api/files/',
-  '/files/',
-] as const
-
-/** The first path segment under `/api/`, or undefined when not under it. */
-function apiSegment(path: string): string | undefined {
-  if (!path.startsWith('/api/')) return undefined
-  return path.slice('/api/'.length).split('/')[0]
-}
-
-function collisionFor(
-  route: DeclaredRoute,
-  tableNames: readonly string[],
-): string | undefined {
-  const { path } = route
-  if (RESERVED_EXACT.includes(path as (typeof RESERVED_EXACT)[number])) {
-    return `it is reserved by bunderstack`
-  }
-  for (const prefix of RESERVED_PREFIXES) {
-    if (path.startsWith(prefix)) {
-      return `"${prefix}*" is reserved by bunderstack`
-    }
-  }
-  const segment = apiSegment(path)
-  if (segment === undefined) return undefined
-  if (segment === '*' || segment.startsWith(':')) {
-    return `a parameter or wildcard here would shadow every generated CRUD route`
-  }
-  if (tableNames.includes(segment)) {
-    return `it collides with the generated CRUD route for table "${segment}"`
-  }
-  return undefined
-}
-
-/**
- * Throws when any declared route would collide with a bunderstack route.
- *
- * Custom routes are registered before the built-ins, so a collision silently
- * shadows core behaviour — including authentication. Failing at construction is
- * the cheapest place to find out.
- */
-export function validateCustomRoutes(
-  routes: readonly DeclaredRoute[],
-  tableNames: readonly string[],
-): void {
-  const problems: string[] = []
-  for (const route of routes) {
-    const reason = collisionFor(route, tableNames)
-    if (reason) {
-      problems.push(`  ${route.method} ${route.path} — ${reason}`)
-    }
-  }
-  if (problems.length === 0) return
-  throw new Error(
-    `[bunderstack] routes: ${problems.length} route(s) collide with bunderstack's own:\n${problems.join('\n')}\nChoose different paths.`,
-  )
-}
-
-import type { Hono } from 'hono'
-
-import type { AccessUser, AuthSessionResolver } from './access'
-import type { DbFor } from './db'
-import type { EmailFacade } from './email'
-import type { JobsRuntimeFacade } from './jobs/define'
-import type { RealtimeFacade } from './realtime/facade'
-import type { AuthInstance, StorageFacade } from './index'
-
-import { resolveAccessUser, resolveSession } from './access'
-
-export type RouteContext<
-  TSchema extends Record<string, unknown> = Record<string, unknown>,
-  TEnvResult = Record<string, unknown>,
-> = {
-  db: DbFor<TSchema>
-  env: TEnvResult
-  storage: StorageFacade
-  email: EmailFacade
-  jobs: JobsRuntimeFacade
-  realtime: RealtimeFacade<TSchema>
-  auth: AuthInstance
-  /** Resolve the caller's session. Costs an auth round-trip; call only when needed. */
-  getSession(
-    request: Request,
-  ): Promise<{ user: AccessUser | null; activeOrganizationId: string | null }>
-  /** Convenience wrapper over getSession when the organization is irrelevant. */
-  getUser(request: Request): Promise<AccessUser | null>
-}
-
-/** Alias mirroring the JobContext / BunderstackJobContext pair. */
-export type BunderstackRouteContext<
-  TSchema extends Record<string, unknown> = Record<string, unknown>,
-  TEnvResult = Record<string, unknown>,
-> = RouteContext<TSchema, TEnvResult>
-
-export type RoutesBuilder<
-  TSchema extends Record<string, unknown> = Record<string, unknown>,
-  TEnvResult = Record<string, unknown>,
-> = (ctx: RouteContext<TSchema, TEnvResult>) => Hono
-
-export function createRouteContext<
-  TSchema extends Record<string, unknown>,
-  TEnvResult,
->(deps: {
-  db: DbFor<TSchema>
-  env: TEnvResult
-  storage: StorageFacade
-  email: EmailFacade
-  jobs: JobsRuntimeFacade
-  realtime: RealtimeFacade<TSchema>
-  auth: AuthInstance
-  authResolver: AuthSessionResolver | undefined
-}): RouteContext<TSchema, TEnvResult> {
-  return {
-    db: deps.db,
-    env: deps.env,
-    storage: deps.storage,
-    email: deps.email,
-    jobs: deps.jobs,
-    realtime: deps.realtime,
-    auth: deps.auth,
-    // Lazy on purpose: a webhook has no session, and resolving one eagerly
-    // would spend an auth round-trip per request on a value nobody reads.
-    getSession: (request) => resolveSession(deps.authResolver, request.headers),
-    getUser: (request) => resolveAccessUser(deps.authResolver, request.headers),
-  }
-}
-