@human-synthesis/norns 0.0.16 → 0.2.0

package/src/server/events.js

@@ -0,0 +1,86 @@
+import { publishRefresh } from './live.js';
+
+/**
+ * Event bus behind `container.resolve('events')` — the target of generated
+ * `emit` steps and spec triggers.
+ *
+ * Local mode (default): `emit` dispatches in-process, awaiting every matching
+ * handler. Queue mode (`{ queue }` — a Cloudflare Queues producer binding):
+ * `emit` enqueues `{ name, payload }` and delivery happens in the consumer
+ * Worker, whose queue handler calls `events.consumer()` on an instance with
+ * the same handlers registered.
+ *
+ * `on(name)` matches exact names; `on('*')` sees everything.
+ *
+ * @param {{ queue?: { send(body: *): Promise<void> | void } }} [opts]
+ */
+export function createEvents({ queue } = {}) {
+	/** @type {Map<string, Set<(payload: *, name: string) => *>>} */
+	const handlers = new Map();
+
+	async function dispatch(name, payload) {
+		const matched = [...(handlers.get(name) ?? []), ...(handlers.get('*') ?? [])];
+		for (const fn of matched) await fn(payload, name);
+		return matched.length;
+	}
+
+	return {
+		on(name, fn) {
+			if (!handlers.has(name)) handlers.set(name, new Set());
+			handlers.get(name).add(fn);
+			return () => handlers.get(name)?.delete(fn);
+		},
+
+		async emit(name, payload) {
+			if (queue) return queue.send({ name, payload });
+			return dispatch(name, payload);
+		},
+
+		/** Consumer-side delivery, bypassing the queue. */
+		dispatch,
+
+		/**
+		 * Cloudflare Queues batch handler: `queue(batch) { return events.consumer()(batch) }`.
+		 * Acks per message; a throwing handler retries that message only.
+		 */
+		consumer() {
+			return async (batch) => {
+				for (const msg of batch.messages) {
+					try {
+						await dispatch(msg.body.name, msg.body.payload);
+						msg.ack?.();
+					} catch {
+						msg.retry?.();
+					}
+				}
+			};
+		}
+	};
+}
+
+/**
+ * Wire generated trigger tables (`[{ on, action }]`) into the bus. The
+ * payload convention matches emitted `emit` steps: `{ row, input, user }`;
+ * actions fall back to `{ id: row.id }` input when the event carries none.
+ *
+ * @param {*} container
+ * @param {{ on: string, action: { run(ctx: *): * } }[]} triggers
+ * @returns {() => void} unsubscribe-all
+ */
+export function registerTriggers(container, triggers) {
+	const events = container.resolve('events');
+	const offs = triggers.map(({ on, action }) =>
+		events.on(on, async (payload = {}) => {
+			const result = await action.run({
+				input: payload.input ?? (payload.row ? { id: payload.row.id } : {}),
+				container,
+				user: payload.user
+			});
+			await publishRefresh(container, action.refresh);
+			return result;
+		})
+	);
+	return () => {
+		for (const off of offs) off();
+	};
+}

package/src/server/guard.js

@@ -0,0 +1,48 @@
+import { error } from '@sveltejs/kit';
+
+/**
+ * Deny-by-default policy guard over the CEL-compiled policy objects the
+ * generator emits (`{ read: { check, where }, write: { check, where }, run? }`).
+ *
+ * - Missing policy, missing rule, or a rule without a `check` function → 403.
+ * - A `check` that throws counts as a denial, never as a bypass.
+ *
+ * @param {*} policy   emitted policy object (e.g. `OrderPolicy`)
+ * @param {'read' | 'write'} kind
+ * @param {{ row?: *, user?: * }} [ctx]
+ * @returns {true}
+ */
+export function guard(policy, kind, { row, user } = {}) {
+	const rule = policy?.[kind];
+	if (typeof rule?.check !== 'function') throw error(403, 'forbidden');
+	let ok = false;
+	try {
+		ok = rule.check(row, user) === true;
+	} catch {
+		ok = false;
+	}
+	if (!ok) throw error(403, 'forbidden');
+	return true;
+}
+
+/**
+ * Guard a named action against `policy.run[action]` predicates. Actions
+ * without a run rule pass (the write guard is the floor; run rules narrow).
+ *
+ * @param {*} policy
+ * @param {string} action
+ * @param {{ row?: *, user?: * }} [ctx]
+ * @returns {true}
+ */
+export function guardRun(policy, action, { row, user } = {}) {
+	const rule = policy?.run?.[action];
+	if (rule === undefined) return true;
+	let ok = false;
+	try {
+		ok = (typeof rule === 'function' ? rule(row, user) : rule) === true;
+	} catch {
+		ok = false;
+	}
+	if (!ok) throw error(403, 'forbidden');
+	return true;
+}

