@fabrika/app 0.0.1

package/README.md

@@ -0,0 +1,174 @@
+# `@fabrika/app`
+
+The server framework for Fabrika applications: Fetch-based HTTP routing,
+middleware, typed RPC, object-level authorization, and a typed browser client.
+
+Proxy gates remain the application's structural front door. The app receives a
+verified Fabrika authorization context and uses `.require(action, scope)` for
+checks that depend on application-owned objects.
+
+## Installation
+
+```bash
+bun add @fabrika/app
+```
+
+## Example
+
+```ts
+import {
+	type AuthContext,
+	createRpcClient,
+	defineApp,
+	initRpc,
+	type Middleware,
+	route,
+} from '@fabrika/app'
+import { z } from 'zod'
+
+interface Env {
+	ASSETS: { fetch(request: Request): Promise<Response> }
+}
+
+interface Ctx {
+	env: Env
+	auth: AuthContext
+}
+
+const rpc = initRpc<Ctx>()
+
+const appRouter = rpc.router({
+	projects: rpc.router({
+		rename: rpc.procedure
+			.input(z.object({ id: z.string(), name: z.string() }))
+			.require('project:write', (input) => ({
+				type: 'project',
+				value: input.id,
+			}))
+			.mutation(async ({ ctx, input }) => {
+				await renameProject(ctx.env, input.id, input.name)
+				return { ok: true }
+			}),
+	}),
+})
+
+export type AppRouter = typeof appRouter
+
+const auth: Middleware<Ctx> = async (_request, ctx, next) => {
+	ctx.auth = await readFabrikaAuth(ctx.env)
+	return next()
+}
+
+export const app = defineApp<Env, Ctx>({
+	context: (env) => ({ env, auth: anonymousAuth() }),
+	middleware: () => [auth],
+	routes: [
+		route.get('/health', () => new Response('ok')),
+		route.rpc('/api/rpc', appRouter),
+	],
+	assets: (env) => env.ASSETS,
+})
+
+export const api = createRpcClient<AppRouter>({ baseUrl: '/api/rpc' })
+```
+
+Input and output validators may use any Standard Schema implementation.
+
+## Portable RPC contracts
+
+Put only DTOs and type-only procedure declarations in a browser-safe contract
+package. The browser does not need to import the server router, its validators,
+or its context:
+
+```ts
+import type { RpcProcedureContract } from '@fabrika/app'
+
+export interface AppRpcContract {
+	projects: {
+		list: RpcProcedureContract<
+			{ ownerId: string },
+			{ id: string; name: string }[]
+		>
+	}
+}
+```
+
+The server verifies that its router implements the contract, while the browser
+uses the same contract directly:
+
+```ts
+import type { AppRpcContract } from '@example/app-contract'
+import { createRpcClient, initRpc, type RpcRouterFor } from '@fabrika/app'
+
+const rpc = initRpc<Ctx>()
+
+export const appRouter = rpc.router({
+	projects: rpc.router({
+		list: rpc.procedure.input(listInput).output(projectList).query(listProjects),
+	}),
+}) satisfies RpcRouterFor<Ctx, AppRpcContract>
+
+export const api = createRpcClient<AppRpcContract>({ baseUrl: '/api/rpc' })
+```
+
+## Runtime adapters
+
+`defineApp()` builds the runtime-neutral Fetch request pipeline. Runtime
+entrypoints adapt that application explicitly.
+
+A Cloudflare Worker module imports `@fabrika/app/cloudflare`:
+
+```ts
+import { createCloudflareWorker } from '@fabrika/app/cloudflare'
+import { app } from './app'
+
+export default createCloudflareWorker(app)
+```
+
+A long-running Bun process wraps the app with `createBunHandler()`:
+
+```ts
+import { defineApp, route } from '@fabrika/app'
+import { createBunHandler } from '@fabrika/app/bun'
+
+const app = defineApp<Deps, Ctx>({
+	context: (deps, request, exec) => ({ deps, request, exec }),
+	routes: [route.get('/healthz', () => Response.json({ status: 'ok' }))],
+})
+
+const handler = createBunHandler(app, deps, {
+	onBackgroundError: () => console.error('background task failed'),
+})
+
+const server = Bun.serve({ fetch: handler.fetch })
+
+const shutdown = async (): Promise<void> => {
+	await server.stop(false)
+	await handler.drain()
+	await closeApplicationResources()
+}
+```
+
+`drain()` waits for every task registered through the request execution context's
+`waitUntil()`. Stop accepting requests before draining, then close databases and
+other process resources.
+
+## Runtime conformance
+
+Use the test-runner-neutral `@fabrika/app/testing` entrypoint to prove that a
+portable route behaves the same through direct Fetch dispatch and both runtime
+adapters:
+
+```ts
+import { assertAppRuntimeConformance } from '@fabrika/app/testing'
+
+const response = await assertAppRuntimeConformance({
+	app,
+	createEnv: () => createIsolatedTestEnv(),
+	createRequest: () => new Request('https://app.test/healthz'),
+})
+```
+
+The helper drains registered background work and compares normalized status,
+headers, and text body. Do not use it for routes that exist in only one runtime
+composition.

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "@fabrika/app",
+	"version": "0.0.1",
+	"type": "module",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/contember/fabrika-platform.git",
+		"directory": "packages/app"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src",
+		"!src/**/__tests__/**"
+	],
+	"exports": {
+		".": {
+			"bun": "./src/index.ts",
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./bun": {
+			"bun": "./src/bun.ts",
+			"types": "./src/bun.ts",
+			"default": "./src/bun.ts"
+		},
+		"./cloudflare": {
+			"bun": "./src/cloudflare.ts",
+			"types": "./src/cloudflare.ts",
+			"default": "./src/cloudflare.ts"
+		},
+		"./testing": {
+			"bun": "./src/testing.ts",
+			"types": "./src/testing.ts",
+			"default": "./src/testing.ts"
+		}
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"test": "bun test"
+	},
+	"dependencies": {
+		"@fabrika/auth": "^0.0.1"
+	}
+}

