@ultimabase/rest 0.0.0-stage → 0.1.1

package/src/json-schema.ts

@@ -0,0 +1,51 @@
+// A function's standard JSON Schema exports (D-45), read as GraphQL reads
+// them: its input's tells a GET's string parameters from its JSON ones, its
+// output's whether it accepts `null`.
+import type { Node } from '@ultimabase/http/internal'
+import { isNode } from '@ultimabase/http/internal'
+
+/** The node a `$ref` names among the root's `$defs`, or the node itself. */
+export function resolved(node: Node, root: Node): Node {
+	const ref = node['$ref']
+	if (typeof ref !== 'string' || !ref.startsWith('#/$defs/')) return node
+	const defs = isNode(root['$defs']) ? root['$defs'] : {}
+	const found = defs[ref.slice(8)]
+	return isNode(found) ? found : node
+}
+
+/** A value only ever a string, which a query parameter holds as is. */
+export function isText(node: Node, root: Node): boolean {
+	const own = resolved(node, root)
+	const { type } = own
+	if (type === 'string') return true
+	// `['string', 'null']`, a nullable string.
+	if (Array.isArray(type)) {
+		return (
+			type.includes('string') &&
+			type.every((each) => each === 'string' || each === 'null')
+		)
+	}
+	if (typeof own['const'] === 'string') return true
+	const values = own['enum']
+	if (Array.isArray(values)) {
+		return (
+			values.length > 0 && values.every((value) => typeof value === 'string')
+		)
+	}
+	const variants = own['anyOf'] ?? own['oneOf']
+	if (!Array.isArray(variants)) return false
+	const kept = variants
+		.filter(isNode)
+		.filter((each) => resolved(each, root)['type'] !== 'null')
+	return kept.length > 0 && kept.every((each) => isText(each, root))
+}
+
+/** A node that accepts `null`, as GraphQL types a nullable output. */
+export function acceptsNull(node: Node): boolean {
+	const variants: unknown = node['anyOf'] ?? node['oneOf']
+	if (Array.isArray(variants)) {
+		return variants.some((each) => isNode(each) && each['type'] === 'null')
+	}
+	const { type } = node
+	return Array.isArray(type) ? type.includes('null') : type === 'null'
+}

package/src/limits.ts

@@ -0,0 +1,28 @@
+// The limits of a request of a caller other than Master (D-107): how deep it
+// nests and, unless it is live (D-154), how many rows it may return.
+import { badInput } from '@ultimabase/http/internal'
+import type { Caller } from 'ultimabase'
+import type { Api } from './entries.ts'
+import type { Shape } from './fields.ts'
+import { depthOf, rowsBelow } from './fields.ts'
+
+/** Refuses a request above the limits; `rows` absent checks its depth only. */
+export function bounded(
+	api: Api,
+	caller: Caller,
+	shape: Shape,
+	rows?: number,
+): void {
+	if (caller.kind === 'master') return
+	const depth = depthOf(shape)
+	if (depth > api.maxDepth) {
+		throw badInput(
+			`The request is nested ${depth} levels deep, its orderBy included; the most is ${api.maxDepth}.`,
+		)
+	}
+	if (rows === undefined || rows + rowsBelow(shape, rows) <= api.maxRows) return
+	const fewer = api.pagination === 'list' ? 'take' : 'first or last'
+	throw badInput(
+		`The request asks for more than ${api.maxRows.toLocaleString('en-US')} rows. Ask for fewer with ${fewer}.`,
+	)
+}

package/src/live.ts

