@fabrika/app 0.3.3 → 0.4.1

package/src/implement/environment.ts

@@ -0,0 +1,47 @@
+// The framework's variables, taken out of the process before any application module loads. A module that copies the
+// environment while it initialises then copies an environment without them.
+
+import type { ApplicationEnvironment } from './implement'
+
+/** Every variable under this prefix is the framework's; no application code sees one. */
+export const FRAMEWORK_PREFIX = 'FABRIKA_'
+
+export interface CapturedEnvironment {
+	/** The `FABRIKA_*` variables, for `boot` only. */
+	readonly framework: Readonly<Record<string, string>>
+	/** Every other variable or binding, for the application's `deps`. */
+	readonly application: ApplicationEnvironment
+}
+
+/** Deletes every framework variable from `process.env` and `Bun.env`. */
+function scrubProcessEnvironment(): void {
+	const environments = [typeof process === 'undefined' ? undefined : process.env, typeof Bun === 'undefined' ? undefined : Bun.env]
+	for (const environment of environments) {
+		if (environment === undefined) {
+			continue
+		}
+		for (const name of Object.keys(environment)) {
+			if (name.startsWith(FRAMEWORK_PREFIX)) {
+				delete environment[name]
+			}
+		}
+	}
+}
+
+/**
+ * Splits `source` into the framework's variables and the application's, then scrubs the process environment.
+ * The generated entrypoint calls it through its runtime adapter before it imports `src/app.ts`.
+ */
+export function captureEnvironment(source: Readonly<Record<string, unknown>>): CapturedEnvironment {
+	const framework: Record<string, string> = {}
+	const application: Record<string, unknown> = {}
+	for (const [name, value] of Object.entries(source)) {
+		if (!name.startsWith(FRAMEWORK_PREFIX)) {
+			Object.defineProperty(application, name, { value, enumerable: true })
+		} else if (typeof value === 'string') {
+			Object.defineProperty(framework, name, { value, enumerable: true })
+		}
+	}
+	scrubProcessEnvironment()
+	return Object.freeze({ framework: Object.freeze(framework), application: Object.freeze(application) })
+}

package/src/implement/failures.ts