package/src/app.ts

@@ -0,0 +1,76 @@
+// ─── Application ─────────────────────────────────────────────────────
+//
+// `defineApp` owns the runtime-neutral Fetch request pipeline.
+
+import { defaultOnError, jsonResponse } from './errors.js'
+import type { Middleware } from './middleware.js'
+import { runChain } from './middleware.js'
+import { matchRoutes } from './router.js'
+import type { Route } from './router.js'
+import { dispatchRpcRequest } from './rpc/dispatcher.js'
+
+/** Runtime-neutral background-work capability available while handling a request. */
+export interface RequestExecutionContext {
+	waitUntil(promise: Promise<unknown>): void
+}
+
+/** Something that can serve static assets (e.g. a Workers Assets binding). */
+export interface AssetsLike {
+	fetch(request: Request): Promise<Response>
+}
+
+export interface AppConfig<Env, Ctx> {
+	/** Build the base per-request context. Auth is added later by middleware. */
+	context: (env: Env, request: Request, exec: RequestExecutionContext) => Ctx | Promise<Ctx>
+	/** Middleware, run in declared order around the inner dispatch. */
+	middleware?: (env: Env) => Middleware<Ctx>[]
+	/** HTTP + RPC routes. */
+	routes: Route<Ctx>[]
+	/** SPA fallback served for an unmatched GET. */
+	assets?: (env: Env) => AssetsLike
+	/** Map a thrown value to a `Response`. Defaults to `defaultOnError`. */
+	onError?: (err: unknown, request: Request, env: Env) => Response
+}
+
+export interface FabrikaApp<Env> {
+	fetch(request: Request, env: Env, exec: RequestExecutionContext): Promise<Response>
+}
+
+function createFetch<Env, Ctx>(
+	config: AppConfig<Env, Ctx>,
+): (request: Request, env: Env, exec: RequestExecutionContext) => Promise<Response> {
+	const onError = config.onError ?? defaultOnError
+
+	return async (request: Request, env: Env, exec: RequestExecutionContext): Promise<Response> => {
+		try {
+			const ctx = await config.context(env, request, exec)
+			const middleware = config.middleware ? config.middleware(env) : []
+
+			const dispatch = async (): Promise<Response> => {
+				const matched = matchRoutes(config.routes, request)
+				if (matched) {
+					const inner = (): Promise<Response> => {
+						if (matched.route.kind === 'rpc') {
+							return dispatchRpcRequest({ router: matched.route.router, ctx, request })
+						}
+						return Promise.resolve(matched.route.handler(ctx, matched.params))
+					}
+					// Route-scoped middleware run after the global chain, around the handler.
+					return runChain(request, ctx, matched.route.use, inner)
+				}
+				if (request.method === 'GET' && config.assets) {
+					return config.assets(env).fetch(request)
+				}
+				return jsonResponse({ error: { type: 'not_found', message: 'Not found' } }, 404)
+			}
+
+			return await runChain(request, ctx, middleware, dispatch)
+		} catch (err) {
+			return onError(err, request, env)
+		}
+	}
+}
+
+export function defineApp<Env, Ctx>(config: AppConfig<Env, Ctx>): FabrikaApp<Env> {
+	return { fetch: createFetch(config) }
+}