package/src/server/handle/auth.js

@@ -0,0 +1,54 @@
+/** @typedef {import('@sveltejs/kit').Handle} Handle */
+
+/**
+ * Normalize a better-auth user for policy predicates: `owner` compares
+ * `row[ownerField] === user.id`; `role:x` checks `user.roles.includes('x')`.
+ * better-auth's admin plugin stores roles as a comma-separated `role` string.
+ *
+ * @param {*} user
+ * @returns {{ id: *, roles: string[] } | null}
+ */
+export function normalizeUser(user) {
+	if (!user) return null;
+	const roles = Array.isArray(user.roles)
+		? user.roles
+		: typeof user.role === 'string'
+			? user.role.split(',').map((r) => r.trim()).filter(Boolean)
+			: [];
+	return { ...user, roles };
+}
+
+/**
+ * Session middleware over a better-auth instance (`betterAuth({...})`):
+ *
+ * - requests under `basePath` (default `/api/auth`) go straight to
+ *   better-auth's fetch handler (sign-in/out, callbacks, etc.)
+ * - for everything else the session is resolved once per request;
+ *   `event.locals.user` / `event.locals.session` are set, and — when
+ *   `contextHandle` already attached a request scope — `user` and `session`
+ *   are bound into `event.locals.container` so downstream code can
+ *   `container.resolve('user')`.
+ *
+ * Anonymous requests get `user: null`; policy guards deny by default.
+ *
+ * @param {{ handler(req: Request): Response | Promise<Response>, api: { getSession(opts: { headers: Headers }): * } }} auth
+ * @param {{ basePath?: string }} [opts]
+ * @returns {Handle}
+ */
+export function authHandle(auth, { basePath = '/api/auth' } = {}) {
+	return async ({ event, resolve }) => {
+		if (event.url.pathname === basePath || event.url.pathname.startsWith(`${basePath}/`)) {
+			return auth.handler(event.request);
+		}
+		const session = await auth.api.getSession({ headers: event.request.headers });
+		const user = normalizeUser(session?.user ?? null);
+		event.locals.session = session?.session ?? null;
+		event.locals.user = user;
+		const scope = event.locals.container;
+		if (scope) {
+			scope.single('user', () => user);
+			scope.single('session', () => event.locals.session);
+		}
+		return resolve(event);
+	};
+}

package/src/server/index.js

@@ -3,7 +3,21 @@ export { withScope, getScope, getContainer } from './scope.js';
 export { boot, createApp } from './boot.js';
 export { contextHandle } from './handle/context.js';
 export { errorHandle } from './handle/error.js';
+export { authHandle, normalizeUser } from './handle/auth.js';
 export { route, setSerializer, getSerializer } from './route.js';
 export { page } from './page.js';
 export { validate, ValidationError } from './validate.js';
-export { betterSqlite, d1, libsql, postgres, withTransaction } from './db.js';
+export { guard, guardRun } from './guard.js';
+export { machine } from './machine.js';
+export { createEvents, registerTriggers } from './events.js';
+export { cronMatches, cronTriggers, scheduledHandler, startCronShim } from './cron.js';
+export { r2Storage, dirStorage } from './storage.js';
+export { Room, roomStub } from './room.js';
+export { REFRESH_EVENT, dependsKey, createLive, publishRefresh, liveHandler, remoteAction } from './live.js';
+export { betterSqlite, d1, libsql, postgres, withTransaction, applyMigrations } from './db.js';
+export { serviceClient, ServiceError } from './service.js';
+export { job, runJob, registerJobs, createJobs, backoffMs } from './job.js';
+export { endpoint } from './endpoint.js';
+// Runtime-safe re-export for generated policies.c — the kernel entry itself
+// pulls CLI-only node builtins and must stay out of worker bundles.
+export { compileWhere } from '../kernel/expr-compile.js';

