@ultimabase/realtime 0.0.0-stage → 0.1.0

package/src/viewer.ts

@@ -0,0 +1,389 @@
+// A viewer (D-154): one connection's caller and its live reads. The reads
+// that built the caller and planned each live read are kept; a write that
+// may change one rebuilds the caller, which resyncs the reads whose plan
+// changed and closes them all when it is no longer the same user. A caller
+// that stops holding at a time is built again then. A live function runs
+// again as the rebuilt caller.
+import type { Caller, ExposedFunction, ExposedModel, Logger } from 'ultimabase'
+import type { Recorded } from 'ultimabase/internal'
+import { livePlan, recording } from 'ultimabase/internal'
+import type { Batch } from './changes.ts'
+import { checked, invalid } from './checked.ts'
+import { Computed } from './computed.ts'
+import type { LiveMessage } from './messages.ts'
+import { Live } from './live.ts'
+import type { Loader } from './reads.ts'
+import { liveArgs, shapeOf } from './shape.ts'
+import { anyStale } from './stale.ts'
+
+export type Settings = {
+	readonly models: readonly ExposedModel<{ readonly maxLive?: number }>[]
+	readonly functions: readonly ExposedFunction<{ readonly debounce?: number }>[]
+	readonly maxLive: number
+	readonly maxSubscriptions: number
+	readonly maxConnectionRows: number
+	readonly identify: (request: Request) => Promise<Caller>
+	readonly logger: Logger
+}
+
+/** A live read's handle. */
+export interface LiveHandle {
+	/** Shows `more` rows after the last; a list over its limit is refused. */
+	grow(this: void, more: number): Promise<void>
+	/** Sends the whole window again, as after messages were dropped. */
+	resend(this: void): Promise<void>
+	close(this: void): void
+}
+
+type Subscription = {
+	readonly model: string
+	readonly args: unknown
+	readonly row: boolean
+	readonly send: (message: LiveMessage) => void
+	/** The rows it follows, nested rows included. */
+	rows: number
+	reads: readonly Recorded[]
+	expires: Date | undefined
+}
+
+type Built<R> = Awaited<ReturnType<typeof recording<R>>>
+
+/** The least wait before a rebuild, so a past expiry is no hot loop. */
+const soonest = 1000
+/** The longest wait `setTimeout` keeps. */
+const latest = 2 ** 31 - 1
+
+/** A function's name, with its plugin's for a plugin's (D-113). */
+export const ownerOf = (fn: ExposedFunction): string =>
+	fn.plugin === undefined ? fn.name : `${fn.plugin}.${fn.name}`
+
+/** How long a live function's wake waits for quiet, in milliseconds. */
+const debounce = 50
+
+/** Who `caller` is, which a rebuilt caller must keep. */
+const whoOf = (caller: Caller): string => {
+	if (caller.kind !== 'user') return JSON.stringify(caller)
+	const id: unknown = Reflect.get(caller.user, 'id')
+	return JSON.stringify(['user', id])
+}
+
+export class Viewer {
+	readonly #settings: Settings
+	#request: Request
+	readonly #onClose: () => void
+	readonly #onDue: () => void
+	readonly #live = new Map<Live, Subscription>()
+	readonly #computed = new Map<Computed, (message: LiveMessage) => void>()
+	#caller: Caller
+	#reads: readonly Recorded[]
+	#expires: Date | undefined
+	#due: NodeJS.Timeout | undefined
+	#closed = false
+
+	/** `onDue` runs once the caller stops holding, to rebuild it. */
+	constructor(
+		settings: Settings,
+		request: Request,
+		identified: Built<Caller>,
+		hooks: { readonly onClose: () => void; readonly onDue: () => void },
+	) {
+		this.#settings = settings
+		this.#request = request
+		this.#caller = identified.result
+		this.#reads = identified.reads
+		this.#expires = identified.expires
+		this.#onClose = hooks.onClose
+		this.#onDue = hooks.onDue
+		this.#reschedule()
+	}
+
+	/** The caller the live reads run as, kept current by each rebuild. */
+	get caller(): Caller {
+		return this.#caller
+	}
+
+	get closed(): boolean {
+		return this.#closed
+	}
+
+	/** A live list of `model`'s rows, from the top of its order. */
+	async list(
+		model: string,
+		args: unknown,
+		send: (message: LiveMessage) => void,
+	): Promise<LiveHandle> {
+		return this.#follow(model, args, false, send)
+	}
+
+	/** A live row of `model`, by a unique `where`. */
+	async row(
+		model: string,
+		args: unknown,
+		send: (message: LiveMessage) => void,
+	): Promise<LiveHandle> {
+		return this.#follow(model, args, true, send)
+	}
+
+	/**
+	 * A live function's result, `compute` as the caller, run again once a
+	 * write may change what it read.
+	 */
+	async value(
+		name: string,
+		compute: (caller: Caller) => Promise<unknown>,
+		send: (message: LiveMessage) => void,
+	): Promise<LiveHandle> {
+		if (this.#closed) throw new Error('The viewer is closed.')
+		const exposed = this.#settings.functions.find((fn) => ownerOf(fn) === name)
+		if (!exposed?.used) throw invalid('function', `${name} is not live.`)
+		this.#holds()
+		const computed = new Computed(
+			{
+				compute,
+				send,
+				debounce: exposed.with?.debounce ?? debounce,
+				onRun: () => this.#reschedule(),
+				onFail: () => this.#computed.delete(computed),
+			},
+			this.#caller,
+		)
+		this.#computed.set(computed, send)
+		try {
+			await computed.start()
+		} catch (error) {
+			this.#computed.delete(computed)
+			throw error
+		}
+		return {
+			grow: async () => {
+				throw invalid('first', `${name} is no live list.`)
+			},
+			resend: async () => computed.resend(),
+			close: () => {
+				computed.close()
+				this.#computed.delete(computed)
+			},
+		}
+	}
+
+	close(): void {
+		if (this.#closed) return
+		this.#closed = true
+		clearTimeout(this.#due)
+		for (const live of this.#live.keys()) live.close()
+		this.#live.clear()
+		for (const computed of this.#computed.keys()) computed.close()
+		this.#computed.clear()
+		this.#onClose()
+	}
+
+	/** Follows `batch`: rebuilds the caller first when a write may change it. */
+	async flush(batch: Batch, loader: Loader, missed: boolean): Promise<void> {
+		if (this.#closed) return
+		const reads = [
+			...this.#reads,
+			...[...this.#live.values()].flatMap((subscription) => subscription.reads),
+		]
+		if (missed || (await anyStale(reads, batch, loader))) {
+			await this.rebuild()
+		}
+		const lives = [...this.#live.keys(), ...this.#computed.keys()]
+		await Promise.all(
+			lives.map(async (live) => live.apply(batch, loader, missed)),
+		)
+	}
+
+	/**
+	 * Follows `request`'s caller from now on, built again at once; whether
+	 * it is the same user, as a closed viewer is not.
+	 */
+	async adopt(request: Request): Promise<boolean> {
+		this.#request = request
+		await this.rebuild()
+		return !this.#closed
+	}
+
+	/** Builds the caller again, then each live read's plan. */
+	async rebuild(): Promise<void> {
+		if (this.#closed) return
+		let identified: Built<Caller>
+		try {
+			identified = await recording(async () =>
+				this.#settings.identify(this.#request),
+			)
+		} catch {
+			return this.end()
+		}
+		const caller = identified.result
+		if (whoOf(caller) !== whoOf(this.#caller)) return this.end()
+		this.#caller = caller
+		this.#reads = identified.reads
+		this.#expires = identified.expires
+		await Promise.all(
+			[...this.#live].map(async ([live, subscription]) => {
+				try {
+					const { model, args, row } = subscription
+					const planned = await recording(async () =>
+						livePlan(model, liveArgs(args, row), caller, row),
+					)
+					subscription.reads = planned.reads
+					subscription.expires = planned.expires
+					await live.replan(caller, planned.result)
+				} catch (error) {
+					this.#settings.logger.error(
+						{ err: error },
+						`A live read of ${subscription.model} cannot be planned: it closes.`,
+					)
+					this.#drop(live)
+				}
+			}),
+		)
+		await Promise.all(
+			[...this.#computed.keys()].map(async (computed) =>
+				computed.replan(caller),
+			),
+		)
+		this.#reschedule()
+	}
+
+	/** Waits for the earliest time the caller or a live read stops holding. */
+	#reschedule(): void {
+		clearTimeout(this.#due)
+		this.#due = undefined
+		if (this.#closed) return
+		const subscriptions = [...this.#live.values(), ...this.#computed.keys()]
+		const times = [
+			this.#expires,
+			...subscriptions.map(({ expires }) => expires),
+		]
+			.filter((at) => at !== undefined)
+			.map((at) => at.getTime())
+		if (times.length === 0) return
+		const wait = Math.min(
+			Math.max(Math.min(...times) - Date.now(), soonest),
+			latest,
+		)
+		this.#due = setTimeout(this.#onDue, wait)
+		this.#due.unref()
+	}
+
+	#drop(live: Live): void {
+		const subscription = this.#live.get(live)
+		live.close()
+		this.#live.delete(live)
+		subscription?.send({ kind: 'closed' })
+	}
+
+	/** Closes every live read, telling each. */
+	end(): void {
+		const sends = [
+			...[...this.#live.values()].map(({ send }) => send),
+			...this.#computed.values(),
+		]
+		this.close()
+		for (const send of sends) send({ kind: 'closed' })
+	}
+
+	async #follow(
+		model: string,
+		args: unknown,
+		row: boolean,
+		send: (message: LiveMessage) => void,
+	): Promise<LiveHandle> {
+		if (this.#closed) throw new Error('The viewer is closed.')
+		const exposed = this.#settings.models.find(
+			({ schema }) => schema.name === model,
+		)
+		if (!exposed?.used) throw invalid('model', `${model} is not live.`)
+		this.#holds()
+		const { first, where, totalCount, shape } = shapeOf(args, row)
+		const caller = this.#caller
+		const planned = await recording(async () =>
+			livePlan(model, liveArgs(args, row), caller, row),
+		)
+		const limit = exposed.with?.maxLive ?? this.#settings.maxLive
+		const nested = checked(
+			this.#settings.models,
+			model,
+			planned.result,
+			'include',
+		)
+		if (first * (1 + nested) > limit) {
+			throw invalid(
+				'first',
+				`first is over ${limit}, the most a live list follows.`,
+			)
+		}
+		this.#fits(first * (1 + nested))
+		const live = new Live(
+			{
+				model,
+				queries: exposed.queries,
+				where,
+				shape,
+				totalCount,
+				row,
+				send,
+				logger: this.#settings.logger,
+			},
+			caller,
+			planned.result,
+			first,
+		)
+		const { reads, expires } = planned
+		const rows = first * (1 + nested)
+		const subscription = { model, args, row, send, rows, reads, expires }
+		this.#live.set(live, subscription)
+		try {
+			await live.start()
+		} catch (error) {
+			this.#live.delete(live)
+			throw error
+		}
+		this.#reschedule()
+		return {
+			grow: async (more) => {
+				if (!Number.isInteger(more) || more < 1) {
+					throw invalid('first', 'first must be a positive integer.')
+				}
+				if ((live.first + more) * (1 + nested) > limit) {
+					throw invalid(
+						'first',
+						`first is over ${limit}, the most a live list follows.`,
+					)
+				}
+				const grown = (live.first + more) * (1 + nested)
+				this.#fits(grown - subscription.rows)
+				subscription.rows = grown
+				return live.grow(more)
+			},
+			resend: async () => live.resend(),
+			close: () => {
+				live.close()
+				this.#live.delete(live)
+			},
+		}
+	}
+
+	/** Refuses one more live read past what the connection holds. */
+	#holds(): void {
+		const { maxSubscriptions } = this.#settings
+		if (this.#live.size + this.#computed.size < maxSubscriptions) return
+		throw invalid(
+			'subscriptions',
+			`A connection holds at most ${maxSubscriptions} live reads.`,
+		)
+	}
+
+	/** Refuses `more` rows past what the connection follows in all. */
+	#fits(more: number): void {
+		const { maxConnectionRows } = this.#settings
+		let rows = more
+		for (const subscription of this.#live.values()) rows += subscription.rows
+		if (rows <= maxConnectionRows) return
+		throw invalid(
+			'first',
+			`A connection follows at most ${maxConnectionRows} rows.`,
+		)
+	}
+}

package/src/window.ts

@@ -0,0 +1,153 @@
+// A live list's window (D-154): the first rows of its order, each kept as
+// its id and sort keys, never as the row it shows, and one row more, which
+// says whether rows follow without a read. A row is placed by a binary
+// search; one placed after the last row, when rows may follow, is outside.
+// It notes the rows it changes since a mark, so what changed costs what was
+// changed, not a pass over it.
+import type { Order } from 'ultimabase'
+import { compareKeys } from 'ultimabase/internal'
+
+export type Entry = { readonly id: string; readonly keys: readonly unknown[] }
+
+/** What changed between two windows, in the order a client applies it. */
+export type Moves = {
+	readonly removed: readonly string[]
+	/** Each row placed again, after the row before it, `null` for the first. */
+	readonly placed: readonly {
+		readonly id: string
+		readonly after: string | null
+	}[]
+}
+
+export class Window {
+	readonly #entries: Entry[] = []
+	readonly #ids = new Set<string>()
+	/** Rows may follow the last entry. */
+	rest = false
+	first: number
+	readonly #orderBy: readonly Order[]
+	/** The rows changed since the mark, each with its keys then, if it was in. */
+	#was: Map<string, readonly unknown[] | undefined> | undefined
+	/** The row past those shown at the mark. */
+	#extra: string | undefined
+
+	constructor(orderBy: readonly Order[], first: number) {
+		this.#orderBy = orderBy
+		this.first = first
+	}
+
+	/** Starts noting changes: `moves` tells those since. */
+	mark(): void {
+		this.#was = new Map()
+		this.#extra = this.#entries[this.first]?.id
+	}
+
+	#note(id: string, keys: readonly unknown[] | undefined): void {
+		const was = this.#was
+		if (was !== undefined && !was.has(id)) was.set(id, keys)
+	}
+
+	/** The rows a client shows. */
+	get entries(): readonly Entry[] {
+		return this.#entries
+	}
+
+	shown(): readonly Entry[] {
+		return this.#entries.slice(0, this.first)
+	}
+
+	hasMore(): boolean {
+		return this.#entries.length > this.first
+	}
+
+	/** The ids of the entries, kept as they change. */
+	ids(): ReadonlySet<string> {
+		return this.#ids
+	}
+
+	/** How many rows a read after the last entry must bring. */
+	missing(): number {
+		return this.rest ? this.first + 1 - this.#entries.length : 0
+	}
+
+	/** Adds the rows read after the last entry. */
+	fill(entries: readonly Entry[], rest: boolean): void {
+		this.#entries.push(...entries)
+		for (const { id } of entries) {
+			this.#note(id, undefined)
+			this.#ids.add(id)
+		}
+		this.rest = rest
+	}
+
+	remove(id: string): boolean {
+		if (!this.#ids.delete(id)) return false
+		const at = this.#entries.findIndex((entry) => entry.id === id)
+		this.#note(id, this.#entries[at]?.keys)
+		this.#entries.splice(at, 1)
+		return true
+	}
+
+	/** Places a row that passes the filter, or leaves it outside. */
+	place(entry: Entry): void {
+		this.remove(entry.id)
+		const entries = this.#entries
+		let low = 0
+		let high = entries.length
+		while (low < high) {
+			const middle = (low + high) >> 1
+			const keys = entries[middle]?.keys ?? []
+			if (compareKeys(keys, entry.keys, this.#orderBy) < 0) low = middle + 1
+			else high = middle
+		}
+		if (low === entries.length && this.rest) return
+		this.#note(entry.id, undefined)
+		entries.splice(low, 0, entry)
+		this.#ids.add(entry.id)
+		const last = entries.length > this.first + 1 ? entries.pop() : undefined
+		if (last !== undefined) {
+			this.#note(last.id, last.keys)
+			this.#ids.delete(last.id)
+			this.rest = true
+		}
+	}
+
+	/**
+	 * How the rows shown at the mark, none before the first, became those
+	 * shown now. Only the rows changed since, and the one past the shown rows
+	 * then and now, may have come or gone.
+	 */
+	moves(again: ReadonlySet<string>): Moves {
+		const entries = this.#entries
+		const after = (at: number) => ({
+			id: entries[at]?.id ?? '',
+			after: entries[at - 1]?.id ?? null,
+		})
+		const notes = this.#was
+		if (notes === undefined) {
+			return { removed: [], placed: this.shown().map((_, at) => after(at)) }
+		}
+		const extra = entries[this.first]?.id
+		const was = (id: string): boolean =>
+			id !== this.#extra &&
+			(notes.has(id) ? notes.get(id) !== undefined : this.#ids.has(id))
+		const shown = (id: string): boolean => id !== extra && this.#ids.has(id)
+		const ids = [
+			...new Set([...notes.keys(), ...again, this.#extra, extra]),
+		].filter((id) => id !== undefined)
+		const removed = ids.filter((id) => was(id) && !shown(id))
+		const placed = ids.flatMap((id) => {
+			if (!shown(id)) return []
+			const at = entries.findIndex((entry) => entry.id === id)
+			const old = notes.get(id)
+			// The rows whose keys stayed keep their order among themselves.
+			const still =
+				was(id) &&
+				!again.has(id) &&
+				(old === undefined ||
+					compareKeys(old, entries[at]?.keys ?? [], this.#orderBy) === 0)
+			return still ? [] : [at]
+		})
+		return { removed, placed: placed.toSorted((a, b) => a - b).map(after) }
+	}
+}