package/src/bun.ts

@@ -0,0 +1,63 @@
+// ─── Bun process adapter ─────────────────────────────────────────────
+//
+// A long-running Bun process needs only request dispatch and explicit draining.
+// It does not emulate Worker cron, queues, or passThroughOnException().
+
+import type { FabrikaApp, RequestExecutionContext } from './app.js'
+
+export interface ManagedBunHandlerOptions {
+	/** Required sink for rejected background tasks. Do not log raw errors or secret-bearing values. */
+	onBackgroundError(error: unknown): void
+	executionContext?: never
+}
+
+export interface ExternalBunHandlerOptions {
+	/** Existing supervised process context. Its owner remains responsible for draining it. */
+	executionContext: RequestExecutionContext
+	onBackgroundError?: never
+}
+
+export type BunHandlerOptions = ManagedBunHandlerOptions | ExternalBunHandlerOptions
+
+export interface BunHandler {
+	fetch(request: Request): Promise<Response>
+	/** Wait until every task registered through `waitUntil()` has settled. */
+	drain(): Promise<void>
+}
+
+export function createBunHandler<Env>(app: FabrikaApp<Env>, env: Env, options: BunHandlerOptions): BunHandler {
+	if (options.executionContext !== undefined) {
+		return {
+			fetch: (request) => app.fetch(request, env, options.executionContext),
+			drain: () => Promise.resolve(),
+		}
+	}
+
+	const pending = new Set<Promise<void>>()
+
+	const exec: RequestExecutionContext = {
+		waitUntil(promise) {
+			const tracked = promise.then(
+				() => undefined,
+				(error) => {
+					try {
+						options.onBackgroundError(error)
+					} catch {
+						// Draining must remain reliable even if the reporting hook fails.
+					}
+				},
+			)
+			pending.add(tracked)
+			void tracked.then(() => pending.delete(tracked))
+		},
+	}
+
+	return {
+		fetch: (request) => app.fetch(request, env, exec),
+		async drain() {
+			while (pending.size > 0) {
+				await Promise.all(pending)
+			}
+		},
+	}
+}

package/src/client.ts

