@meith/db 0.16.0

package/src/outbox-repo.ts

@@ -0,0 +1,78 @@
+import { inArray, sql } from 'drizzle-orm'
+
+import type { DomainEventName, OutboxReader, OutboxRecord } from '@meith/events'
+
+import type { Database } from './client'
+import { resultRows } from './result-rows'
+import { outbox } from './schema'
+
+const MAX_CLAIMS = 10
+
+export class PostgresOutboxReader implements OutboxReader {
+  constructor(private readonly db: Database) {}
+
+  async claimUnrelayed(limit: number): Promise<OutboxRecord[]> {
+    const result = await this.db.execute(sql`
+      update ${outbox}
+         set attempts = ${outbox.attempts} + 1
+       where id in (
+         select id from ${outbox}
+          where dispatched_at is null
+            and attempts < ${MAX_CLAIMS}
+          order by id
+          limit ${limit}
+          for update skip locked
+       )
+      returning id, topic, payload, created_at, dispatched_at
+    `)
+
+    return (
+      resultRows(result) as Array<{
+        id: number
+        topic: string
+        payload: unknown
+        created_at: Date | string
+        dispatched_at: Date | string | null
+      }>
+    ).map((row) => ({
+      id: Number(row.id),
+      name: row.topic as DomainEventName,
+      payload: row.payload,
+      dedupeKey: null,
+      createdAt: new Date(row.created_at),
+      relayedAt: row.dispatched_at === null ? null : new Date(row.dispatched_at),
+    }))
+  }
+
+  async markRelayed(ids: number[]): Promise<void> {
+    if (ids.length === 0) return
+    await this.db.update(outbox).set({ dispatchedAt: new Date() }).where(inArray(outbox.id, ids))
+  }
+
+  async stuck(limit = 50): Promise<OutboxRecord[]> {
+    const rows = await this.db.execute(sql`
+      select id, topic, payload, created_at, dispatched_at
+        from ${outbox}
+       where dispatched_at is null and attempts >= ${MAX_CLAIMS}
+       order by id
+       limit ${limit}
+    `)
+
+    return (
+      resultRows(rows) as Array<{
+        id: number
+        topic: string
+        payload: unknown
+        created_at: Date | string
+        dispatched_at: Date | string | null
+      }>
+    ).map((row) => ({
+      id: Number(row.id),
+      name: row.topic as DomainEventName,
+      payload: row.payload,
+      dedupeKey: null,
+      createdAt: new Date(row.created_at),
+      relayedAt: row.dispatched_at === null ? null : new Date(row.dispatched_at),
+    }))
+  }
+}

package/src/permission-version.ts

@@ -0,0 +1,24 @@
+import { sql } from 'drizzle-orm'
+
+import type { Database } from './client'
+
+export type Tx = Parameters<Parameters<Database['transaction']>[0]>[0]
+
+export async function bumpPermissionVersion(tx: Tx): Promise<void> {
+  await tx.execute(sql`
+    insert into cache_versions (key, version) values ('permissions', 1)
+    on conflict (key) do update
+       set version = cache_versions.version + 1, bumped_at = now()
+  `)
+}
+
+export async function withPermissionVersionBump<T>(
+  db: Database,
+  work: (tx: Tx) => Promise<T>,
+): Promise<T> {
+  return db.transaction(async (tx) => {
+    const result = await work(tx)
+    await bumpPermissionVersion(tx)
+    return result
+  })
+}

package/src/permissions-map.ts

@@ -0,0 +1,52 @@
+import {
+  emptyPermissionSet,
+  FORUM_PERMISSION_FIELDS,
+  type ForumPermissions,
+  PERMISSION_FIELDS,
+  type PermissionField,
+  type PermissionSet,
+} from '@meith/core'
+
+export type PermissionRow = Record<string, unknown>
+
+function coerceField(field: PermissionField, raw: unknown): boolean | number | undefined {
+  if (raw === null || raw === undefined) return undefined
+
+  if (field.kind === 'numeric') {
+    const n = typeof raw === 'number' ? raw : Number(raw)
+    if (!Number.isFinite(n)) {
+      throw new TypeError(
+        `Permission field "${field.key}" expected a number, got ${JSON.stringify(raw)}`,
+      )
+    }
+    return n
+  }
+
+  if (typeof raw === 'boolean') return raw
+  if (raw === 't' || raw === 1 || raw === '1') return true
+  if (raw === 'f' || raw === 0 || raw === '0') return false
+
+  throw new TypeError(
+    `Permission field "${field.key}" expected a boolean, got ${JSON.stringify(raw)}`,
+  )
+}
+
+export function groupRowToPermissionSet(row: PermissionRow): PermissionSet {
+  const out = emptyPermissionSet()
+  for (const field of PERMISSION_FIELDS) {
+    const value = coerceField(field, row[field.key])
+    if (value !== undefined) {
+      ;(out as Record<string, boolean | number>)[field.key] = value
+    }
+  }
+  return out
+}
+
+export function forumRowToOverride(row: PermissionRow): Partial<ForumPermissions> {
+  const out: Record<string, boolean | number> = {}
+  for (const field of FORUM_PERMISSION_FIELDS) {
+    const value = coerceField(field, row[field.key])
+    if (value !== undefined) out[field.key] = value
+  }
+  return out as Partial<ForumPermissions>
+}

