@fabrika/db 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/db",
-	"version": "0.6.0",
+	"version": "0.7.0",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -61,8 +61,8 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@fabrika/auth-core": "0.6.0",
-		"@fabrika/platform-node": "0.6.0",
+		"@fabrika/auth-core": "0.7.0",
+		"@fabrika/platform-node": "0.7.0",
 		"kysely": "0.29.6",
 		"kysely-postgres-js": "5.0.1",
 		"zod": "^3.25.76"

package/src/{form-admissions.ts → admissions.ts}

@@ -1,38 +1,34 @@
-// The framework's side of `fabrika_form_admissions` and `fabrika_form_challenges` (`@fabrika/db/migrations`): the
-// per-minute counters a form's admission takes from, shared by every instance of the application, and the digests of
-// the challenge tokens a form accepted. Only `@fabrika/app`'s form dispatcher reaches them, through
-// `frameworkTablesOf`. Each operation is one statement, so two instances never read a counter and then write it, and
-// each prunes a bounded batch of expired rows of its own table, so neither table grows past what the last minutes hold.
-
-import { runFixedStatement, type Session, sessionOf } from './database'
+// The framework's side of `fabrika_form_admissions`, `fabrika_form_challenges` and `fabrika_form_bytes`
+// (`@fabrika/db/migrations`): the per-minute buckets a procedure's admission takes from, shared by every instance of the
+// application, the digests of the challenge tokens it accepted, and its hourly byte budget (`bytesPerHour`). Each is
+// keyed by the endpoint id; the tables keep the names and the `form` column they were created with. Only `@fabrika/app`'s
+// dispatcher reaches them, through `frameworkTablesOf`. Each operation is one statement, so two instances never read a
+// counter and then write it, and each prunes a bounded batch of expired rows of its own table, so no table grows past
+// what the last minutes or hours hold.
+
+import { runFixedStatement, sessionOf } from './database'
 import { QueryRefusedError } from './errors'
 import { FORM_ADMISSIONS_TABLE, FORM_BYTES_TABLE, FORM_CHALLENGES_TABLE } from './migrations'
 import type { DataLayerRuntime } from './store'
 