package/src/server/job.js

@@ -0,0 +1,102 @@
+/**
+ * Job runtime (K-22/R-14). Generated `lib/<m>/jobs.c` wraps each unit in
+ * `job({...})`; `registerJobs` subscribes them to `job:<address>` bus
+ * messages, and the `jobs` container facade enqueues through the same bus —
+ * production rides Cloudflare Queues (boot `queue` opt) while dev runs
+ * inline, awaited, with the same retry/backoff/DLQ semantics.
+ */
+
+/**
+ * @typedef {{
+ *   address: string,
+ *   retry?: { attempts: number, backoff: 'none'|'fixed'|'exponential', baseMs?: number },
+ *   dlq?: string,
+ *   concurrency?: number,
+ *   run: (ctx: { input: *, container: *, user?: * }) => Promise<*>
+ * }} JobDef
+ */
+
+/** Identity wrapper — the shape is the contract. @param {JobDef} def */
+export function job(def) {
+	return def;
+}
+
+/** Delay before retry `attempt` (1-based) under a retry policy. */
+export function backoffMs(retry, attempt) {
+	const base = retry?.baseMs ?? 1000;
+	switch (retry?.backoff) {
+		case 'fixed':
+			return base;
+		case 'exponential':
+			return base * 2 ** (attempt - 1);
+		default:
+			return 0;
+	}
+}
+
+const sleep = (ms) => (ms > 0 ? new Promise((r) => setTimeout(r, ms)) : Promise.resolve());
+
+/**
+ * Run a job under its declared retry policy. On exhaustion: with a `dlq`,
+ * a `dlq:<name>` event carries the failure and the message counts as
+ * handled; without one the error rethrows (in queue mode Cloudflare then
+ * applies its own message retry).
+ *
+ * @param {JobDef} jobDef
+ * @param {{ input: *, container: *, user?: * }} ctx
+ */
+export async function runJob(jobDef, ctx) {
+	const attempts = jobDef.retry?.attempts ?? 1;
+	for (let attempt = 1; ; attempt++) {
+		try {
+			return await jobDef.run(ctx);
+		} catch (err) {
+			if (attempt < attempts) {
+				await sleep(backoffMs(jobDef.retry, attempt));
+				continue;
+			}
+			if (jobDef.dlq) {
+				await ctx.container.resolve('events').emit(`dlq:${jobDef.dlq}`, {
+					job: jobDef.address,
+					input: ctx.input,
+					error: String(err?.message ?? err),
+					attempts: attempt
+				});
+				return undefined;
+			}
+			throw err;
+		}
+	}
+}
+
+/**
+ * Wire job tables (generated `jobs` maps, address → JobDef) into the bus.
+ *
+ * @param {*} container
+ * @param {Record<string, JobDef> | Record<string, JobDef>[]} tables
+ * @returns {() => void} unsubscribe-all
+ */
+export function registerJobs(container, tables) {
+	const events = container.resolve('events');
+	const offs = [];
+	for (const table of Array.isArray(tables) ? tables : [tables]) {
+		for (const [address, jobDef] of Object.entries(table ?? {})) {
+			offs.push(
+				events.on(`job:${address}`, (payload = {}) =>
+					runJob(jobDef, { input: payload.input ?? {}, container, user: payload.user })
+				)
+			);
+		}
+	}
+	return () => {
+		for (const off of offs) off();
+	};
+}
+
+/** The `jobs` container facade behind generated `enqueue` steps. */
+export function createJobs(container) {
+	return {
+		enqueue: (address, input, user) =>
+			container.resolve('events').emit(`job:${address}`, { input, user })
+	};
+}

package/src/server/live.js