package/src/pglite.fixture.ts

@@ -0,0 +1,87 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { PGlite } from '@electric-sql/pglite'
+import { drizzle } from 'drizzle-orm/pglite'
+
+import type { Database } from './client'
+import * as schema from './schema'
+
+export interface QueryLog {
+  readonly count: number
+  readonly statements: readonly string[]
+  reset(): void
+}
+
+export interface TestDb {
+  readonly db: Database
+  readonly queries: QueryLog
+  /**
+   * The engine underneath, for the few tests that need to send it something
+   * drizzle cannot: `exec()` takes a script of several statements, which is how
+   * the migration files arrive and what a prepared statement refuses.
+   */
+  readonly client: PGlite
+  close(): Promise<void>
+}
+
+/** The checked-in migrations, as one script `client.exec()` will accept. */
+export function migrationScript(): string {
+  return migrationSql().split('--> statement-breakpoint').join('\n')
+}
+
+function migrationSql(): string {
+  const here = path.dirname(fileURLToPath(import.meta.url))
+  const dir = path.resolve(here, '..', 'migrations')
+
+  const journal = JSON.parse(readFileSync(path.join(dir, 'meta', '_journal.json'), 'utf8')) as {
+    entries: { idx: number; tag: string }[]
+  }
+
+  return [...journal.entries]
+    .sort((a, b) => a.idx - b.idx)
+    .map((entry) => readFileSync(path.join(dir, `${entry.tag}.sql`), 'utf8'))
+    .join('\n')
+}
+
+export async function createTestDb(): Promise<TestDb> {
+  const client = new PGlite()
+
+  await client.exec(migrationScript())
+
+  const statements: string[] = []
+
+  const originalQuery = client.query.bind(client)
+  ;(client as unknown as { query: typeof originalQuery }).query = ((
+    sqlText: string,
+    ...rest: unknown[]
+  ) => {
+    statements.push(sqlText)
+    return (originalQuery as (...a: unknown[]) => unknown)(sqlText, ...rest)
+  }) as typeof originalQuery
+
+  const db = drizzle(client, {
+    schema,
+    casing: 'snake_case',
+  }) as unknown as Database
+
+  return {
+    db,
+    client,
+    queries: {
+      get count() {
+        return statements.length
+      },
+      get statements() {
+        return [...statements]
+      },
+      reset() {
+        statements.length = 0
+      },
+    },
+    async close() {
+      await client.close()
+    },
+  }
+}

package/src/plugin-data.ts