-/** The bucket of `fabrika_form_admissions` an inbox append takes from, in the append's own transaction. */
-export interface InboxQuota {
-	readonly bucket: string
-	readonly limit: number
-}
-
-export interface FormAdmissions {
+export interface Admissions {
 	/**
-	 * Takes one from `bucket` of `form` in the database's current minute; `false` when `limit` were already taken
+	 * Takes one from `bucket` of `endpoint` in the database's current minute; `false` when `limit` were already taken
 	 * there. The counter and the check are one statement.
 	 */
-	take(form: string, bucket: string, limit: number): Promise<boolean>
+	take(endpoint: string, bucket: string, limit: number): Promise<boolean>
 	/**
-	 * Records the digest of a challenge token `form` accepted, kept for `retainMs`; `false` when it was already
+	 * Records the digest of a challenge token `endpoint` accepted, kept for `retainMs`; `false` when it was already
 	 * recorded and has not expired, which makes the token's second use a replay.
 	 */
-	recordChallenge(form: string, tokenDigest: string, retainMs: number): Promise<boolean>
+	recordChallenge(endpoint: string, tokenDigest: string, retainMs: number): Promise<boolean>
 	/**
-	 * Reserves `bytes` of `form`'s hourly byte budget `limit`, in the database's current hour; `false`, with nothing
+	 * Reserves `bytes` of `endpoint`'s hourly byte budget `limit`, in the database's current hour; `false`, with nothing
 	 * taken, when they no longer fit. The check and the counter are one statement.
 	 */
-	reserveBytes(form: string, bytes: number, limit: number): Promise<boolean>
-	/** Gives back `bytes` of a reservation of the current hour that a written file did not need. */
-	releaseBytes(form: string, bytes: number): Promise<void>
+	reserveBytes(endpoint: string, bytes: number, limit: number): Promise<boolean>
+	/** Gives back `bytes` of a reservation of the current hour that the request did not need. */
+	releaseBytes(endpoint: string, bytes: number): Promise<void>
 }
 
 const A = FORM_ADMISSIONS_TABLE
@@ -85,34 +81,31 @@ function positiveInteger(value: number, what: string): number {
 	return value
 }
 
-/** One take of `bucket` in `session`, which may be a transaction: rolled back with it, the take is given back. */
-export async function takeFromBucket(session: Session, form: string, bucket: string, limit: number): Promise<boolean> {
-	const rows = await runFixedStatement(session, SQL_TAKE, [form, bucket, positiveInteger(limit, 'a form limit')])
-	return rows.length > 0
-}
-
-export function formAdmissions(runtime: () => DataLayerRuntime): FormAdmissions {
+export function admissions(runtime: () => DataLayerRuntime): Admissions {
 	const session = () => sessionOf(runtime())
 	return Object.freeze({
-		take: (form: string, bucket: string, limit: number): Promise<boolean> => takeFromBucket(session(), form, bucket, limit),
+		async take(endpoint: string, bucket: string, limit: number): Promise<boolean> {
+			const rows = await runFixedStatement(session(), SQL_TAKE, [endpoint, bucket, positiveInteger(limit, 'a bucket limit')])
+			return rows.length > 0
+		},
 
-		async recordChallenge(form: string, tokenDigest: string, retainMs: number): Promise<boolean> {
-			const rows = await runFixedStatement(session(), SQL_RECORD_CHALLENGE, [form, tokenDigest, positiveInteger(retainMs, 'a retention')])
+		async recordChallenge(endpoint: string, tokenDigest: string, retainMs: number): Promise<boolean> {
+			const rows = await runFixedStatement(session(), SQL_RECORD_CHALLENGE, [endpoint, tokenDigest, positiveInteger(retainMs, 'a retention')])
 			return rows.length > 0
 		},
 
-		async reserveBytes(form: string, bytes: number, limit: number): Promise<boolean> {
+		async reserveBytes(endpoint: string, bytes: number, limit: number): Promise<boolean> {
 			const rows = await runFixedStatement(session(), SQL_RESERVE_BYTES, [
-				form,
+				endpoint,
 				positiveInteger(bytes, 'a reservation'),
 				positiveInteger(limit, 'a byte budget'),
 			])
 			return rows.length > 0
 		},
 
-		async releaseBytes(form: string, bytes: number): Promise<void> {
+		async releaseBytes(endpoint: string, bytes: number): Promise<void> {
 			if (bytes > 0) {
-				await runFixedStatement(session(), SQL_RELEASE_BYTES, [form, positiveInteger(bytes, 'a release')])
+				await runFixedStatement(session(), SQL_RELEASE_BYTES, [endpoint, positiveInteger(bytes, 'a release')])
 			}
 		},
 	})

package/src/capability.ts

@@ -20,6 +20,14 @@ export interface AppCapability<Action extends string> {
 	readonly '~capability': { readonly kind: 'app'; readonly action: Action }
 }
 
+/**
+ * One claimed row of one queue table, for one action: what a claim answers as `row.ref`, and what `tx.db.on(row.ref)`
+ * finishes the row through. Like a `Ref`, the member is type-only.
+ */
+export interface RowRef<Table extends string, Action extends string> {
+	readonly '~capability': { readonly kind: 'row'; readonly table: Table; readonly action: Action }
+}
+
 export interface RefGrant {
 	readonly kind: 'ref'
 	readonly dimension: string
@@ -63,11 +71,28 @@ export interface AppGrant {
 	readonly principal: string
 }
 
-export type CapabilityGrant = RefGrant | WithinGrant | AppGrant
+/** A row a claim leased: the table, its key, and the containment it had then, column by column. */
+export interface RowGrant {
+	readonly kind: 'row'
+	readonly table: string
+	readonly action: string
+	readonly principal: string
+	readonly id: string
+	/** The row's containment columns and their values when it was claimed: a row moved since is out of reach. */
+	readonly chain: ReadonlyMap<string, string>
+}
+
+export type CapabilityGrant = RefGrant | WithinGrant | AppGrant | RowGrant
 
-/** How a refusal names a capability: `a Ref of note`, `a Within of workspace`, `an app capability`. */
+/** How a refusal names a capability: `a Ref of note`, `a Within of workspace`, `an app capability`, `a row of outbox`. */
 export function describeGrant(grant: CapabilityGrant): string {
-	return grant.kind === 'app' ? 'an app capability' : `a ${grant.kind === 'ref' ? 'Ref' : 'Within'} of ${grant.dimension}`
+	if (grant.kind === 'app') {
+		return 'an app capability'
+	}
+	if (grant.kind === 'row') {
+		return `a row of ${grant.table}`
+	}
+	return `a ${grant.kind === 'ref' ? 'Ref' : 'Within'} of ${grant.dimension}`
 }
 
 /** One generation of a job's lease, held by one attempt. A write of the attempt commits only while it still holds it. */
@@ -85,6 +110,8 @@ export interface LeaseFence {
  */
 export interface CapabilityAuthority {
 	resolve(capability: unknown): CapabilityGrant
+	/** Mints the capability of one claimed row, bound to the work running now as every capability is. */
+	row(grant: Omit<RowGrant, 'kind'>): unknown
 	/**
 	 * The lease the work running now must still hold for a write to commit: the job attempt's, or `null` in a
 	 * request. Every mutation checks it inside its own transaction.

package/src/description.ts

@@ -63,7 +63,8 @@ export interface TableShape {
 
 export interface JoinShape {
 	readonly shape: TableShape
-	readonly readAction: string
+	/** The child's read actions: a select of the parent joins it only with one of them. */
+	readonly readActions: readonly string[]
 	/** The composite foreign key: child column = parent column, for each pair. */
 	readonly on: readonly { readonly childColumn: string; readonly parentColumn: string }[]
 }

package/src/errors.ts

@@ -34,7 +34,7 @@ export class CapabilityError extends Error {
 export const QUERY_REFUSALS = {
 	invalid_argument: 'a data-layer call took an argument of another shape than its type declares',
 	invalid_value: 'a value cannot be bound: an invalid or out-of-range date, or a non-finite number',
-	invalid_name: 'a configured name (application, schema, file collection or owner column) breaks its naming rule',
+	invalid_name: 'a configured name (application, schema, table or file column) breaks its naming rule',
 	unknown_column: 'a column the table does not declare, or one this operation may not set',
 	unknown_table: 'a table src/db/tables.ts does not declare, or one no store, join or locator reaches',
 	framework_table: "a framework table or a catalog name: application data reaches only the application's own tables",
@@ -55,7 +55,13 @@ export const QUERY_REFUSALS = {
 	sql_function: 'ctx.sql calls a function that is not a reviewed built-in',
 	sql_outside_transaction: 'a job runs ctx.sql only inside ctx.transaction((tx) => …), as tx.sql',
 	sql_scope: 'ctx.sql.scope(…) stands alone, joined by AND, in a WHERE or JOIN … ON clause of its own invocation',
-	file_scan: "a scan operation on a file collection without scan: true, or a scan verdict outside the scan job's lease",
+	file_scan: "a scan verdict outside the scan job's lease",
+	claim_site: 'claim leases rows in a transaction of its own: a job calls it on ctx.db, never inside ctx.transaction or a request',
+	on_conflict: "an insert's onConflict names no column of the table, a column the insert leaves empty, or another action",
+	public_reach: "a public procedure updates, removes, locks or claims no row, and an insert's conflict writes nothing",
+	file_value:
+		"a file column takes a file reference this request holds and may read (an incoming file, a put, or a read under the table's read action) of the column's kind, or null",
+	file_scope: 'a file is referenced from another top-level scope than the one its first reference set',
 } as const
 
 export type QueryRefusal = keyof typeof QUERY_REFUSALS

package/src/file-columns.ts

@@ -0,0 +1,184 @@
+// A table's file columns in the data layer. A read answers a file reference in each one, with the file's metadata
+// loaded in one statement per read; a write takes only a reference its site holds and may read, of the column's kind,
+// and claims, locks and stamps the file in the write's own transaction. The file's row is `fabrika_files`
+// (`stored-files.ts`); the column is a foreign key to it, so a file some row references is never deleted.
+
+import { defineValue, ownDescriptor, ownKeys } from './builtins'
+import { runFixedStatement, type Session } from './database'
+import type { Primitive } from './description'
+import { NotFoundError, QueryRefusedError } from './errors'
+import { fileHoldingOf, fileReference, holdsFile } from './file-references'
+import { isPlainIdentifier } from './identifier'
+import type { TableModel } from './policy'
+import { claimStoredFile, lockStoredFile, stampStoredFile, storedFilesMetadata } from './stored-files'
+
+/** Where a site's file references belong, and what claiming a pending one needs. */
+export interface FileBinding {
+	/** The work a reference of this site belongs to: one request, or one job attempt. */
+	readonly holder: object
+	/** The id a pending file must carry to be claimed here: the request (or attempt) that staged it. */
+	readonly request: string
+	/** How long a pending file may wait for its first reference. */
+	readonly graceMs: number
+	/** Whether files of `kind` wait for a clean scan: a claimed one is `quarantined` until then. */
+	scans(kind: string): boolean
+}
+
+/** Whether a reference read with `action` lets its holder serve, open and copy the file: the table's or the column's read action. */
+function readsFile(model: TableModel, column: string, action: string): boolean {
+	const own = Object.hasOwn(model.columnReads, column) ? model.columnReads[column] : undefined
+	return own === undefined ? model.actions.read.includes(action) : own === action
+}
+
+/**
+ * Puts a file reference in each file column of `rows`, read with `action` in `session`: one statement loads every
+ * file's metadata. Without a binding (a store's own runner) the columns keep their ids.
+ */
+export async function answerFiles<R>(model: TableModel, binding: FileBinding | undefined, session: Session, rows: R[], action: string): Promise<R[]> {
+	const columns = ownKeys(model.files)
+	if (binding === undefined || columns.length === 0 || rows.length === 0) {
+		return rows
+	}
+	const ids: string[] = []
+	for (const row of rows) {
+		for (const column of columns) {
+			const value: unknown = typeof row === 'object' && row !== null ? ownDescriptor(row, column)?.value : undefined
+			if (typeof value === 'string') {
+				ids.push(value)
+			}
+		}
+	}
+	const metadata = await storedFilesMetadata(session, ids)
+	for (const row of rows) {
+		if (typeof row !== 'object' || row === null) {
+			continue
+		}
+		for (const column of columns) {
+			const value: unknown = ownDescriptor(row, column)?.value
+			if (typeof value !== 'string') {
+				continue
+			}
+			const meta = metadata.get(value)
+			if (meta === undefined) {
+				throw new QueryRefusedError('unexpected_row', `${model.name}.${column} references a file that is not stored`)
+			}
+			defineValue(row, column, fileReference(meta, binding.holder, readsFile(model, column, action)))
+		}
+	}
+	return rows
+}
+
+/**
+ * A write's value for a file column: `null`, or the id of a file reference of the column's kind. A string id, a copied
+ * object or a reference of another kind is refused; whether the site holds it is checked where the write runs.
+ */
+export function fileValue(model: TableModel, column: string, value: unknown): string | null {
+	if (value === null) {
+		return null
+	}
+	const kind = model.files[column]
+	const holding = fileHoldingOf(value)
+	if (holding === undefined) {
+		throw new QueryRefusedError(
+			'file_value',
+			`${model.name}.${column} takes a file reference (an input file, a ctx.files.put, or a file column read here) or null, never an id`,
+		)
+	}
+	if (holding.kind !== kind) {
+		throw new QueryRefusedError('file_value', `${model.name}.${column} holds files of kind '${kind}', and the reference is of another kind`)
+	}
+	return holding.id
+}
+
+/**
+ * The top-level scope a row of `model` lies in, from the values it is written with: `<dimension>:<value>`, or `null` for
+ * an application table, which sets no scope.
+ */
+export function rowScope(model: TableModel, values: ReadonlyMap<string, Primitive | null>): string | null | undefined {
+	const scope = model.scope
+	if (scope.mode !== 'dimension' && scope.mode !== 'child') {
+		return null
+	}
+	const top = model.chain[model.chain.length - 1]
+	const [dimension, column] = top === undefined
+		? scope.mode === 'dimension' ? [scope.dimension, scope.key] : [undefined, undefined]
+		: [top.dimension, top.column]
+	if (dimension === undefined || column === undefined) {
+		return null
+	}
+	const value = values.get(column)
+	return value === undefined || value === null ? undefined : `${dimension}:${String(value)}`
+}
+
+/** The top-level scope of the row whose key is `key`, read in `session`: what an update's file references are stamped with. */
+export async function storedRowScope(model: TableModel, session: Session, key: string, keyValue: string): Promise<string | null> {
+	const scope = model.scope
+	if (scope.mode !== 'dimension' && scope.mode !== 'child') {
+		return null
+	}
+	const top = model.chain[model.chain.length - 1]
+	const dimension = top === undefined ? (scope.mode === 'dimension' ? scope.dimension : undefined) : top.dimension
+	const column = top === undefined ? (scope.mode === 'dimension' ? scope.key : undefined) : top.column
+	if (dimension === undefined || column === undefined) {
+		return null
+	}
+	if (!isPlainIdentifier(model.name) || !isPlainIdentifier(column) || !isPlainIdentifier(key)) {
+		throw new QueryRefusedError('invalid_name', "a file column's table is named by plain identifiers")
+	}
+	const [found] = await runFixedStatement(session, `select ${column}::text as scope from ${model.name} where ${key}::text = $1`, [keyValue])
+	const value: unknown = typeof found === 'object' && found !== null ? ownDescriptor(found, 'scope')?.value : undefined
+	if (typeof value !== 'string') {
+		throw new NotFoundError(`${model.name} not found`)
+	}
+	return `${dimension}:${value}`
+}
+
+/**
+ * The file references of a write, in `session` (its transaction), after its statement: each file is locked `for share`
+ * while its state is checked, a pending one this request staged within the grace is claimed, and the first reference
+ * from a dimensional table stamps its scope; a reference from another top-level scope is refused.
+ */
+export async function referenceFiles(
+	model: TableModel,
+	binding: FileBinding | undefined,
+	session: Session,
+	values: ReadonlyMap<string, Primitive | null>,
+	scope: () => Promise<string | null>,
+): Promise<void> {
+	const written = ownKeys(model.files).flatMap((column) => {
+		const id = values.get(column)
+		return typeof id === 'string' ? [{ column, id }] : []
+	})
+	if (written.length === 0) {
+		return
+	}
+	if (binding === undefined) {
+		throw new QueryRefusedError('file_value', `${model.name}: a file column is written only by a handler, through ctx.db`)
+	}
+	const stamp = await scope()
+	for (const { column, id } of written) {
+		const kind = model.files[column] ?? ''
+		if (!holdsFile(binding.holder, id)) {
+			throw new QueryRefusedError('file_value', `${model.name}.${column}: this site holds no reference to that file it may read`)
+		}
+		const locked = await lockStoredFile(session, id, binding.graceMs)
+		if (locked === null) {
+			throw new NotFoundError('the file is no longer stored')
+		}
+		if (locked.kind !== kind) {
+			throw new QueryRefusedError('file_value', `${model.name}.${column} holds files of kind '${kind}', and the file is of another kind`)
+		}
+		if (locked.status === 'pending') {
+			if (locked.request !== binding.request || !locked.fresh) {
+				throw new QueryRefusedError(
+					'file_value',
+					`${model.name}.${column}: a pending file is claimed only by the request that wrote it, within the grace`,
+				)
+			}
+			await claimStoredFile(session, id, binding.scans(kind) ? 'quarantined' : 'live')
+		}
+		if (stamp !== null && !(await stampStoredFile(session, id, stamp))) {
+			throw new QueryRefusedError('file_scope', `${model.name}.${column}: the file belongs to another top-level scope than this row`)
+		}
+	}
+}

package/src/file-references.ts

@@ -0,0 +1,60 @@
+// File references: the request-bound values a file column holds. The data layer answers one for each file column of a
+// row it reads, and `@fabrika/app` mints one for a file a request received or put; a file column takes nothing else. A
+// reference is a frozen object of the file's metadata, registered here with the work it belongs to: a reference of
+// another request, or one read under an action that does not read the file, is refused where it is written or served.
+
+import { freeze } from './builtins'
+import type { StoredFileMeta, StoredFileStatus } from './stored-files'
+
+/** What a handler sees of a stored file: its metadata, never its object. */
+export interface FileReference {
+	readonly id: string
+	readonly name: string | null
+	readonly type: string
+	readonly size: number
+	readonly status: StoredFileStatus
+}
+
+/** Whose a reference is, and what it lets that work do. */
+export interface FileHolding {
+	readonly id: string
+	readonly kind: string
+	/** The work that holds it: one request, or one job attempt. */
+	readonly holder: object
+	/** Read under an action that reads the file (or received, or put): it may be written into a column, served and opened. */
+	readonly readable: boolean
+}
+
+// Captured when the module loads, before application code: a later patch to WeakMap does not change the registry.
+const holdings = new WeakMap<object, FileHolding>()
+const readableIds = new WeakMap<object, Set<string>>()
+const apply = Reflect.apply
+const getHolding: (this: WeakMap<object, FileHolding>, key: object) => FileHolding | undefined = WeakMap.prototype.get
+const setHolding: (this: WeakMap<object, FileHolding>, key: object, value: FileHolding) => WeakMap<object, FileHolding> = WeakMap.prototype.set
+const getReadable: (this: WeakMap<object, Set<string>>, key: object) => Set<string> | undefined = WeakMap.prototype.get
+const setReadable: (this: WeakMap<object, Set<string>>, key: object, value: Set<string>) => WeakMap<object, Set<string>> = WeakMap.prototype.set
+
+/**
+ * A reference to a file for `holder`; only `@fabrika/db` and the framework mint one. A `readable` one also lets its
+ * holder write the file into a column, serve it and open it, through any reference to the same file.
+ */
+export function fileReference(meta: StoredFileMeta, holder: object, readable: boolean): FileReference {
+	const reference: FileReference = freeze({ id: meta.id, name: meta.name, type: meta.type, size: meta.size, status: meta.status })
+	apply(setHolding, holdings, [reference, freeze({ id: meta.id, kind: meta.kind, holder, readable })])
+	if (readable) {
+		const ids = apply(getReadable, readableIds, [holder]) ?? new Set<string>()
+		ids.add(meta.id)
+		apply(setReadable, readableIds, [holder, ids])
+	}
+	return reference
+}
+
+/** What a reference holds, or `undefined` for any other value: a structural copy, a string id or a forged object. */
+export function fileHoldingOf(value: unknown): FileHolding | undefined {
+	return typeof value === 'object' && value !== null ? apply(getHolding, holdings, [value]) : undefined
+}
+
+/** Whether `holder` received, put, or read under a read action the file `id`. */
+export function holdsFile(holder: object, id: string): boolean {
+	return apply(getReadable, readableIds, [holder])?.has(id) === true
+}