@@ -0,0 +1,143 @@
+// ─── RPC client ──────────────────────────────────────────────────────
+//
+// A typed proxy: `client.a.b.c(input)` POSTs `{ method: 'a.b.c', input }` to the
+// configured endpoint and unwraps `{ result }` / `{ error }`. Errors surface as
+// `RpcError` (carrying `type`, `loginUrl`, … off the error envelope).
+//
+// `bounceOnAuth` folds the SSO redirect every SPA needs into the client: on a
+// human-gated 401 (`type: 'auth'` + `loginUrl`) it redirects the browser to the
+// login URL (returning the current page) instead of throwing, with a short
+// re-entry guard so an unprovisioned identity can't loop forever.
+
+import type { InferRpcClient } from './rpc/contract.js'
+
+export class RpcError extends Error {
+	readonly type: string
+	readonly issues?: unknown
+	readonly loginUrl?: string
+	readonly httpStatus?: number
+	constructor(payload: { type: string; message: string; issues?: unknown; loginUrl?: string; httpStatus?: number }) {
+		super(payload.message)
+		this.name = 'RpcError'
+		this.type = payload.type
+		if (payload.issues !== undefined) this.issues = payload.issues
+		if (payload.loginUrl !== undefined) this.loginUrl = payload.loginUrl
+		if (payload.httpStatus !== undefined) this.httpStatus = payload.httpStatus
+	}
+}
+
+/** Minimal Fetch API surface required by the RPC client. */
+export type RpcFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+
+interface BounceConfig {
+	readonly sessionKey: string
+	readonly windowMs: number
+}
+
+export interface RpcClientOptions {
+	/** Endpoint the RPC proxy POSTs to (e.g. `/rpc`). */
+	readonly baseUrl: string
+	/**
+	 * Auto-redirect to SSO on a human-gated 401 (`type: 'auth'` + `loginUrl`) instead of throwing.
+	 * `true` uses sane defaults; pass `{ sessionKey, windowMs }` to tune the re-entry guard.
+	 */
+	readonly bounceOnAuth?: boolean | { sessionKey?: string; windowMs?: number }
+	/** Override `fetch` (tests / non-browser). Defaults to the global `fetch`. */
+	readonly fetch?: RpcFetch
+}
+
+function resolveBounce(baseUrl: string, opt: RpcClientOptions['bounceOnAuth']): BounceConfig | null {
+	if (!opt) return null
+	const tuning = opt === true ? {} : opt
+	return { sessionKey: tuning.sessionKey ?? `fabrika:login-bounce:${baseUrl}`, windowMs: tuning.windowMs ?? 10_000 }
+}
+
+/** Guarded SSO redirect. Returns true if it navigated (caller should hang), false if guarded/non-browser. */
+function bounceToLogin(loginUrl: string, cfg: BounceConfig): boolean {
+	if (typeof window === 'undefined') return false
+	const now = Date.now()
+	const last = Number(sessionStorage.getItem(cfg.sessionKey) ?? '0')
+	if (Number.isFinite(last) && now - last < cfg.windowMs) return false
+	sessionStorage.setItem(cfg.sessionKey, String(now))
+	const target = new URL(loginUrl)
+	target.searchParams.set('redirect', window.location.href)
+	window.location.assign(target.toString())
+	return true
+}
+
+function clearBounce(cfg: BounceConfig | null): void {
+	if (cfg && typeof window !== 'undefined') sessionStorage.removeItem(cfg.sessionKey)
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === 'object'
+}
+
+function normalizeError(
+	raw: unknown,
+	httpStatus: number,
+): { type: string; message: string; issues?: unknown; loginUrl?: string; httpStatus: number } {
+	if (typeof raw === 'string') {
+		return { type: httpStatus === 401 ? 'auth' : 'error', message: raw, httpStatus }
+	}
+	if (isRecord(raw)) {
+		const type = typeof raw['type'] === 'string' ? raw['type'] : 'error'
+		const message = typeof raw['message'] === 'string' ? raw['message'] : 'Unknown error'
+		const issues = raw['issues']
+		const loginUrl = typeof raw['loginUrl'] === 'string' ? raw['loginUrl'] : undefined
+		return { type, message, httpStatus, ...(issues !== undefined ? { issues } : {}), ...(loginUrl !== undefined ? { loginUrl } : {}) }
+	}
+	return { type: 'error', message: `HTTP ${httpStatus}`, httpStatus }
+}
+
+async function callRpc(opts: RpcClientOptions, bounce: BounceConfig | null, method: string, input: unknown): Promise<unknown> {
+	const doFetch = opts.fetch ?? fetch
+	let response: Response
+	try {
+		response = await doFetch(opts.baseUrl, {
+			method: 'POST',
+			credentials: 'include',
+			headers: { 'content-type': 'application/json' },
+			body: JSON.stringify({ method, input: input ?? null }),
+		})
+	} catch {
+		throw new RpcError({ type: 'transport', message: 'Network request failed', httpStatus: 0 })
+	}
+	let data: { result?: unknown; error?: unknown }
+	try {
+		data = await response.json()
+	} catch {
+		// Non-JSON response (proxy error, HTML error page, etc.) — surface the HTTP status.
+		throw new RpcError({ type: 'transport', message: `${response.status} ${response.statusText}`, httpStatus: response.status })
+	}
+	if (data.error !== undefined) {
+		const normalized = normalizeError(data.error, response.status)
+		if (bounce && normalized.type === 'auth' && normalized.loginUrl !== undefined && bounceToLogin(normalized.loginUrl, bounce)) {
+			// Navigation is in flight — never resolve, so the caller (a route loader) stays pending.
+			return new Promise<never>(() => {})
+		}
+		throw new RpcError(normalized)
+	}
+	clearBounce(bounce)
+	return data.result
+}
+
+function makeProxy(opts: RpcClientOptions, bounce: BounceConfig | null, path: string): unknown {
+	const fn = (input: unknown) => callRpc(opts, bounce, path, input)
+	return new Proxy(fn, {
+		get(_target, prop) {
+			if (typeof prop !== 'string') return undefined
+			return makeProxy(opts, bounce, path ? `${path}.${prop}` : prop)
+		},
+	})
+}
+
+function isClient<TApi>(value: unknown): value is InferRpcClient<TApi> {
+	return typeof value === 'function'
+}
+
+export function createRpcClient<TApi>(opts: RpcClientOptions): InferRpcClient<TApi> {
+	const proxy = makeProxy(opts, resolveBounce(opts.baseUrl, opts.bounceOnAuth), '')
+	if (!isClient<TApi>(proxy)) throw new Error('unreachable')
+	return proxy
+}

