@plitzi/sdk-server 0.37.2 → 0.37.4

package/dist/modules/functions/runner/remote.js

@@ -0,0 +1,116 @@
+import { FunctionFailure } from "../protocol.js";
+import { frameText } from "../../../helpers/wsFrame.js";
+import { readResponseMessage } from "./messages.js";
+import { WebSocket } from "ws";
+//#region src/modules/functions/runner/remote.ts
+/** What reading a bundle may take on the runner (its own ceiling is 5 s), and then some. */
+var DESCRIBE_DEADLINE_MS = 1e4;
+var unreachable = (detail) => new FunctionFailure("error", `The functions runner is unreachable (${detail})`);
+/**
+* The platform's side of the runner service: a {@link FunctionRunner} over one WebSocket per operation. Each call the
+* code makes arrives on it and is answered on it, by this process — the one holding the run.
+*/
+var createRemoteRunner = ({ url, secret, connectTimeoutMs = 5e3, graceMs = 5e3 }) => {
+	const operate = ({ first, load, bundleId, deadlineMs, answer, signal, onUsage }) => new Promise((resolve, reject) => {
+		const socket = new WebSocket(url, {
+			headers: { authorization: `Bearer ${secret}` },
+			handshakeTimeout: connectTimeoutMs
+		});
+		let settled = false;
+		const send = (message) => {
+			if (socket.readyState === WebSocket.OPEN) socket.send(JSON.stringify(message));
+		};
+		const settle = (outcome) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(deadline);
+			signal?.removeEventListener("abort", onAbort);
+			outcome();
+			socket.close(1e3);
+		};
+		const deadline = setTimeout(() => {
+			settle(() => reject(new FunctionFailure("wall", `The functions runner did not answer within ${String(deadlineMs)} ms`)));
+			socket.terminate();
+		}, deadlineMs);
+		const onAbort = () => send({ type: "abort" });
+		signal?.addEventListener("abort", onAbort, { once: true });
+		socket.on("open", () => {
+			send(first);
+			if (signal?.aborted) onAbort();
+		});
+		socket.on("message", (data) => {
+			const message = readResponseMessage(frameText(data));
+			if (!message) {
+				settle(() => reject(new FunctionFailure("error", "The functions runner answered outside the protocol")));
+				return;
+			}
+			switch (message.type) {
+				case "needBundle":
+					load().then((code) => send({
+						type: "bundle",
+						bundle: {
+							id: bundleId,
+							code
+						}
+					}), (error) => settle(() => reject(new FunctionFailure("error", `The functions could not be read: ${error instanceof Error ? error.message : String(error)}`))));
+					return;
+				case "call":
+					answer(message.call).then((value) => send({
+						type: "answer",
+						id: message.id,
+						answer: {
+							ok: true,
+							value: value ?? null
+						}
+					}), (error) => send({
+						type: "answer",
+						id: message.id,
+						answer: {
+							ok: false,
+							error: error instanceof Error ? error.message : String(error)
+						}
+					}));
+					return;
+				case "done":
+					if (message.usage) onUsage?.(message.usage);
+					settle(() => resolve(message.value));
+					return;
+				case "failed":
+					if (message.usage) onUsage?.(message.usage);
+					settle(() => reject(new FunctionFailure(message.reason, message.error)));
+			}
+		});
+		socket.on("error", (error) => settle(() => reject(unreachable(error.message))));
+		socket.on("close", (code) => settle(() => reject(unreachable(`closed with ${String(code)}`))));
+	});
+	return {
+		describe: (bundle) => operate({
+			first: {
+				type: "describe",
+				protocol: 1,
+				bundle
+			},
+			load: () => Promise.resolve(bundle.code),
+			bundleId: bundle.id,
+			deadlineMs: DESCRIBE_DEADLINE_MS,
+			answer: () => Promise.reject(/* @__PURE__ */ new Error("Nothing is reachable while a bundle is read"))
+		}),
+		invoke: ({ bundle, invocation, limits, answer, signal, onUsage }) => operate({
+			first: {
+				type: "invoke",
+				protocol: 1,
+				bundleId: bundle.id,
+				invocation,
+				limits
+			},
+			load: bundle.load,
+			bundleId: bundle.id,
+			deadlineMs: limits.wallMs + graceMs,
+			answer,
+			signal,
+			onUsage
+		})
+	};
+};
+//#endregion
+export { createRemoteRunner };

