@ultimabase/rest 0.0.0-stage → 0.1.1

package/src/openapi-models.ts

@@ -0,0 +1,367 @@
+// A model's part of the document (D-144): its row, as GraphQL's type, its
+// pages, its `select` and `include`, and its six routes.
+import {
+	isNode,
+	jsonSchemaOf,
+	readable,
+	readableVirtuals,
+} from '@ultimabase/http/internal'
+import type { ExposedVirtual } from 'ultimabase'
+import type { Entry } from './entries.ts'
+import { entryOf, system } from './entries.ts'
+import type { Doc } from './openapi-inputs.ts'
+import {
+	dataOf,
+	orderByOf,
+	uniqueOf,
+	valueOf,
+	whereOf,
+} from './openapi-inputs.ts'
+import { outputOf } from './openapi-functions.ts'
+import type { Schema } from './openapi.ts'
+import {
+	arrayOf,
+	describe,
+	described,
+	failed,
+	hoisted,
+	json,
+	objectOf,
+	orNull,
+} from './openapi.ts'
+
+const upper = (name: string): string =>
+	name.charAt(0).toUpperCase() + name.slice(1)
+
+const text: Schema = { type: 'string' }
+const flag: Schema = { type: 'boolean' }
+
+/** `PageInfo`, `PostEdge` and a connection of its edges. */
+function connectionOf(doc: Doc, name: string, target: string): Schema {
+	const { components } = doc
+	return components.ref(name, () => {
+		const pageInfo = components.ref('PageInfo', () =>
+			objectOf(
+				{
+					hasNextPage: flag,
+					hasPreviousPage: flag,
+					startCursor: orNull(text),
+					endCursor: orNull(text),
+				},
+				['hasNextPage', 'hasPreviousPage', 'startCursor', 'endCursor'],
+			),
+		)
+		const edge = components.ref(`${target}Edge`, () =>
+			objectOf({ cursor: text, node: rowOf(doc, target) }, ['cursor', 'node']),
+		)
+		return objectOf(
+			{
+				edges: arrayOf(edge),
+				pageInfo,
+				totalCount: { type: 'integer', minimum: 0 },
+			},
+			['edges', 'pageInfo'],
+		)
+	})
+}
+
+/**
+ * `Post`: its default fields, which a row always holds without `select`,
+ * and its relations, which `include` adds. A field with a read rule may be
+ * `null`, a `one` relation always may (D-44).
+ */
+export function rowOf(doc: Doc, model: string): Schema {
+	return doc.components.ref(model, () => {
+		const entry = entryOf(doc.api, model)
+		const date: Schema = { type: 'string', format: 'date-time' }
+		const fields: { [name: string]: Schema } = {
+			id: text,
+			createdAt: date,
+			updatedAt: date,
+		}
+		const required = [...system]
+		for (const field of readable(entry)) {
+			const ruled = entry.exposed.readRules[field.name] === 'rule'
+			if (field.kind === 'scalar') {
+				const value = valueOf(doc, entry, field, 'output')
+				const empty = ruled || (field.optional && !field.list)
+				fields[field.name] = empty ? orNull(value) : value
+				required.push(field.name)
+			} else if (field.kind === 'one') {
+				fields[field.name] = orNull(rowOf(doc, field.target))
+			} else {
+				const many =
+					doc.api.pagination === 'connection'
+						? connectionOf(
+								doc,
+								`${model}${upper(field.name)}Connection`,
+								field.target,
+							)
+						: arrayOf(rowOf(doc, field.target))
+				fields[field.name] = ruled ? orNull(many) : many
+			}
+		}
+		// A virtual, computed: in the default row without an input (D-151).
+		for (const virtual of readableVirtuals(entry)) {
+			const { name } = virtual
+			const owner = `${model}.${name}`
+			const value = {
+				...outputOf(doc, virtual.output, owner, `${model}${upper(name)}Output`),
+				readOnly: true,
+			}
+			const ruled = entry.exposed.readRules[name] === 'rule'
+			fields[name] = describe(
+				ruled ? orNull(value) : value,
+				virtual.description,
+			)
+			if (virtual.default) required.push(name)
+		}
+		const { description, descriptions } = entry.exposed
+		return describe(
+			objectOf(described(fields, descriptions), required),
+			description,
+		)
+	})
+}
+
+/** A list's page arguments, within the model's `maxTake`. */
+function pageOf(doc: Doc, entry: Entry): { [name: string]: Schema } {
+	const rows: Schema = { type: 'integer', minimum: 0, maximum: entry.maxTake }
+	return doc.api.pagination === 'list'
+		? { take: rows, skip: { type: 'integer', minimum: 0 } }
+		: { first: rows, after: text, last: rows, before: text }
+}
+
+/** `PostSelect`, `PostInclude`, a relation's arguments (D-129). */
+function fieldsOf(doc: Doc, model: string, select: boolean): Schema {
+	const name = `${model}${select ? 'Select' : 'Include'}`
+	return doc.components.ref(name, () => {
+		const entry = entryOf(doc.api, model)
+		const fields: { [name: string]: Schema } = {}
+		if (select) for (const key of system) fields[key] = flag
+		for (const field of readable(entry)) {
+			if (field.kind === 'scalar') {
+				if (select) fields[field.name] = flag
+				continue
+			}
+			const args =
+				field.kind === 'one'
+					? argsOf(doc, field.target)
+					: listArgsOf(doc, field.target)
+			fields[field.name] = { anyOf: [flag, args] }
+		}
+		for (const virtual of readableVirtuals(entry)) {
+			fields[virtual.name] = virtualArgsOf(doc, model, virtual)
+		}
+		return objectOf(fields)
+	})
+}
+
+const either: Schema = { not: { required: ['select', 'include'] } }
+
+/**
+ * A virtual in `select` and `include` (D-151): `true` unless its input
+ * needs a property, its input, and a model's `select` or `include`.
+ */
+function virtualArgsOf(
+	doc: Doc,
+	model: string,
+	virtual: ExposedVirtual,
+): Schema {
+	const { name, input, output } = virtual
+	const owner = `${model}.${name}`
+	const base = `${model}${upper(name)}`
+	const node =
+		input === undefined
+			? undefined
+			: hoisted(
+					doc.components,
+					jsonSchemaOf(input, 'input', `${owner}: input`),
+					'input',
+					owner,
+					`${base}Input`,
+				)
+	const listed: unknown = node?.['required']
+	const required = Array.isArray(listed)
+		? listed.filter((key): key is string => typeof key === 'string')
+		: []
+	const needed = required.length > 0
+	const or = (schema: Schema) => (needed ? schema : { anyOf: [flag, schema] })
+	if (output.kind !== 'model') return node === undefined ? flag : or(node)
+	const properties = node?.['properties']
+	return or(
+		doc.components.ref(`${base}Args`, () => ({
+			...objectOf(
+				{
+					...(isNode(properties) ? properties : {}),
+					select: fieldsOf(doc, output.name, true),
+					include: fieldsOf(doc, output.name, false),
+				},
+				required,
+			),
+			...either,
+		})),
+	)
+}
+
+/** `PostArgs`: a `one` relation's `select` or `include`. */
+function argsOf(doc: Doc, model: string): Schema {
+	return doc.components.ref(`${model}Args`, () => ({
+		...objectOf({
+			select: fieldsOf(doc, model, true),
+			include: fieldsOf(doc, model, false),
+		}),
+		...either,
+	}))
+}
+
+/** `PostListArgs`: a `many` relation's, its page and filter too. */
+function listArgsOf(doc: Doc, model: string): Schema {
+	return doc.components.ref(`${model}ListArgs`, () => {
+		const entry = entryOf(doc.api, model)
+		const counts = doc.api.pagination === 'connection'
+		return {
+			...objectOf({
+				select: fieldsOf(doc, model, true),
+				include: fieldsOf(doc, model, false),
+				where: whereOf(doc, model),
+				orderBy: ordering(doc, model),
+				...pageOf(doc, entry),
+				...(counts && { totalCount: flag }),
+			}),
+			...either,
+		}
+	})
+}
+
+const ordering = (doc: Doc, model: string): Schema => {
+	const order = orderByOf(doc, model)
+	return { anyOf: [order, arrayOf(order)] }
+}
+
+/** A query parameter: JSON, or a string or a number as is. */
+const param = (name: string, schema: Schema, description?: string): Schema => {
+	const plain = schema['type'] === 'string' || schema['type'] === 'integer'
+	return {
+		name,
+		in: 'query',
+		...(description !== undefined && { description }),
+		...(plain || schema === flag ? { schema } : { content: json(schema) }),
+	}
+}
+
+function fieldParams(doc: Doc, model: string): readonly Schema[] {
+	return [
+		param(
+			'select',
+			fieldsOf(doc, model, true),
+			'The fields to return, and only those; not with include.',
+		),
+		param(
+			'include',
+			fieldsOf(doc, model, false),
+			'The relations to add to the default fields.',
+		),
+	]
+}
+
+const answer = (description: string, schema: Schema): Schema => ({
+	description,
+	content: json(schema),
+})
+
+const body = (schema: Schema): Schema => ({
+	required: true,
+	content: json(schema),
+})
+
+/** `/posts` and `/posts/{id}`, as REST serves them (D-129, D-142). */
+export function modelPaths(doc: Doc, entry: Entry): { [path: string]: Schema } {
+	const { components } = doc
+	const model = entry.model.name
+	const own = (id: string) => components.operation(id, model, 'plural')
+	const tags = [model]
+	const row = rowOf(doc, model)
+	const counts = doc.api.pagination === 'connection'
+	const list = counts
+		? connectionOf(doc, `${model}Connection`, model)
+		: arrayOf(row)
+	const pages = Object.entries(pageOf(doc, entry)).map(([name, schema]) =>
+		param(name, schema),
+	)
+	const one = model.charAt(0).toLowerCase() + model.slice(1)
+	const id = {
+		name: 'id',
+		in: 'path',
+		required: true,
+		schema: text,
+	}
+	return {
+		[`/${entry.plural}`]: {
+			get: {
+				operationId: own(entry.plural),
+				tags,
+				parameters: [
+					param('where', whereOf(doc, model)),
+					param('orderBy', ordering(doc, model)),
+					...fieldParams(doc, model),
+					...pages,
+					...(counts ? [param('totalCount', flag)] : []),
+				],
+				responses: { 200: answer(`The ${model} rows.`, list), ...failed },
+			},
+			post: {
+				operationId: own(`create${model}`),
+				tags,
+				parameters: fieldParams(doc, model),
+				requestBody: body(dataOf(doc, model, true)),
+				responses: { 201: answer(`The ${model} created.`, row), ...failed },
+			},
+			put: {
+				operationId: own(`upsert${model}`),
+				tags,
+				description: `Updates the ${model} where matches, or creates it.`,
+				parameters: fieldParams(doc, model),
+				requestBody: body(
+					objectOf(
+						{
+							where: uniqueOf(doc, model),
+							create: dataOf(doc, model, true),
+							update: dataOf(doc, model, false),
+						},
+						['where', 'create', 'update'],
+					),
+				),
+				responses: {
+					200: answer(`The ${model} updated.`, row),
+					201: answer(`The ${model} created.`, row),
+					...failed,
+				},
+			},
+		},
+		[`/${entry.plural}/{id}`]: {
+			parameters: [id],
+			get: {
+				operationId: own(one),
+				tags,
+				parameters: fieldParams(doc, model),
+				responses: { 200: answer(`The ${model}.`, row), ...failed },
+			},
+			patch: {
+				operationId: own(`update${model}`),
+				tags,
+				parameters: fieldParams(doc, model),
+				requestBody: body(dataOf(doc, model, false)),
+				responses: { 200: answer(`The ${model} updated.`, row), ...failed },
+			},
+			delete: {
+				operationId: own(`delete${model}`),
+				tags,
+				responses: {
+					200: answer(`The ${model} as it was, without relations.`, row),
+					...failed,
+				},
+			},
+		},
+	}
+}