package/src/cloudflare.ts

@@ -0,0 +1,46 @@
+// ─── Cloudflare Workers adapter ──────────────────────────────────────
+
+import type { FabrikaApp, RequestExecutionContext } from './app.js'
+
+/** Minimal structural view of a Workers `ExecutionContext`. */
+export interface CloudflareExecutionContext extends RequestExecutionContext {
+	passThroughOnException(): void
+}
+
+/** Minimal structural view of a Workers cron `ScheduledController`. */
+export interface CloudflareScheduledController {
+	readonly scheduledTime: number
+	readonly cron: string
+	noRetry(): void
+}
+
+/** Minimal structural view of a Workers queue `MessageBatch`. */
+export interface CloudflareMessageBatch {
+	readonly queue: string
+	readonly messages: ReadonlyArray<unknown>
+}
+
+export interface CloudflareWorkerOptions<Env> {
+	scheduled?: (controller: CloudflareScheduledController, env: Env, exec: CloudflareExecutionContext) => Promise<void>
+	queue?: (batch: CloudflareMessageBatch, env: Env, exec: CloudflareExecutionContext) => Promise<void>
+}
+
+export interface CloudflareWorker<Env> {
+	fetch(request: Request, env: Env, exec: CloudflareExecutionContext): Promise<Response>
+	scheduled?(controller: CloudflareScheduledController, env: Env, exec: CloudflareExecutionContext): Promise<void>
+	queue?(batch: CloudflareMessageBatch, env: Env, exec: CloudflareExecutionContext): Promise<void>
+}
+
+/** Adapt a runtime-neutral Fabrika application to a Workers module export. */
+export function createCloudflareWorker<Env>(
+	app: FabrikaApp<Env>,
+	options: CloudflareWorkerOptions<Env> = {},
+): CloudflareWorker<Env> {
+	const scheduled = options.scheduled
+	const queue = options.queue
+	return {
+		fetch: (request, env, exec) => app.fetch(request, env, exec),
+		...(scheduled ? { scheduled } : {}),
+		...(queue ? { queue } : {}),
+	}
+}

package/src/errors.ts

