@human-synthesis/norns 0.1.0 → 0.2.1

package/src/live-client.js

@@ -40,6 +40,150 @@ export function liveQueries(addresses, invalidate, opts = {}) {
 	return () => source.close();
 }
 
+/**
+ * Read a streaming Endpoint (K-23 typed SSE frames) as an async iterator
+ * (R-16). Backpressure-aware — the response body is only pulled when the
+ * consumer asks for the next frame — and abortable: breaking out of the
+ * loop (or firing `opts.signal`) aborts the underlying request.
+ *
+ *   for await (const frame of streamSource('/api/chat', { input: { prompt } }))
+ *     text += frame.delta
+ *
+ * @param {string} url the Endpoint's declared route
+ * @param {{ input?: *, method?: string, signal?: AbortSignal, fetch?: typeof fetch }} [opts]
+ *   `input` is sent as a JSON POST body (streaming endpoints take their
+ *   input up front); omit it for GET-style streams.
+ * @returns {AsyncGenerator<*>} parsed `data:` frames (JSON when possible)
+ */
+export async function* streamSource(url, opts = {}) {
+	const f = opts.fetch ?? globalThis.fetch;
+	const controller = new AbortController();
+	const abort = () => controller.abort();
+	opts.signal?.addEventListener('abort', abort, { once: true });
+
+	const hasInput = opts.input !== undefined;
+	const res = await f(url, {
+		method: opts.method ?? (hasInput ? 'POST' : 'GET'),
+		headers: {
+			accept: 'text/event-stream',
+			...(hasInput ? { 'content-type': 'application/json' } : {})
+		},
+		body: hasInput ? JSON.stringify(opts.input) : undefined,
+		signal: controller.signal
+	});
+	if (!res.ok || !res.body) {
+		throw new Error(`streamSource ${url}: ${res.status}${res.body ? '' : ' — no body'}`);
+	}
+
+	const reader = res.body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = '';
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			let cut;
+			while ((cut = buffer.indexOf('\n\n')) !== -1) {
+				const event = buffer.slice(0, cut);
+				buffer = buffer.slice(cut + 2);
+				const data = event
+					.split('\n')
+					.filter((line) => line.startsWith('data:'))
+					.map((line) => line.slice(5).replace(/^ /, ''))
+					.join('\n');
+				if (data === '') continue;
+				try {
+					yield JSON.parse(data);
+				} catch {
+					yield data;
+				}
+			}
+		}
+	} finally {
+		opts.signal?.removeEventListener('abort', abort);
+		controller.abort();
+	}
+}
+
+/**
+ * Connect to a Room over WebSocket with reconnect/backoff (R-16). Frames
+ * are the `{ type, ...payload }` envelope the Room contract declares in
+ * `messages`; `send(type, payload)` queues while disconnected and flushes
+ * on (re)connect. Reconnects use exponential backoff with jitter and stop
+ * after `close()`.
+ *
+ * @param {string} name room address (`module.Worker.name`), used to build
+ *   the default path `/_norns/room/<name>/ws`
+ * @param {{ path?: string, WebSocket?: typeof WebSocket, backoffMs?: number,
+ *   maxBackoffMs?: number }} [opts]
+ * @returns {{ send(type: string, payload?: object): void,
+ *   on(type: string, fn: (frame: *) => void): () => void, close(): void }}
+ *   `on('*', fn)` receives every frame; other types match `frame.type`.
+ */
+export function roomChannel(name, opts = {}) {
+	const WS = opts.WebSocket ?? globalThis.WebSocket;
+	const path = opts.path ?? `/_norns/room/${encodeURIComponent(name)}/ws`;
+	const handlers = new Map();
+	const queue = [];
+	let socket = null;
+	let timer = null;
+	let attempts = 0;
+	let closed = typeof WS !== 'function'; // SSR-safe: stay inert without a WebSocket
+
+	const backoff = () => {
+		const capped = Math.min(opts.maxBackoffMs ?? 15_000, (opts.backoffMs ?? 500) * 2 ** attempts);
+		return capped / 2 + Math.random() * (capped / 2);
+	};
+
+	const connect = () => {
+		if (closed) return;
+		socket = new WS(path);
+		socket.onopen = () => {
+			attempts = 0;
+			while (queue.length > 0) socket.send(queue.shift());
+		};
+		socket.onmessage = (e) => {
+			let frame;
+			try {
+				frame = JSON.parse(e.data);
+			} catch {
+				return;
+			}
+			for (const fn of handlers.get(frame?.type) ?? []) fn(frame);
+			for (const fn of handlers.get('*') ?? []) fn(frame);
+		};
+		socket.onclose = () => {
+			socket = null;
+			if (closed) return;
+			timer = setTimeout(connect, backoff());
+			attempts += 1;
+		};
+		socket.onerror = () => socket?.close?.();
+	};
+	connect();
+
+	return {
+		send(type, payload) {
+			const message = JSON.stringify({ type, ...(payload ?? {}) });
+			if (socket?.readyState === 1) socket.send(message);
+			else queue.push(message);
+		},
+		on(type, fn) {
+			const set = handlers.get(type) ?? new Set();
+			set.add(fn);
+			handlers.set(type, set);
+			return () => set.delete(fn);
+		},
+		close() {
+			closed = true;
+			clearTimeout(timer);
+			socket?.close?.();
+			socket = null;
+		}
+	};
+}
+
 /**
  * Call a `transport: remote` action endpoint
  * (`module.Action.name` → POST `/api/<module>/<name>`).

package/src/server/boot.js

@@ -5,6 +5,7 @@ import { authHandle } from './handle/auth.js';
 import { errorHandle } from './handle/error.js';
 import { setSerializer } from './route.js';
 import { createEvents, registerTriggers } from './events.js';
+import { createJobs, registerJobs } from './job.js';
 import { createLive } from './live.js';
 import { scheduledHandler, startCronShim } from './cron.js';
 
@@ -44,6 +45,13 @@ export function createApp() {
  *   cron ones are served by the returned `scheduled` handler.
  * - `queue` — Cloudflare Queues producer binding; `emit` enqueues instead of
  *   dispatching in-process.
+ * - `jobs` — generated job tables (`lib/<m>/jobs.c` `jobs` exports), nested
+ *   arrays flattened. Wired to `job:<address>` bus messages with
+ *   retry/backoff/DLQ semantics; a `jobs` facade singleton (enqueue) is
+ *   bound automatically unless a feature bound one.
+ * - `services` — generated service tables (`lib/<m>/services.c` `services`
+ *   exports), flattened; each client is container-registered under its unit
+ *   address so custom bodies can `container.resolve('crm.Service.mailer')`.
  * - `cronShim: true` — local minute-timer for cron triggers (`norns dev`).
  * - `auth` — a better-auth-shaped instance (`.handler(request)` +
  *   `.api.getSession({ headers })`); requests under `authBasePath`
@@ -62,6 +70,8 @@ export function createApp() {
  *   handleError?: import('@sveltejs/kit').HandleServerError,
  *   serializer?: import('./route.js').Serializer | null,
  *   triggers?: *[],
+ *   jobs?: *[],
+ *   services?: *[],
  *   queue?: { send(body: *): Promise<void> | void },
  *   cronShim?: boolean,
  *   room?: *,
@@ -112,6 +122,18 @@ export async function boot(opts = {}) {
 		);
 	}
 
+	if (!container.has('jobs')) {
+		container.single('jobs', () => createJobs(container));
+	}
+	const jobTables = (opts.jobs ?? []).flat(Infinity);
+	if (jobTables.length > 0) registerJobs(container, jobTables);
+
+	for (const table of (opts.services ?? []).flat(Infinity)) {
+		for (const [address, client] of Object.entries(table ?? {})) {
+			if (!container.has(address)) container.single(address, () => client);
+		}
+	}
+
 	const triggers = (opts.triggers ?? []).flat(Infinity);
 	if (triggers.length > 0) {
 		registerTriggers(container, triggers.filter((t) => !t.schedule));

package/src/server/db.js

@@ -100,7 +100,11 @@ export async function betterSqlite(path, opts = {}) {
  * @returns {Promise<any>}
  */
 export async function d1(binding, opts = {}) {
-	const { drizzle } = await importDynamic('drizzle-orm/d1');
+	// Literal specifier on purpose: wrangler's esbuild must bundle the D1
+	// driver into the worker (a runtime importDynamic() can never resolve
+	// inside a workerd bundle). Safe to resolve statically — drizzle-orm is
+	// a hard dependency of every generated app, unlike the native drivers.
+	const { drizzle } = await import('drizzle-orm/d1');
 	return drizzle(binding, opts.drizzle);
 }
 

