@ultimabase/graphql 0.0.0-stage → 0.1.0

package/src/functions.ts

@@ -0,0 +1,291 @@
+// The application's functions (D-109): a query under Query, a mutation
+// under Mutation, each run as the request's caller with the arguments the
+// client sent; a live query also under Subscription (D-154).
+import type {
+	GraphQLFieldConfig,
+	GraphQLNamedType,
+	GraphQLOutputType,
+	GraphQLResolveInfo,
+} from 'graphql'
+import {
+	GraphQLBoolean,
+	GraphQLList,
+	GraphQLNonNull,
+	GraphQLObjectType,
+} from 'graphql'
+import { readableVirtuals } from '@ultimabase/http/internal'
+import type {
+	ExposedFunction,
+	ExposedOutput,
+	ExposedType,
+	ExposedVirtual,
+} from 'ultimabase'
+import { Refused } from 'ultimabase'
+import type { Path } from './data.ts'
+import type { DataTypes } from './data-types.ts'
+import { checkName, inputArgs, outputData } from './data.ts'
+import { upper } from './names.ts'
+import { isMaster, objectType } from './outputs.ts'
+import { selectOf } from './select.ts'
+import { followed } from './subscriptions.ts'
+import type { Args, Context, Registry } from './registry.ts'
+import { as } from './registry.ts'
+import { reread } from './reread.ts'
+import { plain } from './scalars.ts'
+import type { Read } from './rows.ts'
+
+/** A function's key of `.with` (D-109): its field's name, or hidden. */
+export type GraphqlFunctionWith = { readonly name?: string } | false
+
+export type Field = GraphQLFieldConfig<unknown, Context, Args>
+
+/** A function's root field, and the function that gives it. */
+export type RootField = {
+	readonly query: boolean
+	readonly name: string
+	readonly owner: string
+	readonly field: Field
+}
+
+const at = (owner: string, name: string, place: string): Path => ({
+	owner,
+	name,
+	suffix: '',
+	at: place,
+})
+
+/** Whether a model's rows, as `info` selects them, read a relation. */
+function relates(
+	registry: Registry,
+	model: string,
+	info: GraphQLResolveInfo,
+	master: boolean,
+): boolean {
+	const type = objectType(registry, model)
+	const select = selectOf(registry, info, type, info.fieldNodes, master)
+	return Object.values(select).some((read) => read !== true)
+}
+
+class Builder {
+	readonly #types = new Map<string, GraphQLObjectType>()
+	readonly #registry: Registry
+	readonly #data: DataTypes
+	readonly #take: number
+	/** What each field reads, by type then field, for the row budget. */
+	readonly reads = new Map<string, Map<string, Read>>()
+	/** Each named type, and the first function to give it. */
+	readonly owners: Map<string, string>
+
+	constructor(registry: Registry, take: number) {
+		this.#registry = registry
+		this.#data = registry.data
+		this.owners = this.#data.owners
+		this.#take = take
+	}
+
+	/** A model or a type is non-null unless `.nullable()`; a list too. */
+	output(
+		output: ExposedOutput,
+		path: Path,
+		parent: string,
+		field: string,
+	): GraphQLOutputType {
+		if (output.kind === 'schema') {
+			const { type, nullable } = outputData(output.schema, path, this.#data)
+			return nullable ? type : new GraphQLNonNull(type)
+		}
+		const reads = this.reads.get(parent) ?? new Map<string, Read>()
+		this.reads.set(parent, reads)
+		const list = output.form === 'list'
+		reads.set(
+			field,
+			list ? { kind: 'list', size: this.#take } : { kind: 'one' },
+		)
+		const named =
+			output.kind === 'model'
+				? objectType(this.#registry, output.name)
+				: this.#type(output.type, path.owner)
+		if (output.form === 'nullable') return named
+		const item = new GraphQLNonNull(named)
+		return list ? new GraphQLNonNull(new GraphQLList(item)) : item
+	}
+
+	/** The type named `name`, if a function, a virtual or a field gave it. */
+	named(name: string): GraphQLNamedType | undefined {
+		return this.#types.get(name) ?? this.#data.named(name)
+	}
+
+	/** A `defineType`, built once; its fields cannot refer back to it. */
+	#type(type: ExposedType, owner: string): GraphQLObjectType {
+		const known = this.#types.get(type.name)
+		if (known !== undefined) return known
+		const { name } = type
+		checkName(name, `defineType ${name}`)
+		const other = this.owners.get(name)
+		if (other !== undefined) {
+			throw new Refused(
+				`${other} and ${owner} give the type ${name} two shapes; name each once.`,
+			)
+		}
+		this.owners.set(name, owner)
+		const fields = [...type.fields].map(([field, output]): [string, Field] => {
+			checkName(field, `${name}.${field}`)
+			const path = at(name, `${name}${upper(field)}`, field)
+			return [field, { type: this.output(output, path, name, field) }]
+		})
+		const built = new GraphQLObjectType<unknown, Context>({
+			name,
+			description: type.description,
+			fields: Object.fromEntries(fields),
+		})
+		this.#types.set(name, built)
+		return built
+	}
+
+	/** A virtual's field: an argument per input property, its output (D-151). */
+	virtual(model: string, virtual: ExposedVirtual, ruled: boolean): Field {
+		const { name, input, output } = virtual
+		const owner = `${model}.${name}`
+		const base = `${model}${upper(name)}`
+		const given =
+			input === undefined
+				? undefined
+				: inputArgs(input, at(owner, `${base}Input`, 'input'), this.#data)
+		if (given?.flat === false) {
+			throw new Refused(
+				`${owner}: its input is an object schema, whose properties are its arguments.`,
+			)
+		}
+		const type = this.output(
+			output,
+			at(owner, `${base}Output`, name),
+			model,
+			name,
+		)
+		const take = this.#take
+		const registry = this.#registry
+		return {
+			// Absent when a read rule hides it (D-44).
+			type: ruled && type instanceof GraphQLNonNull ? type.ofType : type,
+			description: virtual.description,
+			args: given?.args ?? {},
+			resolve: (source, _, context, info) => {
+				const value: unknown = Reflect.get(Object(source), name)
+				// The budget counts `take` rows in a list (D-109).
+				if (
+					output.kind === 'model' &&
+					Array.isArray(value) &&
+					value.length > take &&
+					relates(registry, output.name, info, isMaster(context))
+				) {
+					throw new RangeError(
+						`${owner} returned ${value.length} rows; a list counts take (${take}) rows, so it holds no more under a selected relation.`,
+					)
+				}
+				return value
+			},
+		}
+	}
+
+	/**
+	 * A function's field, and its subscription when it is `live` (D-154),
+	 * whose rows the budget counts as the query's.
+	 */
+	field(
+		fn: ExposedFunction,
+		name: string,
+		owner: string,
+		live: boolean,
+	): { readonly field: Field; readonly live?: Field } {
+		const { input, output } = fn
+		const base = upper(name)
+		const given =
+			input === undefined
+				? undefined
+				: inputArgs(input, at(owner, `${base}Input`, 'input'), this.#data)
+		const root = fn.query ? 'Query' : 'Mutation'
+		const type =
+			output === undefined
+				? new GraphQLNonNull(GraphQLBoolean)
+				: this.output(output, at(owner, `${base}Output`, 'output'), root, name)
+		const registry = this.#registry
+		const take = this.#take
+		const value = async (
+			args: Args,
+			context: Context,
+			info: GraphQLResolveInfo,
+		): Promise<unknown> => {
+			const sent = given?.flat === true ? args : args['input']
+			const result = await fn.run(plain(sent), as(context), context.client)
+			if (output === undefined) return true
+			if (result === undefined && type instanceof GraphQLNonNull) {
+				throw new TypeError(
+					`${fn.name} returned undefined; make its output .nullable() and return null.`,
+				)
+			}
+			const call = { name: fn.name, take }
+			return reread(registry, output, result, context, info, call)
+		}
+		const config = {
+			type,
+			description: fn.description,
+			args: given?.args ?? {},
+		}
+		const field: Field = {
+			...config,
+			resolve: async (_, args, context, info) => value(args, context, info),
+		}
+		if (!live) return { field }
+		const read = this.reads.get(root)?.get(name)
+		if (read !== undefined) {
+			const reads = this.reads.get('Subscription') ?? new Map<string, Read>()
+			this.reads.set('Subscription', reads.set(name, read))
+		}
+		return { field, live: followed(owner, config, value) }
+	}
+}
+
+/** The functions' root fields, and what each reads (D-109). */
+export function functionFields(
+	registry: Registry,
+	functions: readonly ExposedFunction<GraphqlFunctionWith>[],
+	take: number,
+	live: (owner: string) => boolean,
+): {
+	readonly fields: readonly RootField[]
+	/** The live functions' subscriptions, named as their fields (D-154). */
+	readonly subscriptions: { readonly [name: string]: Field }
+	readonly reads: ReadonlyMap<string, ReadonlyMap<string, Read>>
+	readonly owners: ReadonlyMap<string, string>
+	readonly named: (name: string) => GraphQLNamedType | undefined
+} {
+	const builder = new Builder(registry, take)
+	registry.virtualFields = (model) => {
+		const entry = registry.entry(model)
+		const { readRules } = entry.exposed
+		return Object.fromEntries(
+			readableVirtuals(entry).map((virtual) => [
+				virtual.name,
+				builder.virtual(model, virtual, readRules[virtual.name] === 'rule'),
+			]),
+		)
+	}
+	const fields: RootField[] = []
+	const subscriptions: { [name: string]: Field } = {}
+	for (const fn of functions) {
+		if (fn.with === false) continue
+		const name = checkName(fn.with?.name ?? fn.name, fn.name)
+		// A plugin's function is named with its plugin (D-113).
+		const owner = fn.plugin === undefined ? fn.name : `${fn.plugin}.${fn.name}`
+		const built = builder.field(fn, name, owner, live(owner))
+		fields.push({ query: fn.query, name, owner, field: built.field })
+		if (built.live !== undefined) subscriptions[name] = built.live
+	}
+	return {
+		fields,
+		subscriptions,
+		reads: builder.reads,
+		owners: builder.owners,
+		named: (name) => builder.named(name),
+	}
+}

package/src/graphiql.ts

@@ -0,0 +1,54 @@
+// GraphiQL 5 (D-107): the page a browser gets at `/graphql` outside
+// production, its modules loaded from esm.sh at pinned versions.
+
+const imports = {
+	react: 'https://esm.sh/react@19.3.1',
+	'react/': 'https://esm.sh/react@19.3.1/',
+	'react-dom': 'https://esm.sh/react-dom@19.3.1',
+	'react-dom/': 'https://esm.sh/react-dom@19.3.1/',
+	graphiql:
+		'https://esm.sh/graphiql@5.4.0?standalone&external=react,react-dom,@graphiql/react,graphql',
+	'graphiql/': 'https://esm.sh/graphiql@5.4.0/',
+	'@graphiql/react':
+		'https://esm.sh/@graphiql/react@0.39.1?standalone&external=react,react-dom,graphql,@graphiql/toolkit,@emotion/is-prop-valid',
+	'@graphiql/toolkit':
+		'https://esm.sh/@graphiql/toolkit@0.12.1?standalone&external=graphql',
+	graphql: 'https://esm.sh/graphql@17.0.2',
+	'@emotion/is-prop-valid': 'data:text/javascript,',
+}
+
+/** A value written into a script, unable to close it. */
+const inline = (value: unknown): string =>
+	JSON.stringify(value).replaceAll('<', '\\u003c')
+
+/** The page, served at `path`, that sends its documents to `path`. */
+export function graphiqlPage(path: string): () => Response {
+	const html = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>UltimaBase GraphiQL</title>
+<style>html,body,#graphiql{height:100%;margin:0}</style>
+<link rel="stylesheet" href="https://esm.sh/graphiql@5.4.0/dist/style.css">
+<script type="importmap">${inline({ imports })}</script>
+<script type="module">
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import { GraphiQL } from 'graphiql'
+import { createGraphiQLFetcher } from '@graphiql/toolkit'
+import 'graphiql/setup-workers/esm.sh'
+const fetcher = createGraphiQLFetcher({ url: ${inline(path)} })
+ReactDOM.createRoot(document.getElementById('graphiql')).render(
+	React.createElement(GraphiQL, { fetcher }),
+)
+</script>
+</head>
+<body><div id="graphiql"></div></body>
+</html>
+`
+	return () =>
+		new Response(html, {
+			headers: { 'content-type': 'text/html; charset=utf-8' },
+		})
+}

package/src/index.ts

@@ -0,0 +1,231 @@
+// `graphqlPlugin()` (D-107, D-109): a Relay schema generated from the models
+// and the functions, mounted on the HTTP plugin and run as each request's
+// caller; with the realtime plugin, its live models' subscriptions (D-154).
+import type { GraphQLSchema } from 'graphql'
+import {
+	executeRootSelectionSet,
+	MaxIntrospectionDepthRule,
+	NoSchemaIntrospectionCustomRule,
+	parse,
+	specifiedRules,
+	validate,
+	validateExecutionArgs,
+} from 'graphql'
+import { createHandler } from 'graphql-http/lib/use/fetch'
+import type { Http } from '@ultimabase/http'
+import { clientOf, httpPlugin, routes } from '@ultimabase/http'
+import type { Realtime } from '@ultimabase/realtime'
+import { realtimePlugin } from '@ultimabase/realtime'
+import type { Caller, Client, PluginOf, PluginTypes, UseOf } from 'ultimabase'
+import { definePlugin } from 'ultimabase'
+import manifest from '../package.json' with { type: 'json' }
+import { depthRule, introspectionDepthRule } from './depth.ts'
+import { formatter } from './errors.ts'
+import type { GraphqlFunctionWith } from './functions.ts'
+import { functionFields } from './functions.ts'
+import { graphiqlPage } from './graphiql.ts'
+import { overlapRefusal } from './overlap.ts'
+import { rootNames } from './names.ts'
+import type { Context, Entry, GraphqlWith } from './registry.ts'
+import { Registry } from './registry.ts'
+import { rowBudget } from './rows.ts'
+import { schemaOf } from './schema.ts'
+import { selectFor } from './select.ts'
+import type { Operations } from './sockets.ts'
+import { serveSockets } from './sockets.ts'
+import { subscriptionFields } from './subscriptions.ts'
+
+export type { GraphqlFunctionWith } from './functions.ts'
+export type { Context as GraphqlContext, GraphqlWith } from './registry.ts'
+
+/** What `graphqlPlugin` takes (D-107). */
+export interface GraphqlOptions {
+	/** `/graphql` 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 document of a caller other than Master nests; 10 by default. */
+	readonly maxDepth?: number
+	/**
+	 * The most rows a document of a caller other than Master may return, each
+	 * list times the lists above it; 20 000 by default.
+	 */
+	readonly maxRows?: number
+	/**
+	 * Introspection and "Did you mean" suggestions: closed in production,
+	 * open elsewhere, unless set.
+	 */
+	readonly introspection?: boolean
+	/** Replaces the generated schema with one built from it (D-45). */
+	readonly extend?: (schema: GraphQLSchema) => GraphQLSchema
+}
+
+/** The GraphQL plugin's types (D-57). */
+export interface Graphql extends PluginTypes {
+	readonly name: 'graphql'
+	readonly appOptions: GraphqlOptions
+	readonly requires: Http
+	readonly optional: Realtime
+	readonly with: GraphqlWith
+	readonly functionWith: GraphqlFunctionWith
+}
+
+/** About ten times the standard introspection query. */
+const maxTokens = 2000
+
+// What closes each running application's WebSockets, by its plugin's context.
+const closers = new WeakMap<object, () => Promise<void>>()
+
+const plugin = definePlugin<Graphql>({
+	name: 'graphql',
+	manifest,
+	requires: { http: httpPlugin },
+	optional: { realtime: realtimePlugin },
+	api: (pluginContext) => {
+		const { plugins, models, functions, options, logger } = pluginContext
+		const { realtime } = plugins
+		const take = options.take ?? 100
+		const entries = new Map<string, Entry>()
+		for (const exposed of models) {
+			const name = exposed.schema.name
+			const own = exposed.with === false ? {} : (exposed.with ?? {})
+			entries.set(name, {
+				exposed,
+				model: exposed.schema,
+				visible: exposed.with !== false,
+				...rootNames(name, own.plural),
+				take,
+				maxTake: own.maxTake ?? options.maxTake ?? 100,
+			})
+		}
+		const registry = new Registry(entries, {
+			pagination: options.pagination ?? 'connection',
+		})
+		const liveFunction = realtime?.liveFunction ?? (() => false)
+		const called = functionFields(registry, functions, take, liveFunction)
+		const live = realtime?.live ?? (() => false)
+		const generated = schemaOf(registry, {
+			...called,
+			subscriptions: {
+				...subscriptionFields(registry, live),
+				...called.subscriptions,
+			},
+		})
+		const schema = options.extend?.(generated) ?? generated
+		const production = process.env['NODE_ENV'] === 'production'
+		const hideSuggestions = !(options.introspection ?? !production)
+		const closed = hideSuggestions ? [NoSchemaIntrospectionCustomRule] : []
+		const maxDepth = options.maxDepth ?? 10
+		const depth = depthRule(maxDepth)
+		const maxRows = options.maxRows ?? 20_000
+		const budget = rowBudget(registry, { maxRows, maxDepth }, called.reads)
+		// The contexts of Master's requests, which no budget limits.
+		const exempt = new WeakSet<object>()
+		// The caller the HTTP plugin read and the client, by its request.
+		const requests = new WeakMap<
+			Request,
+			{ readonly caller: Caller; readonly client: Client }
+		>()
+		const heldOf = (request: Request) => {
+			const held = requests.get(request)
+			if (held === undefined) throw new Error('No caller was read.')
+			return held
+		}
+		const operations: Operations = {
+			schema,
+			// Validation is quadratic in a field repeated under one key, so a
+			// document is bounded before it is validated.
+			parse: (source) => parse(source, { maxTokens }),
+			rules: (master) => [
+				...specifiedRules.filter((rule) => rule !== MaxIntrospectionDepthRule),
+				introspectionDepthRule,
+				...closed,
+				...(master ? [] : [depth]),
+			],
+			validate: (document, rules) => {
+				const refused = overlapRefusal(document)
+				if (refused !== undefined) return [refused]
+				return validate(schema, document, rules, { hideSuggestions })
+			},
+			execute: async (args) => {
+				const validated = validateExecutionArgs({ ...args, hideSuggestions })
+				if (!('schema' in validated)) return { errors: validated }
+				const { contextValue } = validated
+				const master =
+					typeof contextValue === 'object' &&
+					contextValue !== null &&
+					exempt.has(contextValue)
+				const refused = master ? undefined : budget(validated)
+				if (refused !== undefined) return { errors: [refused] }
+				return executeRootSelectionSet(validated)
+			},
+			context: (caller, client) => {
+				const master = caller.kind === 'master'
+				const select = selectFor(registry, master)
+				const context = { caller, client, select }
+				if (master) exempt.add(context)
+				return context
+			},
+			hideSuggestions,
+			format: formatter(logger),
+			logger,
+		}
+		const handler = createHandler<Context>({
+			schema,
+			parse: operations.parse,
+			context: (request) => {
+				const { caller, client } = heldOf(request.raw)
+				return operations.context(caller, client)
+			},
+			validationRules: (request) =>
+				operations.rules(heldOf(request.raw).caller.kind === 'master'),
+			validate: (_, document, rules) => operations.validate(document, rules),
+			execute: operations.execute,
+			formatError: operations.format,
+		})
+		const path = options.path ?? '/graphql'
+		const page = production ? undefined : graphiqlPage(path)
+		plugins.http.mount(
+			routes().on(['GET', 'POST'], path, async (c) => {
+				// A browser opening the URL, not a client sending a document.
+				const browsing =
+					c.req.method === 'GET' &&
+					c.req.header('accept')?.includes('text/html') === true
+				if (page !== undefined && browsing) return page()
+				// A middleware may have read the body: Hono kept it, not the request.
+				const request =
+					c.req.method === 'POST' && c.req.raw.bodyUsed
+						? new Request(c.req.raw, {
+								method: 'POST',
+								body: await c.req.text(),
+							})
+						: c.req.raw
+				const { client, sent } = clientOf(c)
+				requests.set(request, { caller: c.var.caller, client })
+				return sent(await handler(request))
+			}),
+		)
+		if (realtime !== undefined) {
+			const close = serveSockets(plugins.http, path, realtime, operations)
+			closers.set(pluginContext, close)
+		}
+	},
+	start: ({ plugins, options, logger }) => {
+		if (process.env['NODE_ENV'] === 'production') return
+		logger.info(
+			`GraphiQL on ${plugins.http.url()}${options.path ?? '/graphql'}.`,
+		)
+	},
+	// Before the HTTP plugin's stop, which waits for the sockets to close.
+	stop: async (context) => closers.get(context)?.(),
+})
+
+/** The application's GraphQL API, served by `httpPlugin` (D-107). */
+export const graphqlPlugin: PluginOf<Graphql> = plugin.plugin
+
+/** A model's `.with({ graphql })`, from its `use` (D-107). */
+export const graphql: UseOf<Graphql> = plugin.use