@@ -0,0 +1,134 @@
+/**
+ * Live-query bridge (R-11) — publishes "these queries changed" signals to
+ * connected clients so pages with `live: true` queries can re-run their
+ * loads.
+ *
+ * Dev/local (single process): refresh signals ride the in-process event bus
+ * and stream out of `/_norns/live` as SSE directly.
+ *
+ * Workers prod (many isolates): pass the `ROOM` Durable Object namespace as
+ * `room` — publishes are forwarded to the Room instance (R-08) and the SSE
+ * endpoint proxies to it, so every isolate's clients share one fanout point.
+ *
+ * The payload is only ever a list of query addresses — no row data crosses
+ * the live channel; clients re-run their loads through the normal
+ * policy-guarded path.
+ */
+
+import { route } from './route.js';
+
+export const REFRESH_EVENT = 'norns:refresh';
+
+/** SvelteKit `depends`/`invalidate` key for a query address. */
+export const dependsKey = (address) => `norns:${address}`;
+
+const ENC = new TextEncoder();
+
+/**
+ * @param {{
+ *   events: { emit(name: string, payload: *): *, on(name: string, fn: (payload: *) => *): () => void },
+ *   room?: { idFromName(name: string): *, get(id: *): { fetch(input: *, init?: *): Promise<Response> } },
+ *   roomName?: string,
+ *   heartbeatMs?: number
+ * }} opts
+ */
+export function createLive({ events, room, roomName = 'live', heartbeatMs = 15000 }) {
+	const stub = () => room.get(room.idFromName(roomName));
+
+	return {
+		/** Announce that these query addresses have (potentially) new data. */
+		async publish(queries) {
+			if (!Array.isArray(queries) || queries.length === 0) return;
+			await events.emit(REFRESH_EVENT, { queries });
+			if (room) {
+				await stub().fetch('https://room/publish', {
+					method: 'POST',
+					headers: { 'content-type': 'application/json' },
+					body: JSON.stringify({ queries })
+				});
+			}
+		},
+
+		/** @param {(payload: { queries: string[] }) => *} fn */
+		subscribe(fn) {
+			return events.on(REFRESH_EVENT, fn);
+		},
+
+		/** SSE handler for the `/_norns/live` endpoint. */
+		handler(event) {
+			if (room) {
+				return stub().fetch('https://room/sse', { headers: event.request.headers });
+			}
+			let off = () => {};
+			let timer;
+			let open = true;
+			const stream = new ReadableStream({
+				start(controller) {
+					const send = (text) => {
+						if (!open) return;
+						try {
+							controller.enqueue(ENC.encode(text));
+						} catch {
+							open = false;
+						}
+					};
+					send(': connected\n\n');
+					off = events.on(REFRESH_EVENT, (payload) => send(`data: ${JSON.stringify(payload)}\n\n`));
+					timer = setInterval(() => send(': ping\n\n'), heartbeatMs);
+				},
+				cancel() {
+					open = false;
+					off();
+					clearInterval(timer);
+				}
+			});
+			return new Response(stream, {
+				headers: {
+					'content-type': 'text/event-stream',
+					'cache-control': 'no-cache',
+					connection: 'keep-alive'
+				}
+			});
+		}
+	};
+}
+
+/**
+ * Publish an action's refresh list through the container's live bridge, if
+ * one is bound. Shared by form actions, remote actions, and triggers.
+ */
+export async function publishRefresh(container, refresh) {
+	if (!Array.isArray(refresh) || refresh.length === 0) return;
+	if (!container?.has?.('live')) return;
+	await container.resolve('live').publish(refresh);
+}
+
+/**
+ * Generated `/_norns/live/+server.c` GET handler — streams refresh signals
+ * for the app booted into `event.locals.container`.
+ */
+export function liveHandler(event) {
+	const container = event.locals?.container;
+	if (!container?.has?.('live')) {
+		return new Response('live bridge not enabled', { status: 404 });
+	}
+	return container.resolve('live').handler(event);
+}
+
+/**
+ * Wrap a generated action unit as a `transport: remote` POST endpoint:
+ * same schema validation and guarded `run` as the form-action path, plus
+ * refresh publication, returned as JSON (or the app serializer).
+ *
+ * @param {{ input?: *, run(ctx: *): *, refresh?: string[] }} action
+ */
+export function remoteAction(action) {
+	return route({
+		input: action.input,
+		handler: async ({ input, container, event, user }) => {
+			const result = await action.run({ input, container, event, user });
+			await publishRefresh(container, action.refresh);
+			return result;
+		}
+	});
+}

package/src/server/machine.js

