@fabrika/app 0.8.2 → 0.9.0-cloudflare.2

package/src/cloudflare/ops.ts

@@ -0,0 +1,246 @@
+// The object's side of Control's ops channel (ADR-0069 §1, §2): it authenticates the caller before it reads anything
+// the request names, answers every refusal with `opsRefusal()`, and serves the view from its storage alone, so it
+// works while the application cannot boot. Framework code only: an ops request never reaches the contract.
+
+import {
+	type ApplicationObjects,
+	ENDPOINT_HEADER,
+	FABRIKA_APPLICATION_OBJECT,
+	FABRIKA_APPLICATION_OBJECTS,
+	FABRIKA_OPS_KEY_DIGESTS,
+	formatEndpointHeader,
+	OPS_METHOD,
+	OPS_ROW_COUNT_CAP,
+	type OpsBootFailureContent,
+	type OpsContentView,
+	opsKeyDigest,
+	type OpsOperation,
+	opsRefusal,
+	type OpsView,
+	parseApplicationObjects,
+	parseOpsContentView,
+	parseOpsInspectRequest,
+	parseOpsKeyDigests,
+	parseOpsMigrateRequest,
+	parseOpsOperation,
+	parseOpsStateRequest,
+	parseOpsView,
+} from '@fabrika/auth-core'
+import { FILES_TABLE, JOB_LEASES_TABLE, WEBHOOK_BINDINGS_TABLE, WEBHOOK_DELIVERIES_TABLE } from '@fabrika/db/migrations'
+import type { SqliteCursor, SqliteValue } from '@fabrika/db/sqlite'
+import { opsProxyRow } from '@fabrika/proxy-core/manifest'
+import { timingSafeEqual } from 'node:crypto'
+import appPackage from '../../package.json' with { type: 'json' }
+import { jsonResponse } from '../errors.js'
+
+/** What the view reads of the object's storage; workerd's `DurableObjectStorage` has both optional members. */
+export interface OpsStorage {
+	readonly sql: {
+		exec(query: string, ...bindings: SqliteValue[]): SqliteCursor
+		/** The bun:sqlite test double has no size. */
+		readonly databaseSize?: number
+	}
+	/** The bun:sqlite test double has no alarm. */
+	getAlarm?(): Promise<number | null>
+}
+
+const OPS_ROW = opsProxyRow()
+
+/** `X-Fabrika-Endpoint` of the composed ops row, the only value an ops request may carry (ADR-0022 rule 3). */
+export const OPS_ENDPOINT = formatEndpointHeader(OPS_ROW.id, OPS_ROW.digest)
+
+/** A view with no data but one table, through which `admittedTableName` asks the wire's own parser about a name. */
+const ONE_TABLE_VIEW = {
+	release: '0.0.0',
+	maintenance: { mode: 'open', generation: null, published: false },
+	migrations: [],
+	scheduler: { alarm: null },
+	jobs: [],
+	files: [],
+	webhooks: [],
+	bootFailure: null,
+}
+
+/** The migration ledger `@fabrika/db/sqlite-migrate` keeps in the object's SQLite. */
+const MIGRATION_LEDGER = 'fabrika_migrations'
+
+/** What the platform wrote for the ops channel: the key digests and the objects a request may name. */
+export interface OpsAccess {
+	readonly digests: readonly Uint8Array[]
+	readonly objects: ApplicationObjects
+}
+
+/** The environment's ops access, or `null` (an older deploy, or a malformed value), which refuses every ops request. */
+export function opsAccess(env: Readonly<Record<string, unknown>>): OpsAccess | null {
+	const digests = parseOpsKeyDigests(stringOf(env[FABRIKA_OPS_KEY_DIGESTS]) ?? '')
+	const objects = parseApplicationObjects(stringOf(env[FABRIKA_APPLICATION_OBJECT]), stringOf(env[FABRIKA_APPLICATION_OBJECTS]))
+	if (digests === null || objects === null) {
+		return null
+	}
+	return { digests: digests.map((digest) => new TextEncoder().encode(digest)), objects }
+}
+
+/** What an ops request reads of the object it reached. */
+export interface OpsTarget {
+	readonly storage: OpsStorage
+	/**
+	 * The instance's last failed boot, the application's error text included. Asked only after authentication: it
+	 * waits for a boot under way and never starts one.
+	 */
+	bootFailure(): Promise<OpsBootFailureContent | null>
+}
+
+/**
+ * Answers an ops request the Worker forwarded with the proxy secret, which the object checked before. Authentication
+ * runs first; an unknown operation, a malformed body and an object name the list lacks are refused after it.
+ */
+export async function serveOps(request: Request, access: OpsAccess | null, target: OpsTarget): Promise<Response> {
+	if (access === null || !opsAuthenticated(request, access)) {
+		return opsRefusal()
+	}
+	const operation = parseOpsOperation(new URL(request.url).pathname)
+	if (operation === null) {
+		return opsRefusal()
+	}
+	const body = await jsonBody(request)
+	if (operation === 'inspect') {
+		const inspect = parseOpsInspectRequest(body)
+		if (inspect === null || !access.objects.objects.includes(inspect.object)) {
+			return opsRefusal()
+		}
+		return jsonResponse(await inspectView(target, inspect.content), 200)
+	}
+	const object = objectNamed(operation, body)
+	if (object === null || !access.objects.objects.includes(object)) {
+		return opsRefusal()
+	}
+	// `state` and `migrate` belong to the maintenance barrier (work unit 3.3b).
+	return jsonResponse({ refused: 'not_implemented' }, 501)
+}
+
+/** The object an ops request names, read with its operation's strict parser; `null` for a body that does not parse. */
+export function objectNamed(operation: OpsOperation, body: unknown): string | null {
+	switch (operation) {
+		case 'inspect':
+			return parseOpsInspectRequest(body)?.object ?? null
+		case 'state':
+			return parseOpsStateRequest(body)?.object ?? null
+		case 'migrate':
+			return parseOpsMigrateRequest(body)?.object ?? null
+	}
+}
+
+/** The request's body as JSON, or `undefined` when it is none: every parser refuses `undefined`. */
+export async function jsonBody(request: { text(): Promise<string> }): Promise<unknown> {
+	try {
+		return JSON.parse(await request.text())
+	} catch {
+		return undefined
+	}
+}
+
+/**
+ * Control's credentials on an ops request: the row's method, its endpoint header, and a key whose digest is one the
+ * platform wrote, compared in constant time. The Worker and the object both run it; it reads nothing the body names.
+ */
+export function opsAuthenticated(request: Request, access: OpsAccess): boolean {
+	if (request.method !== OPS_METHOD || request.headers.get(ENDPOINT_HEADER) !== OPS_ENDPOINT) {
+		return false
+	}
+	const authorization = request.headers.get('Authorization') ?? ''
+	const key = authorization.startsWith('Bearer ') ? authorization.slice('Bearer '.length) : ''
+	if (key === '') {
+		return false
+	}
+	const presented = new TextEncoder().encode(opsKeyDigest(key))
+	let matched = false
+	for (const digest of access.digests) {
+		// Every digest is compared, so the answer's timing does not say which one matched.
+		if (timingSafeEqual(presented, digest)) {
+			matched = true
+		}
+	}
+	return matched
+}
+
+/**
+ * The view of the object's storage, read and never written. A table the framework has not created yet (a boot that
+ * failed before its migrations) reads as empty. What the storage holds is parsed by the wire's own parser.
+ */
+async function inspectView(target: OpsTarget, content: boolean): Promise<OpsView | OpsContentView> {
+	const { storage } = target
+	const bootFailure = await target.bootFailure()
+	const tables = tableNames(storage)
+	const has = (name: string) => tables.includes(name)
+	const alarm = storage.getAlarm === undefined ? missing('getAlarm') : await storage.getAlarm()
+	const view = {
+		release: appPackage.version,
+		maintenance: { mode: 'open', generation: null, published: false },
+		database: {
+			sizeBytes: storage.sql.databaseSize ?? missing('sql.databaseSize'),
+			tables: tables.filter(admittedTableName).map((name) => ({ name, rows: cappedCount(storage, name) })),
+		},
+		migrations: has(MIGRATION_LEDGER)
+			? rows(storage, `select bundle, name, checksum, applied_at as appliedAt from ${MIGRATION_LEDGER} order by bundle, name`)
+			: [],
+		scheduler: { alarm: alarm === null ? null : new Date(alarm).toISOString() },
+		jobs: has(JOB_LEASES_TABLE)
+			? rows(
+				storage,
+				`select job, last_status as lastStatus, last_started_at as lastStartedAt, last_finished_at as lastFinishedAt,
+					last_duration_ms as lastDurationMs from ${JOB_LEASES_TABLE} order by job`,
+			)
+			: [],
+		files: has(FILES_TABLE)
+			? rows(storage, `select kind, status, count(*) as count from ${FILES_TABLE} group by kind, status order by kind, status`)
+			: [],
+		webhooks: has(WEBHOOK_BINDINGS_TABLE) && has(WEBHOOK_DELIVERIES_TABLE)
+			? rows(
+				storage,
+				`select b.webhook as webhook, case when d.lease_until is null then 'completed' else 'claimed' end as state, count(*) as count
+				from ${WEBHOOK_DELIVERIES_TABLE} d join ${WEBHOOK_BINDINGS_TABLE} b on b.id = d.binding_id
+				group by 1, 2 order by 1, 2`,
+			)
+			: [],
+		bootFailure: content || bootFailure === null ? bootFailure : { at: bootFailure.at },
+	}
+	const parsed = content ? parseOpsContentView(view) : parseOpsView(view)
+	if (parsed === null) {
+		throw new Error("the object's ops view does not parse as the wire's view")
+	}
+	return parsed
+}
+
+/** Cloudflare's own `_cf_*` tables and SQLite's `sqlite_*` are no table of the application or the framework. */
+function tableNames(storage: OpsStorage): string[] {
+	return storage.sql.exec(
+		`select name from sqlite_schema where type = 'table' and name not like '\\_cf\\_%' escape '\\' and name not like 'sqlite\\_%' escape '\\'
+		order by name`,
+	).toArray().flatMap((row) => typeof row['name'] === 'string' ? [row['name']] : [])
+}
+
+/**
+ * Whether the view admits `name`. A table SQLite allows but the wire does not (`"MixedCase"`, from a raw migration) is
+ * left out, so one such table never takes the whole view down with it.
+ */
+function admittedTableName(name: string): boolean {
+	return parseOpsView({ ...ONE_TABLE_VIEW, database: { sizeBytes: 0, tables: [{ name, rows: 0 }] } }) !== null
+}
+
+/** At most `OPS_ROW_COUNT_CAP`: a full count bills every row read. */
+function cappedCount(storage: OpsStorage, table: string): unknown {
+	const quoted = `"${table.replaceAll('"', '""')}"`
+	return storage.sql.exec(`select count(*) as count from (select 1 from ${quoted} limit ${OPS_ROW_COUNT_CAP})`).toArray()[0]?.['count']
+}
+
+function rows(storage: OpsStorage, query: string): Record<string, SqliteValue>[] {
+	return storage.sql.exec(query).toArray()
+}
+
+function missing(member: string): never {
+	throw new Error(`the object's storage has no ${member}; a Durable Object's storage has it`)
+}
+
+function stringOf(value: unknown): string | undefined {
+	return typeof value === 'string' ? value : undefined
+}