@@ -0,0 +1,223 @@
+// A live model's list and row over Server-Sent Events (D-154): the read's
+// JSON as `event: data`, then what changed as `event: live`, the JSON GraphQL
+// sends under `extensions.live`; in page mode, `event: data` each time. A
+// list first sends the token that resumes it, as `event: resume`. A live
+// function sends its whole result as `event: data` each time it changes.
+import { randomUUID } from 'node:crypto'
+import { applied, badInput, connection, run } from '@ultimabase/http/internal'
+import type { Caller, Logger, Row } from 'ultimabase'
+import { PublicError } from 'ultimabase'
+import type { Api, Args, Entry } from './entries.ts'
+import type { Shape } from './fields.ts'
+import { readerOf, shaped } from './fields.ts'
+import { bounded } from './limits.ts'
+import { paramsOf } from './params.ts'
+import type { Live, Sink, Write } from './streams.ts'
+import { streamed } from './streams.ts'
+
+/** Whether `request` asks for a stream of events. */
+export const wantsEvents = (request: Request): boolean =>
+	(request.headers.get('accept') ?? '').includes('text/event-stream')
+
+/** The engine, unless `entry`'s model is not live. */
+function liveOf(live: Live | undefined, entry: Entry): Live {
+	const { name } = entry.model
+	if (live !== undefined && live.realtime.live(name)) return live
+	throw badInput(`${name} is not live: list realtime() in its use.`)
+}
+
+const fromTop = { size: undefined, backward: false }
+const paging = new Set(['take', 'skip', 'cursor'])
+
+/** What a live list's messages write, with what it sent so far. */
+function listWriter(
+	events: Sink,
+	connected: boolean,
+	page: boolean,
+	counted: boolean,
+	shape: Shape,
+): Write {
+	const node = (row: Row) => shaped(row, shape)
+	let window: readonly Row[] = []
+	let hasMore = false
+	let count: number | undefined
+	let pageInfo = ''
+	const infoOf = () => {
+		const { pageInfo: info } = connection(window, fromTop, () => null)
+		return { ...info, hasNextPage: hasMore }
+	}
+	const data = (revision: number) => {
+		const info = infoOf()
+		pageInfo = JSON.stringify(info)
+		const { edges } = connection(window, fromTop, node)
+		const body = connected
+			? { edges, pageInfo: info, ...(counted && { totalCount: count }) }
+			: window.map(node)
+		events.send('data', body, revision)
+	}
+	return (message) => {
+		const { revision } = message
+		hasMore = message.hasMore ?? hasMore
+		count = message.totalCount ?? count
+		if (message.kind === 'reset' || page) {
+			window =
+				message.kind === 'reset'
+					? message.rows
+					: applied(window, message.changes, (row) => row)
+			return data(revision)
+		}
+		const { changes } = message
+		window = applied(window, changes, ({ id }) => ({ id }))
+		const live: { [key: string]: unknown } = {
+			revision,
+			changes: changes.map((change) => {
+				if ('remove' in change) return change
+				const [edge] = connection([change.upsert], fromTop, node).edges
+				return {
+					upsert: connected ? edge : node(change.upsert),
+					after: change.after,
+				}
+			}),
+		}
+		if (counted && message.totalCount !== undefined) {
+			live['totalCount'] = message.totalCount
+		}
+		const info = infoOf()
+		if (connected && JSON.stringify(info) !== pageInfo) {
+			pageInfo = JSON.stringify(info)
+			live['pageInfo'] = info
+		}
+		events.send('live', live, revision)
+	}
+}
+
+/** `GET /api/posts` with `Accept: text/event-stream`: a live window. */
+export async function liveList(
+	api: Api,
+	live: Live | undefined,
+	entry: Entry,
+	caller: Caller,
+	request: Request,
+): Promise<Response> {
+	const followed = liveOf(live, entry)
+	const connected = api.pagination === 'connection'
+	const arg = connected ? 'first' : 'take'
+	const params = paramsOf(request.url, {
+		json: [
+			'where',
+			'orderBy',
+			'select',
+			'include',
+			arg,
+			...(connected ? ['totalCount'] : []),
+		],
+		text: ['mode', 'resume'],
+	})
+	const { totalCount, mode, resume, ...args } = params
+	if (totalCount !== undefined && typeof totalCount !== 'boolean') {
+		throw badInput('totalCount must be true or false.')
+	}
+	if (mode !== undefined && mode !== 'page') {
+		throw badInput('mode must be page.')
+	}
+	const { name } = entry.model
+	const read = await run(async () =>
+		readerOf(api, caller.kind === 'master').list(entry, args, ''),
+	)
+	const asked = args[arg]
+	const rows = typeof asked === 'number' ? asked : entry.take
+	const page = mode === 'page'
+	if (page && rows > entry.maxTake) {
+		throw badInput(
+			`${arg} is at most ${entry.maxTake} on ${name} in page mode.`,
+		)
+	}
+	// A live list is bounded by maxLive, not by maxRows (D-154).
+	bounded(api, caller, read.shape)
+	// The window starts at the top of its order and holds `first` rows.
+	const listed: Args = {
+		...Object.fromEntries(
+			Object.entries(read.read).filter(([key]) => !paging.has(key)),
+		),
+		first: rows,
+		totalCount: totalCount === true,
+	}
+	return streamed(
+		followed,
+		request,
+		read.shape,
+		async (viewer, send) => viewer.list(name, listed, send),
+		{
+			write: (events) =>
+				listWriter(events, connected, page, totalCount === true, read.shape),
+			signature: JSON.stringify([name, page, { ...listed, first: undefined }]),
+			first: rows,
+			resume: typeof resume === 'string' ? resume : undefined,
+		},
+	)
+}
+
+/** `GET /api/posts/:id` with `Accept: text/event-stream`: a live row. */
+export async function liveRow(
+	api: Api,
+	live: Live | undefined,
+	entry: Entry,
+	caller: Caller,
+	request: Request,
+	id: string,
+): Promise<Response> {
+	const followed = liveOf(live, entry)
+	const params = paramsOf(request.url, {
+		json: ['select', 'include'],
+		// A live row is not resumed: it starts afresh.
+		text: ['resume'],
+	})
+	const { resume: _, ...fields } = params
+	const read = await run(async () =>
+		readerOf(api, caller.kind === 'master').fields(entry, fields, ''),
+	)
+	bounded(api, caller, read.shape)
+	const args = { ...read.read, where: { id } }
+	return streamed(followed, request, read.shape, async (viewer, send) =>
+		viewer.row(entry.model.name, args, send),
+	)
+}
+
+/** A live function's error as its client gets it: public as is, else masked and logged. */
+function failure(error: unknown, logger: Logger): unknown {
+	if (error instanceof PublicError) {
+		const { code, message, details } = error
+		return details === undefined
+			? { code, message }
+			: { code, message, details }
+	}
+	const correlationId = randomUUID()
+	logger.error({ correlationId, err: error }, 'A live function failed.')
+	return { code: 'INTERNAL', message: 'Internal error.', correlationId }
+}
+
+const noShape: Shape = { fields: [] }
+
+/**
+ * `GET /api/functions/:name` with `Accept: text/event-stream`: the result
+ * `compute` gives as the subscriber, again each time it changes.
+ */
+export async function liveValue(
+	live: Live | undefined,
+	owner: string,
+	request: Request,
+	compute: (caller: Caller) => Promise<unknown>,
+): Promise<Response> {
+	if (live === undefined || !live.realtime.liveFunction(owner)) {
+		throw badInput(`${owner} is not live: list realtime() in its use.`)
+	}
+	const { logger } = live
+	return streamed(live, request, noShape, async (viewer, send) =>
+		viewer.value(owner, compute, (message) => {
+			if (message.kind !== 'closed' || message.error === undefined) {
+				return send(message)
+			}
+			send({ kind: 'closed', error: failure(message.error, logger) })
+		}),
+	)
+}