package/dist/modules/functions/runner/remote.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/functions/runner/service.d.ts

@@ -0,0 +1,32 @@
+import { default as http } from 'node:http';
+import { FunctionRunner } from '../protocol';
+import { IsolateRunnerOptions } from '../sandbox/isolate';
+import { AddressInfo } from 'node:net';
+export type FunctionsRunnerServiceOptions = IsolateRunnerOptions & {
+    /** What the platform presents as `Authorization: Bearer <secret>`. Required: a runner anybody reaches runs anybody's code. */
+    secret: string;
+    port?: number;
+    host?: string;
+    /**
+     * The engine; the isolates in this process by default, warmed before the service listens. It keeps the bundles it
+     * runs — this service keeps none of its own — and asks the platform for one it does not have.
+     */
+    runner?: FunctionRunner;
+    /**
+     * What answers plain HTTP besides `/health` — a space runtime's endpoints — behind the same secret as the protocol.
+     * Answers whether it took the request; one it did not take is a 404.
+     */
+    http?: (req: http.IncomingMessage, res: http.ServerResponse) => Promise<boolean>;
+};
+export type FunctionsRunnerService = {
+    /** Where it listens, once it does. */
+    address: () => AddressInfo;
+    close: () => Promise<void>;
+};
+/**
+ * The functions runner as a service: a process that holds no secrets, no database and no documents, and runs the
+ * spaces' code in isolates for the platform that authenticates to it. What a sandbox escape reaches is this process.
+ *
+ * `GET /health` answers 200 for the orchestrator; everything else is the WebSocket protocol, behind the secret.
+ */
+export declare const startFunctionsRunnerService: ({ secret, port, host, runner, http: answerHttp, ...isolate }: FunctionsRunnerServiceOptions) => Promise<FunctionsRunnerService>;

package/dist/modules/functions/runner/service.js