@@ -0,0 +1,116 @@
+// A request that answered 5xx: one server log line and, with an Operations DSN, one error event. Both carry fixed codes
+// and bounded identifiers only, never an error's name or message: application code, drivers and even the framework's
+// own refusals can put request data there. A framework failure adds its reason and the reason's catalog text.
+
+import { CAPABILITY_ERRORS, CapabilityError, QUERY_REFUSALS, QueryRefusedError } from '@fabrika/db/framework'
+import { isStructuralError } from '../errors'
+import type { OperationsReporter } from '../jobs/report'
+import { CAPABILITY_REFUSALS, CapabilityRefusedError } from './capability'
+import { SERVER_FAULTS, ServerFault } from './faults'
+
+export type RequestFailureCode =
+	| 'framework_fault'
+	| 'unavailable'
+	| 'capability_refused'
+	| 'query_refused'
+	| 'handler_status'
+	| 'handler_failed'
+
+/** At most this many request failures per process and minute become Operations events; every one is logged. */
+export const MAX_FAILURE_REPORTS_PER_MINUTE = 30
+
+const MINUTE_MS = 60_000
+/** The proxy's request id is a UUID; anything else is left out of a report rather than echoed. */
+const REQUEST_ID = /^[0-9A-Za-z-]{1,64}$/
+
+/** Chosen by `instanceof` against the framework's own classes, never by `name`, which any thrown value can set. */
+export function failureCode(error: unknown): RequestFailureCode {
+	if (error instanceof ServerFault) {
+		return error.status === 503 ? 'unavailable' : 'framework_fault'
+	}
+	if (error instanceof CapabilityRefusedError || error instanceof CapabilityError) {
+		return 'capability_refused'
+	}
+	if (error instanceof QueryRefusedError) {
+		return 'query_refused'
+	}
+	return isStructuralError(error) ? 'handler_status' : 'handler_failed'
+}
+
+/** What a log may say of a framework failure: the reason its catalog keys it by, and that reason's fixed text. */
+export interface FailureReason {
+	readonly reason: string
+	readonly text: string
+}
+
+/** A framework failure's reason and the fixed text its catalog gives it; `null` for any other thrown value. */
+export function failureReason(error: unknown): FailureReason | null {
+	if (error instanceof ServerFault) {
+		return { reason: error.reason, text: SERVER_FAULTS[error.reason] }
+	}
+	if (error instanceof CapabilityRefusedError) {
+		return { reason: error.reason, text: CAPABILITY_REFUSALS[error.reason] }
+	}
+	if (error instanceof CapabilityError) {
+		return { reason: error.reason, text: CAPABILITY_ERRORS[error.reason] }
+	}
+	if (error instanceof QueryRefusedError) {
+		return { reason: error.reason, text: QUERY_REFUSALS[error.reason] }
+	}
+	return null
+}
+
+export interface RequestFailure {
+	/** The endpoint id the request selected, or `request` before one was selected. */
+	readonly endpoint: string
+	/** The proxy's `X-Request-Id`. */
+	readonly requestId: string | null
+	readonly status: number
+	readonly error: unknown
+}
+
+export class FailureReports {
+	readonly #reporter: OperationsReporter | null
+	readonly #now: () => number
+	#window = -1
+	#reported = 0
+
+	/** `reporter` is `null` without an Operations DSN: the log line is then the only record. */
+	constructor(reporter: OperationsReporter | null, now: () => number = Date.now) {
+		this.#reporter = reporter
+		this.#now = now
+	}
+
+	/** Never rejects. The returned delivery may outlive the response; a runtime with `waitUntil` keeps it alive. */
+	record(failure: RequestFailure): Promise<void> {
+		const code = failureCode(failure.error)
+		const why = failureReason(failure.error)
+		console.error(`fabrika: ${failure.endpoint}: ${code}${why === null ? '' : `: ${why.reason}: ${why.text}`}`)
+		if (this.#reporter === null || !this.#admit()) {
+			return Promise.resolve()
+		}
+		const tags: Record<string, string> = { endpoint: failure.endpoint, code, status: String(failure.status) }
+		if (why !== null) {
+			tags['reason'] = why.reason
+		}
+		if (failure.requestId !== null && REQUEST_ID.test(failure.requestId)) {
+			tags['request'] = failure.requestId
+		}
+		return this.#reporter.report({
+			fingerprint: ['fabrika-request-failed', failure.endpoint, code],
+			type: 'RequestFailed',
+			message: `endpoint '${failure.endpoint}' answered ${failure.status}: ${code}`,
+			tags,
+		})
+	}
+
+	#admit(): boolean {
+		const window = Math.floor(this.#now() / MINUTE_MS)
+		if (window !== this.#window) {
+			this.#window = window
+			this.#reported = 0
+		}
+		this.#reported++
+		return this.#reported <= MAX_FAILURE_REPORTS_PER_MINUTE
+	}
+}

package/src/implement/faults.ts