package/src/models.ts

@@ -0,0 +1,180 @@
+// A model's routes (D-129): its list, its row, and its four writes, an
+// upsert included (D-142), each one kernel query run as the request's
+// caller, answered with the JSON the matching GraphQL field returns.
+import type { Routes, StandardSchema } from '@ultimabase/http'
+import { validate } from '@ultimabase/http'
+import { badInput, connection, pageArgs, run } from '@ultimabase/http/internal'
+import type { Caller, Row } from 'ultimabase'
+import { InvalidQuery, PublicError } from 'ultimabase'
+import type { Api, Args, Entry } from './entries.ts'
+import type { Read } from './fields.ts'
+import { defaultShape, filterOf, readerOf, shaped } from './fields.ts'
+import { bounded } from './limits.ts'
+import type { Live } from './streams.ts'
+import { liveList, liveRow, wantsEvents } from './live.ts'
+import type { Accepted } from './params.ts'
+import { paramsOf } from './params.ts'
+import { dataOf, isArgs, whereOf } from './values.ts'
+
+/** Any JSON body: the kernel checks the data (D-129). */
+export const anyBody: StandardSchema = {
+	'~standard': { validate: (value) => ({ value }) },
+}
+
+const fieldParams: Accepted = { json: ['select', 'include'], text: [] }
+
+/** The kernel read of one row's `select` or `include`. */
+function oneRead(api: Api, entry: Entry, caller: Caller, url: string): Read {
+	const params = paramsOf(url, fieldParams)
+	const read = readerOf(api, caller.kind === 'master').fields(entry, params, '')
+	bounded(api, caller, read.shape, 1)
+	return read
+}
+
+/** `GET /api/posts`: a connection, or a list with `pagination: 'list'`. */
+async function list(
+	api: Api,
+	entry: Entry,
+	caller: Caller,
+	url: string,
+): Promise<unknown> {
+	const counts = api.pagination === 'connection'
+	const params = paramsOf(url, {
+		json: [
+			'where',
+			'orderBy',
+			'select',
+			'include',
+			...pageArgs(api.pagination).filter(
+				(arg) => arg !== 'after' && arg !== 'before',
+			),
+			...(counts ? ['totalCount'] : []),
+		],
+		text: counts ? ['after', 'before'] : [],
+	})
+	const { totalCount, ...args } = params
+	if (totalCount !== undefined && typeof totalCount !== 'boolean') {
+		throw badInput('totalCount must be true or false.')
+	}
+	const read = readerOf(api, caller.kind === 'master').list(entry, args, '')
+	// A count reads the rows it counts, however few the page returns.
+	const size = totalCount === true ? Math.max(read.size, entry.take) : read.size
+	bounded(api, caller, read.shape, size)
+	const { queries } = entry.exposed
+	const rows = await queries.findMany(read.read, { as: caller })
+	const node = (row: Row) => shaped(row, read.shape)
+	if (read.relay === undefined) return rows.map(node)
+	const page = connection(rows, read.relay, node)
+	if (totalCount !== true) return page
+	const where = filterOf(api, entry, args['where'], 'where')
+	return { ...page, totalCount: await queries.count(where, { as: caller }) }
+}
+
+const notFound = (entry: Entry): Error =>
+	new PublicError('NOT_FOUND', `No ${entry.model.name} matches.`)
+
+const written = (api: Api, entry: Entry, body: unknown): unknown =>
+	isArgs(body) ? dataOf(api, entry.model.name, body, 'data') : body
+
+const upsertKeys = new Set(['where', 'create', 'update'])
+
+/** An upsert's body, its dates read; the kernel checks the rest (D-142). */
+function upserting(api: Api, entry: Entry, body: unknown): Args {
+	const { name } = entry.model
+	if (!isArgs(body))
+		throw new InvalidQuery('body', 'The body must be an object.')
+	const read: { [key: string]: unknown } = {}
+	for (const [key, value] of Object.entries(body)) {
+		if (!upsertKeys.has(key)) {
+			throw new InvalidQuery(key, `Unknown key '${key}' on ${name}.`)
+		}
+		if (!isArgs(value)) read[key] = value
+		else if (key === 'where') read[key] = whereOf(api, name, value, key)
+		else read[key] = dataOf(api, name, value, key)
+	}
+	return read
+}
+
+/** Each route of a visible model, under `base`; its reads live with `live`. */
+export function modelRoutes(
+	app: Routes,
+	api: Api,
+	entry: Entry,
+	base: string,
+	live: Live | undefined,
+): void {
+	const path = `${base}/${entry.plural}`
+	const { queries } = entry.exposed
+	app.get(path, async (c) => {
+		const { caller } = c.var
+		if (wantsEvents(c.req.raw)) {
+			return liveList(api, live, entry, caller, c.req.raw)
+		}
+		return c.json(await run(() => list(api, entry, caller, c.req.url)))
+	})
+	/** The row `query` returns, shaped as `url` asks. */
+	const one = async (
+		caller: Caller,
+		url: string,
+		query: (read: Args, as: { as: Caller }) => Promise<Row | null>,
+	): Promise<unknown> => {
+		const { row, shape } = await run(async () => {
+			const fields = oneRead(api, entry, caller, url)
+			return { row: await query(fields.read, { as: caller }), ...fields }
+		})
+		if (row === null) throw notFound(entry)
+		return shaped(row, shape)
+	}
+	app.get(`${path}/:id`, async (c) => {
+		const { caller } = c.var
+		const id = c.req.param('id')
+		if (wantsEvents(c.req.raw)) {
+			return liveRow(api, live, entry, caller, c.req.raw, id)
+		}
+		return c.json(
+			await one(caller, c.req.url, async (read, as) =>
+				queries.findUnique({ ...read, where: { id } }, as),
+			),
+		)
+	})
+	app.post(path, validate('json', anyBody), async (c) => {
+		const body: unknown = c.req.valid('json')
+		const row = await one(c.var.caller, c.req.url, async (read, as) =>
+			queries.create({ ...read, data: written(api, entry, body) }, as),
+		)
+		return c.json(row, 201)
+	})
+	// 201 when it created the row, 200 when it updated it (D-142).
+	app.put(path, validate('json', anyBody), async (c) => {
+		const body: unknown = c.req.valid('json')
+		const { caller } = c.var
+		const { row, created, shape } = await run(async () => {
+			const fields = oneRead(api, entry, caller, c.req.url)
+			const args = { ...fields.read, ...upserting(api, entry, body) }
+			const upserted = await entry.exposed.upsert(args, { as: caller })
+			return { ...upserted, shape: fields.shape }
+		})
+		return c.json(shaped(row, shape), created ? 201 : 200)
+	})
+	app.patch(`${path}/:id`, validate('json', anyBody), async (c) => {
+		const body: unknown = c.req.valid('json')
+		const where = { id: c.req.param('id') }
+		return c.json(
+			await one(c.var.caller, c.req.url, async (read, as) =>
+				queries.update({ ...read, where, data: written(api, entry, body) }, as),
+			),
+		)
+	})
+	app.delete(`${path}/:id`, async (c) => {
+		const { caller } = c.var
+		const row = await run(async () => {
+			paramsOf(c.req.url, { json: [], text: [] })
+			return queries.delete(
+				{ where: { id: c.req.param('id') } },
+				{ as: caller },
+			)
+		})
+		// As it was, without its relations (D-102).
+		return c.json(shaped(row, defaultShape(entry)))
+	})
+}