@@ -0,0 +1,88 @@
+import { type SQL, sql } from 'drizzle-orm'
+
+import { ValidationError } from '@meith/core'
+import type { PluginData } from '@meith/plugin-kit'
+
+import type { Database } from './client'
+import type { Tx } from './permission-version'
+import { resultRows } from './result-rows'
+
+export interface PluginDataOptions {
+  readonly statementTimeoutMs?: number
+}
+
+const DEFAULT_TIMEOUT_MS = 3_000
+
+export function bindPluginSql(
+  text: string,
+  params: readonly unknown[],
+  where = 'plugin query',
+): SQL {
+  const out = sql.empty()
+  let last = 0
+
+  for (const match of text.matchAll(/\$(\d+)/g)) {
+    const index = Number(match[1]) - 1
+    if (index < 0 || index >= params.length) {
+      throw new ValidationError(
+        `${where}: the statement names $${match[1]} but only ${params.length} parameter(s) were passed.`,
+      )
+    }
+    out.append(sql.raw(text.slice(last, match.index)))
+    out.append(sql`${params[index]}`)
+    last = match.index + match[0].length
+  }
+
+  out.append(sql.raw(text.slice(last)))
+  return out
+}
+
+function onExecutor(executor: Tx, where: string): PluginData {
+  const run = async (text: string, params: readonly unknown[] = []) => {
+    return resultRows<Record<string, unknown>>(
+      await executor.execute(bindPluginSql(text, params, where)),
+    )
+  }
+
+  const data: PluginData = {
+    async query(text, params) {
+      return (await run(text, params ?? [])) as never
+    },
+    async one(text, params) {
+      const rows = await run(text, params ?? [])
+      return (rows[0] ?? null) as never
+    },
+    async tx(work) {
+      return work(data)
+    },
+  }
+  return data
+}
+
+export function pluginData(
+  db: Database,
+  pluginKey: string,
+  options: PluginDataOptions = {},
+): PluginData {
+  const timeoutMs = Math.max(1, Math.trunc(options.statementTimeoutMs ?? DEFAULT_TIMEOUT_MS))
+  const where = `plugin "${pluginKey}"`
+
+  const inTransaction = async <T>(work: (data: PluginData) => Promise<T>): Promise<T> => {
+    return db.transaction(async (tx) => {
+      await tx.execute(sql.raw(`set local statement_timeout = ${timeoutMs}`))
+      return work(onExecutor(tx, where))
+    })
+  }
+
+  return {
+    async query(text, params) {
+      return inTransaction(async (data) => data.query(text, params))
+    },
+    async one(text, params) {
+      return inTransaction(async (data) => data.one(text, params))
+    },
+    async tx(work) {
+      return inTransaction(work)
+    },
+  }
+}

package/src/plugin-grants.ts