@@ -0,0 +1,120 @@
+// ─── HTTP errors ─────────────────────────────────────────────────────
+//
+// The app framework never relies on cross-package `instanceof`. The error contract is purely
+// STRUCTURAL: any thrown value MAY expose `httpStatus` / `type` / `message` /
+// `issues` / `loginUrl`, and the mapper below reads those fields off whatever it
+// is handed. The classes here are a convenience for framework code (and apps
+// that want them) — they are not a requirement for interop.
+
+interface ErrorOptions {
+	readonly issues?: unknown
+	readonly loginUrl?: string
+}
+
+export class HttpError extends Error {
+	readonly httpStatus: number
+	readonly type: string
+	readonly issues?: unknown
+	readonly loginUrl?: string
+
+	constructor(httpStatus: number, type: string, message: string, options?: ErrorOptions) {
+		super(message)
+		this.name = new.target.name
+		this.httpStatus = httpStatus
+		this.type = type
+		if (options?.issues !== undefined) this.issues = options.issues
+		if (options?.loginUrl !== undefined) this.loginUrl = options.loginUrl
+	}
+}
+
+export class BadRequestError extends HttpError {
+	constructor(message = 'Bad request', options?: ErrorOptions) {
+		super(400, 'bad_request', message, options)
+	}
+}
+
+export class UnauthorizedError extends HttpError {
+	constructor(message = 'Unauthorized', options?: ErrorOptions) {
+		super(401, 'auth', message, options)
+	}
+}
+
+export class ForbiddenError extends HttpError {
+	constructor(message = 'Forbidden', options?: ErrorOptions) {
+		super(403, 'forbidden', message, options)
+	}
+}
+
+export class NotFoundError extends HttpError {
+	constructor(message = 'Not found', options?: ErrorOptions) {
+		super(404, 'not_found', message, options)
+	}
+}
+
+export class ConflictError extends HttpError {
+	constructor(message = 'Conflict', options?: ErrorOptions) {
+		super(409, 'conflict', message, options)
+	}
+}
+
+// ─── Structural mapping ──────────────────────────────────────────────
+
+export interface StructuralError {
+	readonly httpStatus: number
+	readonly type: string
+	readonly message: string
+	readonly issues?: unknown
+	readonly loginUrl?: string
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === 'object'
+}
+
+/**
+ * Read the structural HTTP-error fields off ANY thrown value. Defaults:
+ * `httpStatus → 500`, `type → 'internal'`, `message → the Error message or 'Internal error'`.
+ */
+export function readStructuralError(err: unknown): StructuralError {
+	const record: Record<string, unknown> = isRecord(err) ? err : {}
+	const httpStatus = typeof record['httpStatus'] === 'number' ? record['httpStatus'] : 500
+	const type = typeof record['type'] === 'string' ? record['type'] : 'internal'
+	const message = err instanceof Error
+		? err.message
+		: typeof record['message'] === 'string'
+		? record['message']
+		: 'Internal error'
+	const issues = record['issues']
+	const loginUrl = typeof record['loginUrl'] === 'string' ? record['loginUrl'] : undefined
+	return {
+		httpStatus,
+		type,
+		message,
+		...(issues !== undefined ? { issues } : {}),
+		...(loginUrl !== undefined ? { loginUrl } : {}),
+	}
+}
+
+export function jsonResponse(body: unknown, status: number): Response {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { 'content-type': 'application/json' },
+	})
+}
+
+/** Map any thrown value to a JSON `Response` per the structural error contract. */
+export function toErrorResponse(err: unknown): Response {
+	const { httpStatus, type, message, issues, loginUrl } = readStructuralError(err)
+	const error = {
+		type,
+		message,
+		...(issues !== undefined ? { issues } : {}),
+		...(loginUrl !== undefined ? { loginUrl } : {}),
+	}
+	return jsonResponse({ error }, httpStatus)
+}
+
+/** The default `onError` handler — a thin wrapper around {@link toErrorResponse}. */
+export function defaultOnError(err: unknown, _request?: Request): Response {
+	return toErrorResponse(err)
+}