@@ -0,0 +1,35 @@
+import { error } from '@sveltejs/kit';
+
+/**
+ * Runtime status-machine enforcement over a spec transitions map
+ * (`{ draft: ['submitted'], submitted: ['paid', 'cancelled'], ... }`).
+ * Unknown states and undeclared transitions are always denied.
+ *
+ * @param {Record<string, string[]>} transitions
+ */
+export function machine(transitions) {
+	const states = Object.keys(transitions).sort();
+
+	// Same rule as the generated schema default: the state no transition
+	// targets; falls back to the (sorted) first.
+	const targeted = new Set(Object.values(transitions).flat());
+	const sources = states.filter((s) => !targeted.has(s));
+	const initial = sources.length === 1 ? sources[0] : states[0];
+
+	return {
+		states,
+		initial,
+		can(from, to) {
+			return (transitions[from] ?? []).includes(to);
+		},
+		next(from) {
+			return [...(transitions[from] ?? [])];
+		},
+		assert(from, to) {
+			if (!this.can(from, to)) {
+				throw error(409, `invalid transition ${String(from)} -> ${String(to)}`);
+			}
+			return to;
+		}
+	};
+}

package/src/server/page.js

@@ -1,5 +1,6 @@
 import { fail } from '@sveltejs/kit';
 import { validate, ValidationError } from './validate.js';
+import { publishRefresh } from './live.js';
 
 /** @typedef {import('@sveltejs/kit').ServerLoadEvent} ServerLoadEvent */
 /** @typedef {import('@sveltejs/kit').RequestEvent} RequestEvent */