@@ -0,0 +1,46 @@
+// The framework's own failures. The envelope of every 5xx is fixed (`dispatch.ts`'s `errorResponse`), and a server
+// log names only the fault's reason and its catalog text (`failures.ts`): the message may quote request data.
+
+/** Why the framework failed a request, as a closed catalog with the fixed text a log may print. */
+export const SERVER_FAULTS = {
+	iam_unavailable: 'IAM could not be reached or could not complete the operation',
+	delegation_missing: "a membership endpoint was reached without the proxy's delegation grant",
+	iam_answer_mismatch: 'IAM answered for another scope or principal than the request asked for',
+	iam_answer_unlabelled: "IAM answered a member without a label where the member directory's dimension shows labels",
+	link_mount: 'the endpoint asked for a link of a mount it does not issue',
+	directory_unlocated: "no table locates the value of the member directory's dimension that the endpoint's object lies in",
+	facility_unbound: 'a facility the endpoint needs (assets, data layer, framework tables or IAM transport) was not bound at boot',
+	endpoint_decision_missing: "the request did not carry the proxy's endpoint decision",
+	endpoint_decision_mismatch: 'the proxy applied other rules than this version serves the endpoint with',
+	key_set_unavailable: 'the IAM key set could not be fetched; nothing was checked',
+	output_refused: 'the handler returned a value its output schema refuses',
+	contract_inconsistent: 'the compiled endpoint misses what its kind needs (a path parameter, a body limit or a capability kind)',
+	webhook_binding_mismatch: "a webhook binding reaches another dimension than the webhook's",
+	workload_unauthorized: "the workload's key or token does not carry the authority its declaration needs",
+	request_cancelled: 'the request was cancelled or outlived its budget before its transaction committed; nothing it wrote is kept',
+	file_object_missing: "a file's object is missing from storage",
+	file_object_mismatch: "a file's object has another size than its row records",
+	file_key_taken: "a new file's object key already held an object this upload did not write",
+	file_collection_unknown: 'ctx.files named a collection the contract does not declare',
+	file_sweep_failed: "the sweep could not delete a removed or orphaned file's object or row; the next run retries it",
+	challenge_unavailable: "a form's challenge provider could not be reached in time or did not answer as it documents",
+	challenge_misconfigured: "a form's challenge provider refused the application's secret",
+	attachment_rows: 'the handler returned more rows than its attachment declares (maxRows)',
+	attachment_cell: 'a cell of the attachment is longer than one cell may hold',
+	attachment_size: 'the encoded attachment is larger than it declares (maxBytes); no body was sent',
+} as const
+
+export type ServerFaultReason = keyof typeof SERVER_FAULTS
+
+/** A failure the framework itself describes. Its message is for the author's own run, never the response or a log. */
+export class ServerFault extends Error {
+	override readonly name = 'ServerFault'
+	readonly reason: ServerFaultReason
+	readonly status: number
+
+	constructor(reason: ServerFaultReason, message: string, status = 500) {
+		super(message)
+		this.reason = reason
+		this.status = status
+	}
+}

package/src/implement/form-admission.ts