package/src/openapi.ts

@@ -0,0 +1,204 @@
+// The OpenAPI 3.1 document (D-144): REST's routes and their JSON, typed as
+// GraphQL types them and named as it names them, seen as a caller other
+// than Master. Built once, at startup.
+import type { Node } from '@ultimabase/http/internal'
+import { isNode } from '@ultimabase/http/internal'
+import { Refused } from 'ultimabase'
+import type { Api } from './entries.ts'
+import type { Routed } from './functions.ts'
+import { functionPaths } from './openapi-functions.ts'
+import { modelPaths } from './openapi-models.ts'
+
+export type Schema = Node
+
+export const refTo = (name: string): Schema => ({
+	$ref: `#/components/schemas/${name}`,
+})
+
+/** `schema` or `null`; any value already takes `null`. */
+export const orNull = (schema: Schema): Schema =>
+	Object.keys(schema).length === 0
+		? schema
+		: { anyOf: [schema, { type: 'null' }] }
+
+export const arrayOf = (items: Schema): Schema => ({ type: 'array', items })
+
+/** `schema` with its `description`, when it has one (D-150). */
+export const describe = (
+	schema: Schema,
+	description: string | undefined,
+): Schema => (description === undefined ? schema : { ...schema, description })
+
+/** Each property with its field's `description` (D-150). */
+export const described = (
+	properties: { readonly [key: string]: Schema },
+	descriptions: { readonly [field: string]: string },
+): { readonly [key: string]: Schema } =>
+	Object.fromEntries(
+		Object.entries(properties).map(([key, schema]) => [
+			key,
+			describe(schema, descriptions[key]),
+		]),
+	)
+
+/** An object of these properties, and no other. */
+export const objectOf = (
+	properties: { readonly [key: string]: Schema },
+	required: readonly string[] = [],
+): Schema => ({
+	type: 'object',
+	properties,
+	...(required.length > 0 && { required }),
+	additionalProperties: false,
+})
+
+/** A JSON value under `name`, as a parameter or a body holds it. */
+export const json = (schema: Schema): Schema => ({
+	'application/json': { schema },
+})
+
+/** The answer of each failed request (D-106). */
+export const failed: Schema = {
+	default: {
+		description: 'The request failed.',
+		content: json(refTo('Error')),
+	},
+}
+
+const errorSchema: Schema = {
+	type: 'object',
+	properties: {
+		code: { type: 'string' },
+		message: { type: 'string' },
+		details: {},
+		correlationId: { type: 'string' },
+	},
+	required: ['code', 'message'],
+}
+
+type Known = { readonly owner: string; readonly key: string | undefined }
+
+const rest = 'REST'
+
+const clash = (owner: string, name: string): Refused =>
+	new Refused(`${owner}: REST names a schema ${name}; give yours another name.`)
+
+/** The document's named schemas, each name of one shape. */
+export class Components {
+	readonly schemas: { [name: string]: Schema } = {}
+	readonly #known = new Map<string, Known>()
+	readonly #operations = new Map<string, string>()
+
+	/** The schema REST names `name`, built on its first use. */
+	ref(name: string, build: () => Schema): Schema {
+		const known = this.#known.get(name)
+		if (known !== undefined && known.owner !== rest)
+			throw clash(known.owner, name)
+		if (known === undefined) {
+			this.#known.set(name, { owner: rest, key: undefined })
+			// Set first: a schema may refer to itself.
+			this.schemas[name] = {}
+			this.schemas[name] = build()
+		}
+		return refTo(name)
+	}
+
+	/** A schema a JSON Schema names, its id `name`. */
+	shared(name: string, schema: Schema, owner: string): Schema {
+		if (!/^[\w.-]+$/.test(name)) {
+			throw new Refused(
+				`${owner}: ${name} is not a schema name, which takes letters, digits, '.', '-' and '_'.`,
+			)
+		}
+		// One shape whatever it says of itself: its first description stays.
+		const { description: _, ...shape } = schema
+		const key = JSON.stringify(shape)
+		const known = this.#known.get(name)
+		if (known?.owner === rest) throw clash(owner, name)
+		if (known === undefined) {
+			this.#known.set(name, { owner, key })
+			this.schemas[name] = schema
+		} else if (known.key !== key) {
+			throw new Refused(
+				`${known.owner} and ${owner} give the schema ${name} two shapes; name each once.`,
+			)
+		}
+		return refTo(name)
+	}
+
+	/** An operation's id, which no other operation has. */
+	operation(id: string, owner: string, setting: 'plural' | 'name'): string {
+		const other = this.#operations.get(id)
+		if (other !== undefined) {
+			throw new Refused(
+				`${owner}: the operation ${id} is ${other}'s; set .with({ rest: { ${setting} } }).`,
+			)
+		}
+		this.#operations.set(id, owner)
+		return id
+	}
+}
+
+/**
+ * A JSON Schema with its `$defs` among the components, named by their ids,
+ * `Input`-suffixed on the input side as in GraphQL; `#` is `root`'s own.
+ */
+export function hoisted(
+	components: Components,
+	node: Node,
+	side: 'input' | 'output',
+	owner: string,
+	root: string,
+): Schema {
+	const suffix = side === 'input' ? 'Input' : ''
+	let recursive = false
+	const rewrite = (value: unknown): unknown => {
+		if (Array.isArray(value)) return value.map(rewrite)
+		if (!isNode(value)) return value
+		const ref = value['$ref']
+		if (ref === '#') {
+			recursive = true
+			return { ...value, $ref: refTo(root)['$ref'] }
+		}
+		if (typeof ref === 'string' && ref.startsWith('#/$defs/')) {
+			return { ...value, $ref: refTo(`${ref.slice(8)}${suffix}`)['$ref'] }
+		}
+		return Object.fromEntries(
+			Object.entries(value).map(([key, inner]) => [key, rewrite(inner)]),
+		)
+	}
+	const { $defs: defs, $schema: _, ...own } = node
+	if (isNode(defs)) {
+		for (const [id, def] of Object.entries(defs)) {
+			const schema = rewrite(def)
+			if (isNode(schema)) components.shared(`${id}${suffix}`, schema, owner)
+		}
+	}
+	const schema = rewrite(own)
+	const result = isNode(schema) ? schema : {}
+	return recursive ? components.shared(root, result, owner) : result
+}
+
+/** The document `GET {path}/openapi.json` answers. */
+export function openapiOf(
+	api: Api,
+	functions: readonly Routed[],
+	base: string,
+	version: string,
+): Schema {
+	const components = new Components()
+	components.ref('Error', () => errorSchema)
+	const doc = { components, api }
+	const paths: { [path: string]: Schema } = {}
+	for (const entry of api.entries.values()) {
+		if (entry.visible) Object.assign(paths, modelPaths(doc, entry))
+	}
+	Object.assign(paths, functionPaths(doc, functions))
+	return {
+		openapi: '3.1.0',
+		info: { title: 'UltimaBase REST API', version },
+		servers: [{ url: base === '' ? '/' : base }],
+		paths,
+		components: { schemas: components.schemas },
+	}
+}