package/src/server/endpoint.js

@@ -0,0 +1,142 @@
+/**
+ * Endpoint shell runtime (D14/K-23).
+ *
+ * The generated `routes<route>/+server.c` calls `endpoint(def)` with the
+ * spec-derived contract plus the custom body: auth verifies *before*
+ * anything else runs, input validates before the body, output validates
+ * after it — or, with `def.stream`, the body's yielded frames are served
+ * as SSE, each checked against the declared frame shape.
+ *
+ * Credentials resolve at request time from the env binding named in spec
+ * (container `env` token or process.env) — never from spec values.
+ */
+
+import { json, error } from '@sveltejs/kit';
+
+import { envOf, hmacHex, shapeIssues } from './service.js';
+
+/** Verify the inbound request against `def.auth` (401 on mismatch). */
+async function verifyAuth(def, event, bodyText, container) {
+	const { mode, binding, header } = def.auth ?? { mode: 'none' };
+	if (mode === 'none') return;
+	const value = envOf(container)[binding];
+	if (!value) {
+		throw error(500, { message: `Endpoint ${def.name}: env binding "${binding}" is not set` });
+	}
+	const headers = event.request.headers;
+	const ok =
+		mode === 'bearer'
+			? headers.get('authorization') === `Bearer ${value}`
+			: mode === 'basic'
+				? headers.get('authorization') === `Basic ${btoa(value)}`
+				: mode === 'header'
+					? headers.get(header) === value
+					: mode === 'hmac'
+						? headers.get('x-signature') === (await hmacHex(value, bodyText))
+						: false;
+	if (!ok) throw error(401, { message: 'unauthorized' });
+}
+
+// Query-string values arrive as strings; nudge them toward the declared type.
+const COERCE = {
+	int: (s) => (/^-?\d+$/.test(s) ? Number(s) : s),
+	number: (s) => (s !== '' && !Number.isNaN(Number(s)) ? Number(s) : s),
+	money: (s) => (s !== '' && !Number.isNaN(Number(s)) ? Number(s) : s),
+	bool: (s) => (s === 'true' ? true : s === 'false' ? false : s)
+};
+
+function coerceQuery(shape, raw) {
+	for (const [key, t] of Object.entries(shape ?? {})) {
+		const spec = (typeof t === 'string' ? t : t?.type ?? '').replace(/\?$/, '');
+		if (COERCE[spec] && typeof raw[key] === 'string') raw[key] = COERCE[spec](raw[key]);
+	}
+	return raw;
+}
+
+function sseResponse(def, frames) {
+	const enc = new TextEncoder();
+	const stream = new ReadableStream({
+		async start(controller) {
+			try {
+				for await (const frame of frames) {
+					const issues = def.stream?.frame ? shapeIssues(def.stream.frame, frame, 'frame') : [];
+					if (issues.length > 0) throw new Error(`Endpoint ${def.name}: ${issues.join('; ')}`);
+					controller.enqueue(enc.encode(`data: ${JSON.stringify(frame)}\n\n`));
+				}
+				controller.enqueue(enc.encode('event: done\ndata: {}\n\n'));
+			} catch (e) {
+				const message = String(e?.message ?? e);
+				controller.enqueue(enc.encode(`event: error\ndata: ${JSON.stringify({ message })}\n\n`));
+			}
+			controller.close();
+		}
+	});
+	return new Response(stream, {
+		headers: {
+			'content-type': 'text/event-stream',
+			'cache-control': 'no-cache',
+			connection: 'keep-alive'
+		}
+	});
+}
+
+/**
+ * @param {{
+ *   name: string,
+ *   auth?: { mode: string, binding?: string, header?: string },
+ *   input?: Record<string, *>,
+ *   output?: Record<string, *>,
+ *   stream?: { frame: Record<string, *> },
+ *   body: (ctx: { input: *, container: *, event: *, user: * }) => *
+ * }} def
+ * @returns {(event: import('@sveltejs/kit').RequestEvent) => Promise<Response>}
+ */
+export function endpoint(def) {
+	if (typeof def?.body !== 'function') throw new Error('endpoint(): `body` is required');
+
+	return async (event) => {
+		const container = event.locals.container;
+		const method = event.request.method;
+		const usesBody = method !== 'GET' && method !== 'DELETE' && method !== 'HEAD';
+		const bodyText = usesBody ? await event.request.text() : '';
+		await verifyAuth(def, event, bodyText, container);
+
+		let input;
+		if (usesBody) {
+			try {
+				input = bodyText === '' ? {} : JSON.parse(bodyText);
+			} catch {
+				throw error(400, { message: `Endpoint ${def.name}: body is not valid JSON` });
+			}
+		} else {
+			input = coerceQuery(def.input, Object.fromEntries(event.url.searchParams));
+		}
+		if (def.input) {
+			const issues = shapeIssues(def.input, input, 'input');
+			if (issues.length > 0) {
+				throw error(400, { message: `Endpoint ${def.name}: ${issues.join('; ')}`, issues });
+			}
+		}
+
+		const ctx = { input, container, event, user: event.locals.user };
+
+		if (def.stream) {
+			let frames = def.body(ctx);
+			if (!frames?.[Symbol.asyncIterator]) frames = await frames;
+			if (!frames?.[Symbol.asyncIterator]) {
+				throw error(500, { message: `Endpoint ${def.name}: stream body must return an async iterable of frames` });
+			}
+			return sseResponse(def, frames);
+		}
+
+		const result = await def.body(ctx);
+		if (result instanceof Response) return result;
+		if (def.output) {
+			const issues = shapeIssues(def.output, result, 'output');
+			if (issues.length > 0) {
+				throw error(500, { message: `Endpoint ${def.name}: ${issues.join('; ')}`, issues });
+			}
+		}
+		return json(result ?? null);
+	};
+}

package/src/server/index.js

@@ -15,6 +15,9 @@ 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/room.js

@@ -19,6 +19,10 @@
  * (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();
@@ -26,6 +30,8 @@ const ENC = new TextEncoder();
 export class Room {
 	tickMs = 1000;
 	persistEvery = 0;
+	presenceMs = 0;
+	#presenceTimer = null;
 
 	constructor(state, env) {
 		this.state = state;
@@ -68,8 +74,18 @@ export class Room {
 		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);
 		}
@@ -77,6 +93,7 @@ export class Room {
 
 	#leave(set, item) {
 		if (!set.delete(item)) return;
+		this.#presence();
 		if (this.clients === 0) {
 			if (this.timer !== null) {
 				clearInterval(this.timer);