@@ -0,0 +1,120 @@
+// A form's admission: which bucket a request takes from, and what a submission carries beside its row. The buckets
+// live in the application's database (`@fabrika/db`'s `FormAdmissions`), so every instance shares them. Admission is
+// not authorization: a form is anonymous, and this only bounds how much one client and all clients together submit.
+
+import { CLIENT_ADDRESS_HEADER } from '@fabrika/auth-core'
+import { createHash } from 'node:crypto'
+import { FORM_CHALLENGE_FIELD } from '../contract/defaults'
+
+/** The bucket of a form's accepted submissions; a client's bucket is `client:<digest>`, so the two never meet. */
+export const ACCEPTED_BUCKET = 'accepted'
+
+/** Longest header value read; an IPv6 address with a zone id fits with room to spare. */
+const MAX_ADDRESS_LENGTH = 64
+
+const IPV4 = /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(?:\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/
+const HEXTET = /^[0-9a-f]{1,4}$/
+
+/**
+ * The eight groups of an IPv6 address, or `null`. An embedded IPv4 tail (`::ffff:192.0.2.1`) counts as two groups,
+ * and a zone id (`%eth0`) is dropped.
+ */
+function ipv6Groups(text: string): number[] | null {
+	const address = text.split('%')[0] ?? ''
+	const halves = address.split('::')
+	if (halves.length > 2) {
+		return null
+	}
+	const groupsOf = (half: string): number[] | null => {
+		if (half === '') {
+			return []
+		}
+		const groups: number[] = []
+		const parts = half.split(':')
+		for (const [index, part] of parts.entries()) {
+			if (index === parts.length - 1 && IPV4.test(part)) {
+				const [a = 0, b = 0, c = 0, d = 0] = part.split('.').map(Number)
+				groups.push(a * 256 + b, c * 256 + d)
+			} else if (HEXTET.test(part)) {
+				groups.push(Number.parseInt(part, 16))
+			} else {
+				return null
+			}
+		}
+		return groups
+	}
+	const head = groupsOf(halves[0] ?? '')
+	const tail = halves.length === 2 ? groupsOf(halves[1] ?? '') : []
+	if (head === null || tail === null) {
+		return null
+	}
+	if (halves.length === 1) {
+		return head.length === 8 ? head : null
+	}
+	const missing = 8 - head.length - tail.length
+	return missing < 1 ? null : [...head, ...Array.from({ length: missing }, () => 0), ...tail]
+}
+
+/**
+ * The client a per-client limit counts: an IPv4 address, or an IPv6 address's /64 (one subscriber's prefix, of which
+ * it may hold every address). Anything else, the header's absence included, is one shared `unknown` client.
+ */
+export function clientKey(header: string | null): string {
+	const value = (header ?? '').split(',')[0]?.trim().toLowerCase() ?? ''
+	if (value === '' || value.length > MAX_ADDRESS_LENGTH) {
+		return 'unknown'
+	}
+	if (IPV4.test(value)) {
+		return value
+	}
+	const groups = ipv6Groups(value.startsWith('[') && value.endsWith(']') ? value.slice(1, -1) : value)
+	if (groups === null) {
+		return 'unknown'
+	}
+	const mapped = groups.slice(0, 5).every((group) => group === 0) && groups[5] === 0xffff
+	if (mapped) {
+		const [high = 0, low = 0] = groups.slice(6)
+		return [high >> 8, high & 0xff, low >> 8, low & 0xff].join('.')
+	}
+	return `${groups.slice(0, 4).map((group) => group.toString(16)).join(':')}::/64`
+}
+
+/**
+ * The bucket of the client the proxy saw. Only `X-Fabrika-Client-Ip` is read: the proxy deletes it and sets it from
+ * the connection on every request, and the proxy secret proves the request came through it. A forwarding header a
+ * client can write (`X-Forwarded-For`, `CF-Connecting-IP`) is never read. The address is kept as its digest.
+ */
+export function clientBucket(request: Request): string {
+	return `client:${createHash('sha256').update(clientKey(request.headers.get(CLIENT_ADDRESS_HEADER))).digest('hex')}`
+}
+
+/** What the form declared beside its row: its honeypot field and whether a challenge token travels in the input. */
+export interface SubmissionFields {
+	readonly honeypot: string | null
+	readonly challenge: boolean
+}
+
+export interface Submission {
+	/** The honeypot was filled: the answer is the constant one, and nothing is written. */
+	readonly trapped: boolean
+	/** The challenge token, when the form declares a challenge. */
+	readonly token: string | null
+	/** The columns the inbox row gets: the input without the honeypot and the token. */
+	readonly row: Readonly<Record<string, unknown>>
+}
+
+export function submissionOf(input: Readonly<Record<string, unknown>>, fields: SubmissionFields): Submission {
+	const row: Record<string, unknown> = {}
+	for (const [name, value] of Object.entries(input)) {
+		if (name !== fields.honeypot && !(fields.challenge && name === FORM_CHALLENGE_FIELD)) {
+			row[name] = value
+		}
+	}
+	const trap = fields.honeypot === null ? undefined : input[fields.honeypot]
+	const token = fields.challenge ? input[FORM_CHALLENGE_FIELD] : undefined
+	return {
+		trapped: typeof trap === 'string' && trap !== '',
+		token: typeof token === 'string' ? token : null,
+		row,
+	}
+}

package/src/implement/headers.ts

@@ -0,0 +1,17 @@
+// The one response header policy of a contract application (ADR-0022, "Response headers"). The framework sets it on
+// every response it answers, denials included; the proxy sets the same definition, from `@fabrika/proxy-core/headers`.
+
+import type { CspExtensions } from '@fabrika/auth-core'
+import { applyHeaderPolicy, cspOrigins, type HeaderPolicy, headerPolicy, withResponseHeaders } from '@fabrika/proxy-core/headers'
+
+export type { HeaderPolicy }
+
+/** The policy of an application: its contract's named origins and the Operations ingest origin the browser reports to. */
+export function applicationPolicy(csp: CspExtensions, operationsOrigin: string | null): HeaderPolicy {
+	return headerPolicy(cspOrigins(csp), operationsOrigin)
+}
+
+/** A copy of `response` carrying the policy; whatever the handler or an asset server set for these names is replaced. */
+export function withHeaderPolicy(response: Response, policy: HeaderPolicy): Response {
+	return withResponseHeaders(response, (headers) => applyHeaderPolicy(headers, policy))
+}

package/src/implement/implement.ts

@@ -0,0 +1,81 @@
+// `implement(contract, { database, deps, handlers })`: the only way an application serves its contract. Handlers
+// mirror the contract's procedure tree exactly; there is no slot for routes, middleware, authentication or a server.
+
+import type { TablePolicyArtifact } from '@fabrika/auth-core'
+import type { DataLayer } from '@fabrika/db'
+import type { CapabilityAuthority } from '@fabrika/db/capability'
+import type { ConnectSnapshot } from '../contract/connect'
+import type { AnyContract } from '../contract/define'
+import type { ConnectSnapshots, ExactHandlers, HandlersOf } from './types'
+
+/**
+ * What the framework reads from the application's tables before a handler runs. The table policies are what
+ * `compileContract` takes; `locate` resolves an object's containment chain for `on` and checks that an `in` scope
+ * exists. For `@fabrika/db`'s `scoped(tables)`, `boot` builds one from the locator only it receives when it binds.
+ */
+export interface ContractDatabase {
+	readonly tables: Readonly<Record<string, TablePolicyArtifact>>
+	/** The containers an object lies in, by dimension, or `null` when the table that owns `dimension` has no such row. */
+	locate(dimension: string, id: string): Promise<ReadonlyMap<string, string> | null>
+}
+
+/** `scoped(tables)` of `@fabrika/db`, which `boot` binds, or a `ContractDatabase` of the application's own. */
+export type ImplementationDatabase = DataLayer | ContractDatabase
+
+/**
+ * The application's own variables: everything the platform and the operator set except the framework's. Values are
+ * unchecked, so `deps` parses what it reads.
+ */
+export type ApplicationEnvironment = Readonly<Record<string, unknown>>
+
+/** What the framework hands `deps`: the authority `@fabrika/db` asks whether a capability belongs to this request. */
+export interface DepsRuntime {
+	readonly capabilities: CapabilityAuthority
+}
+
+/** A contract with its handlers, ready for `boot`. Only `implement` and `serve` make one. */
+export interface ContractImplementation<C extends AnyContract = AnyContract> {
+	readonly contract: C
+	readonly database: ImplementationDatabase | null
+	/** The vendored snapshot of each import, by the import's name; `boot` checks each against the contract's digest. */
+	readonly connect?: Readonly<Record<string, ConnectSnapshot>>
+	/** Runs `deps`, then `handlers` over its result. The tree is checked by the types of `implement`, and again by `boot`. */
+	readonly handlers: (env: ApplicationEnvironment, runtime: DepsRuntime) => unknown
+}
+
+/**
+ * Binds one handler to every procedure of the contract. `deps` runs once, at `boot`; `handlers` receives what it
+ * returned and builds the handler tree, so a handler reaches its dependencies through that closure.
+ */
+export function implement<const C extends AnyContract, Deps, H extends HandlersOf<C, Snap>, Snap extends ConnectSnapshots<C> = ConnectSnapshots<C>>(
+	contract: C,
+	implementation: {
+		readonly database: ImplementationDatabase | null
+		/** The vendored snapshot of each import (`fabrika/connect/*.ts`), by the import's name. */
+		readonly connect?: Snap
+		readonly deps: (env: ApplicationEnvironment, runtime: DepsRuntime) => Deps
+		readonly handlers: (deps: Deps) => H & ExactHandlers<H, C>
+	},
+): ContractImplementation<C> {
+	const { database, connect, deps, handlers } = implementation
+	return contractImplementation({
+		contract,
+		database,
+		connect: connect ?? {},
+		handlers: (env: ApplicationEnvironment, runtime: DepsRuntime) => handlers(deps(env, runtime)),
+	})
+}
+
+const implementations = new WeakSet<object>()
+
+/** The one way a `ContractImplementation` is made, by `implement` and `serve`: frozen, and known to `isContractImplementation`. */
+export function contractImplementation<C extends AnyContract>(made: ContractImplementation<C>): ContractImplementation<C> {
+	const frozen = Object.freeze({ ...made })
+	implementations.add(frozen)
+	return frozen
+}
+
+/** Whether `value` is what `implement` or `serve` returned: how a loader checks a module it imported by path. */
+export function isContractImplementation(value: unknown): value is ContractImplementation {
+	return typeof value === 'object' && value !== null && implementations.has(value)
+}

package/src/implement/index.ts

@@ -0,0 +1,60 @@
+// @fabrika/app/implement — serving a contract: `serve` binds the handlers its endpoints carry, `boot` (called only by
+// the generated entrypoint, through a runtime adapter) serves it. Imports `node:async_hooks`, so it is not browser-safe.
+// `implement` (a mirrored handler tree) is the framework's own test entry, `./implement`, and no application's.
+export { FILE_SWEEP_JOB } from '../files/collections'
+export type { FileCollectionHandle, FileCollectionReader, FileListing, ListedFile, OpenedFile } from '../files/handle'
+export {
+	FILE_SCAN_JOB,
+	type FileScanner,
+	SCAN_LIMITS,
+	type ScanBatchResult,
+	type ScanFailure,
+	type ScanObject,
+	type ScanVerdict,
+} from '../files/scan'
+export type { OperationsReport, OperationsReporter } from '../jobs/report'
+export { type ContractJobs, type JobClock, JobError, type JobFailureCode, type JobRunOptions, type JobRunResult } from '../jobs/runner'
+export type { JobContext, JobHandler, JobHandlersOf, JobPrincipal } from '../jobs/types'
+export { LINK_BOOTSTRAP_SCRIPT } from './anonymous'
+export { boot, BootError, type BootOptions, type ContractApp, type IamKeySource } from './boot'
+export { readBoundedBytes, REQUEST_BUDGET_MS } from './bounded'
+export { AppCapability, CapabilityRefusedError, Ref, Within } from './capability'
+export { CHALLENGE_LIMITS, type ChallengeFetch, TURNSTILE_VERIFY_URL } from './challenge'
+export { type ConnectFailure, type ConnectFetch, type ConnectResult, type ConnectVariables, connectVariables, isJsonMediaType } from './connect'
+export type { SpaAssets } from './dispatch'
+export { type CapturedEnvironment, captureEnvironment } from './environment'
+export type { ApplicationEnvironment, ContractDatabase, ContractImplementation, DepsRuntime, ImplementationDatabase } from './implement'
+export { isContractImplementation } from './implement'
+export type {
+	ApplicationDirectory,
+	ApplicationMember,
+	ApplicationMemberPage,
+	ApplicationMemberRole,
+	AssignedMember,
+	DirectoryMember,
+	IssuedLink,
+	LinkIssuing,
+	Member,
+	MemberDirectory,
+	MemberList,
+	MemberLookup,
+	MemberManagement,
+	MemberTarget,
+} from './membership'
+export type { AppPrincipal, LinkHolder, Principal, PrincipalOf, ServicePrincipal, UserPrincipal } from './principal'
+export { type AppDeps, defineDeps, serve, type ServeOptions } from './serve'
+export type {
+	AccessContext,
+	ConnectCall,
+	ConnectContext,
+	ConnectSnapshots,
+	ContractContext,
+	ExactHandlers,
+	Handler,
+	HandlerInput,
+	HandlersOf,
+	RequestContext,
+	WebhookHandler,
+} from './types'
+export type { WebhookDelivery, WebhookPrincipal } from './webhook'
+export { issuerWorkloadTokens, type WorkloadTokenSource } from './workload'