@ultimabase/realtime 0.0.0-stage → 0.1.1

package/src/engine.ts

@@ -0,0 +1,122 @@
+// The realtime engine (D-154): changes wait 50 ms, then one flush reads each
+// changed row once and hands the batch to every viewer, a few at a time.
+// Every viewer's caller is built again on a timer, and when it expires.
+import type { Changed } from 'ultimabase'
+import { liveSchema, recording } from 'ultimabase/internal'
+import { batchOf } from './changes.ts'
+import { Loader } from './reads.ts'
+import type { Settings } from './viewer.ts'
+import { Viewer } from './viewer.ts'
+
+/** How long changes wait, so the writes close together share one message. */
+const gather = 50
+/** How many viewers follow a flush at once. */
+const concurrency = 8
+
+/** Runs `task` on each of `items`, `limit` at a time. */
+async function bounded<T>(
+	items: readonly T[],
+	limit: number,
+	task: (item: T) => Promise<void>,
+): Promise<void> {
+	let next = 0
+	const worker = async (): Promise<void> => {
+		while (next < items.length) {
+			const item = items[next]
+			next += 1
+			if (item !== undefined) await task(item)
+		}
+	}
+	await Promise.all(Array.from({ length: limit }, worker))
+}
+
+export class Engine {
+	readonly #settings: Settings
+	readonly #viewers = new Set<Viewer>()
+	readonly #refresh: NodeJS.Timeout
+	#changes: Changed[] = []
+	#missed = false
+	#stopped = false
+	#timer: NodeJS.Timeout | undefined
+	#chain: Promise<void> = Promise.resolve()
+
+	constructor(settings: Settings, refresh: number) {
+		this.#settings = settings
+		this.#refresh = setInterval(() => {
+			this.#chain = this.#chain.then(async () => this.#rebuild())
+		}, refresh)
+		this.#refresh.unref()
+	}
+
+	/** A viewer for `request`'s caller, kept until it closes. */
+	async connect(request: Request): Promise<Viewer> {
+		const { identify } = this.#settings
+		const identified = await recording(async () => identify(request))
+		const viewer = new Viewer(this.#settings, request, identified, {
+			onClose: () => this.#viewers.delete(viewer),
+			onDue: () => {
+				this.#chain = this.#chain.then(async () =>
+					this.#guarded(viewer, async () => viewer.rebuild()),
+				)
+			},
+		})
+		this.#viewers.add(viewer)
+		return viewer
+	}
+
+	changed(changes: readonly Changed[]): void {
+		this.#changes.push(...changes)
+		this.#schedule()
+	}
+
+	missed(): void {
+		this.#missed = true
+		this.#schedule()
+	}
+
+	async stop(): Promise<void> {
+		this.#stopped = true
+		clearInterval(this.#refresh)
+		clearTimeout(this.#timer)
+		this.#timer = undefined
+		for (const viewer of this.#viewers) viewer.close()
+		await this.#chain
+	}
+
+	#schedule(): void {
+		// A change the adapter delivers once the application stopped is late.
+		if (this.#stopped || this.#timer !== undefined) return
+		this.#timer = setTimeout(() => {
+			this.#timer = undefined
+			this.#chain = this.#chain.then(async () => this.#flush())
+		}, gather)
+	}
+
+	async #flush(): Promise<void> {
+		const changes = this.#changes
+		const missed = this.#missed
+		this.#changes = []
+		this.#missed = false
+		const batch = batchOf(changes, liveSchema())
+		const loader = new Loader()
+		await bounded([...this.#viewers], concurrency, async (viewer) =>
+			this.#guarded(viewer, async () => viewer.flush(batch, loader, missed)),
+		)
+	}
+
+	async #rebuild(): Promise<void> {
+		await bounded([...this.#viewers], concurrency, async (viewer) =>
+			this.#guarded(viewer, async () => viewer.rebuild()),
+		)
+	}
+
+	/** A viewer that fails is logged and closed; the others go on. */
+	async #guarded(viewer: Viewer, task: () => Promise<void>): Promise<void> {
+		try {
+			await task()
+		} catch (error) {
+			this.#settings.logger.error({ err: error }, 'A live viewer failed.')
+			viewer.end()
+		}
+	}
+}

package/src/index.ts

