@fabrika/app 0.3.3 → 0.4.0

package/src/contract/compile.ts

@@ -0,0 +1,143 @@
+// `compileContract`: the evaluated contract → its declaration with every zod schema read as a `SchemaShape` →
+// `buildArtifact`. A reader of source produces the same declaration and calls `buildArtifact` itself.
+
+import type { ContractArtifact, SchemaShape, TablePolicyArtifact } from '@fabrika/auth-core'
+import { inboxColumns, isTables, tablePolicies, type Tables } from '@fabrika/db/tables'
+import { attachmentOf } from './attachment'
+import { buildArtifact } from './build'
+import {
+	type AttachmentDeclaration,
+	type ContractDeclaration,
+	type ExportDeclaration,
+	isProcedure,
+	type MountDeclaration,
+	type ProcedureDeclaration,
+	type ProcedureTreeDeclaration,
+	SURFACE_SECTIONS,
+	type SurfaceSection,
+} from './declaration'
+import type { AnyContract, AnyMount, Schema, Surface } from './define'
+import { Problems } from './problems'
+import { describeSchema } from './schema-shape'
+
+/**
+ * The normalized artifact of a contract and its table policies: what `defineTables` returned (`src/db/tables.ts`),
+ * or the artifact form of each policy. Only the first knows each inbox's columns, so only it checks a form's fields
+ * against them; `boot` checks them against the data layer either way.
+ */
+export function compileContract<DB, P>(
+	contract: AnyContract,
+	tables: Tables<DB, P> | Readonly<Record<string, TablePolicyArtifact>>,
+): ContractArtifact {
+	const described = describeContract(contract)
+	return isTables(tables) ? buildArtifact(described, tablePolicies(tables), inboxColumns(tables)) : buildArtifact(described, tables)
+}
+
+/** The contract with its schemas read as shapes; throws `ContractError` for a schema outside the subset. */
+export function describeContract(contract: AnyContract): ContractDeclaration<SchemaShape> {
+	const problems = new Problems()
+	const reader = new SchemaReader(problems)
+	const { surface, vocabulary } = contract
+	const mounts: Record<string, MountDeclaration<SchemaShape>> = {}
+	for (const [name, entry] of Object.entries(surface)) {
+		if (isSection(name)) {
+			continue
+		}
+		if (isMount(entry)) {
+			mounts[name] = reader.mount(name, entry)
+		} else {
+			problems.add(`mount '${name}'`, 'is not a mount (allowed: c.rpc, c.link, c.spa, c.health, c.form or c.webhook)')
+		}
+	}
+	const exports: Record<string, ExportDeclaration<SchemaShape>> = {}
+	for (const [name, declaration] of Object.entries(surface.exports ?? {})) {
+		exports[name] = { ...declaration, procedures: reader.tree(`export '${name}'`, declaration.procedures) }
+	}
+	problems.throwIfAny()
+	return {
+		app: vocabulary.app,
+		dimensions: vocabulary.dimensions,
+		actions: vocabulary.actions,
+		roles: vocabulary.roles,
+		mounts,
+		files: surface.files ?? {},
+		jobs: surface.jobs ?? {},
+		exports,
+		imports: surface.imports ?? {},
+		csp: surface.csp ?? {},
+		...(vocabulary.locale === undefined ? {} : { locale: vocabulary.locale }),
+		...(vocabulary.displayName === undefined ? {} : { displayName: vocabulary.displayName }),
+		...(vocabulary.mail === undefined ? {} : { mail: vocabulary.mail }),
+		...(vocabulary.members === undefined ? {} : { members: vocabulary.members }),
+		...(vocabulary.directory === undefined ? {} : { directory: vocabulary.directory }),
+	}
+}
+
+const SECTIONS: ReadonlySet<string> = new Set(SURFACE_SECTIONS)
+
+function isSection(name: string): name is SurfaceSection {
+	return SECTIONS.has(name)
+}
+
+const MOUNT_KINDS: ReadonlySet<string> = new Set(['rpc', 'link', 'spa', 'health', 'form', 'webhook'])
+
+function isMount(entry: Surface[string]): entry is AnyMount {
+	return typeof entry === 'object' && 'kind' in entry && typeof entry.kind === 'string' && MOUNT_KINDS.has(entry.kind)
+}
+
+class SchemaReader {
+	readonly #problems: Problems
+
+	constructor(problems: Problems) {
+		this.#problems = problems
+	}
+
+	mount(name: string, mount: AnyMount): MountDeclaration<SchemaShape> {
+		const where = `mount '${name}'`
+		switch (mount.kind) {
+			case 'rpc':
+				return { ...mount, procedures: this.tree(where, mount.procedures) }
+			case 'link':
+				return { ...mount, procedures: this.tree(where, mount.procedures) }
+			case 'form':
+				return { ...mount, input: this.schema(`${where} input`, mount.input) }
+			case 'webhook':
+				return { ...mount, input: this.schema(`${where} input`, mount.input) }
+			default:
+				return mount
+		}
+	}
+
+	tree<Access>(where: string, tree: ProcedureTreeDeclaration<Schema, Access>, prefix = ''): ProcedureTreeDeclaration<SchemaShape, Access> {
+		const described: Record<string, ProcedureDeclaration<SchemaShape, Access> | ProcedureTreeDeclaration<SchemaShape, Access>> = {}
+		for (const [name, node] of Object.entries(tree)) {
+			const path = prefix === '' ? name : `${prefix}.${name}`
+			if (isProcedure(node)) {
+				const at = `${where} procedure '${path}'`
+				described[name] = {
+					...node,
+					input: node.input === null ? null : this.schema(`${at} input`, node.input),
+					...this.output(`${at} output`, node.output),
+				}
+			} else {
+				described[name] = this.tree(where, node, path)
+			}
+		}
+		return described
+	}
+
+	/** An `attachment()` output is described as the rows' array, its declaration carried beside it. */
+	output(where: string, schema: Schema): { readonly output: SchemaShape; readonly attachment?: AttachmentDeclaration } {
+		const mark = attachmentOf(schema)
+		if (mark === null) {
+			return { output: this.schema(where, schema) }
+		}
+		const row = this.schema(`${where} row`, mark.row)
+		return { output: { type: 'array', items: row, minItems: null, maxItems: null }, attachment: mark.declaration }
+	}
+
+	/** A failed schema leaves a placeholder; `describeContract` throws before anything reads it. */
+	schema(where: string, schema: Schema): SchemaShape {
+		return describeSchema(schema, where, this.#problems) ?? { type: 'null' }
+	}
+}

package/src/contract/connect.ts

@@ -0,0 +1,170 @@
+// Connectors between applications, as data: an export's description (what the owner serves and a consumer vendors),
+// the vendored snapshot a consumer imports, and the one way each is read back into shapes and a digest.
+// Browser-safe: the snapshot is imported by the contract, which the SPA imports.
+
+import {
+	canonicalJson,
+	canonicalShape,
+	type ContractArtifact,
+	type ExportDescription,
+	exportDigest,
+	type ExportProcedureDescription,
+	isAttachmentShape,
+	type SchemaShape,
+} from '@fabrika/auth-core'
+import { z } from 'zod/v4'
+import { schemaShapeSchema } from './artifact-schema'
+import { exportBase } from './defaults'
+import type { InputSchema, Schema } from './define'
+import { ContractError, Problems } from './problems'
+import { describeSchema } from './schema-shape'
+
+/** One vendored procedure: the zod schemas `fabrika connect add` generated from the owner's description. */
+export interface SnapshotProcedure {
+	readonly input: InputSchema | null
+	readonly output: Schema
+}
+
+/**
+ * The vendored description of another application's export, as `fabrika connect add` writes it to
+ * `fabrika/connect/<app>.<export>.v<version>.ts`. The consumer passes it to `implement({ connect })` and imports its
+ * digest into the contract.
+ */
+export interface ConnectSnapshot {
+	readonly app: string
+	readonly export: string
+	readonly version: number
+	readonly audience: string
+	readonly digest: string
+	/** By the procedure's dotted path in the export. */
+	readonly procedures: { readonly [path: string]: SnapshotProcedure }
+}
+
+/** The description the owner serves for `name`, or `null` when the artifact declares no such export. */
+export function exportDescription(artifact: ContractArtifact, name: string): ExportDescription | null {
+	const declaration = Object.hasOwn(artifact.exports, name) ? artifact.exports[name] : undefined
+	if (declaration === undefined) {
+		return null
+	}
+	const prefix = `${exportBase(name, declaration.version)}.`
+	const procedures: Record<string, ExportProcedureDescription> = {}
+	for (const row of artifact.endpoints) {
+		// The build refuses an attachment on an export, so an export row's output is a schema.
+		if (
+			row.source.kind === 'export' && row.source.name === name && row.id.startsWith(prefix) && row.output !== null && !isAttachmentShape(row.output)
+		) {
+			procedures[row.id.slice(prefix.length)] = { input: row.input, output: row.output }
+		}
+	}
+	const described = { app: artifact.app, export: name, version: declaration.version, audience: declaration.audience, procedures }
+	return { ...described, digest: exportDigest(described) }
+}
+
+/**
+ * The description a snapshot's schemas describe now, with the digest of that. A snapshot whose recomputed digest is
+ * not its own `digest` was edited after `fabrika connect add` wrote it. Throws `ContractError` for a schema outside
+ * the contract subset.
+ */
+export function describeSnapshot(snapshot: ConnectSnapshot): ExportDescription {
+	const problems = new Problems()
+	const procedures: Record<string, ExportProcedureDescription> = {}
+	for (const [path, procedure] of Object.entries(snapshot.procedures)) {
+		const where = `snapshot ${snapshot.app}/${snapshot.export}@${snapshot.version} procedure '${path}'`
+		const input = procedure.input === null ? null : describeSchema(procedure.input, `${where} input`, problems)
+		const output = describeSchema(procedure.output, `${where} output`, problems)
+		procedures[path] = { input, output: output ?? { type: 'null' } }
+	}
+	problems.throwIfAny()
+	const described = { app: snapshot.app, export: snapshot.export, version: snapshot.version, audience: snapshot.audience, procedures }
+	return { ...described, digest: exportDigest(described) }
+}
+
+const procedureDescription: z.ZodType<ExportProcedureDescription> = z.strictObject({
+	input: schemaShapeSchema.nullable(),
+	output: schemaShapeSchema,
+})
+
+/** The parser of a description another application served; the digest is checked by `parseExportDescription`. */
+export const exportDescriptionSchema: z.ZodType<ExportDescription> = z.strictObject({
+	app: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+	export: z.string().regex(/^[A-Za-z][A-Za-z0-9_]*$/),
+	version: z.int().positive(),
+	audience: z.string().min(1),
+	procedures: z.record(z.string().regex(/^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)*$/), procedureDescription),
+	digest: z.string().regex(/^sha256:[0-9a-f]{64}$/),
+})
+
+const DESCRIPTION_FIELDS: readonly string[] = ['app', 'export', 'version', 'audience', 'procedures', 'digest']
+
+/** A served description, parsed, whose digest is the digest of what it describes; throws `ContractError` otherwise. */
+export function parseExportDescription(value: unknown): ExportDescription {
+	const parsed = exportDescriptionSchema.safeParse(value)
+	if (!parsed.success) {
+		// Another application wrote the value: name only the fields this parser declares and zod's fixed codes.
+		const problems = parsed.error.issues.map((issue) => {
+			const [top] = issue.path
+			const field = typeof top === 'string' && DESCRIPTION_FIELDS.includes(top) ? top : '(root)'
+			return `description: invalid at ${field} (${issue.code})`
+		})
+		throw new ContractError([...new Set(problems)])
+	}
+	const { digest, ...described } = parsed.data
+	if (exportDigest(described) !== digest) {
+		throw new ContractError([`description ${described.app}/${described.export}@${described.version}: its digest does not match what it describes`])
+	}
+	return parsed.data
+}
+
+/**
+ * What an owner's change of one export version breaks for a consumer that imports `procedures` of it: a removed
+ * procedure, an input that accepts less, a changed output, or a changed audience. An output may not even gain a field,
+ * because the consumer parses every answer against its vendored schema, whose objects are strict; an input object may
+ * gain optional fields. Every other change is a new version. Empty when the change is compatible.
+ */
+export function incompatibleChanges(before: ExportDescription, after: ExportDescription, procedures: readonly string[]): string[] {
+	const problems: string[] = []
+	if (before.audience !== after.audience) {
+		problems.push('changes its audience')
+	}
+	for (const path of procedures) {
+		const old = Object.hasOwn(before.procedures, path) ? before.procedures[path] : undefined
+		const now = Object.hasOwn(after.procedures, path) ? after.procedures[path] : undefined
+		// A procedure the export never had is the consumer's mistake, which its own deploy is refused for.
+		if (old === undefined) {
+			continue
+		}
+		if (now === undefined) {
+			problems.push(`removes '${path}'`)
+			continue
+		}
+		if (!acceptsEveryInput(old.input, now.input)) {
+			problems.push(`'${path}' accepts less input than before`)
+		}
+		if (canonicalJson(canonicalShape(old.output)) !== canonicalJson(canonicalShape(now.output))) {
+			problems.push(`'${path}' answers another output than before`)
+		}
+	}
+	return problems
+}
+
+function acceptsEveryInput(before: SchemaShape | null, after: SchemaShape | null): boolean {
+	if (before === null || after === null) {
+		return before === after
+	}
+	return widens(canonicalShape(before), canonicalShape(after))
+}
+
+/** Whether `after` accepts every value `before` does, by the one widening allowed: an object field that is new and optional. */
+function widens(before: SchemaShape, after: SchemaShape): boolean {
+	if (before.type === 'object' && after.type === 'object') {
+		const kept = Object.entries(before.fields).every(([name, field]) => {
+			const next = Object.hasOwn(after.fields, name) ? after.fields[name] : undefined
+			return next !== undefined && widens(field, next)
+		})
+		return kept && Object.entries(after.fields).every(([name, field]) => Object.hasOwn(before.fields, name) || field.type === 'optional')
+	}
+	if ((before.type === 'optional' && after.type === 'optional') || (before.type === 'nullable' && after.type === 'nullable')) {
+		return widens(before.inner, after.inner)
+	}
+	return canonicalJson(before) === canonicalJson(after)
+}