package/src/cloudflare/r2-files.ts

@@ -0,0 +1,172 @@
+// The stored files of an application environment in its R2 bucket (`FABRIKA_FILES`, ADR-0065 §6): the
+// `FileObjectStore` port, as the S3 store serves it on Zerops. A version is the object's etag.
+
+import { type FileObjectStore, ObjectExistsError, type ObjectMetadata, ObjectTooLargeError, type StoredObject } from '@fabrika/platform'
+import { method } from './bindings.js'
+
+/**
+ * R2 stores a stream only when its length is known up front, which an upload's is not. A body up to this size is
+ * buffered and written in one conditional put; a longer one goes up in parts of this size, so an object holds at most
+ * one part in memory. R2 takes parts of at least 5 MiB, all but the last of one size.
+ */
+export const R2_PART_BYTES = 8 * 1024 * 1024
+
+interface R2Info {
+	readonly size: number
+	readonly etag: string
+	readonly contentType: string | null
+	readonly body: ReadableStream<Uint8Array> | null
+}
+
+/** An R2 answer's object, or `null` for anything else. */
+function infoOf(value: unknown): R2Info | null {
+	if (typeof value !== 'object' || value === null) {
+		return null
+	}
+	const size: unknown = Reflect.get(value, 'size')
+	const etag: unknown = Reflect.get(value, 'etag')
+	if (typeof size !== 'number' || !Number.isSafeInteger(size) || typeof etag !== 'string' || etag === '') {
+		return null
+	}
+	const metadata: unknown = Reflect.get(value, 'httpMetadata')
+	const type: unknown = typeof metadata === 'object' && metadata !== null ? Reflect.get(metadata, 'contentType') : undefined
+	const body: unknown = 'body' in value ? Reflect.get(value, 'body') : null
+	return { size, etag, contentType: typeof type === 'string' && type !== '' ? type : null, body: body instanceof ReadableStream ? body : null }
+}
+
+function required(binding: unknown, name: string): (...args: unknown[]) => unknown {
+	const found = method(binding, name)
+	if (found === null) {
+		throw new Error(`the FABRIKA_FILES binding has no ${name}; it is an R2 bucket`)
+	}
+	return found
+}
+
+function joined(chunks: readonly Uint8Array[], length: number): Uint8Array {
+	const bytes = new Uint8Array(length)
+	let offset = 0
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset)
+		offset += chunk.byteLength
+	}
+	return bytes
+}
+
+interface MultipartUpload {
+	uploadPart(bytes: Uint8Array): Promise<void>
+	complete(): Promise<void>
+	abort(): Promise<void>
+}
+
+async function multipartUpload(bucket: unknown, key: string, contentType: string): Promise<MultipartUpload> {
+	const upload: unknown = await required(bucket, 'createMultipartUpload')(key, { httpMetadata: { contentType } })
+	const parts: { readonly partNumber: number; readonly etag: string }[] = []
+	return {
+		async uploadPart(bytes) {
+			const partNumber = parts.length + 1
+			const uploaded: unknown = await required(upload, 'uploadPart')(partNumber, bytes)
+			const etag: unknown = typeof uploaded === 'object' && uploaded !== null ? Reflect.get(uploaded, 'etag') : undefined
+			if (typeof etag !== 'string') {
+				throw new Error('R2 answered a part upload without its etag')
+			}
+			parts.push({ partNumber, etag })
+		},
+		async complete() {
+			await required(upload, 'complete')(parts)
+		},
+		async abort() {
+			await required(upload, 'abort')()
+		},
+	}
+}
+
+/** `bucket` (an R2 binding) as the files' object store, or `undefined` when the environment binds none. */
+export function r2FileObjectStore(bucket: unknown): FileObjectStore | undefined {
+	if (!['head', 'get', 'put', 'delete'].every((name) => method(bucket, name) !== null)) {
+		return undefined
+	}
+	const head = required(bucket, 'head')
+	const get = required(bucket, 'get')
+	const put = required(bucket, 'put')
+	const remove = required(bucket, 'delete')
+
+	const stored = (answer: unknown): StoredObject | null => {
+		const info = infoOf(answer)
+		// An object without a body is R2's answer to a failed condition: the object was replaced.
+		if (info === null || info.body === null) {
+			return null
+		}
+		return { size: info.size, contentType: info.contentType, version: info.etag, body: info.body }
+	}
+	const stopped = (signal: AbortSignal | undefined): void => {
+		if (signal?.aborted === true) {
+			throw new Error('the object read was stopped')
+		}
+	}
+
+	return {
+		async write(key, body, options): Promise<ObjectMetadata> {
+			// A file's key is a fresh UUID behind a unique row; the conditional put refuses a reused key atomically, and
+			// this check refuses one before a multipart upload, which takes no condition.
+			if ((await head(key)) !== null) {
+				await body.cancel()
+				throw new ObjectExistsError()
+			}
+			const httpMetadata = { contentType: options.contentType }
+			const reader = body.getReader()
+			const pending: Uint8Array[] = []
+			let buffered = 0
+			let size = 0
+			let upload: MultipartUpload | null = null
+			try {
+				for (;;) {
+					const { done, value } = await reader.read()
+					if (done) {
+						break
+					}
+					size += value.byteLength
+					if (size > options.maxBytes) {
+						await reader.cancel()
+						throw new ObjectTooLargeError(options.maxBytes)
+					}
+					pending.push(value)
+					buffered += value.byteLength
+					while (buffered >= R2_PART_BYTES) {
+						const all = joined(pending, buffered)
+						pending.length = 0
+						pending.push(all.subarray(R2_PART_BYTES))
+						buffered -= R2_PART_BYTES
+						upload ??= await multipartUpload(bucket, key, options.contentType)
+						await upload.uploadPart(all.subarray(0, R2_PART_BYTES))
+					}
+				}
+				const rest = joined(pending, buffered)
+				if (upload === null) {
+					if ((await put(key, rest, { httpMetadata, onlyIf: { etagDoesNotMatch: '*' } })) === null) {
+						throw new ObjectExistsError()
+					}
+				} else {
+					if (rest.byteLength > 0) {
+						await upload.uploadPart(rest)
+					}
+					await upload.complete()
+				}
+			} catch (error) {
+				await upload?.abort().catch(() => undefined)
+				throw error
+			}
+			return { size, contentType: options.contentType }
+		},
+		async read(key, signal) {
+			stopped(signal)
+			return stored(await get(key))
+		},
+		async readVersion(key, version, signal) {
+			stopped(signal)
+			return stored(await get(key, { onlyIf: { etagMatches: version } }))
+		},
+		async delete(key) {
+			await remove(key)
+		},
+	}
+}