@@ -0,0 +1,100 @@
+// `realtimePlugin()` and `realtime()` (D-154): live lists and live rows of
+// the models that use it, which follow each commit's changes and send only
+// what changed, under the caller's read rules; and the live functions, the
+// queries whose `use` lists it, run again when what they read changes.
+import type { PluginOf, PluginTypes, UseOf } from 'ultimabase'
+import { definePlugin } from 'ultimabase'
+import manifest from '../package.json' with { type: 'json' }
+import { Engine } from './engine.ts'
+import type { Viewer } from './viewer.ts'
+import { ownerOf } from './viewer.ts'
+
+export type { LiveMessage, Removal, Upsert } from './messages.ts'
+export type { LiveHandle, Viewer } from './viewer.ts'
+
+export type RealtimeOptions = {
+	/** The most rows a live list follows, nested rows included; 1000. */
+	readonly maxLive?: number
+	/** The most live reads one connection holds; 100. */
+	readonly maxSubscriptions?: number
+	/** The most rows one connection follows in all, nested rows included; 10 000. */
+	readonly maxConnectionRows?: number
+	/** How often, in milliseconds, each caller is built again; 5 minutes. */
+	readonly refresh?: number
+}
+
+/** What the realtime plugin offers transports. */
+export interface RealtimeApi {
+	/** Follows `request`'s caller; its live reads close with it. */
+	connect(this: void, request: Request): Promise<Viewer>
+	/** Whether `model`'s `use` lists `realtime()`. */
+	live(this: void, model: string): boolean
+	/** Whether function `name`'s `use` lists `realtime()`, `plugin.name` for a plugin's. */
+	liveFunction(this: void, name: string): boolean
+}
+
+/** The realtime plugin's types (D-57). */
+export interface Realtime extends PluginTypes {
+	readonly name: 'realtime'
+	readonly appOptions: RealtimeOptions
+	readonly with: { readonly maxLive?: number }
+	/** A live function's wait for quiet after a write, in milliseconds; 50. */
+	readonly functionWith: { readonly debounce?: number }
+	readonly queryOnly: true
+	readonly api: RealtimeApi
+}
+
+// Each running application's engine, by the context its plugin received.
+const engines = new WeakMap<object, Engine>()
+
+const positive = (name: string, value: number | undefined): void => {
+	if (value === undefined || (Number.isInteger(value) && value > 0)) return
+	throw new Error(`realtime's ${name} must be a positive integer.`)
+}
+
+const realtimeDefinition = definePlugin<Realtime>({
+	name: 'realtime',
+	manifest,
+	api: (context) => {
+		const { options, identify, logger, models, functions } = context
+		positive('maxLive', options.maxLive)
+		positive('maxSubscriptions', options.maxSubscriptions)
+		positive('maxConnectionRows', options.maxConnectionRows)
+		positive('refresh', options.refresh)
+		for (const model of models) positive('maxLive', model.with?.maxLive)
+		for (const fn of functions) {
+			positive('debounce', fn.with?.debounce)
+			if (fn.used && !fn.query) {
+				throw new Error(`${ownerOf(fn)} is a mutation: it cannot be live.`)
+			}
+		}
+		const engine = new Engine(
+			{
+				models,
+				functions,
+				identify,
+				logger,
+				maxLive: options.maxLive ?? 1000,
+				maxSubscriptions: options.maxSubscriptions ?? 100,
+				maxConnectionRows: options.maxConnectionRows ?? 10_000,
+			},
+			options.refresh ?? 300_000,
+		)
+		engines.set(context, engine)
+		const live = new Set(
+			models.filter(({ used }) => used).map(({ schema }) => schema.name),
+		)
+		const followed = new Set(functions.filter(({ used }) => used).map(ownerOf))
+		return {
+			connect: async (request) => engine.connect(request),
+			live: (model) => live.has(model),
+			liveFunction: (name) => followed.has(name),
+		}
+	},
+	changed: (changes, context) => engines.get(context)?.changed(changes),
+	missed: (context) => engines.get(context)?.missed(),
+	stop: async (context) => engines.get(context)?.stop(),
+})
+
+export const realtime: UseOf<Realtime> = realtimeDefinition.use
+export const realtimePlugin: PluginOf<Realtime> = realtimeDefinition.plugin

package/src/live.ts

