@avelonjs/supabase 0.1.0

package/src/database/driver.ts

@@ -0,0 +1,437 @@
+import { SQL } from 'bun'
+import {
+  Invalid,
+  type DatabaseDriver,
+  type MigrationPlan,
+  type MigrationStatus,
+  type Predicate,
+  type QueryIR,
+  type QueryResult,
+  type RelationLoad,
+  type RowSecuritySurface,
+} from '@avelonjs/core'
+import {
+  applyMigrations,
+  assertQueryAgainstSchema,
+  combinedPredicate,
+  loadSchemaCache,
+  planMigrations,
+  rollbackMigrations,
+  statusMigrations,
+  validateQueryIR,
+  type PostgresMigration,
+  type SchemaCache,
+} from '@avelonjs/postgres'
+import { compilePostgrest } from './compile'
+import { mapPostgrestError } from './errors'
+import { resetSupabaseAssayFixtures } from './fixtures'
+import { compileAllWardPolicies, type WardPolicy } from './wards'
+
+/** Exact capability declaration for the Supabase/PostgREST database driver. */
+export const supabaseDatabaseCapabilities = {
+  transactions: false,
+  rowSecurity: true,
+  /** Measured against live PostgREST embed/relation loading in M0; nested loads are application-side. */
+  maxRelationDepth: 2,
+  fullTextSearch: false,
+  upsert: true,
+  returning: true,
+  windowFunctions: false,
+  jsonOperators: true,
+} as const
+
+/** Construction options for {@link SupabaseDatabase}. */
+export interface SupabaseDatabaseOptions {
+  /** PostgREST REST root, e.g. `http://127.0.0.1:3001`. */
+  restUrl?: string
+  /** Service-role JWT used for privileged conformance and sync operations. */
+  serviceRoleKey?: string
+  /** Direct Postgres URL for fixtures, schema cache, migrations, and RLS sync. */
+  databaseUrl?: string
+  /** Configured connection name. */
+  instance?: string
+  /** Ward policies applied by `syncWards()`. */
+  wards?: readonly WardPolicy[]
+  /** Driver-owned SQL migrations applied over the direct Postgres admin connection. */
+  migrations?: readonly PostgresMigration[]
+}
+
+type Row = Record<string, unknown>
+
+function defaultRestUrl(): string {
+  return process.env.SUPABASE_REST_URL ?? process.env.REST_URL ?? 'http://127.0.0.1:3001'
+}
+
+function defaultServiceRoleKey(): string {
+  return (
+    process.env.SUPABASE_SERVICE_ROLE_KEY ??
+    process.env.SERVICE_ROLE_KEY ??
+    // Local PostgREST test JWT for role=service_role (see packages/supabase/README.md).
+    'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoic2VydmljZV9yb2xlIiwiaXNzIjoiYXZlbG9uIn0.pXO2ckfFU75vmRms3ufo5B8Vto-b2ESmMt4wnyj9GYY'
+  )
+}
+
+function defaultDatabaseUrl(): string {
+  return (
+    process.env.SUPABASE_DB_URL ??
+    process.env.DATABASE_URL ??
+    'postgresql://postgres:avelon@127.0.0.1:5432/avelon_supabase'
+  )
+}
+
+function includeColumns(select: string[] | '*', columns: string[]): string[] | '*' {
+  if (select === '*') return '*'
+  return [...new Set([...select, ...columns])]
+}
+
+function projectRow(row: Row, select: string[] | '*', relations: readonly RelationLoad[]): Row {
+  const output: Row = {}
+  const columns =
+    select === '*'
+      ? Object.keys(row).filter((column) => !relations.some((relation) => relation.relation === column))
+      : select
+  for (const column of columns) output[column] = row[column]
+  for (const relation of relations) output[relation.relation] = row[relation.relation]
+  return output
+}
+
+function unique(values: unknown[]): unknown[] {
+  const output: unknown[] = []
+  for (const value of values) {
+    if (!output.some((existing) => existing === value)) output.push(value)
+  }
+  return output
+}
+
+/**
+ * Supabase/PostgREST implementation of the frozen database contract.
+ *
+ * Query traffic goes through PostgREST. Fixture reset, schema introspection, migrations, and ward
+ * sync use a direct Postgres connection because those operations are not portable over REST.
+ */
+export class SupabaseDatabase
+  implements
+    DatabaseDriver<typeof supabaseDatabaseCapabilities, { restUrl: string }>,
+    RowSecuritySurface
+{
+  readonly name = 'supabase'
+  readonly instance: string
+  readonly capabilities = supabaseDatabaseCapabilities
+
+  readonly #restUrl: string
+  readonly #serviceRoleKey: string
+  readonly #sql: SQL
+  readonly #wards: readonly WardPolicy[]
+  readonly #migrations: readonly PostgresMigration[]
+  #schema: SchemaCache | undefined
+  #roundTrips = 0
+
+  constructor(options: SupabaseDatabaseOptions = {}) {
+    this.instance = options.instance ?? 'default'
+    this.#restUrl = (options.restUrl ?? defaultRestUrl()).replace(/\/$/, '')
+    this.#serviceRoleKey = options.serviceRoleKey ?? defaultServiceRoleKey()
+    this.#sql = new SQL(options.databaseUrl ?? defaultDatabaseUrl())
+    this.#wards = options.wards ?? []
+    this.#migrations = options.migrations ?? []
+  }
+
+  /** Number of PostgREST round trips. Used by conformance short-circuit checks. */
+  get roundTrips(): number {
+    return this.#roundTrips
+  }
+
+  /** Returns the REST configuration at the vendor boundary. */
+  raw(): { restUrl: string } {
+    return { restUrl: this.#restUrl }
+  }
+
+  /** Recreates assay fixtures and reloads the PostgREST schema cache. */
+  async resetFixtures(): Promise<void> {
+    await resetSupabaseAssayFixtures(this.#sql)
+    this.#schema = undefined
+    await this.#waitForSchema()
+  }
+
+  /** Closes the direct Postgres admin client. */
+  async close(): Promise<void> {
+    await this.#sql.close()
+  }
+
+  async execute<TRow = Record<string, unknown>>(query: QueryIR): Promise<QueryResult<TRow>> {
+    return this.#execute(query, this.#serviceRoleKey) as Promise<QueryResult<TRow>>
+  }
+
+  /**
+   * Executes a query as a specific bearer token.
+   *
+   * Used by the live RLS denial test so two authenticated identities can be compared.
+   */
+  async executeAs<TRow = Record<string, unknown>>(
+    bearerToken: string,
+    query: QueryIR,
+  ): Promise<QueryResult<TRow>> {
+    return this.#execute(query, bearerToken) as Promise<QueryResult<TRow>>
+  }
+
+  async rpc<TResult = unknown>(
+    routine: string,
+    args: Readonly<Record<string, unknown>>,
+  ): Promise<TResult> {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(routine)) {
+      throw new Invalid('Routine name must be a simple identifier.', {
+        metadata: { fields: { routine: [routine] } },
+      })
+    }
+    this.#roundTrips += 1
+    const response = await fetch(`${this.#restUrl}/rpc/${routine}`, {
+      method: 'POST',
+      headers: {
+        ...this.#authHeaders(this.#serviceRoleKey),
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+      // PostgREST matches JSON keys to function argument names; assay_echo(args jsonb).
+      body: JSON.stringify({ args }),
+    })
+    const text = await response.text()
+    if (!response.ok) mapPostgrestError(response.status, text, 'rpc')
+    if (text.length === 0) return undefined as TResult
+    const parsed = JSON.parse(text) as unknown
+    return decodeJsonResult(parsed) as TResult
+  }
+
+  /** Produces the pending migration plan from the direct Postgres connection. */
+  async plan(): Promise<MigrationPlan> {
+    return planMigrations(this.#sql, this.#migrations)
+  }
+
+  /** Applies pending driver-owned migrations. */
+  async apply(): Promise<readonly MigrationStatus[]> {
+    return applyMigrations(this.#sql, this.#migrations)
+  }
+
+  /** Rolls back applied migration batches. */
+  async rollback(steps?: number): Promise<readonly MigrationStatus[]> {
+    return rollbackMigrations(this.#sql, this.#migrations, steps)
+  }
+
+  /** Returns all migration states. */
+  async status(): Promise<readonly MigrationStatus[]> {
+    return statusMigrations(this.#sql, this.#migrations)
+  }
+
+  /** Compiles registered wards into Postgres RLS policies and applies them. */
+  async syncWards(): Promise<void> {
+    const statements = compileAllWardPolicies(this.#wards)
+    for (const statement of statements) {
+      await this.#sql.unsafe(statement)
+    }
+    await this.#sql.unsafe(`NOTIFY pgrst, 'reload schema'`)
+  }
+
+  async #schemaCache(): Promise<SchemaCache> {
+    if (this.#schema === undefined) this.#schema = await loadSchemaCache(this.#sql)
+    return this.#schema
+  }
+
+  async #execute(ir: QueryIR, bearerToken: string): Promise<QueryResult> {
+    validateQueryIR(ir, this.capabilities.maxRelationDepth)
+    assertQueryAgainstSchema(await this.#schemaCache(), ir)
+    const predicate = combinedPredicate(ir)
+
+    if (predicate.kind === 'const' && !predicate.value) {
+      return ir.mode === 'count' ? { rows: [], affected: 0, count: 0 } : { rows: [], affected: 0 }
+    }
+
+    if ((ir.mode === 'insert' || ir.mode === 'upsert') && predicate.kind !== 'const') {
+      throw new Invalid(`${ir.mode} with a non-constant where or ward has no documented row scope.`, {
+        metadata: { fields: { where: [`${ir.mode} predicates are not documented`] } },
+      })
+    }
+
+    if (ir.mode === 'select') {
+      const primitive: QueryIR = {
+        ...ir,
+        select: includeColumns(
+          ir.select,
+          ir.relations.map((relation) => relation.localKey),
+        ),
+        relations: [],
+      }
+      const rows = await this.#executePrimitive(primitive, predicate, bearerToken)
+      await this.#loadRelations(rows, ir.relations, bearerToken)
+      return {
+        rows: rows.map((row) => projectRow(row, ir.select, ir.relations)),
+        affected: 0,
+      }
+    }
+
+    if (ir.mode === 'count') {
+      const count = await this.#executeCount(ir, predicate, bearerToken)
+      return { rows: [], affected: 0, count }
+    }
+
+    const rows = await this.#executePrimitive(ir, predicate, bearerToken)
+    return {
+      rows: ir.returning === undefined ? [] : projectReturning(rows, ir.returning),
+      affected: rows.length,
+    }
+  }
+
+  async #executeCount(ir: QueryIR, predicate: Predicate, bearerToken: string): Promise<number> {
+    const compiled = compilePostgrest({ ...ir, mode: 'count', select: [], order: [], relations: [] }, predicate)
+    const url = new URL(`${this.#restUrl}${compiled.path}`)
+    if (compiled.query) url.search = compiled.query
+    this.#roundTrips += 1
+    const response = await fetch(url, {
+      method: 'HEAD',
+      headers: { ...this.#authHeaders(bearerToken), ...compiled.headers },
+    })
+    if (!response.ok) {
+      mapPostgrestError(response.status, await response.text(), 'count')
+    }
+    const range = response.headers.get('content-range')
+    if (range === null) {
+      throw new Invalid('PostgREST returned no content-range for a count.', {
+        metadata: { fields: { mode: ['Expected exact count'] } },
+      })
+    }
+    const total = range.split('/')[1]
+    if (total === undefined || total === '*') {
+      throw new Invalid(`PostgREST count was not exact: ${range}`, {
+        metadata: { fields: { mode: [range] } },
+      })
+    }
+    return Number(total)
+  }
+
+  async #executePrimitive(
+    ir: QueryIR,
+    predicate: Predicate,
+    bearerToken: string,
+  ): Promise<Row[]> {
+    const compiled = compilePostgrest(ir, predicate)
+    const path = compiled.query ? `${compiled.path}?${compiled.query}` : compiled.path
+    const rows = await this.#requestRows(path, {
+      method: compiled.method,
+      headers: { ...this.#authHeaders(bearerToken), ...compiled.headers },
+      body: compiled.body,
+    })
+    if (compiled.path === '/rpc/avelon_upsert_subset') {
+      // RPC returns a JSON array value; PostgREST may wrap it as [{ avelon_upsert_subset: [...] }].
+      if (rows.length === 1 && Array.isArray(rows[0]?.avelon_upsert_subset)) {
+        return rows[0].avelon_upsert_subset as Row[]
+      }
+      return rows
+    }
+    return rows
+  }
+
+  async #loadRelations(
+    parents: Row[],
+    relations: readonly RelationLoad[],
+    bearerToken: string,
+  ): Promise<void> {
+    for (const relation of relations) {
+      const keys = unique(
+        parents
+          .map((parent) => parent[relation.localKey])
+          .filter((value) => value !== null && value !== undefined),
+      )
+      if (keys.length === 0) {
+        for (const parent of parents) {
+          parent[relation.relation] = relation.kind === 'hasMany' ? [] : null
+        }
+        continue
+      }
+
+      const childSelect = includeColumns(relation.select, [
+        relation.foreignKey,
+        ...relation.relations.map((nested) => nested.localKey),
+      ])
+      const childWhere: Predicate[] = [
+        ...(relation.where === null ? [] : [relation.where]),
+        { kind: 'in', column: relation.foreignKey, values: keys, negated: false },
+      ]
+      const childIR: QueryIR = {
+        table: relation.table,
+        mode: 'select',
+        select: childSelect,
+        where: childWhere,
+        relations: [],
+        order: relation.order,
+      }
+      const predicate = combinedPredicate(childIR)
+      const children =
+        predicate.kind === 'const' && !predicate.value
+          ? []
+          : await this.#executePrimitive(childIR, predicate, bearerToken)
+      await this.#loadRelations(children, relation.relations, bearerToken)
+
+      for (const parent of parents) {
+        const matches = children.filter(
+          (child) => child[relation.foreignKey] === parent[relation.localKey],
+        )
+        const limited = relation.limit === undefined ? matches : matches.slice(0, relation.limit)
+        const projected = limited.map((child) =>
+          projectRow(child, relation.select, relation.relations),
+        )
+        parent[relation.relation] = relation.kind === 'hasMany' ? projected : (projected[0] ?? null)
+      }
+    }
+  }
+
+  async #requestRows(path: string, init: RequestInit): Promise<Row[]> {
+    this.#roundTrips += 1
+    const response = await fetch(`${this.#restUrl}${path}`, init)
+    const text = await response.text()
+    if (!response.ok) mapPostgrestError(response.status, text, 'execute')
+    if (text.length === 0) return []
+    const parsed = JSON.parse(text) as unknown
+    if (Array.isArray(parsed)) return parsed.map((row) => ({ ...(row as Row) }))
+    if (typeof parsed === 'object' && parsed !== null) return [{ ...(parsed as Row) }]
+    return [{ value: parsed }]
+  }
+
+  #authHeaders(bearerToken: string): Record<string, string> {
+    return {
+      apikey: bearerToken,
+      Authorization: `Bearer ${bearerToken}`,
+    }
+  }
+
+  async #waitForSchema(): Promise<void> {
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+      const response = await fetch(`${this.#restUrl}/assay_users?select=id&limit=0`, {
+        headers: this.#authHeaders(this.#serviceRoleKey),
+      })
+      if (response.ok || response.status === 200 || response.status === 206) return
+      await Bun.sleep(100)
+    }
+  }
+}
+
+/** Creates a Supabase database driver from options or environment defaults. */
+export function createSupabaseDatabase(options: SupabaseDatabaseOptions = {}): SupabaseDatabase {
+  return new SupabaseDatabase(options)
+}
+
+function projectReturning(rows: Row[], returning: string[] | '*'): Row[] {
+  if (returning === '*') return rows
+  return rows.map((row) => {
+    const projected: Row = {}
+    for (const column of returning) projected[column] = row[column]
+    return projected
+  })
+}
+
+function decodeJsonResult(value: unknown): unknown {
+  if (typeof value === 'string') {
+    try {
+      return JSON.parse(value)
+    } catch {
+      return value
+    }
+  }
+  return value
+}

