@ultimabase/rest 0.0.0-stage → 0.1.1

package/src/fields.ts

@@ -0,0 +1,391 @@
+// `select` and `include` (D-129): what a request asks of a model's rows, as
+// one kernel read, and the rows shaped as GraphQL returns them. Without
+// either, a row holds its readable scalar fields and no relation.
+import type { Relay } from '@ultimabase/http/internal'
+import {
+	connection,
+	pageArgs,
+	pageOf,
+	readable,
+	readableVirtuals,
+	rowOf,
+	rowsOf,
+} from '@ultimabase/http/internal'
+import type { ExposedVirtual, Row } from 'ultimabase'
+import { InvalidQuery } from 'ultimabase'
+import type { Api, Args, Entry } from './entries.ts'
+import { entryOf, system } from './entries.ts'
+import { isArgs, whereOf } from './values.ts'
+
+/** A field of the response, in the order the request wrote it. */
+type Out =
+	| {
+			readonly kind: 'scalar'
+			readonly name: string
+			readonly toJSON: ((value: unknown) => unknown) | undefined
+	  }
+	| { readonly kind: 'one'; readonly name: string; readonly shape: Shape }
+	| {
+			readonly kind: 'many'
+			readonly name: string
+			readonly shape: Shape
+			readonly relay: Relay | undefined
+			/** The rows it asks for, which the row budget counts. */
+			readonly size: number
+			/** Whether it answers its `totalCount` (D-134). */
+			readonly counted: boolean
+	  }
+	| {
+			/** A virtual's rows of a model, re-read by the kernel (D-151). */
+			readonly kind: 'returned'
+			readonly name: string
+			readonly owner: string
+			readonly shape: Shape
+			readonly list: boolean
+			/** The rows it counts: `take` for a list, as a function's (D-109). */
+			readonly size: number
+	  }
+
+/**
+ * What a row of the response holds. `sorted` is the relations its list's
+ * `orderBy` goes through, each a level of `maxDepth` (D-134).
+ */
+export type Shape = {
+	readonly fields: readonly Out[]
+	readonly sorted?: number
+}
+
+/** A row's fields and its relations' reads, as the kernel takes them. */
+export type Read = {
+	readonly read: Args
+	readonly shape: Shape
+}
+
+/** The relations an `orderBy` goes through, the deepest path's. */
+function sortDepth(orderBy: unknown): number {
+	if (Array.isArray(orderBy)) return Math.max(0, ...orderBy.map(sortDepth))
+	if (typeof orderBy !== 'object' || orderBy === null) return 0
+	return Math.max(
+		0,
+		...Object.values(orderBy).map((value: unknown) =>
+			typeof value === 'object' && value !== null ? 1 + sortDepth(value) : 0,
+		),
+	)
+}
+
+const unknownKey = (path: string, model: string): InvalidQuery =>
+	new InvalidQuery(path, `Unknown key '${path}' on ${model}.`)
+
+const scalar = (entry: Entry, name: string): Out => ({
+	kind: 'scalar',
+	name,
+	// A plugin field reads as its toJSON gives (D-122).
+	toJSON: entry.exposed.fieldTypes[name]?.toJSON,
+})
+
+/**
+ * `id`, the dates, each scalar field a caller other than Master reads, and
+ * each virtual of a scalar without an input (D-151).
+ */
+export const defaultShape = (entry: Entry): Shape => ({
+	fields: [
+		...system.map((name) => scalar(entry, name)),
+		...readable(entry)
+			.filter((field) => field.kind === 'scalar')
+			.map((field) => scalar(entry, field.name)),
+		...defaultVirtuals(entry).map((name) => scalar(entry, name)),
+	],
+})
+
+/** The virtuals a row holds without `select` (D-151). */
+export const defaultVirtuals = (entry: Entry): readonly string[] =>
+	readableVirtuals(entry)
+		.filter((virtual) => virtual.default)
+		.map((virtual) => virtual.name)
+
+// `take` for none or a negative number; above `maxTake`, the list refuses.
+const sizeOf = (entry: Entry, asked: unknown): number =>
+	typeof asked === 'number' && asked >= 0
+		? Math.min(asked, entry.maxTake)
+		: entry.take
+
+/** A list's `where`, its dates read; `null` is absent, as in GraphQL. */
+export const filterOf = (
+	api: Api,
+	entry: Entry,
+	where: unknown,
+	path: string,
+): Args =>
+	where === undefined || where === null
+		? {}
+		: {
+				where: isArgs(where)
+					? whereOf(api, entry.model.name, where, path)
+					: where,
+			}
+
+/** Reads `select` or `include` as the request wrote them. */
+class Reader {
+	readonly #api: Api
+	readonly #master: boolean
+
+	constructor(api: Api, master: boolean) {
+		this.#api = api
+		this.#master = master
+	}
+
+	/** A row's `select` or `include`, under `path` (`''` at the root). */
+	fields(entry: Entry, args: Args, path: string): Read {
+		const at = (key: string): string => (path === '' ? key : `${path}.${key}`)
+		const { select, include } = args
+		if (select !== undefined && include !== undefined) {
+			throw new InvalidQuery(
+				path,
+				`${at('select')} and include cannot be used together.`,
+			)
+		}
+		const base = select === undefined ? 'include' : 'select'
+		const chosen = select ?? include
+		if (chosen === undefined) return { read: {}, shape: defaultShape(entry) }
+		if (!isArgs(chosen)) {
+			throw new InvalidQuery(at(base), `${at(base)} must be an object.`)
+		}
+		const kernel: { [field: string]: unknown } =
+			base === 'select' ? { id: true } : {}
+		const fields: Out[] =
+			base === 'select' ? [] : [...defaultShape(entry).fields]
+		// The relations' `totalCount`, each the count of its `where` (D-134).
+		const counts: { [field: string]: unknown } = {}
+		const model = entry.model.name
+		for (const [name, value] of Object.entries(chosen)) {
+			const where = `${at(base)}.${name}`
+			const virtual = readableVirtuals(entry).find((each) => each.name === name)
+			if (virtual !== undefined) {
+				if (value === false) continue
+				const read = this.#virtual(entry, virtual, value, where)
+				kernel[name] = read.read
+				// `include` reads a default virtual again, where it is.
+				const known = fields.findIndex((each) => each.name === name)
+				if (known === -1) fields.push(read.field)
+				else fields[known] = read.field
+				continue
+			}
+			const field = readable(entry).find((each) => each.name === name)
+			const isScalar =
+				field === undefined ? system.includes(name) : field.kind === 'scalar'
+			if (
+				(field === undefined && !isScalar) ||
+				(base === 'include' && isScalar)
+			) {
+				throw unknownKey(where, model)
+			}
+			if (value === false) continue
+			if (field === undefined || field.kind === 'scalar') {
+				if (value !== true) {
+					throw new InvalidQuery(where, `${where} must be a boolean.`)
+				}
+				kernel[name] = true
+				fields.push(scalar(entry, name))
+				continue
+			}
+			const target = entryOf(this.#api, field.target)
+			const given = value === true ? {} : value
+			if (!isArgs(given)) {
+				throw new InvalidQuery(where, `${where} must be an object.`)
+			}
+			if (field.kind === 'one') {
+				this.#keys(given, ['select', 'include'], where, model)
+				const nested = this.fields(target, given, where)
+				kernel[name] = nested.read
+				fields.push({ kind: 'one', name, shape: nested.shape })
+				continue
+			}
+			// A list has no count (D-134): `totalCount` is unknown there.
+			const pages = this.#api.pagination === 'connection'
+			const { totalCount, ...listed } = given
+			const many = this.list(target, pages ? listed : given, where)
+			const counted = pages && totalCount === true
+			if (
+				pages &&
+				totalCount !== undefined &&
+				typeof totalCount !== 'boolean'
+			) {
+				const key = `${where}.totalCount`
+				throw new InvalidQuery(key, `${key} must be true or false.`)
+			}
+			if (counted) {
+				const filter = many.read['where']
+				counts[name] = filter === undefined ? true : { where: filter }
+			}
+			kernel[name] = many.read
+			fields.push({
+				kind: 'many',
+				name,
+				shape: many.shape,
+				relay: many.relay,
+				// A count reads the rows it counts, however few the page returns.
+				size: counted ? Math.max(many.size, target.take) : many.size,
+				counted,
+			})
+		}
+		if (Object.keys(counts).length > 0) kernel['_count'] = { select: counts }
+		return { read: { [base]: kernel }, shape: { fields } }
+	}
+
+	/** A virtual's read: `true` or its input, a model's fields too (D-151). */
+	#virtual(
+		entry: Entry,
+		virtual: ExposedVirtual,
+		value: unknown,
+		where: string,
+	): { readonly read: unknown; readonly field: Out } {
+		const { name, output } = virtual
+		if (output.kind !== 'model') {
+			return { read: value, field: scalar(entry, name) }
+		}
+		if (value !== true && !isArgs(value)) {
+			throw new InvalidQuery(where, `${where} must be true or an object.`)
+		}
+		const { select, include, ...input } = value === true ? {} : value
+		const target = entryOf(this.#api, output.name)
+		const nested = this.fields(target, { select, include }, where)
+		const list = output.form === 'list'
+		return {
+			read: value === true ? true : { ...input, ...nested.read },
+			field: {
+				kind: 'returned',
+				name,
+				owner: `${entry.model.name}.${name}`,
+				shape: nested.shape,
+				list,
+				size: list ? this.#api.take : 1,
+			},
+		}
+	}
+
+	/** A list's arguments: its page, filter, order and fields. */
+	list(
+		entry: Entry,
+		args: Args,
+		path: string,
+	): Read & { readonly relay: Relay | undefined; readonly size: number } {
+		const at = (key: string): string => (path === '' ? key : `${path}.${key}`)
+		const paging = pageArgs(this.#api.pagination)
+		const keys = ['select', 'include', 'where', 'orderBy', ...paging]
+		this.#keys(args, keys, path, entry.model.name)
+		const page = pageOf(this.#api.pagination, entry, args, this.#master, at)
+		const { where, orderBy } = args
+		const nested = this.fields(entry, args, path)
+		const asked =
+			this.#api.pagination === 'list'
+				? args['take']
+				: (args['last'] ?? args['first'])
+		return {
+			read: {
+				...nested.read,
+				...page.read,
+				...filterOf(this.#api, entry, where, at('where')),
+				...(orderBy === undefined || orderBy === null ? {} : { orderBy }),
+			},
+			shape: { ...nested.shape, sorted: sortDepth(orderBy) },
+			relay: page.relay,
+			size: sizeOf(entry, asked),
+		}
+	}
+
+	#keys(args: Args, keys: readonly string[], path: string, model: string) {
+		for (const key of Object.keys(args)) {
+			if (!keys.includes(key)) {
+				throw unknownKey(path === '' ? key : `${path}.${key}`, model)
+			}
+		}
+	}
+}
+
+/** The reader of a request's `select` and `include`. */
+export const readerOf = (api: Api, master: boolean): Reader =>
+	new Reader(api, master)
+
+/** The levels of relations a row nests, the row counting one. */
+export function depthOf(shape: Shape): number {
+	let deepest = shape.sorted ?? 0
+	for (const field of shape.fields) {
+		if (field.kind !== 'scalar')
+			deepest = Math.max(deepest, depthOf(field.shape))
+	}
+	return 1 + deepest
+}
+
+/** The rows the relations of `times` rows may return, as D-107 counts them. */
+export function rowsBelow(shape: Shape, times: number): number {
+	let rows = 0
+	for (const field of shape.fields) {
+		if (field.kind === 'scalar') continue
+		const each = field.kind === 'one' ? times : times * field.size
+		rows += each
+		if (each > 0) rows += rowsBelow(field.shape, each)
+	}
+	return rows
+}
+
+/** The count the kernel read of a row's relation (D-134). */
+function countOf(row: Row, name: string): unknown {
+	const counts = row['_count']
+	return isArgs(counts) ? counts[name] : undefined
+}
+
+/** A virtual's rows of a model, at most `take` under a relation (D-109). */
+function returned(
+	field: Extract<Out, { readonly kind: 'returned' }>,
+	value: unknown,
+): unknown {
+	if (!field.list) {
+		const row = rowOf(value)
+		return row === undefined ? null : shaped(row, field.shape)
+	}
+	const rows = rowsOf(value)
+	const relates = field.shape.fields.some((each) => each.kind !== 'scalar')
+	if (rows.length > field.size && relates) {
+		throw new RangeError(
+			`${field.owner} returned ${rows.length} rows; a list counts take (${field.size}) rows, so it holds no more under a selected relation.`,
+		)
+	}
+	return rows.map((row) => shaped(row, field.shape))
+}
+
+/** A row as GraphQL returns it: its fields, its relations' pages. */
+export function shaped(row: Row, shape: Shape): { [field: string]: unknown } {
+	const out: { [field: string]: unknown } = {}
+	for (const field of shape.fields) {
+		const value = row[field.name]
+		if (field.kind === 'scalar') {
+			out[field.name] =
+				value === undefined || value === null
+					? null
+					: field.toJSON === undefined
+						? value
+						: field.toJSON(value)
+		} else if (field.kind === 'one') {
+			const target = rowOf(value)
+			out[field.name] =
+				target === undefined ? null : shaped(target, field.shape)
+		} else if (field.kind === 'returned') {
+			out[field.name] = returned(field, value)
+		} else if (value === undefined || value === null) {
+			// Absent when the field's read rule hides it (D-44).
+			out[field.name] = null
+		} else {
+			const rows = rowsOf(value)
+			const node = (each: Row) => shaped(each, field.shape)
+			if (field.relay === undefined) {
+				out[field.name] = rows.map(node)
+				continue
+			}
+			const page = connection(rows, field.relay, node)
+			out[field.name] = field.counted
+				? { ...page, totalCount: countOf(row, field.name) }
+				: page
+		}
+	}
+	return out
+}

package/src/functions.ts

@@ -0,0 +1,205 @@
+// The application's functions (D-129): a query at `GET /api/functions/:name`,
+// its input keys as query parameters, a mutation at `POST`, its body as its
+// input, each answered with the output GraphQL's field returns; a live query
+// over Server-Sent Events, with `Accept: text/event-stream` (D-154).
+import type { Routes } from '@ultimabase/http'
+import { clientOf, validate } from '@ultimabase/http'
+import type { Node } from '@ultimabase/http/internal'
+import { isNode, jsonSchemaOf, rowOf } from '@ultimabase/http/internal'
+import type { Caller, Client, ExposedFunction, ExposedOutput } from 'ultimabase'
+import { Refused } from 'ultimabase'
+import type { Api, Entry } from './entries.ts'
+import { checkName, entryOf } from './entries.ts'
+import { defaultShape, defaultVirtuals, shaped } from './fields.ts'
+import { acceptsNull, isText, resolved } from './json-schema.ts'
+import { anyBody } from './models.ts'
+import type { Accepted } from './params.ts'
+import { liveValue, wantsEvents } from './live.ts'
+import { paramsOf } from './params.ts'
+import type { Live } from './streams.ts'
+
+/** A function's key of `.with` (D-129): its route's name, or hidden. */
+export type RestFunctionWith = { readonly name?: string } | false
+
+const none: Accepted = { json: [], text: [] }
+
+/** A function REST routes, named, and its input's JSON Schema. */
+export type Routed = {
+	readonly fn: ExposedFunction<RestFunctionWith>
+	readonly owner: string
+	readonly name: string
+	readonly input: Node | undefined
+}
+
+/**
+ * A GET's parameters: an object input's keys, as GraphQL's arguments, or
+ * one `input`; a string as is, any other value as JSON.
+ */
+export function getParams(root: Node | undefined): {
+	readonly accepted: Accepted
+	readonly flat: boolean
+} {
+	if (root === undefined) return { accepted: none, flat: false }
+	const object = resolved(root, root)
+	const { properties } = object
+	if (object['type'] === 'object' && isNode(properties)) {
+		const keys = Object.entries(properties)
+		const text = (node: unknown) => isNode(node) && isText(node, root)
+		return {
+			accepted: {
+				json: keys.filter(([, node]) => !text(node)).map(([key]) => key),
+				text: keys.filter(([, node]) => text(node)).map(([key]) => key),
+			},
+			flat: true,
+		}
+	}
+	const as = isText(root, root) ? 'text' : 'json'
+	return { accepted: { ...none, [as]: ['input'] }, flat: false }
+}
+
+/** The rows of each model whose default virtuals are read again. */
+type Pending = Map<Entry, { id: string; copy: { [field: string]: unknown } }[]>
+
+const nonNull = (where: string): TypeError =>
+	new TypeError(`Cannot return null for non-nullable field ${where}.`)
+
+/** A value as GraphQL returns a function's output, a model's row its scalars. */
+function outputOf(
+	api: Api,
+	output: ExposedOutput,
+	value: unknown,
+	where: string,
+	pending: Pending,
+): unknown {
+	if (output.kind === 'schema') return value ?? null
+	if (value === null || value === undefined) {
+		if (output.form === 'nullable') return null
+		throw nonNull(where)
+	}
+	if (output.form === 'list') {
+		const items: readonly unknown[] = Array.isArray(value) ? value : []
+		const item = { ...output, form: 'one' } as const
+		return items.map((each) => outputOf(api, item, each, where, pending))
+	}
+	if (output.kind === 'model') {
+		const row = rowOf(value)
+		if (row === undefined) {
+			throw new TypeError(`A ${output.name} was returned without its id.`)
+		}
+		const entry = entryOf(api, output.name)
+		const copy = shaped(row, defaultShape(entry))
+		if (defaultVirtuals(entry).length > 0) {
+			pending.set(entry, [...(pending.get(entry) ?? []), { id: row.id, copy }])
+		}
+		return copy
+	}
+	const given: Node = isNode(value) ? value : {}
+	const { type } = output
+	return Object.fromEntries(
+		[...type.fields].map(([name, field]) => [
+			name,
+			outputOf(api, field, given[name], `${type.name}.${name}`, pending),
+		]),
+	)
+}
+
+/** The default virtuals of a function's rows, read by id as the caller (D-151). */
+async function withVirtuals(pending: Pending, as: Caller): Promise<void> {
+	for (const [entry, rows] of pending) {
+		const names = defaultVirtuals(entry)
+		const ids = [...new Set(rows.map(({ id }) => id))]
+		const found = await entry.exposed.queries.findMany(
+			{
+				where: { id: { in: ids } },
+				take: ids.length,
+				select: Object.fromEntries([
+					['id', true],
+					...names.map((name) => [name, true]),
+				]),
+			},
+			{ as },
+		)
+		const byId = new Map(found.map((row) => [row.id, row]))
+		for (const { id, copy } of rows) {
+			// A row the caller cannot read has none (D-109).
+			for (const name of names) copy[name] = byId.get(id)?.[name] ?? null
+		}
+	}
+}
+
+/** Each routed function under `${base}/functions` (D-109, D-113). */
+export function functionRoutes(
+	app: Routes,
+	api: Api,
+	functions: readonly ExposedFunction<RestFunctionWith>[],
+	base: string,
+	live: Live | undefined,
+): readonly Routed[] {
+	const routed: Routed[] = []
+	const owners = new Map<string, string>()
+	for (const fn of functions) {
+		if (fn.with === false) continue
+		// A plugin's function is named with its plugin (D-113).
+		const owner = fn.plugin === undefined ? fn.name : `${fn.plugin}.${fn.name}`
+		const name = checkName(fn.with?.name ?? fn.name, owner)
+		const other = owners.get(name)
+		if (other !== undefined) {
+			throw new Refused(
+				`${owner}: the route functions/${name} is ${other}'s; set .with({ rest: { name } }).`,
+			)
+		}
+		owners.set(name, owner)
+		// GraphQL types both sides from their exports, and refuses without (D-45).
+		const { input, output } = fn
+		const root =
+			input === undefined
+				? undefined
+				: jsonSchemaOf(input, 'input', `${owner}: input`)
+		routed.push({ fn, owner, name, input: root })
+		const nullable =
+			output?.kind === 'schema'
+				? acceptsNull(jsonSchemaOf(output.schema, 'output', `${owner}: output`))
+				: output?.form === 'nullable'
+		const answer = async (as: Caller, client: Client, sent: unknown) => {
+			const value = await fn.run(sent, { as }, client)
+			if (output === undefined) return true
+			if (value === undefined && !nullable) {
+				throw new TypeError(
+					`${fn.name} returned undefined; make its output .nullable() and return null.`,
+				)
+			}
+			const pending: Pending = new Map()
+			const answered = outputOf(api, output, value, fn.name, pending)
+			await withVirtuals(pending, as)
+			return answered
+		}
+		const path = `${base}/functions/${name}`
+		if (fn.query) {
+			const { accepted, flat } = getParams(root)
+			app.get(path, async (c) => {
+				const params = paramsOf(c.req.url, accepted)
+				const { client, sent } = clientOf(c)
+				const given = flat ? params : params['input']
+				if (wantsEvents(c.req.raw)) {
+					const compute = async (as: Caller) => answer(as, client, given)
+					return sent(await liveValue(live, owner, c.req.raw, compute))
+				}
+				return sent(c.json(await answer(c.var.caller, client, given)))
+			})
+		} else if (input === undefined) {
+			app.post(path, async (c) => {
+				paramsOf(c.req.url, none)
+				const { client, sent } = clientOf(c)
+				return sent(c.json(await answer(c.var.caller, client, undefined)))
+			})
+		} else {
+			app.post(path, validate('json', anyBody), async (c) => {
+				paramsOf(c.req.url, none)
+				const { client, sent } = clientOf(c)
+				const body: unknown = c.req.valid('json')
+				return sent(c.json(await answer(c.var.caller, client, body)))
+			})
+		}
+	}
+	return routed
+}

package/src/index.ts

@@ -0,0 +1,105 @@
+// `restPlugin()` (D-129): GraphQL's arguments and responses over resource
+// routes, mounted on the HTTP plugin and run as each request's caller; with
+// the realtime plugin, its live models' reads as Server-Sent Events (D-154).
+import type { Http } from '@ultimabase/http'
+import { httpPlugin, routes } from '@ultimabase/http'
+import type { Realtime } from '@ultimabase/realtime'
+import { realtimePlugin } from '@ultimabase/realtime'
+import type { PluginOf, PluginTypes, UseOf } from 'ultimabase'
+import { definePlugin } from 'ultimabase'
+import manifest from '../package.json' with { type: 'json' }
+import type { RestWith } from './entries.ts'
+import { entriesOf } from './entries.ts'
+import type { RestFunctionWith } from './functions.ts'
+import { functionRoutes } from './functions.ts'
+import { modelRoutes } from './models.ts'
+import { openapiOf } from './openapi.ts'
+
+export type { RestWith } from './entries.ts'
+export type { RestFunctionWith } from './functions.ts'
+
+/** What `restPlugin` takes: `graphqlPlugin`'s options, by name (D-129). */
+export interface RestOptions {
+	/** `/api` by default. */
+	readonly path?: string
+	/** Relay connections, or `take` and `skip` lists. */
+	readonly pagination?: 'connection' | 'list'
+	/** The rows a list returns when none is asked for; 100 by default (D-55). */
+	readonly take?: number
+	/** The rows a caller other than Master may ask for; 100 by default. */
+	readonly maxTake?: number
+	/** The deepest a request of a caller other than Master nests; 10 by default. */
+	readonly maxDepth?: number
+	/**
+	 * The most rows a request of a caller other than Master may return, each
+	 * list times the lists above it; 20 000 by default.
+	 */
+	readonly maxRows?: number
+}
+
+/** The REST plugin's types (D-57). */
+export interface Rest extends PluginTypes {
+	readonly name: 'rest'
+	readonly appOptions: RestOptions
+	readonly requires: Http
+	readonly optional: Realtime
+	readonly with: RestWith
+	readonly functionWith: RestFunctionWith
+}
+
+const baseOf = (options: RestOptions): string =>
+	(options.path ?? '/api').replace(/\/+$/, '')
+
+// What ends each running application's event streams, by its plugin's context.
+const streams = new WeakMap<object, Set<() => void>>()
+
+const plugin = definePlugin<Rest>({
+	name: 'rest',
+	manifest,
+	requires: { http: httpPlugin },
+	optional: { realtime: realtimePlugin },
+	api: (context) => {
+		const { plugins, models, functions, options, logger } = context
+		const { realtime } = plugins
+		const ends = new Set<() => void>()
+		streams.set(context, ends)
+		const live = realtime && {
+			realtime,
+			streams: ends,
+			kept: new Map(),
+			open: new Map(),
+			logger,
+		}
+		const api = {
+			entries: entriesOf(models, options),
+			pagination: options.pagination ?? 'connection',
+			take: options.take ?? 100,
+			maxDepth: options.maxDepth ?? 10,
+			maxRows: options.maxRows ?? 20_000,
+		}
+		const base = baseOf(options)
+		const app = routes()
+		const routed = functionRoutes(app, api, functions, base, live)
+		for (const entry of api.entries.values()) {
+			if (entry.visible) modelRoutes(app, api, entry, base, live)
+		}
+		// Built at startup, so a name clash refuses to start (D-144).
+		const document = openapiOf(api, routed, base, manifest.version)
+		app.get(`${base}/openapi.json`, (c) => c.json(document))
+		plugins.http.mount(app)
+	},
+	start: ({ plugins, options, logger }) => {
+		if (process.env['NODE_ENV'] === 'production') return
+		logger.info(`REST on ${plugins.http.url()}${baseOf(options)}.`)
+	},
+	// Before the HTTP plugin's stop, which waits for the streams to end.
+	stop: (context) => {
+		for (const end of streams.get(context) ?? []) end()
+	},
+})
+
+/** The application's REST API, served by `httpPlugin` (D-129). */
+export const restPlugin: PluginOf<Rest> = plugin.plugin
+
+/** A model's `.with({ rest })`, from its `use` (D-129). */
+export const rest: UseOf<Rest> = plugin.use