@@ -0,0 +1,384 @@
+// A live list or row (D-154): its window follows each flush's changes, a
+// row placed or removed at a time, and sends only what changed. Its tasks
+// run one after another; one that fails reads the window again, and a
+// second failure closes it.
+import type { Caller, Logger, ModelQueries, Row } from 'ultimabase'
+import type { LivePlan } from 'ultimabase/internal'
+import {
+	inMemory,
+	liveSchema,
+	matches,
+	servedRows,
+	sortKeys,
+	storedRows,
+} from 'ultimabase/internal'
+import type { Finder } from './affected.ts'
+import { affected } from './affected.ts'
+import type { Batch } from './changes.ts'
+import type { Reach } from './reach.ts'
+import { reachOf } from './reach.ts'
+import type { Loader } from './reads.ts'
+import { finderOf, pass } from './reads.ts'
+import type { LiveMessage } from './messages.ts'
+import type { Entry } from './window.ts'
+import { Window } from './window.ts'
+import { Tracking } from './tracking.ts'
+
+export type Spec = {
+	readonly model: string
+	readonly queries: ModelQueries
+	/** The read's own `where`, which `totalCount` counts. */
+	readonly where: unknown
+	/** Its `select`, `include` or `omit`, each level's `id` selected. */
+	readonly shape: { readonly [key: string]: unknown }
+	readonly totalCount: boolean
+	readonly row: boolean
+	readonly send: (message: LiveMessage) => void
+	readonly logger: Logger
+}
+
+export class Live {
+	caller: Caller
+	#plan: LivePlan
+	#reach: Reach
+	#window: Window
+	readonly #spec: Spec
+	readonly #find: Finder
+	readonly #tracking = new Tracking()
+	#count: number | undefined
+	#hasMore = false
+	#revision = 0
+	#queue: Promise<void> = Promise.resolve()
+	#closed = false
+
+	constructor(spec: Spec, caller: Caller, plan: LivePlan, first: number) {
+		this.#spec = spec
+		this.caller = caller
+		this.#plan = plan
+		this.#reach = reachOf(liveSchema(), spec.model, plan)
+		this.#window = new Window(plan.orderBy, first)
+		this.#find = finderOf(spec.model)
+	}
+
+	get first(): number {
+		return this.#window.first
+	}
+
+	/** Reads the window and sends it; a failure closes the read. */
+	async start(): Promise<void> {
+		const run = this.#reset()
+		this.#queue = run.catch(() => undefined)
+		try {
+			await run
+		} catch (error) {
+			this.close()
+			throw error
+		}
+	}
+
+	/** Follows `batch`, or reads the window again when changes were missed. */
+	async apply(batch: Batch, loader: Loader, missed: boolean): Promise<void> {
+		const [, settled] = this.#enqueue(async () =>
+			missed ? this.#reset() : this.#apply(batch, loader),
+		)
+		return settled
+	}
+
+	/** Takes the caller's new plan; a changed one reads the window again. */
+	async replan(caller: Caller, plan: LivePlan): Promise<void> {
+		const [, settled] = this.#enqueue(async () => {
+			const same =
+				JSON.stringify(plan) === JSON.stringify(this.#plan) &&
+				JSON.stringify(caller) === JSON.stringify(this.caller)
+			this.caller = caller
+			if (same) return
+			this.#plan = plan
+			this.#reach = reachOf(liveSchema(), this.#spec.model, plan)
+			await this.#reset()
+		})
+		return settled
+	}
+
+	/** Shows `more` rows after the last one. */
+	async grow(more: number): Promise<void> {
+		const [run] = this.#enqueue(async () => {
+			this.#window.mark()
+			this.#window.first += more
+			// Sent even when no row follows: the client waits for it.
+			await this.#send(new Set(), new Set(), false, true)
+		})
+		return run
+	}
+
+	/** Reads the window again and sends it whole. */
+	async resend(): Promise<void> {
+		const [, settled] = this.#enqueue(async () => this.#reset())
+		return settled
+	}
+
+	close(): void {
+		this.#closed = true
+		this.#tracking.clear()
+	}
+
+	#enqueue(task: () => Promise<void>): readonly [Promise<void>, Promise<void>] {
+		const run = this.#queue.then(async () =>
+			this.#closed ? undefined : task(),
+		)
+		const settled = run.catch(async (error: unknown) => this.#recover(error))
+		this.#queue = settled
+		return [run, settled]
+	}
+
+	async #recover(error: unknown): Promise<void> {
+		const { logger, model, send } = this.#spec
+		if (this.#closed) return
+		logger.error(
+			{ err: error },
+			`A live read of ${model} failed: it reads again.`,
+		)
+		try {
+			await this.#reset()
+		} catch (again) {
+			logger.error({ err: again }, `A live read of ${model} failed: it closes.`)
+			this.close()
+			send({ kind: 'closed' })
+		}
+	}
+
+	#entry(row: Row): Entry {
+		const keys = sortKeys(this.#spec.model, row, this.#plan.orderBy)
+		return { id: row.id, keys }
+	}
+
+	/**
+	 * The stored rows after the window's last, from `where` and in order:
+	 * from the flush's read of the read's own filter when its rights, checked
+	 * in memory, leave enough.
+	 */
+	async #after(take: number, loader?: Loader): Promise<readonly Row[]> {
+		const { model } = this.#spec
+		const { where, filter, rights, orderBy } = this.#plan
+		const last = this.#window.entries.at(-1)
+		const page = {
+			orderBy,
+			...(last && { cursor: { id: { equals: last.id } }, skip: 1 }),
+			take,
+		}
+		if (loader !== undefined && inMemory(model, rights)) {
+			const rows = await loader.after(model, {
+				...(filter && { where: filter }),
+				...page,
+			})
+			const kept = rows.filter((row) => matches(model, row, rights))
+			if (kept.length >= take || rows.length < take) return kept.slice(0, take)
+		}
+		return storedRows(model, {
+			...(where && { where }),
+			...page,
+			fields: orderBy.map(({ field }) => field),
+		})
+	}
+
+	async #refill(loader?: Loader): Promise<void> {
+		const missing = this.#window.missing()
+		if (missing <= 0) return
+		const rows = await this.#after(missing + 1, loader)
+		const entries = rows.slice(0, missing).map((row) => this.#entry(row))
+		this.#window.fill(entries, rows.length > missing)
+	}
+
+	async #counted(): Promise<number> {
+		const { queries, where } = this.#spec
+		const args = where === undefined ? {} : { where }
+		return queries.count(args, { as: this.caller })
+	}
+
+	/**
+	 * Reads `ids` as the caller into `nodes`, from the rows the flush loaded
+	 * if any; returns those it cannot read.
+	 */
+	async #read(
+		ids: readonly string[],
+		nodes: Map<string, Row>,
+		loader?: Loader,
+	): Promise<readonly string[]> {
+		if (ids.length === 0) return []
+		const { model, queries, shape } = this.#spec
+		const args = { ...shape, where: { id: { in: ids } } }
+		const found =
+			loader === undefined
+				? await queries.findMany(args, { as: this.caller })
+				: await servedRows(
+						model,
+						args,
+						this.caller,
+						await loader.load(model, ids),
+					)
+		for (const node of found) {
+			nodes.set(node.id, node)
+			this.#tracking.track(node, this.#plan.include)
+		}
+		return ids.filter((id) => !nodes.has(id))
+	}
+
+	/**
+	 * Refills the window and reads the rows it places; a row the caller
+	 * cannot read leaves it, `gone`.
+	 */
+	async #settle(
+		again: ReadonlySet<string>,
+		gone: Set<string>,
+		loader?: Loader,
+	): Promise<{
+		readonly moves: ReturnType<Window['moves']>
+		readonly nodes: ReadonlyMap<string, Row>
+	}> {
+		const nodes = new Map<string, Row>()
+		for (let round = 0; round < 3; round += 1) {
+			await this.#refill(loader)
+			const moves = this.#window.moves(again)
+			const unread = moves.placed.flatMap(({ id }) =>
+				nodes.has(id) ? [] : [id],
+			)
+			const missing = await this.#read(unread, nodes, loader)
+			if (missing.length === 0) return { moves, nodes }
+			for (const id of missing) {
+				this.#window.remove(id)
+				gone.add(id)
+			}
+		}
+		throw new Error('The rows the live plan finds are not readable.')
+	}
+
+	#next(): number {
+		this.#revision += 1
+		return this.#revision
+	}
+
+	async #reset(): Promise<void> {
+		const { model, row, send, totalCount } = this.#spec
+		const { where, orderBy } = this.#plan
+		const { first } = this.#window
+		this.#window = new Window(orderBy, first)
+		this.#tracking.clear()
+		const rows = await storedRows(model, {
+			...(where && { where }),
+			orderBy,
+			take: first + 2,
+			fields: orderBy.map(({ field }) => field),
+		})
+		const entries = rows.slice(0, first + 1).map((each) => this.#entry(each))
+		this.#window.fill(entries, rows.length > first + 1)
+		const { nodes } = await this.#settle(new Set(), new Set())
+		this.#count = totalCount ? await this.#counted() : undefined
+		this.#hasMore = this.#window.hasMore()
+		const shown = this.#window.shown().flatMap(({ id }) => nodes.get(id) ?? [])
+		if (this.#closed) return
+		if (row) {
+			send({ kind: 'row', revision: this.#next(), row: shown[0] ?? null })
+			return
+		}
+		send({
+			kind: 'reset',
+			revision: this.#next(),
+			rows: shown,
+			hasMore: this.#hasMore,
+			...(this.#count !== undefined && { totalCount: this.#count }),
+		})
+	}
+
+	async #apply(batch: Batch, loader: Loader): Promise<void> {
+		const { model, totalCount } = this.#spec
+		const window = this.#window
+		const effect = await affected(
+			{
+				model,
+				reach: this.#reach,
+				window: window.ids(),
+				tracked: this.#tracking.tracked,
+				find: this.#find,
+			},
+			batch,
+		)
+		if (effect === 'resync') return this.#reset()
+		const gone = new Set(effect.deleted)
+		const candidates = [...effect.candidates].filter((id) => !gone.has(id))
+		const rows = await loader.load(model, candidates)
+		const kept = await pass(model, rows, this.#plan.where)
+		const inside = window.ids()
+		const leaving = candidates.filter((id) => inside.has(id) && !kept.has(id))
+		const left = new Map(
+			leaving.flatMap((id) => rows.get(id) ?? []).map((row) => [row.id, row]),
+		)
+		const readable = await pass(model, left, this.#plan.rights)
+		const recount =
+			totalCount &&
+			(candidates.length > 0 || effect.deleted.size > 0 || effect.beyond)
+		// A write that leaves the window as it was costs no pass over it.
+		const touched =
+			gone.size > 0 ||
+			effect.resend.size > 0 ||
+			kept.size > 0 ||
+			leaving.length > 0
+		if (!touched && !recount) return
+		window.mark()
+		for (const id of effect.deleted) window.remove(id)
+		for (const id of leaving) {
+			window.remove(id)
+			if (!readable.has(id)) gone.add(id)
+		}
+		for (const id of kept) {
+			const row = rows.get(id)
+			if (row !== undefined) window.place(this.#entry(row))
+		}
+		await this.#send(effect.resend, gone, recount, false, loader)
+	}
+
+	/** Sends how the rows shown at the mark changed, if they did or `always`. */
+	async #send(
+		again: ReadonlySet<string>,
+		gone: Set<string>,
+		recount: boolean,
+		always = false,
+		loader?: Loader,
+	): Promise<void> {
+		const { row, send } = this.#spec
+		const { moves, nodes } = await this.#settle(again, gone, loader)
+		for (const id of moves.removed) this.#tracking.untrack(id)
+		let totalCount: number | undefined
+		if (recount) {
+			const count = await this.#counted()
+			if (count !== this.#count) totalCount = count
+			this.#count = count
+		}
+		if (this.#closed) return
+		if (row) {
+			if (moves.removed.length + moves.placed.length === 0) return
+			const [entry] = this.#window.shown()
+			const shown = entry === undefined ? null : (nodes.get(entry.id) ?? null)
+			send({ kind: 'row', revision: this.#next(), row: shown })
+			return
+		}
+		const changes = [
+			...moves.removed.map((id) => ({ remove: id, gone: gone.has(id) })),
+			...moves.placed.flatMap(({ id, after }) => {
+				const node = nodes.get(id)
+				return node === undefined ? [] : [{ upsert: node, after }]
+			}),
+		]
+		const hasMore = this.#window.hasMore()
+		const more = hasMore !== this.#hasMore
+		this.#hasMore = hasMore
+		if (changes.length === 0 && !more && totalCount === undefined && !always) {
+			return
+		}
+		send({
+			kind: 'changes',
+			revision: this.#next(),
+			changes,
+			...(more && { hasMore }),
+			...(totalCount !== undefined && { totalCount }),
+		})
+	}
+}

package/src/messages.ts

@@ -0,0 +1,39 @@
+// What a live read sends (D-154); a transport writes it in its own shape.
+import type { Row } from 'ultimabase'
+
+/** A row that left the window, `gone` when deleted or no longer readable. */
+export type Removal = { readonly remove: string; readonly gone: boolean }
+/** A row placed after another, first with `after: null`. */
+export type Upsert = { readonly upsert: Row; readonly after: string | null }
+
+/** What a live read sends; `revision` grows by one per message. */
+export type LiveMessage =
+	| {
+			readonly kind: 'reset'
+			readonly revision: number
+			readonly rows: readonly Row[]
+			readonly hasMore: boolean
+			readonly totalCount?: number
+	  }
+	| {
+			readonly kind: 'changes'
+			readonly revision: number
+			readonly changes: readonly (Removal | Upsert)[]
+			/** Only when it changed. */
+			readonly hasMore?: boolean
+			/** Only when it changed. */
+			readonly totalCount?: number
+	  }
+	| {
+			readonly kind: 'row'
+			readonly revision: number
+			readonly row: Row | null
+	  }
+	| {
+			readonly kind: 'value'
+			readonly revision: number
+			/** A live function's whole result. */
+			readonly value: unknown
+	  }
+	/** With the error a live function failed with, which closed it. */
+	| { readonly kind: 'closed'; readonly error?: unknown }