package/src/database/errors.ts

@@ -0,0 +1,93 @@
+import { Conflict, DriverFault, Invalid, Unavailable } from '@avelonjs/core'
+
+interface PostgrestErrorBody {
+  readonly code?: string
+  readonly message?: string
+  readonly details?: string | null
+  readonly hint?: string | null
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+/**
+ * Maps a PostgREST HTTP failure into the framework error taxonomy.
+ *
+ * Unique violations become `Conflict`. Missing tables, columns, and routines become `Invalid`.
+ */
+export function mapPostgrestError(
+  status: number,
+  bodyText: string,
+  operation: string,
+): never {
+  let parsed: PostgrestErrorBody | undefined
+  try {
+    const value = JSON.parse(bodyText) as unknown
+    if (isRecord(value)) parsed = value as PostgrestErrorBody
+  } catch {
+    parsed = undefined
+  }
+
+  const code = parsed?.code
+  const message =
+    parsed?.message ?? (bodyText || `PostgREST ${operation} failed (${status})`)
+
+  if (code === '23505' || /duplicate key value/i.test(message)) {
+    throw new Conflict(message, {
+      metadata: { resource: undefined, key: code },
+      cause: { status, bodyText },
+    })
+  }
+
+  if (
+    status === 404 ||
+    code === '42P01' ||
+    code === '42703' ||
+    code === 'PGRST205' ||
+    code === 'PGRST204' ||
+    /does not exist/i.test(message) ||
+    /could not find/i.test(message)
+  ) {
+    const field = /function|routine|rpc/i.test(message)
+      ? 'routine'
+      : /column/i.test(message)
+        ? 'select'
+        : 'table'
+    const routine = field === 'routine' ? (extractRoutine(message) ?? message) : message
+    throw new Invalid(message, {
+      metadata: { fields: { [field]: [routine] } },
+      cause: { status, bodyText },
+    })
+  }
+
+  if (status === 503 || status === 502) {
+    throw new Unavailable(message, {
+      metadata: { service: 'supabase-postgrest' },
+      cause: { status, bodyText },
+    })
+  }
+
+  throw new DriverFault(message, {
+    metadata: { driver: 'database', operation },
+    cause: { status, bodyText, code },
+  })
+}
+
+function extractRoutine(message: string): string | undefined {
+  const match =
+    /function ([a-zA-Z0-9_.]+)/i.exec(message) ?? /rpc[_/ ]([a-zA-Z0-9_]+)/i.exec(message)
+  const name = match?.[1]
+  if (name === undefined) return undefined
+  // Conformance asserts the bare routine name; PostgREST may qualify it with a schema.
+  return name.includes('.') ? (name.split('.').at(-1) as string) : name
+}
+
+/** Documented PostgREST/Postgres codes this driver maps. */
+export const SUPABASE_DATABASE_ERROR_MAP = [
+  { code: '23505', framework: 'Conflict', meaning: 'unique_violation' },
+  { code: '42P01', framework: 'Invalid', meaning: 'undefined_table' },
+  { code: '42703', framework: 'Invalid', meaning: 'undefined_column' },
+  { code: 'PGRST205', framework: 'Invalid', meaning: 'table_not_found_in_schema_cache' },
+  { code: 'PGRST204', framework: 'Invalid', meaning: 'column_not_found_in_schema_cache' },
+] as const