@fabrika/app 0.8.2 → 0.9.0-cloudflare.2

package/src/cloudflare/application.ts

@@ -0,0 +1,352 @@
+// The Durable Object an application environment runs in (ADR-0065): it migrates its SQLite, boots the application and
+// serves every request and minute tick its Worker forwards. A plain class, so Bun and Lopata load it without
+// `cloudflare:workers`.
+
+import { FABRIKA_PROXY_SECRET, OPS_PREFIX, type OpsBootFailureContent, PROXY_SECRET_HEADER } from '@fabrika/auth-core'
+import { isScopedDatabase } from '@fabrika/db/framework'
+import { SQLITE_FRAMEWORK_MIGRATIONS } from '@fabrika/db/migrations-sqlite'
+import { openSqlite, type SqliteStorage } from '@fabrika/db/sqlite'
+import { migrateSqlite } from '@fabrika/db/sqlite-migrate'
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { timingSafeEqual } from 'node:crypto'
+import type { RequestExecutionContext } from '../fetch.js'
+import { boot, type ContractApp } from '../implement/boot.js'
+import { type CrashEvents, environmentCrashReporter, reportSurvivedCrashes } from '../implement/crashes.js'
+import { proxySecretDigest } from '../implement/dispatch.js'
+import { type CapturedEnvironment, captureEnvironment } from '../implement/environment.js'
+import type { ContractImplementation } from '../implement/implement.js'
+import type { CrashReporter } from '../jobs/report.js'
+import { isDueAt } from '../jobs/schedule.js'
+import { environmentScrubber, type Scrubber } from '../jobs/scrub.js'
+import { bindingAssets, bindingKeySource, bindingMembership, bindingTerminals, bindingWorkloadTokens, connectBindings } from './bindings.js'
+import { CLOUDFLARE_ASSETS_BINDING, CLOUDFLARE_FILES_BINDING } from './names.js'
+import { type OpsAccess, opsAccess, type OpsStorage, serveOps } from './ops.js'
+import { r2FileObjectStore } from './r2-files.js'
+
+/** The application module, imported only after the environment was captured: the generated entrypoint's `import()`. */
+export type ImplementationLoader = () => Promise<{ readonly default: ContractImplementation }>
+
+/** One of the application's SQLite migrations, as `fabrika app build` bundles them from `db/migrations`. */
+export interface ApplicationMigration {
+	readonly name: string
+	readonly sql: string
+}
+
+export interface ContractWorkerOptions {
+	/** The application's own SQLite migrations, applied as the bundle `app` after the framework's `fabrika`. */
+	readonly migrations?: readonly ApplicationMigration[]
+	/** Where the isolate hears of an unhandled rejection; the global `unhandledrejection` event by default. */
+	readonly rejections?: CrashEvents
+	/** What posts a report to Operations' ingest; `fetch` by default. */
+	readonly operationsFetch?: (request: Request) => Promise<Response>
+}
+
+/**
+ * Marks the Worker's minute tick, with its `scheduledTime`. The Worker's `fetch` removes it from every request it
+ * forwards, so only its own `scheduled` handler reaches the tick.
+ */
+export const TICK_HEADER = 'X-Fabrika-Tick'
+
+/** What the object needs of its `ctx.storage`; a Durable Object's `DurableObjectStorage` fits it. */
+export type ApplicationStorage = SqliteStorage & OpsStorage
+
+/** What the object needs of its `DurableObjectState`. */
+export interface ApplicationState {
+	readonly storage: ApplicationStorage
+	blockConcurrencyWhile<T>(callback: () => Promise<T>): Promise<T>
+	waitUntil(promise: Promise<unknown>): void
+}
+
+/** The framework's bindings: IAM's application entrypoint and the Workers Assets of the SPA. No handler sees them. */
+const FRAMEWORK_BINDINGS: ReadonlySet<string> = new Set(['IAM', CLOUDFLARE_ASSETS_BINDING])
+
+/**
+ * The application this isolate booted, once: its module is loaded once, and its `scoped(tables)` layer binds once, to
+ * the storage of the object whose event runs (`objectStorage`), never to one database.
+ */
+interface Booted {
+	readonly app: ContractApp
+	/** Whether the application has a data layer, which every object instance migrates in its own storage. */
+	readonly migrates: boolean
+}
+
+interface ApplicationSetup {
+	readonly load: ImplementationLoader
+	readonly options: ContractWorkerOptions
+	booted: Promise<Booted> | null
+	/** Whether the current streak of failed attachments was reported; an attachment that succeeds ends the streak. */
+	failureReported: boolean
+	watchingRejections: boolean
+}
+
+let registered: ApplicationSetup | null = null
+
+/** The storage of the object whose event runs; the work an event hands to `waitUntil` keeps it. */
+const objectStorage = new AsyncLocalStorage<ApplicationStorage>()
+
+function eventStorage(): ApplicationStorage {
+	const storage = objectStorage.getStore()
+	if (storage === undefined) {
+		throw new Error('a statement ran outside any event of an application object: the framework runs every event in its object scope')
+	}
+	return storage
+}
+
+/** What the object classes of this isolate boot: the generated entrypoint's `createContractWorker` registers it. */
+export function registerApplication(load: ImplementationLoader, options: ContractWorkerOptions): void {
+	registered = { load, options, booted: null, failureReported: false, watchingRejections: false }
+}
+
+/** The isolate's `unhandledrejection` event. Listening leaves the runtime's own handling, its log line, in place. */
+function globalRejectionEvents(): CrashEvents {
+	return {
+		listen(listener) {
+			const rejection = (event: Event) => listener('unhandled_rejection', Reflect.get(event, 'reason'))
+			globalThis.addEventListener('unhandledrejection', rejection)
+			return () => globalThis.removeEventListener('unhandledrejection', rejection)
+		},
+	}
+}
+
+/** The framework's tables, then the application's, each migration once: a booted storage applies nothing. */
+async function migrate(storage: ApplicationStorage, migrations: readonly ApplicationMigration[]): Promise<void> {
+	await migrateSqlite({ exec: (query, ...bindings) => storage.sql.exec(query, ...bindings), transactionSync: (fn) => storage.transactionSync(fn) }, [
+		{ bundle: 'fabrika', migrations: SQLITE_FRAMEWORK_MIGRATIONS },
+		{ bundle: 'app', migrations },
+	])
+}
+
+async function bootApplication(
+	setup: ApplicationSetup,
+	state: ApplicationState,
+	env: Readonly<Record<string, unknown>>,
+	environment: CapturedEnvironment,
+	crashes: CrashReporter | null,
+): Promise<Booted> {
+	const { default: implementation } = await setup.load()
+	const migrates = isScopedDatabase(implementation.database)
+	if (migrates) {
+		await migrate(state.storage, setup.options.migrations ?? [])
+	}
+	const database = migrates
+		? openSqlite({
+			sql: { exec: (query, ...bindings) => eventStorage().sql.exec(query, ...bindings) },
+			transaction: (closure) => eventStorage().transaction(closure),
+			transactionSync: (closure) => eventStorage().transactionSync(closure),
+		})
+		: undefined
+	const app = boot(implementation, {
+		environment,
+		iam: bindingKeySource(env['IAM']),
+		assets: bindingAssets(env[CLOUDFLARE_ASSETS_BINDING]),
+		membership: bindingMembership(env['IAM']),
+		terminals: bindingTerminals(env['IAM']),
+		workloadTokens: bindingWorkloadTokens(env['IAM']),
+		connectBindings: connectBindings(env),
+		database,
+		files: r2FileObjectStore(env[CLOUDFLARE_FILES_BINDING]),
+		// The Worker forwards only with the proxy secret, which the object checked; `boot` checks it again.
+		requireProxySecret: true,
+		// The proxy Worker sets `X-Fabrika-Client-Ip` from `CF-Connecting-IP`, the visitor Cloudflare saw.
+		clientAddress: 'vouched',
+		...(setup.options.operationsFetch === undefined ? {} : { operationsFetch: setup.options.operationsFetch }),
+	})
+	const booted: Booted = { app, migrates }
+	if (crashes !== null && !setup.watchingRejections) {
+		setup.watchingRejections = true
+		reportSurvivedCrashes(setup.options.rejections ?? globalRejectionEvents(), crashes)
+	}
+	return booted
+}
+
+/**
+ * The isolate's booted application with this instance's storage migrated, or the first boot. Reports the first failure
+ * of a streak as `boot_failed`, whichever instance or step it comes from; an attachment that succeeds ends the streak.
+ */
+async function attach(
+	setup: ApplicationSetup | null,
+	state: ApplicationState,
+	env: Readonly<Record<string, unknown>>,
+	failed: (failure: OpsBootFailureContent) => void,
+): Promise<Booted> {
+	if (setup === null) {
+		throw new Error('no contract application is registered: the generated entrypoint calls createContractWorker before an object starts')
+	}
+	const environment = captureEnvironment(Object.fromEntries(Object.entries(env).filter(([name]) => !FRAMEWORK_BINDINGS.has(name))))
+	const crashes = environmentCrashReporter(environment, setup.options.operationsFetch)
+	try {
+		const booted = await attachOnce(setup, state, env, environment, crashes)
+		setup.failureReported = false
+		return booted
+	} catch (error) {
+		failed(bootFailure(error, environmentScrubber(environment)))
+		if (crashes !== null && !setup.failureReported) {
+			setup.failureReported = true
+			state.waitUntil(crashes.report('boot_failed', error))
+		}
+		throw error
+	}
+}
+
+async function attachOnce(
+	setup: ApplicationSetup,
+	state: ApplicationState,
+	env: Readonly<Record<string, unknown>>,
+	environment: CapturedEnvironment,
+	crashes: CrashReporter | null,
+): Promise<Booted> {
+	if (setup.booted === null) {
+		const booting = bootApplication(setup, state, env, environment, crashes)
+		setup.booted = booting
+		// A failed boot is not kept: the next object instance boots again and fails with the same problems.
+		booting.catch(() => {
+			setup.booted = null
+		})
+		return await booting
+	}
+	const booted = await setup.booted
+	if (booted.migrates) {
+		await migrate(state.storage, setup.options.migrations ?? [])
+	}
+	return booted
+}
+
+/** A failed boot as the ops view shows it, its text scrubbed as a crash report's is. */
+function bootFailure(error: unknown, scrubber: Scrubber): OpsBootFailureContent {
+	const at = new Date().toISOString()
+	if (error instanceof Error) {
+		return { at, message: scrubber.scrub(error.message), stack: typeof error.stack === 'string' ? scrubber.scrub(error.stack) : null }
+	}
+	const message = typeof error === 'string' ? scrubber.scrub(error) : `a thrown ${error === null ? 'null' : typeof error} that is not an Error`
+	return { at, message, stack: null }
+}
+
+type Outcome = { readonly booted: Booted } | { readonly failure: unknown }
+
+/** The wait after an instance's first failed boot before an event boots again; it doubles with each failure, to the cap. */
+const BOOT_RETRY_MS = 1_000
+const BOOT_RETRY_CAP_MS = 60_000
+
+/** A job run handed to `waitUntil`; the runner logs and reports its own failures. */
+async function runQuietly(app: ContractApp, name: string): Promise<void> {
+	try {
+		await app.jobs.run(name)
+	} catch {
+		console.error(`fabrika: job '${name}' did not start: driver_failed`)
+	}
+}
+
+/** The application environment's one object. The Worker's generated entrypoint exports it as `FabrikaApplication`. */
+export class FabrikaApplication {
+	readonly #state: ApplicationState
+	readonly #env: Readonly<Record<string, unknown>>
+	readonly #setup: ApplicationSetup | null
+	/** `proxySecretDigest` of the environment's proxy secret; `null` refuses every request. */
+	readonly #secret: Uint8Array | null
+	/** What the platform wrote for Control's ops channel; `null` refuses every ops request. */
+	readonly #ops: OpsAccess | null
+	/** The instance's last failed boot, kept in memory for the ops view. */
+	#bootFailure: OpsBootFailureContent | null = null
+	/** The instance's boot, `null` until the first event that needs the application: an ops request never starts it. */
+	#outcome: Promise<Outcome> | null = null
+	#failedBoots = 0
+	/** When an event may boot again after a failed boot; until then every request answers the failure. */
+	#retryAt = 0
+
+	constructor(state: ApplicationState, env: Readonly<Record<string, unknown>>) {
+		this.#state = state
+		this.#env = env
+		this.#setup = registered
+		const secret = env[FABRIKA_PROXY_SECRET]
+		this.#secret = typeof secret === 'string' && secret !== '' ? proxySecretDigest(secret) : null
+		this.#ops = opsAccess(env)
+	}
+
+	async fetch(request: Request): Promise<Response> {
+		// Another Worker on the account that binds this class reaches nothing, not even an answer that the object exists.
+		if (!this.#fromWorker(request)) {
+			return new Response(null, { status: 404 })
+		}
+		if (new URL(request.url).pathname.startsWith(OPS_PREFIX)) {
+			// Served from storage alone: it never starts a boot or a retry, and waits for one under way only once authenticated.
+			return await serveOps(request, this.#ops, {
+				storage: this.#state.storage,
+				bootFailure: async () => {
+					await this.#outcome
+					return this.#bootFailure
+				},
+			})
+		}
+		const outcome = await this.#current()
+		if ('failure' in outcome) {
+			throw outcome.failure
+		}
+		return await objectStorage.run(this.#state.storage, () => this.#serve(outcome.booted, request))
+	}
+
+	/** Settles either way: a callback that rejects would reset the object, and every request answers the failure instead. */
+	#boot(): Promise<Outcome> {
+		return this.#state.blockConcurrencyWhile(() =>
+			attach(this.#setup, this.#state, this.#env, (failure) => {
+				this.#bootFailure = failure
+			}).then((booted): Outcome => ({ booted }), (failure: unknown): Outcome => {
+				this.#failedBoots++
+				this.#retryAt = Date.now() + Math.min(BOOT_RETRY_MS * 2 ** (this.#failedBoots - 1), BOOT_RETRY_CAP_MS)
+				return { failure }
+			})
+		)
+	}
+
+	/**
+	 * The instance's boot, started by the first event that needs it and booted again once a failed boot's backoff has
+	 * passed; concurrent events share one boot and one retry.
+	 */
+	async #current(): Promise<Outcome> {
+		if (this.#outcome === null) {
+			this.#outcome = this.#boot()
+		}
+		const pending = this.#outcome
+		const outcome = await pending
+		if (!('failure' in outcome) || Date.now() < this.#retryAt) {
+			return outcome
+		}
+		if (this.#outcome === pending) {
+			this.#outcome = this.#boot()
+		}
+		return await this.#outcome
+	}
+
+	#serve(booted: Booted, request: Request): Promise<Response> {
+		const tick = request.headers.get(TICK_HEADER)
+		if (tick !== null) {
+			return Promise.resolve(this.#tick(booted, tick))
+		}
+		const exec: RequestExecutionContext = { waitUntil: (promise) => this.#state.waitUntil(promise) }
+		return booted.app.fetch(request, exec)
+	}
+
+	/** The fixed-size digests are compared in constant time, so neither the length nor a prefix of the secret leaks. */
+	#fromWorker(request: Request): boolean {
+		const presented = request.headers.get(PROXY_SECRET_HEADER) ?? ''
+		return this.#secret !== null && presented !== '' && timingSafeEqual(proxySecretDigest(presented), this.#secret)
+	}
+
+	/** Runs every job due in the tick's UTC minute and the jobs' check, each past the answer. */
+	#tick(booted: Booted, scheduledTime: string): Response {
+		const time = Number(scheduledTime)
+		if (!Number.isSafeInteger(time)) {
+			return new Response(null, { status: 400 })
+		}
+		const at = new Date(time)
+		const jobs = booted.app.jobs.scheduled
+		for (const job of jobs) {
+			if (isDueAt(job.schedule, at)) {
+				this.#state.waitUntil(runQuietly(booted.app, job.name))
+			}
+		}
+		if (jobs.length > 0) {
+			this.#state.waitUntil(booted.app.jobs.check())
+		}
+		return new Response(null, { status: 204 })
+	}
+}

