@human-synthesis/norns 0.0.16 → 0.2.0

package/src/server/service.js

@@ -0,0 +1,188 @@
+/**
+ * Service client runtime (D15/K-21, R-15).
+ *
+ * The generated `lib/<m>/services.c` calls `serviceClient(def)` with the
+ * spec-derived manifest; each declared operation becomes
+ * `client.<op>(args, container)`.
+ *
+ * Credentials resolve at call time, never from spec: `def.auth.binding`
+ * names an env binding looked up on the container's `env` token when one is
+ * bound (Cloudflare per-request scope) and `process.env` otherwise (dev).
+ */
+
+export class ServiceError extends Error {
+	/**
+	 * @param {string} service unit address (`crm.Service.mailer`)
+	 * @param {string} operation
+	 * @param {number} status HTTP status (0 for transport failures)
+	 * @param {*} body parsed response body (or error message)
+	 */
+	constructor(service, operation, status, body) {
+		super(`${service}.${operation} failed with ${status}`);
+		this.name = 'ServiceError';
+		this.service = service;
+		this.operation = operation;
+		this.status = status;
+		this.body = body;
+	}
+}
+
+/** Env for credential lookups: container `env` token when bound, else process.env. */
+export function envOf(container) {
+	if (container?.has?.('env')) return container.resolve('env') ?? {};
+	return globalThis.process?.env ?? {};
+}
+
+function credential(def, container) {
+	const { mode, binding } = def.auth ?? { mode: 'none' };
+	if (mode === 'none') return null;
+	const value = envOf(container)[binding];
+	if (!value) throw new Error(`Service ${def.name}: env binding "${binding}" is not set`);
+	return value;
+}
+
+async function authHeaders(def, container, bodyText) {
+	const { mode, header } = def.auth ?? { mode: 'none' };
+	if (mode === 'none') return {};
+	const value = credential(def, container);
+	switch (mode) {
+		case 'bearer':
+			return { authorization: `Bearer ${value}` };
+		case 'basic':
+			return { authorization: `Basic ${btoa(value)}` };
+		case 'header':
+			return { [header]: value };
+		case 'hmac':
+			return { 'x-signature': await hmacHex(value, bodyText ?? '') };
+		default:
+			return {};
+	}
+}
+
+/** HMAC-SHA-256 hex of `text` keyed by `secret` — signing and inbound verification. */
+export async function hmacHex(secret, text) {
+	const enc = new TextEncoder();
+	const key = await crypto.subtle.importKey(
+		'raw',
+		enc.encode(secret),
+		{ name: 'HMAC', hash: 'SHA-256' },
+		false,
+		['sign']
+	);
+	const sig = await crypto.subtle.sign('HMAC', key, enc.encode(text));
+	return [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+const TYPE_OK = {
+	text: (x) => typeof x === 'string',
+	email: (x) => typeof x === 'string' && x.includes('@'),
+	url: (x) => typeof x === 'string',
+	date: (x) => typeof x === 'string' || x instanceof Date,
+	datetime: (x) => typeof x === 'string' || x instanceof Date,
+	int: (x) => Number.isInteger(x),
+	number: (x) => typeof x === 'number',
+	money: (x) => typeof x === 'number',
+	bool: (x) => typeof x === 'boolean',
+	json: () => true
+};
+
+/** Contract check for an operation's input/output shape (spec field types; entity refs pass through). */
+export function shapeIssues(shape, value, label) {
+	const issues = [];
+	for (const [key, t] of Object.entries(shape ?? {})) {
+		const spec = typeof t === 'string' ? t : (t?.type ?? 'json');
+		const optional = typeof t === 'string' ? t.endsWith('?') : t?.optional === true;
+		const type = spec.replace(/\?$/, '');
+		const val = value?.[key];
+		if (val === undefined || val === null) {
+			if (!optional) issues.push(`missing ${label} "${key}"`);
+			continue;
+		}
+		if (!(TYPE_OK[type] ?? (() => true))(val)) issues.push(`${label} "${key}": expected ${type}`);
+	}
+	return issues;
+}
+
+/**
+ * Build a typed client from a Service manifest.
+ *
+ * @param {{
+ *   name: string,
+ *   base: string,
+ *   auth?: { mode: 'none'|'bearer'|'basic'|'hmac'|'header', binding?: string, header?: string },
+ *   timeoutMs?: number,
+ *   operations: Record<string, { method?: string, path?: string, input?: Record<string, *>, output?: * }>
+ * }} def
+ * @param {typeof fetch} [fetchImpl] injectable for tests
+ * @returns {Record<string, (args?: Record<string, *>, container?: *) => Promise<*>>}
+ */
+export function serviceClient(def, fetchImpl) {
+	const client = {};
+	for (const [opName, op] of Object.entries(def.operations ?? {})) {
+		client[opName] = async (args = {}, container) => {
+			const inputIssues = shapeIssues(op.input, args, 'input');
+			if (inputIssues.length > 0) {
+				throw new Error(`Service ${def.name}.${opName}: ${inputIssues.join('; ')}`);
+			}
+			// Op-level container override — trace fixtures and tests bind
+			// `<service address>.<op>` to bypass the network after validation.
+			const fixtureKey = `${def.name}.${opName}`;
+			if (container?.has?.(fixtureKey)) {
+				return await container.resolve(fixtureKey)(args);
+			}
+			const method = (op.method ?? 'POST').toUpperCase();
+			const rest = { ...args };
+			const path = (op.path ?? `/${opName}`).replace(
+				/\{([A-Za-z_][A-Za-z0-9_]*)\}/g,
+				(_, k) => {
+					delete rest[k];
+					return encodeURIComponent(String(args[k]));
+				}
+			);
+			let url = def.base.replace(/\/$/, '') + path;
+			let bodyText;
+			if (method === 'GET' || method === 'DELETE') {
+				const qs = new URLSearchParams();
+				for (const [k, val] of Object.entries(rest)) {
+					if (val !== undefined && val !== null) qs.set(k, String(val));
+				}
+				const q = qs.toString();
+				if (q) url += `?${q}`;
+			} else {
+				bodyText = JSON.stringify(rest);
+			}
+			const headers = {
+				accept: 'application/json',
+				...(bodyText !== undefined ? { 'content-type': 'application/json' } : {}),
+				...(await authHeaders(def, container, bodyText))
+			};
+			let res;
+			try {
+				res = await (fetchImpl ?? fetch)(url, {
+					method,
+					headers,
+					...(bodyText !== undefined ? { body: bodyText } : {}),
+					signal: AbortSignal.timeout(def.timeoutMs ?? 10_000)
+				});
+			} catch (err) {
+				throw new ServiceError(def.name, opName, 0, String(err?.message ?? err));
+			}
+			const text = await res.text();
+			let data;
+			try {
+				data = text ? JSON.parse(text) : null;
+			} catch {
+				data = text;
+			}
+			if (!res.ok) throw new ServiceError(def.name, opName, res.status, data);
+			if (op.output && typeof op.output === 'object') {
+				const outIssues = shapeIssues(op.output, data, 'output');
+				if (outIssues.length > 0) {
+					throw new ServiceError(def.name, opName, res.status, { contract: outIssues, data });
+				}
+			}
+			return data;
+		};
+	}
+	return client;
+}

package/src/server/storage.js

@@ -0,0 +1,97 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync, existsSync, readdirSync } from 'node:fs';
+import { dirname, join, normalize, sep } from 'node:path';
+
+/**
+ * Storage behind `container.resolve('storage')` — backing for the `file`
+ * field type. Two adapters with one surface:
+ *
+ *   put(key, data, { contentType? })  → { key }
+ *   get(key)                          → { body: Uint8Array, contentType? } | null
+ *   delete(key)                       → void
+ *   list(prefix)                      → string[] (keys, sorted)
+ *
+ * Keys are `/`-separated paths (`orders/abc/invoice.pdf`).
+ */
+
+/**
+ * Cloudflare R2 adapter over a bucket binding.
+ * @param {*} bucket R2Bucket binding
+ */
+export function r2Storage(bucket) {
+	return {
+		async put(key, data, { contentType } = {}) {
+			await bucket.put(key, data, contentType ? { httpMetadata: { contentType } } : undefined);
+			return { key };
+		},
+		async get(key) {
+			const obj = await bucket.get(key);
+			if (!obj) return null;
+			return {
+				body: new Uint8Array(await obj.arrayBuffer()),
+				contentType: obj.httpMetadata?.contentType
+			};
+		},
+		async delete(key) {
+			await bucket.delete(key);
+		},
+		async list(prefix = '') {
+			const keys = [];
+			let cursor;
+			do {
+				const page = await bucket.list({ prefix, cursor });
+				for (const obj of page.objects) keys.push(obj.key);
+				cursor = page.truncated ? page.cursor : undefined;
+			} while (cursor);
+			return keys.sort();
+		}
+	};
+}
+
+/**
+ * Local-dir shim for `norns dev` / tests. Content types ride in a `.meta`
+ * sidecar next to each object.
+ * @param {string} root
+ */
+export function dirStorage(root) {
+	const safe = (key) => {
+		const p = normalize(join(root, key));
+		if (!p.startsWith(normalize(root) + sep)) throw new Error(`storage: invalid key ${key}`);
+		return p;
+	};
+	return {
+		async put(key, data, { contentType } = {}) {
+			const path = safe(key);
+			mkdirSync(dirname(path), { recursive: true });
+			writeFileSync(path, typeof data === 'string' ? data : new Uint8Array(data));
+			if (contentType) writeFileSync(`${path}.meta`, contentType);
+			return { key };
+		},
+		async get(key) {
+			const path = safe(key);
+			if (!existsSync(path)) return null;
+			const meta = existsSync(`${path}.meta`) ? readFileSync(`${path}.meta`, 'utf8') : undefined;
+			return { body: new Uint8Array(readFileSync(path)), contentType: meta };
+		},
+		async delete(key) {
+			const path = safe(key);
+			rmSync(path, { force: true });
+			rmSync(`${path}.meta`, { force: true });
+		},
+		async list(prefix = '') {
+			if (!existsSync(root)) return [];
+			const out = [];
+			const walk = (dir) => {
+				for (const entry of readdirSync(dir, { withFileTypes: true })) {
+					const full = join(dir, entry.name);
+					if (entry.isDirectory()) walk(full);
+					else if (!entry.name.endsWith('.meta')) {
+						const key = full.slice(normalize(root).length + 1).split(sep).join('/');
+						if (key.startsWith(prefix)) out.push(key);
+					}
+				}
+			};
+			walk(root);
+			return out.sort();
+		}
+	};
+}