@ultimabase/graphql 0.0.0-stage → 0.1.0

package/src/schema.ts

@@ -0,0 +1,189 @@
+// The schema (D-107): for each visible model, `post(where)` and `posts(...)`,
+// each read in one kernel query as its caller, and its mutations.
+import { connection, rowsOf, run } from '@ultimabase/http/internal'
+import type { GraphQLFieldConfig, GraphQLNamedType } from 'graphql'
+import {
+	GraphQLList,
+	GraphQLNonNull,
+	GraphQLObjectType,
+	GraphQLSchema,
+} from 'graphql'
+import { objectOf, uniqueInput, uniqueWhere } from './inputs.ts'
+import { connectionType, isMaster, listArgs, objectType } from './outputs.ts'
+import { listRead, whereOf } from './pages.ts'
+import type { Args, Context, Entry, Registry } from './registry.ts'
+import { as } from './registry.ts'
+import { rowNodes, selectOf } from './select.ts'
+import { mutationFields } from './mutations.ts'
+import type { RootField } from './functions.ts'
+import { Refused } from 'ultimabase'
+
+type Fields = { [field: string]: GraphQLFieldConfig<unknown, Context, Args> }
+
+function rootFields(registry: Registry, entry: Entry): Fields {
+	const name = entry.model.name
+	const type = objectType(registry, name)
+	const { queries } = entry.exposed
+	const list =
+		registry.settings.pagination === 'list'
+			? new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(type)))
+			: new GraphQLNonNull(connectionType(registry, `${name}Connection`, name))
+	return {
+		[entry.single]: {
+			type,
+			args: {
+				where: { type: new GraphQLNonNull(uniqueInput(registry, name)) },
+			},
+			resolve: async (_, args, context, info) => {
+				const where = uniqueWhere(registry, name, objectOf(args['where']))
+				const select = selectOf(
+					registry,
+					info,
+					type,
+					info.fieldNodes,
+					isMaster(context),
+				)
+				return run(() => queries.findUnique({ where, select }, as(context)))
+			},
+		},
+		[entry.list]: {
+			type: list,
+			args: listArgs(registry, name),
+			resolve: async (_, args, context, info) => {
+				const master = isMaster(context)
+				const { read, page } = listRead(registry, entry, args, master)
+				const select = selectOf(
+					registry,
+					info,
+					type,
+					rowNodes(registry, info),
+					master,
+				)
+				const rows = await run(() =>
+					queries.findMany({ ...read, select }, as(context)),
+				)
+				if (page === undefined) return rows
+				let counted: Promise<unknown> | undefined
+				return {
+					...connection(rowsOf(rows), page, (row) => row),
+					// Called by the default resolver, so counted only when selected,
+					// and once however many aliases ask.
+					totalCount: async () => {
+						counted ??= run(() =>
+							queries.count(whereOf(registry, name, args), as(context)),
+						)
+						return counted
+					},
+				}
+			},
+		},
+	}
+}
+
+const taken = (name: string, owner: string): Error =>
+	new Refused(`${owner}: the type ${name} is a generated type's name.`)
+
+/** The models' types, a json field's among them, built once to name them. */
+function generatedTypes(
+	fields: Fields,
+	mutations: Fields,
+	typeOwners: ReadonlyMap<string, string>,
+): ReturnType<GraphQLSchema['getTypeMap']> {
+	try {
+		return new GraphQLSchema({
+			query: new GraphQLObjectType({ name: 'Query', fields: { ...fields } }),
+			mutation: new GraphQLObjectType({
+				name: 'Mutation',
+				fields: { ...mutations },
+			}),
+		}).getTypeMap()
+	} catch (error) {
+		// A json field's type named like a model's, as `PostStatus`.
+		const name = /multiple types named "(\w+)"/.exec(String(error))?.[1]
+		const owner = name === undefined ? undefined : typeOwners.get(name)
+		if (name === undefined || owner === undefined) throw error
+		throw taken(name, owner)
+	}
+}
+
+/** Refuses two root fields of one name, naming both owners. */
+export function schemaOf(
+	registry: Registry,
+	called: {
+		readonly fields: readonly RootField[]
+		readonly owners: ReadonlyMap<string, string>
+		readonly named: (name: string) => GraphQLNamedType | undefined
+		/** The live models' subscriptions, named as their queries (D-154). */
+		readonly subscriptions: Fields
+	},
+): GraphQLSchema {
+	const { fields: functions, owners: typeOwners, named, subscriptions } = called
+	const roots = {
+		query: new Map<string, string>(),
+		mutation: new Map<string, string>(),
+	}
+	const fields: Fields = {}
+	const mutations: Fields = {}
+	const add = (
+		into: Fields,
+		owners: Map<string, string>,
+		owner: string,
+		hint: string,
+		added: Fields,
+	) => {
+		for (const [name, field] of Object.entries(added)) {
+			const other = owners.get(name)
+			if (other !== undefined) {
+				throw new Refused(
+					`${owner}: the root field ${name} is ${other}'s; set .with({ graphql: { ${hint} } }).`,
+				)
+			}
+			owners.set(name, owner)
+			into[name] = field
+		}
+	}
+	for (const entry of registry.entries.values()) {
+		if (!entry.visible) continue
+		const owner = entry.model.name
+		add(
+			mutations,
+			roots.mutation,
+			owner,
+			'plural',
+			mutationFields(registry, entry),
+		)
+		add(fields, roots.query, owner, 'plural', rootFields(registry, entry))
+	}
+	// The models' types, which no function's or field's type may be named like.
+	const generated = generatedTypes(fields, mutations, typeOwners)
+	for (const [name, owner] of typeOwners) {
+		if (name in generated && generated[name] !== named(name)) {
+			throw taken(name, owner)
+		}
+	}
+	for (const { query, name, owner, field } of functions) {
+		const [into, owners] = query
+			? [fields, roots.query]
+			: [mutations, roots.mutation]
+		add(into, owners, owner, 'name', { [name]: field })
+	}
+	if (Object.keys(fields).length === 0) {
+		throw new Refused(
+			'graphqlPlugin: no query to expose; each model has .with({ graphql: false }) and no function is a query.',
+		)
+	}
+	return new GraphQLSchema({
+		query: new GraphQLObjectType({ name: 'Query', fields }),
+		mutation:
+			Object.keys(mutations).length === 0
+				? undefined
+				: new GraphQLObjectType({ name: 'Mutation', fields: mutations }),
+		subscription:
+			Object.keys(subscriptions).length === 0
+				? undefined
+				: new GraphQLObjectType({
+						name: 'Subscription',
+						fields: subscriptions,
+					}),
+	})
+}