package/src/cloudflare/bindings.ts

@@ -0,0 +1,159 @@
+// The Worker bindings a contract application's object boots with, each read structurally: IAM's application
+// entrypoint, the SPA's Workers Assets and the owners' proxy Workers.
+
+import { DecodedIamMembership, DecodedIamTerminals } from '@fabrika/auth'
+import type { IamMembershipRpc, IamTerminalRpc, MintFromKeyResult } from '@fabrika/auth-core'
+import { parseJwks } from '@fabrika/jwks'
+import { z } from 'zod/v4'
+import type { IamKeySource } from '../implement/boot.js'
+import { CONNECT_BINDING_PREFIX, type ConnectFetch } from '../implement/connect.js'
+import type { SpaAssets } from '../implement/dispatch.js'
+import type { WorkloadTokenSource } from '../implement/workload.js'
+import { isPageRoute } from '../spa-fallback.js'
+
+/** The method `name` of a binding, bound to it, or `null` when it has none. */
+export function method(target: unknown, name: string): ((...args: unknown[]) => unknown) | null {
+	if (typeof target !== 'object' || target === null || !(name in target)) {
+		return null
+	}
+	const found: unknown = Reflect.get(target, name)
+	return typeof found === 'function' ? (...args) => Reflect.apply(found, target, args) : null
+}
+
+export function bindingKeySource(binding: unknown): IamKeySource {
+	const getJwks = method(binding, 'getJwks')
+	if (getJwks === null) {
+		throw new Error('the IAM binding is missing (env.IAM); the platform binds it to every application Worker')
+	}
+	return {
+		async getJwks() {
+			const jwks = parseJwks(await getJwks())
+			if (jwks === null) {
+				throw new Error('IAM returned no usable key set')
+			}
+			return jwks
+		},
+	}
+}
+
+/**
+ * IAM's membership operations on the `IAM` binding (`PropustkaApplication`), every answer decoded like the HTTP
+ * transport's. A binding without them is no membership transport, and `boot` refuses a contract that needs one.
+ */
+export function bindingMembership(binding: unknown): IamMembershipRpc | undefined {
+	const methods = ['requestDelegation', 'createScope', 'assignMember', 'revokeMember', 'listMembers', 'issueLink', 'revokeLink'] as const
+	if (!methods.every((name) => method(binding, name) !== null)) {
+		return undefined
+	}
+	return new DecodedIamMembership(async (name, input) => {
+		const call = method(binding, name)
+		if (call === null) {
+			throw new Error(`the IAM binding has no ${name}`)
+		}
+		return await call(input)
+	})
+}
+
+/** The identifications at a terminal over the IAM binding, when its entrypoint serves them (ADR-0067). */
+export function bindingTerminals(binding: unknown): IamTerminalRpc | undefined {
+	const methods = ['inspectIdentification', 'assertIdentity', 'cancelIdentification'] as const
+	if (!methods.every((name) => method(binding, name) !== null)) {
+		return undefined
+	}
+	return new DecodedIamTerminals(async (name, input) => {
+		const call = method(binding, name)
+		if (call === null) {
+			throw new Error(`the IAM binding has no ${name}`)
+		}
+		return await call(input)
+	})
+}
+
+const mintFromKeyResultSchema = z.union([
+	z.strictObject({ ok: z.literal(true), token: z.string().min(1), expiresAt: z.number() }),
+	z.strictObject({ ok: z.literal(false), reason: z.enum(['invalid_key', 'unknown_principal', 'disabled', 'token_too_large']) }),
+])
+
+/**
+ * IAM's token exchange on the `IAM` binding (`mintFromKey`), for the keys of the jobs, webhooks and public procedures.
+ * An answer that is not IAM's decided outcome throws: "IAM could not be asked".
+ */
+export function bindingWorkloadTokens(binding: unknown): WorkloadTokenSource | undefined {
+	if (method(binding, 'mintFromKey') === null) {
+		return undefined
+	}
+	return {
+		async exchange(input): Promise<MintFromKeyResult> {
+			const mint = method(binding, 'mintFromKey')
+			if (mint === null) {
+				throw new Error('the IAM binding has no mintFromKey')
+			}
+			const parsed = mintFromKeyResultSchema.safeParse(await mint({ app: input.app, key: input.key, requestId: crypto.randomUUID() }))
+			if (!parsed.success) {
+				throw new Error('IAM answered the workload token exchange with something that is not its outcome')
+			}
+			return parsed.data
+		},
+	}
+}
+
+/**
+ * The SPA and link mounts' files from the Workers Assets binding, whose directory mirrors the request paths: the mount
+ * `/admin` reads `admin/…` of it, the root mount the rest (the Cloudflare deploy stages each mount's `dir` there). A page
+ * route that names no file (`isPageRoute`) gets the mount's `index.html`, as `diskAssets` serves it: Workers Assets
+ * answers `<prefix>/` with it. A missing asset stays 404.
+ */
+export function bindingAssets(binding: unknown): SpaAssets | undefined {
+	const fetchAsset = method(binding, 'fetch')
+	if (fetchAsset === null) {
+		return undefined
+	}
+	const fetched = async (request: Request): Promise<Response> => {
+		const response: unknown = await fetchAsset(request)
+		if (!(response instanceof Response)) {
+			throw new Error('the ASSETS binding answered something that is not a Response')
+		}
+		return response
+	}
+	return {
+		async serve(mount, request) {
+			const response = await fetched(request)
+			if (response.status !== 404 || !isPageRoute(request)) {
+				return response
+			}
+			const index = new URL(request.url)
+			index.pathname = mount.prefix === '/' ? '/' : `${mount.prefix}/`
+			index.search = ''
+			if (index.pathname === new URL(request.url).pathname) {
+				return response
+			}
+			await response.body?.cancel()
+			return await fetched(new Request(index, { method: request.method, headers: request.headers }))
+		},
+	}
+}
+
+/**
+ * The service bindings to owners' proxy Workers (`FABRIKA_CONNECT_<IMPORT>`), which `captureEnvironment` keeps from
+ * the application because no `FABRIKA_*` value reaches it. A binding routes by itself: the URL it is called with
+ * carries the owner's host, which the proxy Worker selects the application by.
+ */
+export function connectBindings(env: Readonly<Record<string, unknown>>): Record<string, ConnectFetch> {
+	const bindings: Record<string, ConnectFetch> = {}
+	for (const [name, binding] of Object.entries(env)) {
+		// Read, not tested with `in`: a binding stub may answer `fetch` without owning the property (Lopata's does not).
+		const fetchOwner: unknown = name.startsWith(CONNECT_BINDING_PREFIX) && typeof binding === 'object' && binding !== null
+			? Reflect.get(binding, 'fetch')
+			: undefined
+		if (typeof fetchOwner === 'function') {
+			bindings[name] = async (request) => {
+				const response: unknown = await Reflect.apply(fetchOwner, binding, [request])
+				if (!(response instanceof Response)) {
+					throw new Error(`the ${name} binding answered something that is not a Response`)
+				}
+				return response
+			}
+		}
+	}
+	return bindings
+}

package/src/cloudflare/names.ts

@@ -0,0 +1,16 @@
+// The names the Cloudflare provider and the application's Worker share (ADR-0065); `@fabrika/app/build` exports them.
+
+/** The Durable Object class the Cloudflare entry exports: one object per application environment runs it (ADR-0065). */
+export const CLOUDFLARE_APPLICATION_CLASS = 'FabrikaApplication'
+
+/** The binding through which the application's Worker reaches its object. */
+export const CLOUDFLARE_APPLICATION_BINDING = 'FABRIKA_APPLICATION'
+
+/** The R2 bucket binding of the environment's stored files. */
+export const CLOUDFLARE_FILES_BINDING = 'FABRIKA_FILES'
+
+/**
+ * The Workers Assets binding the SPA and link mounts serve their files from. Its directory mirrors the request paths:
+ * the mount `/admin` serves `<directory>/admin/…`, the root mount `<directory>/…`.
+ */
+export const CLOUDFLARE_ASSETS_BINDING = 'ASSETS'