@@ -52,9 +53,10 @@ export const page = {
 
 	/**
 	 * Wrap a SvelteKit `actions` object. Each action takes `{ input?, run }`
-	 * — `input` is a schema, `run` is the handler.
+	 * — `input` is a schema, `run` is the handler. An action's `refresh` list
+	 * is published through the container's live bridge after a successful run.
 	 *
-	 * @param {Record<string, { input?: any, run: (ctx: ActionContext) => any | Promise<any> }>} spec
+	 * @param {Record<string, { input?: any, run: (ctx: ActionContext) => any | Promise<any>, refresh?: string[] }>} spec
 	 * @returns {Record<string, (event: RequestEvent) => Promise<any>>}
 	 */
 	actions(spec) {
@@ -78,12 +80,14 @@ export const page = {
 						throw e;
 					}
 				}
-				return def.run({
+				const result = await def.run({
 					input,
 					container: event.locals.container,
 					event,
 					user: event.locals.user
 				});
+				await publishRefresh(event.locals.container, def.refresh);
+				return result;
 			};
 		}
 		return out;

package/src/server/room.js

@@ -0,0 +1,179 @@
+/**
+ * Durable Object Room host (R-08) — one instance per room, holding live
+ * connections and in-memory state between requests (validated by the R-13
+ * spike on local workerd).
+ *
+ * Deploy shape: the app exports a DO class extending Room and binds it as
+ * `ROOM` (emit-wrangler adds the binding when specs need it):
+ *
+ *   export class NornsRoom extends Room {}
+ *
+ * Paths served by `fetch`:
+ *   /ws       WebSocket upgrade; incoming messages go to `onMessage`
+ *   /sse      text/event-stream; every `broadcast` becomes a `data:` frame
+ *   /publish  POST (worker-internal) — body is broadcast to every client
+ *   anything else → `{ clients, ticks }` snapshot
+ *
+ * Subclass hooks: `onMessage(data, ws)`, `onTick()`, `persist()`,
+ * `snapshot()` (first SSE frame for a new client), and the knobs `tickMs`
+ * (0 disables ticks) / `persistEvery` (persist() every N ticks; also runs
+ * once when the last client leaves). Ticks only run while clients are
+ * connected.
+ *
+ * Presence (R-16): set `presenceMs > 0` and every join/leave broadcasts
+ * `{ type: 'presence', clients }` — debounced by that window so a
+ * reconnect storm collapses into one frame.
+ */
+
+const ENC = new TextEncoder();
+
+export class Room {
+	tickMs = 1000;
+	persistEvery = 0;
+	presenceMs = 0;
+	#presenceTimer = null;
+
+	constructor(state, env) {
+		this.state = state;
+		this.env = env;
+		this.sockets = new Set();
+		this.streams = new Set();
+		this.ticks = 0;
+		this.timer = null;
+	}
+
+	/* -- subclass hooks ------------------------------------------------ */
+
+	async onMessage(_data, _ws) {}
+	async onTick() {}
+	async persist() {}
+	snapshot() {
+		return null;
+	}
+
+	/* -- connections --------------------------------------------------- */
+
+	get clients() {
+		return this.sockets.size + this.streams.size;
+	}
+
+	/** Send to every connected client (WS + SSE). Returns the client count. */
+	broadcast(message) {
+		const payload = typeof message === 'string' ? message : JSON.stringify(message);
+		for (const ws of this.sockets) {
+			try {
+				ws.send(payload);
+			} catch {
+				this.#leave(this.sockets, ws);
+			}
+		}
+		const frame = ENC.encode(`data: ${payload}\n\n`);
+		for (const writer of this.streams) {
+			writer.write(frame).catch(() => this.#leave(this.streams, writer));
+		}
+		return this.clients;
+	}
+
+	/** Debounced `{ type: 'presence', clients }` broadcast (opt-in via presenceMs). */
+	#presence() {
+		if (this.presenceMs <= 0 || this.#presenceTimer !== null) return;
+		this.#presenceTimer = setTimeout(() => {
+			this.#presenceTimer = null;
+			this.broadcast({ type: 'presence', clients: this.clients });
+		}, this.presenceMs);
+	}
+
+	#join(set, item) {
+		set.add(item);
+		this.#presence();
+		if (this.timer === null && this.tickMs > 0) {
+			this.timer = setInterval(() => this.#tick(), this.tickMs);
+		}
+	}
+
+	#leave(set, item) {
+		if (!set.delete(item)) return;
+		this.#presence();
+		if (this.clients === 0) {
+			if (this.timer !== null) {
+				clearInterval(this.timer);
+				this.timer = null;
+			}
+			Promise.resolve(this.persist()).catch(() => {});
+		}
+	}
+
+	async #tick() {
+		this.ticks += 1;
+		await this.onTick();
+		if (this.persistEvery > 0 && this.ticks % this.persistEvery === 0) {
+			await this.persist();
+		}
+	}
+
+	/* -- request surface ------------------------------------------------ */
+
+	async fetch(request) {
+		const url = new URL(request.url);
+
+		if (url.pathname === '/ws') {
+			if (typeof WebSocketPair === 'undefined') {
+				return new Response('WebSocket unsupported on this runtime', { status: 501 });
+			}
+			const pair = new WebSocketPair();
+			const [client, server] = Object.values(pair);
+			server.accept();
+			this.#join(this.sockets, server);
+			server.addEventListener('message', (e) => {
+				Promise.resolve(this.onMessage(e.data, server)).catch(() => {});
+			});
+			server.addEventListener('close', () => this.#leave(this.sockets, server));
+			return new Response(null, { status: 101, webSocket: client });
+		}
+
+		if (url.pathname === '/sse') {
+			const { readable, writable } = new TransformStream();
+			const writer = writable.getWriter();
+			writer.write(ENC.encode(': connected\n\n')).catch(() => {});
+			const first = this.snapshot();
+			if (first !== null && first !== undefined) {
+				writer.write(ENC.encode(`data: ${JSON.stringify(first)}\n\n`)).catch(() => {});
+			}
+			this.#join(this.streams, writer);
+			request.signal?.addEventListener('abort', () => {
+				this.#leave(this.streams, writer);
+				writer.close().catch(() => {});
+			});
+			return new Response(readable, {
+				headers: {
+					'content-type': 'text/event-stream',
+					'cache-control': 'no-cache',
+					connection: 'keep-alive'
+				}
+			});
+		}
+
+		if (url.pathname === '/publish' && request.method === 'POST') {
+			let body = null;
+			try {
+				body = await request.json();
+			} catch {
+				return Response.json({ ok: false, error: 'body must be JSON' }, { status: 400 });
+			}
+			const clients = this.broadcast(body ?? {});
+			return Response.json({ ok: true, clients });
+		}
+
+		return Response.json({ clients: this.clients, ticks: this.ticks });
+	}
+}
+
+/**
+ * Resolve the DO stub for a named room on a namespace binding (`env.ROOM`).
+ *
+ * @param {{ idFromName(name: string): *, get(id: *): * }} namespace
+ * @param {string} [name]
+ */
+export function roomStub(namespace, name = 'default') {
+	return namespace.get(namespace.idFromName(name));
+}