package/src/select.ts

@@ -0,0 +1,230 @@
+// A query's selection as one kernel read (D-107): the fields asked for, and
+// each `many` relation's own page and count, read with its parent's rows.
+import { badInput, readable } from '@ultimabase/http/internal'
+import type {
+	FieldNode,
+	GraphQLObjectType,
+	GraphQLResolveInfo,
+	SelectionSetNode,
+} from 'graphql'
+import type { ExposedVirtual } from 'ultimabase'
+import {
+	getArgumentValues,
+	getDirectiveValues,
+	getNamedType,
+	GraphQLIncludeDirective,
+	GraphQLSkipDirective,
+	isObjectType,
+	Kind,
+} from 'graphql'
+import { objectType } from './outputs.ts'
+import { plain } from './scalars.ts'
+import { listRead } from './pages.ts'
+import type { Args, Registry } from './registry.ts'
+
+export type Info = Pick<GraphQLResolveInfo, 'fragments' | 'variableValues'>
+/** A field's name, or its alias: the key of its value in the response. */
+export type Key = (node: FieldNode) => string
+/** Fields under one key, the first of them included. */
+export type Fields = readonly [FieldNode, ...FieldNode[]]
+/** A field or an operation: what selects fields. */
+export type Selecting = { readonly selectionSet?: SelectionSetNode | undefined }
+
+function included(info: Info, node: Parameters<typeof getDirectiveValues>[1]) {
+	const skip = getDirectiveValues(
+		GraphQLSkipDirective,
+		node,
+		info.variableValues,
+	)
+	if (skip?.['if'] === true) return false
+	const include = getDirectiveValues(
+		GraphQLIncludeDirective,
+		node,
+		info.variableValues,
+	)
+	return include?.['if'] !== false
+}
+
+// A fragment spread again adds nothing the first spread did not, so each is
+// collected once: spreading each fragment twice into the next would otherwise
+// cost 2^n visits.
+function collect(
+	info: Info,
+	set: SelectionSetNode | undefined,
+	into: Map<string, [FieldNode, ...FieldNode[]]>,
+	key: Key,
+	spread: Set<string>,
+): void {
+	for (const selection of set?.selections ?? []) {
+		if (!included(info, selection)) continue
+		if (selection.kind === Kind.FIELD) {
+			const found = into.get(key(selection))
+			if (found === undefined) into.set(key(selection), [selection])
+			else found.push(selection)
+		} else if (selection.kind === Kind.INLINE_FRAGMENT) {
+			collect(info, selection.selectionSet, into, key, spread)
+		} else if (!spread.has(selection.name.value)) {
+			spread.add(selection.name.value)
+			const fragment = info.fragments[selection.name.value]
+			collect(info, fragment?.selectionSet, into, key, spread)
+		}
+	}
+}
+
+const byName: Key = (node) => node.name.value
+
+/** The fields under some nodes, by name, through fragments and directives. */
+export function grouped(
+	info: Info,
+	nodes: readonly Selecting[],
+	key: Key = byName,
+): ReadonlyMap<string, Fields> {
+	const into = new Map<string, [FieldNode, ...FieldNode[]]>()
+	const spread = new Set<string>()
+	for (const node of nodes) collect(info, node.selectionSet, into, key, spread)
+	return into
+}
+
+/** One relation's arguments, the same under every alias. */
+function argsOf(
+	type: GraphQLObjectType,
+	name: string,
+	nodes: readonly FieldNode[],
+	info: Info,
+): Args {
+	const field = type.getFields()[name]
+	const [first, ...others] = nodes.map((node) =>
+		field === undefined
+			? {}
+			: getArgumentValues(field, node, info.variableValues),
+	)
+	const key = JSON.stringify(first)
+	if (others.some((args) => JSON.stringify(args) !== key)) {
+		throw badInput(
+			`${name} is selected twice with different arguments; read it once.`,
+		)
+	}
+	return first ?? {}
+}
+
+/** Under a connection, the nodes its edges select. */
+export function nodesOf(info: Info, nodes: readonly FieldNode[]): FieldNode[] {
+	const edges = grouped(info, nodes).get('edges') ?? []
+	return [...(grouped(info, edges).get('node') ?? [])]
+}
+
+/** What a root list selects of its rows: under `edges { node }`. */
+export function rowNodes(
+	registry: Registry,
+	info: GraphQLResolveInfo,
+): readonly FieldNode[] {
+	return registry.settings.pagination === 'list'
+		? info.fieldNodes
+		: nodesOf(info, info.fieldNodes)
+}
+
+const system = new Set(['id', 'createdAt', 'updatedAt'])
+
+/** A virtual's read: `true`, its arguments, and a model's `select` (D-151). */
+function virtualRead(
+	registry: Registry,
+	info: Info,
+	type: GraphQLObjectType,
+	virtual: ExposedVirtual,
+	nodes: readonly FieldNode[],
+	master: boolean,
+): unknown {
+	const { output } = virtual
+	const args = plain(argsOf(type, virtual.name, nodes, info))
+	const input = typeof args === 'object' && args !== null ? args : {}
+	if (output.kind !== 'model') return virtual.input === undefined || input
+	const target = objectType(registry, output.name)
+	return { ...input, select: selectOf(registry, info, target, nodes, master) }
+}
+
+/** The kernel's `select` for what a query asks of a model's rows. */
+export function selectOf(
+	registry: Registry,
+	info: Info,
+	type: GraphQLObjectType,
+	nodes: readonly FieldNode[],
+	master: boolean,
+): Args {
+	const entry = registry.entry(type.name)
+	const select: { [field: string]: unknown } = { id: true }
+	// The connections' `totalCount`, each the count of its `where` (D-134).
+	const counts: { [field: string]: unknown } = {}
+	for (const [name, fieldNodes] of grouped(info, nodes)) {
+		if (name === '__typename') continue
+		if (system.has(name)) {
+			select[name] = true
+			continue
+		}
+		const virtual = entry.exposed.virtuals.find((v) => v.name === name)
+		if (virtual !== undefined) {
+			select[name] = virtualRead(
+				registry,
+				info,
+				type,
+				virtual,
+				fieldNodes,
+				master,
+			)
+			continue
+		}
+		const field = entry.model.fields.find((f) => f.name === name)
+		if (field === undefined) {
+			// A field `extend` added: its resolver gets the row's scalars.
+			for (const scalar of readable(entry)) {
+				if (scalar.kind === 'scalar') select[scalar.name] = true
+			}
+			for (const key of system) select[key] = true
+			continue
+		}
+		if (field.kind === 'scalar') {
+			select[name] = true
+			continue
+		}
+		const target = registry.entry(field.target)
+		const targetObject = objectType(registry, field.target)
+		if (field.kind === 'one') {
+			select[name] = {
+				select: selectOf(registry, info, targetObject, fieldNodes, master),
+			}
+			continue
+		}
+		const args = argsOf(type, name, fieldNodes, info)
+		const { read } = listRead(registry, target, args, master)
+		const list = registry.settings.pagination === 'list'
+		const below = list ? fieldNodes : nodesOf(info, fieldNodes)
+		select[name] = {
+			...read,
+			select: selectOf(registry, info, targetObject, below, master),
+		}
+		if (!list && grouped(info, fieldNodes).has('totalCount')) {
+			counts[name] =
+				read['where'] === undefined ? true : { where: read['where'] }
+		}
+	}
+	if (Object.keys(counts).length > 0) select['_count'] = { select: counts }
+	return select
+}
+
+/** `context.select(info)`, for a field that returns a model or a list of one. */
+export function selectFor(
+	registry: Registry,
+	master: boolean,
+): (info: GraphQLResolveInfo) => Args & { readonly id: true } {
+	return (info) => {
+		const type = getNamedType(info.returnType)
+		if (!isObjectType(type) || !registry.entries.has(type.name)) {
+			throw new Error(
+				`context.select(info) reads a model's rows; ${info.parentType.name}.${info.fieldName} returns ${type.name}.`,
+			)
+		}
+		return {
+			...selectOf(registry, info, type, info.fieldNodes, master),
+			id: true,
+		}
+	}
+}