@@ -0,0 +1,369 @@
+import { and, eq, sql } from 'drizzle-orm'
+
+import { ValidationError } from '@meith/core'
+import type { PluginGrantRow, PluginGrants } from '@meith/plugin-kit'
+
+import type { Database } from './client'
+import { bumpPermissionVersion } from './permission-version'
+import { groupRowToPermissionSet } from './permissions-map'
+import { resultRows } from './result-rows'
+import { userGroupMemberships, usergroups, users } from './schema'
+import { permissionsCarryPower } from './staff-groups'
+
+export {
+  PLUGIN_UNGRANTABLE_PERMISSIONS,
+  permissionsCarryPower,
+  type UngrantablePermission,
+} from './staff-groups'
+
+const MAX_GRANT_MS = 2 * 366 * 24 * 60 * 60 * 1000
+
+export const DISPLACED_PRIMARY_REASON =
+  'the group this member is primary in whenever no plugin grant stands in front of it'
+
+interface GrantableGroup {
+  readonly id: number
+  readonly key: string
+}
+
+type Tx = Parameters<Parameters<Database['transaction']>[0]>[0]
+
+export async function isStaffGroup(tx: Tx, groupId: number): Promise<boolean> {
+  const rows = resultRows(
+    await tx.execute(sql`select * from usergroups where id = ${groupId}`),
+  ) as Array<Record<string, unknown>>
+
+  const row = rows[0]
+  if (row === undefined) return false
+
+  return (
+    row.is_staff_group === true || permissionsCarryPower(groupRowToPermissionSet(camelise(row)))
+  )
+}
+
+async function promotePrimary(tx: Tx, userId: number, groupId: number): Promise<void> {
+  const userRows = resultRows(
+    await tx.execute(sql`select primary_group_id from users where id = ${userId} for update`),
+  ) as Array<{ primary_group_id: number }>
+
+  const current = userRows[0]
+  if (current === undefined) return
+
+  const held = Number(current.primary_group_id)
+  if (held === groupId) return
+  if (await isStaffGroup(tx, held)) return
+
+  const displacedRows = resultRows(
+    await tx.execute(sql`
+      select previous_primary_group_id
+        from user_group_memberships
+       where user_id = ${userId} and group_id = ${held}
+    `),
+  ) as Array<{ previous_primary_group_id: number | null }>
+
+  const rooted = displacedRows[0]?.previous_primary_group_id
+  const displaced = rooted === null || rooted === undefined ? held : Number(rooted)
+
+  await tx.execute(sql`
+    insert into user_group_memberships (user_id, group_id, grant_reason)
+    values (${userId}, ${displaced}, ${DISPLACED_PRIMARY_REASON})
+    on conflict (user_id, group_id) do nothing
+  `)
+
+  await tx.execute(sql`
+    update user_group_memberships
+       set previous_primary_group_id = ${displaced}
+     where user_id = ${userId} and group_id = ${groupId}
+  `)
+
+  await tx.execute(sql`
+    update users set primary_group_id = ${groupId}, updated_at = now() where id = ${userId}
+  `)
+}
+
+async function restorePrimary(
+  tx: Tx,
+  userId: number,
+  groupId: number,
+  displaced: number,
+): Promise<void> {
+  const changed = resultRows(
+    await tx.execute(sql`
+      update users
+         set primary_group_id = ${displaced},
+             display_group_id = case when display_group_id = ${groupId} then null else display_group_id end,
+             updated_at = now()
+       where id = ${userId} and primary_group_id = ${groupId}
+      returning id
+    `),
+  )
+
+  if (changed.length === 0) return
+
+  await tx.execute(sql`
+    delete from user_group_memberships
+     where user_id = ${userId}
+       and group_id = ${displaced}
+       and granted_by_plugin is null
+       and expires_at is null
+       and grant_reason = ${DISPLACED_PRIMARY_REASON}
+  `)
+}
+
+function camelise(row: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(row)) {
+    out[key.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase())] = value
+  }
+  return out
+}
+
+async function grantableGroup(
+  db: Database,
+  pluginKey: string,
+  groupKey: string,
+): Promise<GrantableGroup> {
+  const rows = resultRows(
+    await db.execute(sql`select * from usergroups where key = ${groupKey} limit 1`),
+  ) as Array<Record<string, unknown>>
+
+  const row = rows[0]
+  const where = `plugin "${pluginKey}"`
+
+  if (row === undefined) {
+    throw new ValidationError(`${where}: no group is keyed "${groupKey}".`)
+  }
+  if (row.is_system === true) {
+    throw new ValidationError(
+      `${where}: "${groupKey}" is a system group. The board resolves it by key; membership is not a plugin's to hand out.`,
+    )
+  }
+  if (row.is_staff_group === true) {
+    throw new ValidationError(
+      `${where}: "${groupKey}" is a staff group, and staff is appointed, not granted by code.`,
+    )
+  }
+  if (permissionsCarryPower(groupRowToPermissionSet(camelise(row)))) {
+    throw new ValidationError(
+      `${where}: "${groupKey}" carries administrative or moderation power, so no plugin may grant it.`,
+    )
+  }
+  if (row.plugin_grantable !== true) {
+    throw new ValidationError(
+      `${where}: "${groupKey}" is not marked as grantable by plugins. An administrator opts a group in under Admin → Groups.`,
+    )
+  }
+
+  return { id: Number(row.id), key: String(row.key) }
+}
+
+function checkedUntil(pluginKey: string, until: Date, now: Date): Date {
+  if (!(until instanceof Date) || Number.isNaN(until.getTime())) {
+    throw new ValidationError(`plugin "${pluginKey}": the grant needs a valid expiry date.`)
+  }
+  if (until.getTime() <= now.getTime()) {
+    throw new ValidationError(
+      `plugin "${pluginKey}": a grant expiring in the past is a grant that never was. Got ${until.toISOString()}.`,
+    )
+  }
+  if (until.getTime() - now.getTime() > MAX_GRANT_MS) {
+    throw new ValidationError(
+      `plugin "${pluginKey}": grants are capped at two years. A longer arrangement is an operator decision, made in the panel.`,
+    )
+  }
+  return until
+}
+
+export function pluginGrants(
+  db: Database,
+  pluginKey: string,
+  clock: () => Date = () => new Date(),
+): PluginGrants {
+  return {
+    async grant({ userId, groupKey, until, reason, primary }) {
+      const now = clock()
+      const expiry = checkedUntil(pluginKey, until, now)
+      if (reason.trim() === '') {
+        throw new ValidationError(
+          `plugin "${pluginKey}": a grant needs a reason — it is the row's audit trail.`,
+        )
+      }
+
+      const group = await grantableGroup(db, pluginKey, groupKey)
+
+      const userRows = await db
+        .select({ id: users.id })
+        .from(users)
+        .where(eq(users.id, userId))
+        .limit(1)
+      if (userRows.length === 0) {
+        throw new ValidationError(`plugin "${pluginKey}": no user ${userId}.`)
+      }
+
+      await db.transaction(async (tx) => {
+        const existing = await tx
+          .select({
+            grantedByPlugin: userGroupMemberships.grantedByPlugin,
+            expiresAt: userGroupMemberships.expiresAt,
+          })
+          .from(userGroupMemberships)
+          .where(
+            and(
+              eq(userGroupMemberships.userId, userId),
+              eq(userGroupMemberships.groupId, group.id),
+            ),
+          )
+          .limit(1)
+
+        const current = existing[0]
+        if (current === undefined) {
+          await tx.insert(userGroupMemberships).values({
+            userId,
+            groupId: group.id,
+            expiresAt: expiry,
+            grantedByPlugin: pluginKey,
+            grantReason: reason,
+          })
+          if (primary === true) await promotePrimary(tx, userId, group.id)
+          await bumpPermissionVersion(tx)
+          return
+        }
+
+        if (current.grantedByPlugin !== pluginKey) {
+          throw new ValidationError(
+            `plugin "${pluginKey}": user ${userId} is already a member of "${groupKey}" by someone else's hand. That membership is not this plugin's to change.`,
+          )
+        }
+
+        let touched = false
+        if (current.expiresAt === null || current.expiresAt.getTime() < expiry.getTime()) {
+          await tx
+            .update(userGroupMemberships)
+            .set({ expiresAt: expiry, grantReason: reason })
+            .where(
+              and(
+                eq(userGroupMemberships.userId, userId),
+                eq(userGroupMemberships.groupId, group.id),
+              ),
+            )
+          touched = true
+        }
+
+        if (primary === true) {
+          await promotePrimary(tx, userId, group.id)
+          touched = true
+        }
+
+        if (touched) await bumpPermissionVersion(tx)
+      })
+    },
+
+    async extend({ userId, groupKey, until }) {
+      const now = clock()
+      const expiry = checkedUntil(pluginKey, until, now)
+      const group = await grantableGroup(db, pluginKey, groupKey)
+
+      await db.transaction(async (tx) => {
+        const result = await tx.execute(sql`
+          update user_group_memberships
+             set expires_at = ${expiry}
+           where user_id = ${userId}
+             and group_id = ${group.id}
+             and granted_by_plugin = ${pluginKey}
+             and expires_at < ${expiry}
+          returning user_id
+        `)
+        void resultRows(result)
+      })
+    },
+
+    async revoke({ userId, groupKey, reason }) {
+      if (reason.trim() === '') {
+        throw new ValidationError(
+          `plugin "${pluginKey}": a revocation needs a reason, for the same audit trail as the grant.`,
+        )
+      }
+
+      const groupRows = await db
+        .select({ id: usergroups.id })
+        .from(usergroups)
+        .where(eq(usergroups.key, groupKey))
+        .limit(1)
+      const group = groupRows[0]
+      if (group === undefined) return
+
+      await db.transaction(async (tx) => {
+        const result = await tx.execute(sql`
+          delete from user_group_memberships
+           where user_id = ${userId}
+             and group_id = ${group.id}
+             and granted_by_plugin = ${pluginKey}
+          returning previous_primary_group_id
+        `)
+        const gone = resultRows(result) as Array<{ previous_primary_group_id: number | null }>
+        if (gone.length === 0) return
+
+        const displaced = gone[0]?.previous_primary_group_id
+        if (displaced !== null && displaced !== undefined) {
+          await restorePrimary(tx, userId, group.id, Number(displaced))
+        }
+        await bumpPermissionVersion(tx)
+      })
+    },
+
+    async list(userId) {
+      const rows = await db
+        .select({
+          groupKey: usergroups.key,
+          expiresAt: userGroupMemberships.expiresAt,
+        })
+        .from(userGroupMemberships)
+        .innerJoin(usergroups, eq(usergroups.id, userGroupMemberships.groupId))
+        .where(
+          and(
+            eq(userGroupMemberships.userId, userId),
+            eq(userGroupMemberships.grantedByPlugin, pluginKey),
+          ),
+        )
+
+      return rows
+        .filter((row): row is { groupKey: string; expiresAt: Date } => row.expiresAt !== null)
+        .map((row): PluginGrantRow => ({ groupKey: row.groupKey, expiresAt: row.expiresAt }))
+    },
+  }
+}
+
+export async function expireTimedGroupMemberships(db: Database, limit: number): Promise<number> {
+  return db.transaction(async (tx) => {
+    const result = await tx.execute(sql`
+      delete from user_group_memberships
+       where (user_id, group_id) in (
+         select user_id, group_id
+           from user_group_memberships
+          where expires_at is not null
+            and expires_at <= now()
+          limit ${limit}
+       )
+      returning user_id, group_id, previous_primary_group_id
+    `)
+
+    const gone = resultRows(result) as Array<{
+      user_id: number
+      group_id: number
+      previous_primary_group_id: number | null
+    }>
+
+    for (const row of gone) {
+      if (row.previous_primary_group_id === null) continue
+      await restorePrimary(
+        tx,
+        Number(row.user_id),
+        Number(row.group_id),
+        Number(row.previous_primary_group_id),
+      )
+    }
+
+    if (gone.length > 0) await bumpPermissionVersion(tx)
+    return gone.length
+  })
+}