package/src/params.ts

@@ -0,0 +1,39 @@
+// Query parameters (D-129): each the JSON of the GraphQL argument of its
+// name, a string argument as is.
+import { badInput } from '@ultimabase/http/internal'
+import type { Args } from './entries.ts'
+
+/** What a route reads from its query string. */
+export type Accepted = {
+	/** Parameters written as JSON. */
+	readonly json: readonly string[]
+	/** Parameters written as is. */
+	readonly text: readonly string[]
+}
+
+function parsed(name: string, value: string): unknown {
+	try {
+		return JSON.parse(value)
+	} catch (error) {
+		throw badInput(`The query parameter ${name} is not JSON.`, error)
+	}
+}
+
+/** The parameters of a request, each once and each one the route takes. */
+export function paramsOf(url: string, accepted: Accepted): Args {
+	const params: { [name: string]: unknown } = {}
+	const taken = [...accepted.json, ...accepted.text]
+	for (const [name, value] of new URL(url).searchParams) {
+		if (Object.hasOwn(params, name)) {
+			throw badInput(`The query parameter ${name} is given twice.`)
+		}
+		if (!taken.includes(name)) {
+			const takes = taken.length === 0 ? 'none' : taken.join(', ')
+			throw badInput(
+				`Unknown query parameter '${name}'; this route takes ${takes}.`,
+			)
+		}
+		params[name] = accepted.text.includes(name) ? value : parsed(name, value)
+	}
+	return params
+}

