@jigs.design/server 0.2.0 → 0.3.1

package/dist/errors.d.ts

@@ -10,8 +10,8 @@ export declare class JigsError extends Error {
   constructor(code: ThrownCode, message: string);
 }
 /**
- * A source that failed a strict compile, or a spec in `specs` that failed at
- * startup. `diagnostics` holds the error and warning diagnostics; the message
+ * A source that failed a strict compile, or a page that failed at startup
+ * or at its first call. `diagnostics` holds the error and warning diagnostics; the message
  * lists them with their lines.
  */
 export declare class JigsCompileError extends Error {

package/dist/errors.js

@@ -13,13 +13,13 @@ var JigsError = class extends Error {
 function isJigsError(cause) {
 	return typeof cause === "object" && cause !== null && BRAND in cause;
 }
-/** Diagnostics that make a stored spec or a strict compile fail. */
+/** Diagnostics that make a page or a strict compile fail. */
 function fatalDiagnostics(diagnostics) {
 	return diagnostics.filter((diagnostic) => diagnostic.severity === "error" || diagnostic.severity === "warning");
 }
 /**
-* A source that failed a strict compile, or a spec in `specs` that failed at
-* startup. `diagnostics` holds the error and warning diagnostics; the message
+* A source that failed a strict compile, or a page that failed at startup
+* or at its first call. `diagnostics` holds the error and warning diagnostics; the message
 * lists them with their lines.
 */
 var JigsCompileError = class extends Error {

package/dist/events.js

@@ -0,0 +1,129 @@
+import { INTERNAL_MESSAGE } from "./errors.js";
+import { sseFrame, sseResponse } from "./handler.js";
+//#region src/events.ts
+/** The longest `Last-Event-ID`, and event id, the stream accepts. */
+const MAX_EVENT_ID = 200;
+const PRINTABLE = /^[ -~]*$/;
+/** The reconnect delay the stream asks for: 3 s, plus up to 2 s so a fleet of tabs spreads out. */
+const RETRY_MS = 3e3;
+const RETRY_JITTER_MS = 2e3;
+const isEventId = (id) => id.length <= MAX_EVENT_ID && PRINTABLE.test(id);
+/** An event as the client reads it: a page's `saved` mark stays here. */
+function onTheWire(event) {
+	if (event.type !== "invalidate-pages") return event;
+	return {
+		pages: event.pages.map((page) => page.props === void 0 ? { name: page.name } : {
+			name: page.name,
+			props: page.props
+		}),
+		type: event.type
+	};
+}
+/** The client's `Last-Event-ID`, or null when it has none or one out of bounds. */
+function sinceOf(request) {
+	const since = request.headers.get("last-event-id");
+	return since === null || since === "" || !isEventId(since) ? null : since;
+}
+/**
+* Text frames written as they come and read by the response one at a time:
+* `push` queues one, `end` ends the iteration once the queue drains.
+*/
+function frameQueue() {
+	const queued = [];
+	let ended = false;
+	let wake = null;
+	const notify = () => {
+		wake?.();
+		wake = null;
+	};
+	return {
+		end: () => {
+			ended = true;
+			notify();
+		},
+		get ended() {
+			return ended;
+		},
+		async *frames() {
+			for (;;) {
+				const next = queued.shift();
+				if (next !== void 0) {
+					yield next;
+					continue;
+				}
+				if (ended) return;
+				await new Promise((resolve) => {
+					wake = resolve;
+				});
+			}
+		},
+		push: (frame) => {
+			if (ended) return;
+			queued.push(frame);
+			notify();
+		}
+	};
+}
+/**
+* One client's push stream: runs the host's `events` with a `send` that
+* writes to it, and the unsubscribe it returned once the stream ends.
+*/
+async function eventStream(deps, request, context) {
+	const queue = frameQueue();
+	const abort = new AbortController();
+	const leave = () => abort.abort();
+	if (context.signal.aborted) abort.abort();
+	else context.signal.addEventListener("abort", leave, { once: true });
+	let unsubscribe = null;
+	let unsubscribed = false;
+	const stop = () => {
+		context.signal.removeEventListener("abort", leave);
+		queue.end();
+		if (!unsubscribed && unsubscribe !== null) {
+			unsubscribed = true;
+			try {
+				unsubscribe();
+			} catch (error) {
+				deps.onError(error, { type: "events" });
+			}
+		}
+	};
+	abort.signal.addEventListener("abort", stop, { once: true });
+	const send = (event, options) => {
+		if (options?.id !== void 0 && !isEventId(options.id)) throw new Error(`An event id must be at most ${MAX_EVENT_ID} printable characters; got "${options.id.slice(0, 40)}"`);
+		queue.push(sseFrame(onTheWire(event), options?.id));
+	};
+	const close = () => {
+		queue.push(sseFrame({ type: "close" }));
+		queue.end();
+	};
+	try {
+		unsubscribe = await deps.events({
+			close,
+			ctx: context.ctx,
+			send,
+			signal: abort.signal,
+			since: sinceOf(request)
+		});
+	} catch (error) {
+		deps.onError(error, { type: "events" });
+		abort.abort();
+		return deps.http.failure(request, {
+			code: "INTERNAL",
+			message: INTERNAL_MESSAGE
+		});
+	}
+	if (abort.signal.aborted) stop();
+	return sseResponse(deps.http, request, queue.frames(), {
+		abort,
+		cleanup: () => abort.abort(),
+		failed: (cause) => {
+			deps.onError(cause, { type: "events" });
+			return sseFrame({ type: "close" });
+		},
+		retryMs: RETRY_MS + Math.floor(Math.random() * RETRY_JITTER_MS),
+		vary: "Accept"
+	});
+}
+//#endregion
+export { eventStream };

package/dist/handler.d.ts

@@ -0,0 +1,4 @@
+import "./types.js";
+import { Procedures } from "@jigs.design/host";
+import { JigsErrorData, PageProps, SessionEvent } from "@jigs.design/protocol";
+import { z } from "zod";

package/dist/handler.js

@@ -0,0 +1,344 @@
+import { INTERNAL_MESSAGE, statusOf } from "./errors.js";
+import { z } from "zod";
+//#region src/handler.ts
+const VERSION_HEADER = "jigs-version";
+const HEARTBEAT_MS = 15e3;
+/**
+* The body as text, or null once it passes `max` bytes. Reading stops there,
+* so an oversized body is never held in memory.
+*/
+async function readLimited(request, max) {
+	if (request.body === null) return "";
+	const reader = request.body.getReader();
+	const chunks = [];
+	let size = 0;
+	for (;;) {
+		const chunk = await reader.read();
+		if (chunk.done) break;
+		size += chunk.value.byteLength;
+		if (size > max) {
+			await reader.cancel();
+			return null;
+		}
+		chunks.push(chunk.value);
+	}
+	const bytes = new Uint8Array(size);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return new TextDecoder().decode(bytes);
+}
+/**
+* An origin such as `https://app.example.com`. Throws on anything else,
+* including an entry with no `http:` or `https:` scheme: `localhost:3000`
+* parses as a URL whose origin is `"null"`, the `Origin` that sandboxed
+* frames and `file:` pages send.
+*/
+function originOf(entry) {
+	let url = null;
+	try {
+		url = new URL(entry);
+	} catch {}
+	if (url === null || url.protocol !== "http:" && url.protocol !== "https:" || url.origin === "null") throw new Error(`"${entry}" is not an origin: write its scheme and host, such as https://app.example.com`);
+	return url.origin;
+}
+const bodySchema = z.discriminatedUnion("type", [
+	z.object({
+		confirmation: z.string().max(1e3).optional(),
+		input: z.json().optional(),
+		kind: z.enum([
+			"action",
+			"mutation",
+			"query"
+		], { error: "Send the procedure's kind as \"kind\": \"query\", \"mutation\" or \"action\"" }),
+		name: z.string().max(200),
+		type: z.literal("call")
+	}),
+	z.object({
+		document: z.json().optional(),
+		messages: z.json(),
+		options: z.json().optional(),
+		type: z.literal("session")
+	}),
+	z.object({
+		name: z.string().min(1).max(200),
+		props: z.record(z.string(), z.union([
+			z.boolean(),
+			z.number(),
+			z.string()
+		]), { error: "Send props as an object of strings, numbers and booleans" }).optional(),
+		type: z.literal("page")
+	})
+]);
+/**
+* Runs a `safeParse`, with a value nested too deeply to walk reported as a
+* failure instead of a thrown `RangeError`.
+*/
+function parseBounded(parse) {
+	let parsed;
+	try {
+		parsed = parse();
+	} catch {
+		return {
+			message: "The request body is nested too deeply.",
+			success: false
+		};
+	}
+	return parsed.success ? {
+		data: parsed.data,
+		success: true
+	} : {
+		message: issuesText(parsed.error),
+		success: false
+	};
+}
+function issuesText(error) {
+	return error.issues.slice(0, 3).map((issue) => issue.path.length === 0 ? issue.message : `${issue.path.join(".")}: ${issue.message}`).join("; ");
+}
+function createHttp(options) {
+	const serverOrigin = (request) => options.ownOrigin ?? new URL(request.url).origin;
+	const corsHeaders = (request) => {
+		const headers = new Headers({ [VERSION_HEADER]: options.version });
+		const origin = request.headers.get("origin");
+		if (origin !== null && options.allowedOrigins.has(origin)) {
+			headers.set("access-control-allow-origin", origin);
+			headers.set("access-control-allow-credentials", "true");
+			headers.set("access-control-expose-headers", VERSION_HEADER);
+			headers.append("vary", "Origin");
+		}
+		return headers;
+	};
+	const json = (request, status, value) => {
+		const headers = corsHeaders(request);
+		headers.set("content-type", "application/json");
+		headers.set("cache-control", "no-store");
+		return new Response(JSON.stringify(value), {
+			headers,
+			status
+		});
+	};
+	const foreignOrigin = (request) => {
+		const origin = request.headers.get("origin");
+		return origin !== null && origin !== serverOrigin(request) && !options.allowedOrigins.has(origin) ? {
+			code: "FORBIDDEN",
+			message: "This origin may not call this server."
+		} : null;
+	};
+	const refusal = (request) => {
+		const foreign = foreignOrigin(request);
+		if (foreign !== null) return foreign;
+		if (!(request.headers.get("content-type") ?? "").toLowerCase().startsWith("application/json")) return {
+			code: "BAD_INPUT",
+			message: "Send the request body as application/json."
+		};
+		return null;
+	};
+	return {
+		corsHeaders,
+		failure: (request, error) => json(request, statusOf(error.code), { error }),
+		foreignOrigin,
+		json,
+		refusal
+	};
+}
+/** One server-sent event: an optional `id:` line, then its JSON as `data:`. */
+function sseFrame(value, id) {
+	const data = `data: ${JSON.stringify(value)}\n\n`;
+	return id === void 0 ? data : `id: ${id}\n${data}`;
+}
+/**
+* A server-sent event stream of already-framed text, with a `: keep-alive`
+* comment every 15 s. Cancelling the body (the client left) aborts `abort`
+* and ends `frames`. Session turns and the push stream share it.
+*/
+function sseResponse(http, request, frames, options) {
+	const encoder = new TextEncoder();
+	const iterator = frames[Symbol.asyncIterator]();
+	let heartbeat;
+	let open = true;
+	const finish = () => {
+		if (!open) return;
+		open = false;
+		clearInterval(heartbeat);
+		options.cleanup();
+	};
+	const body = new ReadableStream({
+		async cancel() {
+			finish();
+			options.abort.abort();
+			await iterator.return?.();
+		},
+		async pull(controller) {
+			let next;
+			try {
+				next = await iterator.next();
+			} catch (error) {
+				finish();
+				controller.enqueue(encoder.encode(options.failed(error)));
+				controller.close();
+				return;
+			}
+			if (next.done === true) {
+				finish();
+				controller.close();
+				return;
+			}
+			controller.enqueue(encoder.encode(next.value));
+		},
+		start(controller) {
+			if (options.retryMs !== void 0) controller.enqueue(encoder.encode(`retry: ${options.retryMs}\n\n`));
+			heartbeat = setInterval(() => {
+				if (!open) return;
+				try {
+					controller.enqueue(encoder.encode(": keep-alive\n\n"));
+				} catch {
+					finish();
+				}
+			}, HEARTBEAT_MS);
+		}
+	});
+	const headers = http.corsHeaders(request);
+	headers.set("content-type", "text/event-stream; charset=utf-8");
+	headers.set("cache-control", "no-store");
+	headers.set("x-accel-buffering", "no");
+	if (options.vary !== void 0) headers.append("vary", options.vary);
+	return new Response(body, {
+		headers,
+		status: 200
+	});
+}
+/** Session events as a server-sent event stream. */
+function sessionStream(deps, request, events, abort, cleanup) {
+	async function* frames() {
+		for await (const event of events) yield sseFrame(event);
+	}
+	return sseResponse(deps.http, request, frames(), {
+		abort,
+		cleanup,
+		failed: (cause) => {
+			deps.onError(cause, { type: "session" });
+			return sseFrame({
+				error: {
+					code: "INTERNAL",
+					message: INTERNAL_MESSAGE
+				},
+				type: "error"
+			});
+		}
+	});
+}
+/**
+* Whether a `GET` asks for the push stream: its `Accept` lists
+* `text/event-stream` by name. A wildcard is not a match, so the frame's own
+* loads (an iframe's `text/html`, the view's policy probe) still get the
+* frame.
+*/
+function acceptsEventStream(request) {
+	return (request.headers.get("accept") ?? "").split(",").some((range) => (range.split(";")[0] ?? "").trim().toLowerCase() === "text/event-stream");
+}
+/**
+* The fetch handler: preflight, the frame, the push stream, calls, pages
+* and session turns. The core
+* and the model server build one each, differing only in `session`, so they
+* read and refuse requests the same way.
+*/
+function createHandler(deps) {
+	const { http, maxBodyBytes } = deps;
+	const tooLarge = (request) => http.failure(request, {
+		code: "BAD_INPUT",
+		message: `The request body is larger than ${maxBodyBytes} bytes.`
+	});
+	return async (request) => {
+		const origin = request.headers.get("origin");
+		if (request.method === "OPTIONS") {
+			const headers = http.corsHeaders(request);
+			if (origin !== null && deps.allowedOrigins.has(origin)) {
+				headers.set("access-control-allow-methods", "GET, POST");
+				headers.set("access-control-allow-headers", request.headers.get("access-control-request-headers") ?? "content-type");
+				headers.set("access-control-max-age", "600");
+			}
+			return new Response(null, {
+				headers,
+				status: 204
+			});
+		}
+		if (request.method === "GET") return acceptsEventStream(request) ? deps.events(request) : deps.frame(request);
+		if (request.method !== "POST") {
+			const headers = http.corsHeaders(request);
+			headers.set("allow", "GET, POST, OPTIONS");
+			return new Response(null, {
+				headers,
+				status: 405
+			});
+		}
+		const refused = http.refusal(request);
+		if (refused !== null) return http.failure(request, refused);
+		if (Number(request.headers.get("content-length") ?? "0") > maxBodyBytes) return tooLarge(request);
+		let text;
+		try {
+			text = await readLimited(request, maxBodyBytes);
+		} catch {
+			return http.failure(request, {
+				code: "BAD_INPUT",
+				message: "The request body could not be read."
+			});
+		}
+		if (text === null) return tooLarge(request);
+		let raw;
+		try {
+			raw = JSON.parse(text);
+		} catch {
+			return http.failure(request, {
+				code: "BAD_INPUT",
+				message: "The request body is not JSON."
+			});
+		}
+		const body = parseBounded(() => bodySchema.safeParse(raw));
+		if (!body.success) return http.failure(request, {
+			code: "BAD_INPUT",
+			message: body.message
+		});
+		const context = await deps.contextFor(request, body.data.type);
+		if ("error" in context) return http.failure(request, context.error);
+		if (body.data.type === "page") {
+			const reply = await deps.page({
+				name: body.data.name,
+				props: body.data.props ?? {}
+			}, {
+				ctx: context.ctx,
+				signal: request.signal
+			});
+			return "error" in reply ? http.failure(request, reply.error) : http.json(request, 200, reply);
+		}
+		if (body.data.type === "call") {
+			const callRequest = {
+				input: body.data.input,
+				kind: body.data.kind,
+				name: body.data.name
+			};
+			if (body.data.confirmation !== void 0) callRequest.confirmation = body.data.confirmation;
+			const outcome = await deps.call(callRequest, {
+				ctx: context.ctx,
+				signal: request.signal
+			});
+			return http.json(request, "error" in outcome ? statusOf(outcome.error.code) : 200, outcome);
+		}
+		const routed = await deps.session(body.data, {
+			ctx: context.ctx,
+			signal: request.signal
+		});
+		if ("error" in routed) return http.failure(request, routed.error);
+		const abort = new AbortController();
+		const forward = () => abort.abort();
+		if (request.signal.aborted) abort.abort();
+		else request.signal.addEventListener("abort", forward, { once: true });
+		return sessionStream(deps, request, routed.turn({
+			ctx: context.ctx,
+			signal: abort.signal
+		}), abort, () => request.signal.removeEventListener("abort", forward));
+	};
+}
+//#endregion
+export { VERSION_HEADER, acceptsEventStream, createHandler, createHttp, issuesText, originOf, parseBounded, sseFrame, sseResponse };

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import { Advice, DesignCheckCode, Placement } from "./design.js";
 import { ConfirmationStore, memoryConfirmations } from "./confirm.js";
-import { CallContext, CallOutcome, CallReport, CallReportOutcome, CallRequest, ChatBlockResult, ChatBlockSource, ChatEvent, ChatOptions, ChatTurn, CompileOptions, ContextFunction, EditFailureReason, ErrorInfo, JigsServer, JigsServerOptions, ModelFunction, ModelRequest, ModelRequestKind, PolicyCall, RequiresAction, RunFunctions, SessionRequest, Turn, TurnEdits, TurnRewrite, TurnRound, Usage } from "./types.js";
+import { CallContext, CallOutcome, CallReport, CallReportOutcome, CallRequest, ChatBlockResult, ChatBlockSource, ChatEvent, ChatOptions, ChatTurn, CompileOptions, ContextFunction, EditFailureReason, ErrorInfo, EventSubscriber, EventsFunction, JigsModelServer, JigsServer, JigsServerOptions, ModelFunction, ModelOptions, ModelRequest, ModelRequestKind, PageCall, PageFunction, PagePolicy, PageResolver, PolicyCall, PushInvalidate, PushInvalidatePages, PushInvalidation, PushPage, PushSend, RequiresAction, ResolvedPage, RunFunctions, SavedPage, SessionRequest, Turn, TurnEdits, TurnRewrite, TurnRound, Usage } from "./types.js";
 import { chatBlockText } from "./chat.js";
 import { JigsCompileError, JigsError, ThrownCode } from "./errors.js";
-import { createJigsServer, defineRun } from "./server.js";
+import { createJigsServer, defineRun } from "./core.js";
 import { addUsage } from "./usage.js";
-import { PromptMode } from "@jigs.design/prompt";
-import { ChatBlock, ChatBlockStatus, Diagnostic, JigsErrorCode, JigsErrorData, Message, Program, SessionEvent, Severity, Span } from "@jigs.design/protocol";
-export { type Advice, type CallContext, type CallOutcome, type CallReport, type CallReportOutcome, type CallRequest, type ChatBlock, type ChatBlockResult, type ChatBlockSource, type ChatBlockStatus, type ChatEvent, type ChatOptions, type ChatTurn, type CompileOptions, type ConfirmationStore, type ContextFunction, type DesignCheckCode, type Diagnostic, type EditFailureReason, type ErrorInfo, JigsCompileError, JigsError, type JigsErrorCode, type JigsErrorData, type JigsServer, type JigsServerOptions, type Message, type ModelFunction, type ModelRequest, type ModelRequestKind, type Placement, type PolicyCall, type Program, type PromptMode, type RequiresAction, type RunFunctions, type SessionEvent, type SessionRequest, type Severity, type Span, type ThrownCode, type Turn, type TurnEdits, type TurnRewrite, type TurnRound, type Usage, addUsage, chatBlockText, createJigsServer, defineRun, memoryConfirmations };
+import { PromptMode, askOf, withDocument } from "@jigs.design/prompt";
+import { ChatBlock, ChatBlockStatus, Diagnostic, JigsErrorCode, JigsErrorData, Message, PageProps, PageRef, Program, SessionDocument, SessionEvent, Severity, Span } from "@jigs.design/protocol";
+export { type Advice, type CallContext, type CallOutcome, type CallReport, type CallReportOutcome, type CallRequest, type ChatBlock, type ChatBlockResult, type ChatBlockSource, type ChatBlockStatus, type ChatEvent, type ChatOptions, type ChatTurn, type CompileOptions, type ConfirmationStore, type ContextFunction, type DesignCheckCode, type Diagnostic, type EditFailureReason, type ErrorInfo, type EventSubscriber, type EventsFunction, JigsCompileError, JigsError, type JigsErrorCode, type JigsErrorData, type JigsModelServer, type JigsServer, type JigsServerOptions, type Message, type ModelFunction, type ModelOptions, type ModelRequest, type ModelRequestKind, type PageCall, type PageFunction, type PagePolicy, type PageProps, type PageRef, type PageResolver, type Placement, type PolicyCall, type Program, type PromptMode, type PushInvalidate, type PushInvalidatePages, type PushInvalidation, type PushPage, type PushSend, type RequiresAction, type ResolvedPage, type RunFunctions, type SavedPage, type SessionDocument, type SessionEvent, type SessionRequest, type Severity, type Span, type ThrownCode, type Turn, type TurnEdits, type TurnRewrite, type TurnRound, type Usage, addUsage, askOf, chatBlockText, createJigsServer, defineRun, memoryConfirmations, withDocument };

package/dist/index.js

@@ -2,5 +2,6 @@ import { JigsCompileError, JigsError } from "./errors.js";
 import { addUsage } from "./usage.js";
 import { chatBlockText } from "./chat.js";
 import { memoryConfirmations } from "./confirm.js";
-import { createJigsServer, defineRun } from "./server.js";
-export { JigsCompileError, JigsError, addUsage, chatBlockText, createJigsServer, defineRun, memoryConfirmations };
+import { createJigsServer, defineRun } from "./core.js";
+import { askOf, withDocument } from "@jigs.design/prompt";
+export { JigsCompileError, JigsError, addUsage, askOf, chatBlockText, createJigsServer, defineRun, memoryConfirmations, withDocument };

package/dist/inputs.js

@@ -3,6 +3,11 @@ import { z } from "zod";
 //#region src/inputs.ts
 /** A handle declared as `const name = useMutation("procedure")`. */
 const MUTATION_HANDLE = /(?<![\w$.])(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*useMutation\(\s*(["'`])([A-Za-z_$][\w$]*)\2\s*\)/g;
+/**
+* What may follow a provided slot's name in `useQuery`: the call's end, or
+* an empty input (`undefined` or `null`) before or without options.
+*/
+const NO_INPUT = /^(?:,\s*)?\)|^,\s*(?:undefined|null)(?![\w$])/;
 const QUERY_CALL = /(?<![\w$.])useQuery\(\s*(["'`])([A-Za-z_$][\w$]*)\1\s*/g;
 /** At most this many problems per call, so one bad literal does not flood the repair. */
 const MAX_PROBLEMS = 3;
@@ -192,8 +197,18 @@ function inputDiagnostics(host, source) {
 	for (const match of source.matchAll(QUERY_CALL)) {
 		const name = match[2] ?? "";
 		const procedure = procedureOf(name);
-		if (procedure?.kind !== "query" || procedure.input === void 0) continue;
 		const rest = match.index + match[0].length;
+		if (procedure?.kind === "data") {
+			if (NO_INPUT.test(source.slice(rest))) continue;
+			diagnostics.push({
+				code: "data_takes_no_input",
+				message: `useQuery("${name}") reads provided data, which takes no input. Drop the input; the app provides this data`,
+				severity: "error",
+				span: { line: lineAt(source, match.index) }
+			});
+			continue;
+		}
+		if (procedure?.kind !== "query" || procedure.input === void 0) continue;
 		const char = source.charAt(rest);
 		if (char !== "," && char !== ")") continue;
 		const [input] = char === ")" ? [] : readArguments(source, rest + 1);