package/src/sockets.ts

@@ -0,0 +1,291 @@
+// GraphQL over WebSocket (D-154): the `graphql-ws` protocol on the GraphQL
+// path, each connection one viewer of its caller, its subscriptions live
+// reads and its queries and mutations run as over HTTP.
+import type { HttpApi, Upgrade } from '@ultimabase/http'
+import type { RealtimeApi, Viewer } from '@ultimabase/realtime'
+import type {
+	DocumentNode,
+	ExecutionArgs,
+	ExecutionResult,
+	GraphQLSchema,
+	Source,
+	ValidationRule,
+} from 'graphql'
+import {
+	createSourceEventStream,
+	executeSubscriptionEvent,
+	GraphQLError,
+	mapSourceToResponseEvent,
+	validateSubscriptionArgs,
+} from 'graphql'
+import { CloseCode, handleProtocols, makeServer } from 'graphql-ws'
+import type { RawData, WebSocket } from 'ws'
+import { WebSocketServer } from 'ws'
+import type { Caller, Client, Logger } from 'ultimabase'
+import { PublicError } from 'ultimabase'
+import type { formatter } from './errors.ts'
+import type { Channel } from './live-stream.ts'
+import { LiveEvent, lives } from './live-stream.ts'
+import type { Context } from './registry.ts'
+
+/** How the GraphQL plugin runs a document, over HTTP as over WebSocket. */
+export type Operations = {
+	readonly schema: GraphQLSchema
+	readonly parse: (source: string | Source) => DocumentNode
+	readonly rules: (master: boolean) => readonly ValidationRule[]
+	readonly validate: (
+		document: DocumentNode,
+		rules?: readonly ValidationRule[],
+	) => readonly GraphQLError[]
+	readonly execute: (args: ExecutionArgs) => Promise<ExecutionResult>
+	readonly context: (caller: Caller, client: Client) => Context
+	readonly hideSuggestions: boolean
+	readonly format: ReturnType<typeof formatter>
+	readonly logger: Logger
+}
+
+/** A connection's socket, and its viewer once `connection_init` came. */
+type Extra = {
+	readonly upgrade: Upgrade
+	readonly socket: WebSocket
+	viewer?: Viewer
+	channel?: Channel
+}
+
+/** A client's buffer past which its changes are dropped, and the most it sends us. */
+const maxBuffer = 1024 * 1024
+/** Between pings; a socket that has not answered the last one is cut. */
+const keepAlive = 12_000
+
+const unset = () => {
+	throw new Error('A cookie is set over HTTP: a WebSocket cannot set one.')
+}
+
+/** The upgrade request's cookies, which a WebSocket cannot set. */
+function cookiesOf(request: Request): Client['cookies'] {
+	const cookies = new Map<string, string>()
+	for (const part of (request.headers.get('cookie') ?? '').split(';')) {
+		const at = part.indexOf('=')
+		if (at <= 0) continue
+		const name = part.slice(0, at).trim()
+		if (cookies.has(name)) continue
+		try {
+			cookies.set(name, decodeURIComponent(part.slice(at + 1).trim()))
+		} catch {
+			// A value that is no URI component is no cookie this API wrote.
+		}
+	}
+	return { get: (name) => cookies.get(name), set: unset, clear: unset }
+}
+
+// How each socket sends, counted by its channel once it has one.
+const sends = new WeakMap<WebSocket, (data: string) => void>()
+
+/** The socket's channel: what it holds unsent, and when that is written. */
+function channelOf(viewer: Viewer, socket: WebSocket): Channel {
+	let pending = 0
+	const waiters: (() => void)[] = []
+	const written = () => {
+		pending -= 1
+		if (pending > 0) return
+		for (const then of waiters.splice(0)) then()
+	}
+	sends.set(socket, (data) => {
+		pending += 1
+		socket.send(data, written)
+	})
+	return {
+		viewer,
+		full: () => socket.bufferedAmount > maxBuffer,
+		drained: (then) => {
+			if (pending === 0) then()
+			else waiters.push(then)
+		},
+		forbid: () => socket.close(CloseCode.Forbidden, 'Forbidden'),
+		kept: new Map(),
+	}
+}
+
+const text = (data: RawData): string =>
+	Buffer.concat([data].flat().map((part) => new Uint8Array(part))).toString()
+
+const isLive = (
+	value: unknown,
+): value is { readonly mode?: unknown; readonly resume?: unknown } =>
+	typeof value === 'object' && value !== null
+
+/** The authorization `connection_init` gives, over the upgrade's own. */
+function requestOf(upgrade: Upgrade, params: unknown): Request {
+	const headers = new Headers(upgrade.request.headers)
+	const authorization: unknown =
+		typeof params === 'object' && params !== null
+			? Reflect.get(params, 'authorization')
+			: undefined
+	if (typeof authorization === 'string') {
+		headers.set('authorization', authorization)
+	}
+	return new Request(upgrade.request.url, { headers })
+}
+
+/**
+ * Serves `path`'s WebSocket upgrades with `operations`, each connection read
+ * by `realtime`; returns what closes them.
+ */
+export function serveSockets(
+	http: HttpApi,
+	path: string,
+	realtime: RealtimeApi,
+	operations: Operations,
+): () => Promise<void> {
+	const { schema, logger, format, hideSuggestions } = operations
+	const formatted = (errors: readonly GraphQLError[]) =>
+		errors.map((error) => {
+			const shown = format(error)
+			return shown instanceof GraphQLError
+				? shown.toJSON()
+				: { message: shown.message }
+		})
+	const server = makeServer<Record<string, unknown> | undefined, Extra>({
+		schema,
+		onConnect: async (ctx) => {
+			const { upgrade, socket } = ctx.extra
+			try {
+				const request = requestOf(upgrade, ctx.connectionParams)
+				const viewer = await realtime.connect(request)
+				if (socket.readyState !== socket.OPEN) {
+					viewer.close()
+					return false
+				}
+				ctx.extra.viewer = viewer
+				ctx.extra.channel = channelOf(viewer, socket)
+				return true
+			} catch (error) {
+				if (!(error instanceof PublicError)) {
+					logger.error({ err: error }, 'A WebSocket caller was not read.')
+				}
+				return false
+			}
+		},
+		onSubscribe: (ctx, _, payload) => {
+			const { viewer, channel, upgrade, socket } = ctx.extra
+			if (viewer === undefined || channel === undefined || viewer.closed) {
+				socket.close(CloseCode.Forbidden, 'Forbidden')
+				return [new GraphQLError('Forbidden')]
+			}
+			let document: DocumentNode
+			try {
+				document = operations.parse(payload.query)
+			} catch (error) {
+				if (error instanceof GraphQLError) return [error]
+				throw error
+			}
+			const { caller } = viewer
+			const master = caller.kind === 'master'
+			const refused = operations.validate(document, operations.rules(master))
+			if (refused.length > 0) return refused
+			const client = {
+				address: upgrade.address,
+				cookies: cookiesOf(upgrade.request),
+			}
+			const contextValue = operations.context(caller, client)
+			const live: unknown = payload.extensions?.['live']
+			const page = isLive(live) && live.mode === 'page'
+			const resume = isLive(live) ? live.resume : undefined
+			lives.set(contextValue, {
+				channel,
+				page,
+				...(typeof resume === 'string' && { resume }),
+			})
+			return {
+				schema,
+				document,
+				operationName: payload.operationName,
+				variableValues: payload.variables,
+				contextValue,
+			}
+		},
+		execute: async (args) => operations.execute(args),
+		subscribe: async (args) => {
+			const validated = validateSubscriptionArgs({ ...args, hideSuggestions })
+			if (!('schema' in validated)) return { errors: validated }
+			const source = await createSourceEventStream(validated)
+			if (!(Symbol.asyncIterator in source)) return source
+			return mapSourceToResponseEvent(validated, source, async (event) => {
+				const result = await executeSubscriptionEvent(event)
+				const { rootValue } = event
+				return rootValue instanceof LiveEvent
+					? rootValue.finish(result)
+					: result
+			})
+		},
+		onNext: (_ctx, _id, _payload, _args, { data, errors, extensions }) => ({
+			...(data === undefined ? {} : { data }),
+			...(errors === undefined ? {} : { errors: formatted(errors) }),
+			...(extensions === undefined ? {} : { extensions }),
+		}),
+		onError: (_ctx, _id, _payload, errors) => formatted(errors),
+	})
+	const sockets = new WebSocketServer({
+		noServer: true,
+		maxPayload: maxBuffer,
+		perMessageDeflate: { threshold: 1024 },
+		handleProtocols,
+	})
+	const beats = new WeakMap<WebSocket, () => void>()
+	const opened = (socket: WebSocket, upgrade: Upgrade) => {
+		const extra: Extra = { upgrade, socket }
+		let alive = true
+		socket.on('pong', () => {
+			alive = true
+		})
+		beats.set(socket, () => {
+			if (!alive) return socket.terminate()
+			alive = false
+			socket.ping()
+		})
+		const closed = server.opened(
+			{
+				protocol: socket.protocol,
+				send: async (data) => {
+					if (socket.readyState !== socket.OPEN) return
+					const send = sends.get(socket)
+					if (send === undefined) socket.send(data)
+					else send(data)
+				},
+				close: (code, reason) => socket.close(code, reason),
+				onMessage: (received) => {
+					socket.on('message', (data: RawData) => {
+						received(text(data)).catch((error: unknown) => {
+							logger.error({ err: error }, 'A WebSocket message failed.')
+							socket.close(CloseCode.InternalServerError, 'Internal error')
+						})
+					})
+				},
+			},
+			extra,
+		)
+		socket.once('close', (code, reason) => {
+			void closed(code, String(reason))
+			extra.viewer?.close()
+		})
+	}
+	const beating = setInterval(() => {
+		for (const socket of sockets.clients) beats.get(socket)?.()
+	}, keepAlive)
+	beating.unref()
+	http.upgrade(path, (upgrade) => {
+		sockets.handleUpgrade(
+			upgrade.incoming,
+			upgrade.socket,
+			upgrade.head,
+			(socket) => opened(socket, upgrade),
+		)
+	})
+	return async () => {
+		clearInterval(beating)
+		for (const socket of sockets.clients) socket.close(1001, 'Going away')
+		await new Promise<void>((done) => {
+			sockets.close(() => done())
+		})
+	}
+}