package/src/openapi-functions.ts

@@ -0,0 +1,127 @@
+// The functions' part of the document (D-144): each one's route, its
+// parameters or body, and its output, as GraphQL names their types.
+import type { Node } from '@ultimabase/http/internal'
+import { isNode, jsonSchemaOf } from '@ultimabase/http/internal'
+import type { ExposedOutput, ExposedType } from 'ultimabase'
+import type { Routed } from './functions.ts'
+import { getParams } from './functions.ts'
+import type { Doc } from './openapi-inputs.ts'
+import { rowOf } from './openapi-models.ts'
+import type { Schema } from './openapi.ts'
+import {
+	arrayOf,
+	describe,
+	failed,
+	hoisted,
+	json,
+	objectOf,
+	orNull,
+} from './openapi.ts'
+
+const upper = (name: string): string =>
+	name.charAt(0).toUpperCase() + name.slice(1)
+
+const prefix = '#/components/schemas/'
+
+/** A schema, or the component it refers to. */
+function resolve(doc: Doc, schema: Schema): Schema {
+	const ref = schema['$ref']
+	if (typeof ref !== 'string' || !ref.startsWith(prefix)) return schema
+	return doc.components.schemas[ref.slice(prefix.length)] ?? {}
+}
+
+/** A `defineType`, each of its fields always given (D-109). */
+function typeOf(doc: Doc, type: ExposedType, owner: string): Schema {
+	return doc.components.ref(type.name, () =>
+		describe(
+			objectOf(
+				Object.fromEntries(
+					[...type.fields].map(([name, field]) => [
+						name,
+						outputOf(doc, field, owner, `${type.name}${upper(name)}`),
+					]),
+				),
+				[...type.fields.keys()],
+			),
+			type.description,
+		),
+	)
+}
+
+/** A model, a `defineType` or a schema, held as `form` says (D-109). */
+export function outputOf(
+	doc: Doc,
+	output: ExposedOutput,
+	owner: string,
+	root: string,
+): Schema {
+	if (output.kind === 'schema') {
+		const node = jsonSchemaOf(output.schema, 'output', `${owner}: output`)
+		return hoisted(doc.components, node, 'output', owner, root)
+	}
+	const one =
+		output.kind === 'model'
+			? rowOf(doc, output.name)
+			: typeOf(doc, output.type, owner)
+	if (output.form === 'list') return arrayOf(one)
+	return output.form === 'nullable' ? orNull(one) : one
+}
+
+/** A GET's parameters, as `getParams` reads them. */
+function paramsOf(doc: Doc, input: Node, schema: Schema): readonly Schema[] {
+	const { accepted, flat } = getParams(input)
+	if (!flat) {
+		const as = accepted.text.length > 0 ? { schema } : { content: json(schema) }
+		return [{ name: 'input', in: 'query', required: true, ...as }]
+	}
+	const object = resolve(doc, schema)
+	const properties = isNode(object['properties']) ? object['properties'] : {}
+	const required = Array.isArray(object['required']) ? object['required'] : []
+	return Object.entries(properties).map(([name, property]) => ({
+		name,
+		in: 'query',
+		...(required.includes(name) && { required: true }),
+		...(accepted.text.includes(name)
+			? { schema: property }
+			: { content: json(isNode(property) ? property : {}) }),
+	}))
+}
+
+/** `/functions/{name}`, a query over GET, a mutation over POST (D-109). */
+export function functionPaths(
+	doc: Doc,
+	functions: readonly Routed[],
+): { [path: string]: Schema } {
+	const paths: { [path: string]: Schema } = {}
+	for (const { fn, owner, name, input } of functions) {
+		const base = upper(name)
+		const given =
+			input === undefined
+				? undefined
+				: hoisted(doc.components, input, 'input', owner, `${base}Input`)
+		const output =
+			fn.output === undefined
+				? { const: true }
+				: outputOf(doc, fn.output, owner, `${base}Output`)
+		const operation = {
+			operationId: doc.components.operation(name, owner, 'name'),
+			tags: ['functions'],
+			...(fn.description !== undefined && { description: fn.description }),
+			...(fn.query && given !== undefined && input !== undefined
+				? { parameters: paramsOf(doc, input, given) }
+				: {}),
+			...(!fn.query &&
+				given !== undefined && {
+					requestBody: { required: true, content: json(given) },
+				}),
+			responses: {
+				200: { description: `What ${name} returns.`, content: json(output) },
+				...failed,
+			},
+		}
+		paths[`/functions/${name}`] = fn.query
+			? { get: operation }
+			: { post: operation }
+	}
+	return paths
+}