@@ -0,0 +1,209 @@
+import { serverLog } from "../../../helpers/serverLog.js";
+import { FunctionFailure } from "../protocol.js";
+import { frameText } from "../../../helpers/wsFrame.js";
+import { watchConnections } from "../../../core/server/drain.js";
+import { readRequestMessage } from "./messages.js";
+import { createIsolateRunner } from "../sandbox/isolate.js";
+import { createHash, timingSafeEqual } from "node:crypto";
+import http from "node:http";
+import { WebSocketServer } from "ws";
+//#region src/modules/functions/runner/service.ts
+/** A bundle is at most 1 MB and an answer a few; anything past this on one frame is not the platform talking. */
+var MAX_FRAME_BYTES = 8388608;
+var digest = (value) => createHash("sha256").update(value).digest();
+var authorised = (header, secret) => header !== void 0 && timingSafeEqual(digest(header), digest(`Bearer ${secret}`));
+/**
+* One operation on one connection — `describe`, or `invoke` with every call the code makes going back on the same
+* socket. The platform replica that asked is the one answering, so nothing about a run has to be shared between
+* replicas, and a connection that closes is the invocation aborting.
+*/
+var serveConnection = (socket, runner) => {
+	const pending = /* @__PURE__ */ new Map();
+	const controller = new AbortController();
+	let nextCall = 1;
+	let started = false;
+	let waitingBundle;
+	const send = (message) => {
+		if (socket.readyState === socket.OPEN) socket.send(JSON.stringify(message));
+	};
+	const finish = (message) => {
+		send(message);
+		socket.close(1e3);
+	};
+	let usage;
+	const settle = (work) => {
+		work.then((value) => finish({
+			type: "done",
+			value,
+			...usage ? { usage } : {}
+		}), (error) => finish({
+			type: "failed",
+			...error instanceof FunctionFailure ? {
+				reason: error.reason,
+				error: error.message
+			} : {
+				reason: "error",
+				error: error instanceof Error ? error.message : String(error)
+			},
+			...usage ? { usage } : {}
+		}));
+	};
+	const answer = (call) => new Promise((resolve, reject) => {
+		const id = nextCall++;
+		pending.set(id, (reply) => reply.ok ? resolve(reply.value) : reject(new Error(reply.error)));
+		send({
+			type: "call",
+			id,
+			call
+		});
+	});
+	socket.on("message", (data) => {
+		const message = readRequestMessage(frameText(data));
+		if (!message) {
+			finish({
+				type: "failed",
+				reason: "error",
+				error: "Not a message of the functions protocol"
+			});
+			return;
+		}
+		if (message.type === "answer") {
+			const reply = pending.get(message.id);
+			pending.delete(message.id);
+			reply?.(message.answer);
+			return;
+		}
+		if (message.type === "abort") {
+			controller.abort();
+			return;
+		}
+		if (message.type === "bundle") {
+			waitingBundle?.(message.bundle.code);
+			waitingBundle = void 0;
+			return;
+		}
+		if (started) {
+			finish({
+				type: "failed",
+				reason: "error",
+				error: "One operation per connection"
+			});
+			return;
+		}
+		started = true;
+		if (message.protocol !== 1) {
+			finish({
+				type: "failed",
+				reason: "error",
+				error: `This runner speaks protocol ${String(1)}, not ${String(message.protocol)}`
+			});
+			return;
+		}
+		if (message.type === "describe") {
+			settle(runner.describe(message.bundle));
+			return;
+		}
+		const { bundleId, invocation, limits } = message;
+		settle(runner.invoke({
+			bundle: {
+				id: bundleId,
+				load: () => new Promise((resolve) => {
+					waitingBundle = resolve;
+					send({ type: "needBundle" });
+				})
+			},
+			invocation,
+			limits,
+			answer,
+			signal: controller.signal,
+			onUsage: (spent) => {
+				usage = spent;
+			}
+		}));
+	});
+	socket.on("close", () => {
+		controller.abort();
+		pending.forEach((reply) => reply({
+			ok: false,
+			error: "The platform went away"
+		}));
+		pending.clear();
+	});
+};
+/**
+* The functions runner as a service: a process that holds no secrets, no database and no documents, and runs the
+* spaces' code in isolates for the platform that authenticates to it. What a sandbox escape reaches is this process.
+*
+* `GET /health` answers 200 for the orchestrator; everything else is the WebSocket protocol, behind the secret.
+*/
+var startFunctionsRunnerService = async ({ secret, port = 8790, host = "0.0.0.0", runner, http: answerHttp, ...isolate }) => {
+	if (secret.length < 32) throw new Error("The functions runner needs a secret of at least 32 characters");
+	let engine;
+	if (runner) engine = runner;
+	else {
+		const isolates = createIsolateRunner(isolate);
+		await isolates.warm();
+		engine = isolates;
+	}
+	const sockets = new WebSocketServer({
+		noServer: true,
+		maxPayload: MAX_FRAME_BYTES
+	});
+	const notFound = (res) => {
+		res.writeHead(404, { "content-type": "text/plain" });
+		res.end("");
+	};
+	const server = http.createServer((req, res) => {
+		if (req.method === "GET" && req.url === "/health") {
+			res.writeHead(200, { "content-type": "text/plain" });
+			res.end("ok");
+			return;
+		}
+		if (!answerHttp) {
+			notFound(res);
+			return;
+		}
+		if (!authorised(req.headers.authorization, secret)) {
+			res.writeHead(401, { "content-type": "text/plain" });
+			res.end("");
+			return;
+		}
+		answerHttp(req, res).then((taken) => {
+			if (!taken) notFound(res);
+		}, (error) => {
+			serverLog.error("Functions", "an HTTP request failed", error);
+			if (!res.headersSent) res.writeHead(500, { "content-type": "text/plain" });
+			res.end("");
+		});
+	});
+	server.on("upgrade", (req, socket, head) => {
+		if (!authorised(req.headers.authorization, secret)) {
+			socket.end("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+			return;
+		}
+		sockets.handleUpgrade(req, socket, head, (ws) => serveConnection(ws, engine));
+	});
+	const connections = watchConnections(server);
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(port, host, () => {
+			server.off("error", reject);
+			resolve();
+		});
+	});
+	serverLog.info("Functions", `runner listening on ${host}:${String(port)}`);
+	return {
+		address: () => {
+			const address = server.address();
+			if (!address || typeof address === "string") throw new Error("The functions runner is not listening");
+			return address;
+		},
+		close: async () => {
+			sockets.clients.forEach((client) => client.terminate());
+			await connections.drain("Functions");
+			await engine.close?.();
+		}
+	};
+};
+//#endregion
+export { startFunctionsRunnerService };