package/src/sse.ts

@@ -0,0 +1,79 @@
+// A Server-Sent Events body (D-154): each event written whole, gzipped and
+// flushed after each one when the client accepts gzip, and a comment every
+// 12 s so neither a proxy nor the client takes the stream for dead.
+import type { Transform } from 'node:stream'
+import { PassThrough, Readable } from 'node:stream'
+import { constants, createGzip } from 'node:zlib'
+
+/** A client's buffer past which its changes are dropped. */
+const maxBuffer = 1024 * 1024
+/** Between two comments on a quiet stream. */
+const keepAlive = 12_000
+
+/** An open stream of events, and the response that sends it. */
+export type Events = {
+	readonly response: Response
+	/** Writes one event; `id` is the revision it carries. */
+	readonly send: (event: string, data: unknown, id?: number) => void
+	/** Whether the client's buffer holds more than it may. */
+	readonly full: () => boolean
+	/** Runs `then` once the client took what it was sent. */
+	readonly drained: (then: () => void) => void
+	/** Ends the stream. */
+	readonly end: () => void
+}
+
+/** Whether `header` (an `Accept-Encoding`) takes gzip. */
+export function acceptsGzip(header: string | null): boolean {
+	for (const part of (header ?? '').split(',')) {
+		const [name = '', ...params] = part.split(';').map((each) => each.trim())
+		if (name.toLowerCase() !== 'gzip') continue
+		const q = params.find((param) => param.startsWith('q='))
+		return q === undefined || Number(q.slice(2)) > 0
+	}
+	return false
+}
+
+/** A stream of events to `request`'s client; `closed` runs once it ends. */
+export function eventsTo(request: Request, closed: () => void): Events {
+	const gzip = acceptsGzip(request.headers.get('accept-encoding'))
+	const zipped = gzip ? createGzip() : undefined
+	const stream: Transform = zipped ?? new PassThrough()
+	const write = (text: string) => {
+		if (stream.writableEnded || stream.destroyed) return
+		stream.write(text)
+		zipped?.flush(constants.Z_SYNC_FLUSH)
+	}
+	const beating = setInterval(() => write(':\n\n'), keepAlive)
+	beating.unref()
+	stream.once('close', () => {
+		clearInterval(beating)
+		closed()
+	})
+	const end = () => {
+		clearInterval(beating)
+		stream.end()
+	}
+	request.signal.addEventListener('abort', () => stream.destroy())
+	const headers: Record<string, string> = {
+		'content-type': 'text/event-stream; charset=utf-8',
+		'cache-control': 'no-store',
+		// nginx buffers a response unless told not to.
+		'x-accel-buffering': 'no',
+		...(gzip ? { 'content-encoding': 'gzip', vary: 'Accept-Encoding' } : {}),
+	}
+	const body = Readable.toWeb(stream)
+	return {
+		response: new Response(body, { headers }),
+		send: (event, data, id) => {
+			const line = id === undefined ? '' : `id: ${id}\n`
+			write(`${line}event: ${event}\ndata: ${JSON.stringify(data)}\n\n`)
+		},
+		full: () => stream.writableLength + stream.readableLength > maxBuffer,
+		drained: (then) => {
+			if (stream.writableNeedDrain) stream.once('drain', then)
+			else then()
+		},
+		end,
+	}
+}