package/dist/modules/functions/sandbox/guest.d.ts

@@ -0,0 +1,45 @@
+import { changeKv } from '../../actions/runtime/kvChange';
+import { createFunctionsDriver, describeFunctions } from '../driver';
+/** What the runner hands the guest: calls into the runner's own process, the only way out of the isolate. */
+export type GuestHost = {
+    /** A {@link FunctionCall} for the platform, as JSON; answers a `FunctionAnswer`, as JSON. */
+    call: (message: string) => Promise<string>;
+    /** Resolves after `ms` — the runner's clock, bounded by the invocation's time. */
+    sleep: (ms: number) => Promise<void>;
+    /** `length` random bytes, from the runner's CSPRNG. */
+    random: (length: number) => number[];
+    /** A `crypto.subtle` operation the runner does with its own implementation: `{ op, … }` → a `FunctionAnswer` whose
+     *  value is the bytes, base64. */
+    crypto: (message: string) => Promise<string>;
+};
+/**
+ * Functions of the platform's the guest runs as they are, printed in beside it (`isolate.ts`) — one implementation for
+ * native code and the sandbox alike. Each is self-contained by contract, as the guest is.
+ */
+export type GuestShared = {
+    /** `ctx.kv.change`: the read-change-write loop, over the guest's own `get` and `swap` calls. */
+    changeKv: typeof changeKv;
+    /** What a definition declares, as a manifest. */
+    describeFunctions: typeof describeFunctions;
+    /** An invocation of a definition with its `ctx` — the same driver a space runtime runs. */
+    createFunctionsDriver: typeof createFunctionsDriver;
+};
+/** What the runner drives the guest with, once installed. */
+export type GuestDriver = {
+    /** What a definition declares — the manifest the platform reads and checks — as a `FunctionAnswer` (JSON). */
+    describe: (definition: unknown) => string;
+    /** Runs one invocation (JSON) of a definition, and answers a `FunctionAnswer` (JSON). Never rejects. */
+    invoke: (definition: unknown, invocation: string) => Promise<string>;
+    /** The run was aborted: `ctx.signal` fires, for code that listens, before the runner stops it. */
+    abort: (reason: string) => void;
+};
+/**
+ * The runtime a space's code finds in an isolate: the web APIs a bare V8 lacks (`Headers`, `Request`, `Response`,
+ * `TextEncoder`, `AbortSignal`, timers, `crypto`) and the `ctx` its functions are handed.
+ *
+ * It is installed by PRINTING this function into the isolate (`installGuest.toString()`), after the prelude that brings
+ * `URL`, `atob`, `structuredClone` and `DOMException`. So it may use nothing from outside its own body — no import,
+ * no helper beside it — and all it has of the runner is `host`, and the functions in `shared`. Streams are not
+ * provided: a body is text or bytes.
+ */
+export declare const installGuest: (scope: Record<string, unknown>, host: GuestHost, shared: GuestShared) => GuestDriver;