@plitzi/sdk-server 0.37.2 → 0.37.4

package/dist/modules/functions/capabilities.js

@@ -0,0 +1,228 @@
+//#region src/modules/functions/capabilities.ts
+var TEXTUAL = /^(text\/|application\/([\w.+-]*\+)?(json|xml|javascript|x-www-form-urlencoded))/i;
+/** A body as the wire carries it: as text when its type says it is text, base64 otherwise. */
+var wireBodyOf = async (body, contentType) => {
+	const bytes = Buffer.from(await body.arrayBuffer());
+	if (!bytes.length) return null;
+	return contentType && TEXTUAL.test(contentType) ? { text: bytes.toString("utf8") } : { base64: bytes.toString("base64") };
+};
+var bodyOf = (body) => {
+	if (!body) return null;
+	return "text" in body ? body.text : new Uint8Array(Buffer.from(body.base64, "base64"));
+};
+var wireResponseOf = async (response) => ({
+	status: response.status,
+	statusText: response.statusText,
+	headers: [...response.headers],
+	body: await wireBodyOf(response, response.headers.get("content-type"))
+});
+var wireRequestOf = async (request) => ({
+	method: request.method,
+	url: request.url,
+	headers: [...request.headers],
+	body: await wireBodyOf(request, request.headers.get("content-type"))
+});
+var responseOf = ({ status, statusText, headers, body }) => new Response(bodyOf(body), {
+	status,
+	statusText,
+	headers
+});
+var CallError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "CallError";
+	}
+};
+var stringArg = (value, what) => {
+	if (typeof value !== "string") throw new CallError(`${what} is a string`);
+	return value;
+};
+var numberArg = (value, what) => {
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new CallError(`${what} is a number`);
+	return value;
+};
+var optionalNumber = (value, what) => value === void 0 || value === null ? void 0 : numberArg(value, what);
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var headerPairsOf = (value) => Array.isArray(value) ? value.flatMap((pair) => Array.isArray(pair) && typeof pair[0] === "string" && typeof pair[1] === "string" ? [[pair[0], pair[1]]] : []) : [];
+var wireBodyFrom = (value) => {
+	const body = isRecord(value) ? value : void 0;
+	return body && typeof body.text === "string" ? { text: body.text } : body && typeof body.base64 === "string" ? { base64: body.base64 } : null;
+};
+/** An answer that crossed a boundary as a wire response — from a space's code, or from the platform — read, not trusted. */
+var wireResponseFrom = (value) => {
+	const answer = isRecord(value) ? value : {};
+	return {
+		status: typeof answer.status === "number" && answer.status >= 200 && answer.status <= 599 ? answer.status : 500,
+		statusText: typeof answer.statusText === "string" ? answer.statusText : "",
+		headers: headerPairsOf(answer.headers),
+		body: wireBodyFrom(answer.body)
+	};
+};
+/** A request that crossed as a wire request, as a web `Request` again — what a route handler outside the sandbox takes. */
+var requestFromWire = (value) => {
+	const wire = isRecord(value) ? value : {};
+	const method = typeof wire.method === "string" ? wire.method : "GET";
+	return new Request(typeof wire.url === "string" ? wire.url : "http://runtime.invalid/", {
+		method,
+		headers: headerPairsOf(wire.headers),
+		body: method === "GET" || method === "HEAD" ? null : bodyOf(wireBodyFrom(wire.body))
+	});
+};
+var recordArg = (value, what) => {
+	if (!isRecord(value)) throw new CallError(`${what} is an object`);
+	return value;
+};
+var listEntryOf = (value) => {
+	const entry = recordArg(value, "A list entry");
+	return {
+		id: stringArg(entry.id, "A list entry’s id"),
+		score: numberArg(entry.score, "A list entry’s score"),
+		value: entry.value
+	};
+};
+var putOptionsOf = (value) => {
+	if (value === void 0 || value === null) return {};
+	const options = recordArg(value, "List options");
+	const keep = optionalNumber(options.keep, "keep");
+	return {
+		...keep === void 0 ? {} : { keep },
+		...options.higherOnly === true ? { higherOnly: true } : {}
+	};
+};
+var rangeOf = (value) => {
+	if (value === void 0 || value === null) return {};
+	const range = recordArg(value, "A list range");
+	const offset = optionalNumber(range.offset, "offset");
+	const limit = optionalNumber(range.limit, "limit");
+	return {
+		...offset === void 0 ? {} : { offset },
+		...limit === void 0 ? {} : { limit },
+		...range.order === "asc" || range.order === "desc" ? { order: range.order } : {}
+	};
+};
+/**
+* One `kv` call, its arguments read rather than trusted: they were written by the space's code, and the store below
+* takes typed values. The space's namespace is the store's, applied by the platform before the code ever had it.
+*/
+var kvCall = (kv, method, args) => {
+	const [first, second, third, fourth] = args;
+	switch (method) {
+		case "get": return kv.get(stringArg(first, "A key"));
+		case "set": return kv.set(stringArg(first, "A key"), second, optionalNumber(third, "A lifetime"));
+		case "delete": return kv.delete(stringArg(first, "A key"));
+		case "increment": return kv.increment(stringArg(first, "A key"), numberArg(second, "An amount"), optionalNumber(third, "A lifetime"));
+		case "swap": return kv.swap(stringArg(first, "A key"), second ?? void 0, third, optionalNumber(fourth, "A lifetime"));
+		case "listPut": return kv.listPut(stringArg(first, "A list"), listEntryOf(second), putOptionsOf(third));
+		case "listRange": return kv.listRange(stringArg(first, "A list"), rangeOf(second));
+		case "listRemove": return kv.listRemove(stringArg(first, "A list"), stringArg(second, "An entry id"));
+		default: return Promise.reject(new CallError(`kv has no "${method}"`));
+	}
+};
+var fetchInitOf = (value) => {
+	const init = recordArg(value, "A request");
+	const headers = init.headers === void 0 ? {} : recordArg(init.headers, "Headers");
+	return {
+		...init.method === void 0 ? {} : { method: stringArg(init.method, "A method") },
+		headers: Object.fromEntries(Object.entries(headers).map(([name, header]) => [name, stringArg(header, `Header "${name}"`)])),
+		...init.body === void 0 || init.body === null ? {} : { body: stringArg(init.body, "A body") },
+		...init.credential === void 0 ? {} : { credential: stringArg(init.credential, "A credential") }
+	};
+};
+var optionalString = (value, what) => value === void 0 || value === null ? void 0 : stringArg(value, what);
+/** A limit's numbers are checked where it is counted (`countRate`); here only that they are what they claim. */
+var rateLimitOf = (value) => {
+	const limit = recordArg(value, "A rate limit");
+	return {
+		most: numberArg(limit.most, "most"),
+		perSeconds: numberArg(limit.perSeconds, "perSeconds"),
+		...limit.per === "everyone" || limit.per === "caller" ? { per: limit.per } : {}
+	};
+};
+/**
+* A call as the code sent it, read into what it claims to be — every field checked, because it was written by the
+* space's code and carried by a runner, and neither is trusted here. The only place a call is read.
+*/
+var readCall = (value) => {
+	const call = recordArg(value, "A call");
+	switch (call.op) {
+		case "kv": return {
+			op: "kv",
+			method: stringArg(call.method, "A kv method"),
+			args: Array.isArray(call.args) ? call.args : []
+		};
+		case "fetch": return {
+			op: "fetch",
+			url: stringArg(call.url, "A URL"),
+			init: fetchInitOf(call.init ?? {})
+		};
+		case "publish": return {
+			op: "publish",
+			topic: stringArg(call.topic, "A topic"),
+			type: stringArg(call.type, "A type"),
+			data: call.data
+		};
+		case "grant": {
+			const ttlSeconds = optionalNumber(call.ttlSeconds, "A lifetime");
+			return {
+				op: "grant",
+				topic: stringArg(call.topic, "A topic"),
+				...ttlSeconds === void 0 ? {} : { ttlSeconds }
+			};
+		}
+		case "revoke": {
+			const grant = optionalString(call.grant, "A grant");
+			return {
+				op: "revoke",
+				topic: stringArg(call.topic, "A topic"),
+				...grant === void 0 ? {} : { grant }
+			};
+		}
+		case "rateLimit": return {
+			op: "rateLimit",
+			bucket: stringArg(call.bucket, "A bucket"),
+			limit: rateLimitOf(call.limit)
+		};
+		case "sign": return {
+			op: "sign",
+			value: stringArg(call.value, "A value")
+		};
+		case "verify": return {
+			op: "verify",
+			value: stringArg(call.value, "A value"),
+			signature: stringArg(call.signature, "A signature")
+		};
+		case "log": return {
+			op: "log",
+			values: Array.isArray(call.values) ? call.values : []
+		};
+		case "emit": return {
+			op: "emit",
+			chunk: call.chunk
+		};
+		default: throw new CallError("Not a call the platform answers");
+	}
+};
+/**
+* Answers one call from a space's code with the run's own {@link FunctionContext} — the same object a self-hosted
+* server hands its functions, so the sandbox can do exactly what native code can and not one thing more.
+*/
+var answerCall = async (ctx, call) => {
+	switch (call.op) {
+		case "kv": return kvCall(ctx.kv, call.method, call.args);
+		case "fetch": return wireResponseOf(await ctx.fetch(call.url, call.init));
+		case "publish": return ctx.publish(call.topic, call.type, call.data);
+		case "grant": return ctx.grant(call.topic, call.ttlSeconds);
+		case "revoke": return ctx.revoke(call.topic, call.grant);
+		case "rateLimit": return ctx.rateLimit(call.bucket, call.limit);
+		case "sign": return ctx.sign(call.value);
+		case "verify": return ctx.verify(call.value, call.signature);
+		case "log":
+			ctx.log(...call.values);
+			return;
+		case "emit":
+			ctx.emit(call.chunk);
+			return;
+	}
+};
+//#endregion
+export { answerCall, bodyOf, readCall, requestFromWire, responseOf, wireBodyOf, wireRequestOf, wireResponseFrom, wireResponseOf };

package/dist/modules/functions/config.d.ts

@@ -0,0 +1,34 @@
+import { FunctionsDefinition } from './contract';
+import { FunctionLimits, FunctionRunner, FunctionUsage } from './protocol';
+/** One invocation of a space's task, as metering sees it. */
+export type FunctionUsageRecord = {
+    spaceId: number;
+    task: string;
+    ok: boolean;
+    usage: FunctionUsage;
+};
+/**
+ * A server's functions. `native` is code the deployment trusts, loaded in its own process with the context narrowed to
+ * a function's; the spaces' own code — which nobody here reviewed — only ever runs in the sandbox (`runner`).
+ */
+export type FunctionsConfig = {
+    native?: FunctionsDefinition[];
+    /**
+     * Where the spaces' own functions run: `createRemoteRunner` for the runner service, a provider's adapter, or
+     * `createIsolateRunner` only where this process holds nothing a space must not reach. Absent, spaces have no
+     * functions here — their tasks are not offered and none of their code runs.
+     */
+    runner?: FunctionRunner;
+    /** The most one invocation may spend on this deployment. A space's plan may ask for less, never more. */
+    limits?: Partial<FunctionLimits>;
+    /**
+     * Asked before each invocation: why this space may not run code right now — its account spent its CPU for the minute,
+     * say — or nothing. What keeps one space's loop from slowing everybody else's on the same runner.
+     */
+    admit?: (spaceId: number) => Promise<string | undefined>;
+    /** Told what each invocation spent, however it ended: what `admit` budgets by, and what a deployment meters. */
+    onUsage?: (record: FunctionUsageRecord) => void;
+};
+export declare const DEFAULT_FUNCTION_LIMITS: FunctionLimits;
+/** What one invocation of a space may spend: its own limits, never above the deployment's. */
+export declare const functionLimitsFor: (ceilings?: Partial<FunctionLimits>, space?: Partial<FunctionLimits>) => FunctionLimits;

package/dist/modules/functions/config.js

@@ -0,0 +1,24 @@
+//#region src/modules/functions/config.ts
+var DEFAULT_FUNCTION_LIMITS = {
+	cpuMs: 100,
+	wallMs: 1e4,
+	memoryMb: 64,
+	outputBytes: 1e6,
+	calls: 100
+};
+/** What one invocation of a space may spend: its own limits, never above the deployment's. */
+var functionLimitsFor = (ceilings = {}, space = {}) => {
+	const ceiling = {
+		...DEFAULT_FUNCTION_LIMITS,
+		...ceilings
+	};
+	return {
+		cpuMs: Math.min(space.cpuMs ?? ceiling.cpuMs, ceiling.cpuMs),
+		wallMs: Math.min(space.wallMs ?? ceiling.wallMs, ceiling.wallMs),
+		memoryMb: Math.min(space.memoryMb ?? ceiling.memoryMb, ceiling.memoryMb),
+		outputBytes: Math.min(space.outputBytes ?? ceiling.outputBytes, ceiling.outputBytes),
+		calls: Math.min(space.calls ?? ceiling.calls, ceiling.calls)
+	};
+};
+//#endregion
+export { DEFAULT_FUNCTION_LIMITS, functionLimitsFor };

package/dist/modules/functions/context.d.ts

@@ -0,0 +1,17 @@
+import { FunctionContext } from './contract';
+import { ActionTaskContext } from '../actions/types';
+/**
+ * Whether `hostname` is one the space declared: exactly, or under a `*.` wildcard (`*.example.com` is every subdomain of
+ * it, and not `example.com` itself).
+ */
+export declare const hostAllowed: (hostname: string, hosts: readonly string[]) => boolean;
+/**
+ * How the values a function logs read as one line — the one formatting of it, for native functions and for the
+ * sandbox's, whose guest only makes each value safe to send.
+ */
+export declare const lineOf: (values: readonly unknown[]) => string;
+/**
+ * What a space's code is handed, built from the run's own context: the one place a {@link FunctionContext} is made.
+ * A self-hosted server hands it to the code directly; the platform answers the sandbox's calls with it.
+ */
+export declare const functionContextFor: (ctx: ActionTaskContext, hosts: readonly string[]) => FunctionContext;

package/dist/modules/functions/context.js

@@ -0,0 +1,88 @@
+import { fetchOutbound } from "../../helpers/outboundGuard.js";
+import { countRate } from "../actions/runtime/rateLimit.js";
+import { processTwigParam } from "@plitzi/sdk-shared/helpers/twigWrapper";
+//#region src/modules/functions/context.ts
+/**
+* Whether `hostname` is one the space declared: exactly, or under a `*.` wildcard (`*.example.com` is every subdomain of
+* it, and not `example.com` itself).
+*/
+var hostAllowed = (hostname, hosts) => {
+	const host = hostname.toLowerCase();
+	return hosts.some((entry) => {
+		const allowed = entry.toLowerCase();
+		return allowed.startsWith("*.") ? host.endsWith(allowed.slice(1)) : host === allowed;
+	});
+};
+var userOf = ({ id, username, email, verified, permissions, roles }) => ({
+	id,
+	username,
+	email,
+	verified,
+	permissions,
+	roles
+});
+/**
+* A function's `fetch`: only to the hosts the space declared, through the platform's outbound guard (the same rule and
+* the same run budget `http.request` goes through), and — naming a credential — with its values written in where the
+* request says `{{credential.<key>}}`. The value is resolved here and never handed to the code.
+*/
+var functionFetch = (ctx, hosts) => async (input, init = {}) => {
+	const credential = init.credential ? await ctx.credential(init.credential) : void 0;
+	if (init.credential && !credential) throw new Error(`Credential "${init.credential}" is not available for this space`);
+	const render = (value) => credential ? String(processTwigParam(value, { credential })) : value;
+	let url;
+	try {
+		url = new URL(render(typeof input === "string" ? input : input.href));
+	} catch {
+		throw new Error("A function fetches an absolute URL");
+	}
+	if (!hostAllowed(url.hostname, hosts)) throw new Error(`"${url.hostname}" is not among the hosts this space's functions may reach (allow.hosts)`);
+	const headers = Object.fromEntries(Object.entries(init.headers ?? {}).map(([name, value]) => [name, render(value)]));
+	return fetchOutbound(ctx.fetch, url, {
+		method: init.method ?? "GET",
+		headers,
+		body: init.body === void 0 ? void 0 : render(init.body),
+		signal: ctx.signal
+	});
+};
+/**
+* How the values a function logs read as one line — the one formatting of it, for native functions and for the
+* sandbox's, whose guest only makes each value safe to send.
+*/
+var lineOf = (values) => values.map((value) => {
+	if (typeof value === "string") return value;
+	if (value instanceof Error) return `${value.name}: ${value.message}`;
+	if (value === void 0 || typeof value === "function" || typeof value === "symbol") return typeof value;
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return Object.prototype.toString.call(value);
+	}
+}).join(" ");
+var unavailable = (what) => () => Promise.reject(/* @__PURE__ */ new Error(`This server has no realtime channels (${what})`));
+var unsigned = () => Promise.reject(/* @__PURE__ */ new Error("This server signs nothing: its actions were given no signingSecret"));
+/**
+* What a space's code is handed, built from the run's own context: the one place a {@link FunctionContext} is made.
+* A self-hosted server hands it to the code directly; the platform answers the sandbox's calls with it.
+*/
+var functionContextFor = (ctx, hosts) => ({
+	spaceId: ctx.spaceId,
+	environment: ctx.environment,
+	runId: ctx.runId,
+	trigger: ctx.trigger,
+	callerId: ctx.callerId,
+	...ctx.user ? { user: userOf(ctx.user) } : {},
+	kv: ctx.kv,
+	rateLimit: (bucket, limit) => countRate(ctx.kv, ctx.callerId, bucket, limit),
+	sign: ctx.sign ?? unsigned,
+	verify: ctx.verify ?? unsigned,
+	fetch: functionFetch(ctx, hosts),
+	publish: ctx.publish ?? unavailable("publish"),
+	grant: ctx.grant ?? unavailable("grant"),
+	revoke: ctx.revoke ?? unavailable("revoke"),
+	log: (...values) => ctx.log(lineOf(values)),
+	emit: ctx.emit,
+	signal: ctx.signal
+});
+//#endregion
+export { functionContextFor, hostAllowed, lineOf };

package/dist/modules/functions/contract.d.ts

@@ -0,0 +1,121 @@
+import { RateCount, RateLimit } from '../actions/runtime/rateLimit';
+import { ActionKvStore } from '../actions/types';
+import { Environment, InteractionCallbackParam } from '@plitzi/sdk-shared';
+/**
+ * Who started the run, as a space's own code may know them: everything a function decides by — who, their roles and
+ * permissions — and never their session. A token inside the sandbox is a token a function could send anywhere.
+ */
+export type FunctionUser = {
+    id: number;
+    username: string;
+    email: string;
+    verified: boolean;
+    permissions: string[];
+    roles: string[];
+};
+/**
+ * A request a function makes: `fetch`'s own init, and `credential` — the id of one of the space's credentials, whose
+ * values the platform writes into the request where it says `{{credential.<key>}}` (in the URL, a header or the
+ * body). The code never holds the value; it names it.
+ */
+export type FunctionFetchInit = {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    credential?: string;
+};
+/** What a function's `fetch` answers: a web `Response`, whichever runner it is in. */
+export type FunctionFetch = (url: string | URL, init?: FunctionFetchInit) => Promise<Response>;
+/**
+ * Everything a space's code can do besides computing — one object, the same wherever it runs. In a self-hosted server
+ * it is built from the run's own context; in the sandbox each method is a call back to the platform, which scopes it
+ * to the space and the run before doing it.
+ */
+export type FunctionContext = {
+    spaceId: number;
+    environment: Environment;
+    runId: string;
+    /** How the run was started: `call`, `render`, `schedule`, `webhook`… */
+    trigger: string;
+    /** `user:<id>` for a session, `ip:<address>` for everyone else — what a limit per person keys on. */
+    callerId: string;
+    user?: FunctionUser;
+    /**
+     * The space's own key/value store: `get`, `set`, `swap`, `increment`, lists — and `change`, to read, change and write
+     * a value back without undoing a writer that got there first.
+     */
+    kv: ActionKvStore;
+    /**
+     * Counts one more of `bucket` — per caller unless `per: 'everyone'` — and says whether it was within `most` in every
+     * `perSeconds`. The same count as a flow's `flow.rateLimit` step on that bucket. What to answer when it is not is the
+     * code's.
+     */
+    rateLimit: (bucket: string, limit: RateLimit) => Promise<RateCount>;
+    /**
+     * Signs `value` with a key of the space's own that the platform keeps and the code never sees: HMAC-SHA-256,
+     * base64url. What a link, an invitation or a key handed to a page is made of. Refused on a server with no signing
+     * secret.
+     */
+    sign: (value: string) => Promise<string>;
+    /** Whether `signature` is what `sign` answered for `value`, compared in constant time. */
+    verify: (value: string, signature: string) => Promise<boolean>;
+    /** To the hosts the space declared (`allow.hosts`) — and, with `credential`, with one of its secrets written in. */
+    fetch: FunctionFetch;
+    /** Says something on one of the space's realtime channels, as the server. */
+    publish: (topic: string, type: string, data: unknown) => Promise<void>;
+    /** Lets the visitor into one topic of a private (`grant: true`) channel. */
+    grant: (topic: string, ttlSeconds?: number) => Promise<string>;
+    /** Takes a grant back — or every grant for the topic, naming none. */
+    revoke: (topic: string, grant?: string) => Promise<void>;
+    /** A line for whoever reads the run: the builder's Try, and the deployment's logs. */
+    log: (...values: unknown[]) => void;
+    /** Progress for a caller that asked for a stream — a no-op when nobody did. */
+    emit: (chunk: unknown) => void;
+    /** Aborted when the run is: cancelled, or out of time. Hand it to what can stop early. */
+    signal: AbortSignal;
+};
+/**
+ * One step a server action can take, written by the space. The shape of the platform's own tasks — addressed as
+ * `<namespace>.<action>`, drawn in the builder from `params` — run with a {@link FunctionContext} rather than the
+ * platform's full one.
+ */
+export type FunctionTask<T extends Record<string, unknown> = Record<string, unknown>> = {
+    namespace: string;
+    action: string;
+    title: string;
+    description?: string;
+    params: Record<keyof T, InteractionCallbackParam<T>>;
+    run: (params: T, ctx: FunctionContext) => unknown;
+};
+/** What a route's handler gets besides the request: the context, and the `:params` its key named, by name. */
+export type FunctionRouteContext = FunctionContext & {
+    params: Record<string, string>;
+};
+/**
+ * An HTTP endpoint of the space, under `/api/`: a web-standard handler, the shape every edge runtime runs. The request
+ * carries no credentials — `ctx.user` says who is asking — and the response sets no cookies: the host's are the
+ * platform's.
+ */
+export type FunctionRoute = (request: Request, ctx: FunctionRouteContext) => Response | Promise<Response>;
+/** What a space's `functions/index.ts` exports: its tasks, its routes, and where its code may reach. */
+export type FunctionsDefinition = {
+    /** The hosts `ctx.fetch` may reach. Anything else is refused before it leaves. */
+    allow?: {
+        hosts?: string[];
+    };
+    tasks?: FunctionTask<never>[];
+    /** `'GET /board-assets/:board/:asset'` → a handler, served at `/api/board-assets/…`. */
+    routes?: Record<string, FunctionRoute>;
+};
+/**
+ * What a function throws to refuse, with a reason written for whoever asked — a wrong password, a board that is
+ * read-only. Its message reaches the page as the step's error (`{{ step.error }}`), and a route answers it with a 400;
+ * anything else a function throws stays in the run's record, since an error can carry what a visitor must not read.
+ * The platform's own class: the same natively and, printed into the bundle, in the sandbox.
+ */
+export { ActionRefusal } from '../actions/runtime/errors';
+/**
+ * Declares a space's functions. An identity at run time: it is here for the types, and so the same file is valid
+ * wherever it is loaded — natively in a self-hosted server, or built by the platform and run in its sandbox.
+ */
+export declare const defineFunctions: (definition: FunctionsDefinition) => FunctionsDefinition;

package/dist/modules/functions/contract.js

@@ -0,0 +1,9 @@
+import { ActionRefusal } from "../actions/runtime/errors.js";
+//#region src/modules/functions/contract.ts
+/**
+* Declares a space's functions. An identity at run time: it is here for the types, and so the same file is valid
+* wherever it is loaded — natively in a self-hosted server, or built by the platform and run in its sandbox.
+*/
+var defineFunctions = (definition) => definition;
+//#endregion
+export { ActionRefusal, defineFunctions };

package/dist/modules/functions/driver.d.ts

@@ -0,0 +1,36 @@
+import { changeKv } from '../actions/runtime/kvChange';
+/**
+ * What a driver needs of where it runs: the way to the platform, and that place's own `Request` and `Response`.
+ */
+export type FunctionsDriverEnvironment = {
+    /** A call to the platform (a `FunctionCall`): its value, or it throws what the platform said. */
+    call: (message: Record<string, unknown>) => Promise<unknown>;
+    /** Aborted when the invocation is: `ctx.signal`, this environment's own `AbortSignal`, handed through untouched. */
+    signal: unknown;
+    /** What `ctx.fetch` was answered, as this environment's `Response`. */
+    responseOf: (wire: Record<string, unknown>) => unknown;
+    /** A route's request, as this environment's `Request`. */
+    requestOf: (wire: Record<string, unknown>) => unknown;
+    /** What a route answered, as the wire carries it — `undefined` when it is not this environment's `Response`. */
+    wireOfResponse: (response: unknown) => Promise<Record<string, unknown> | undefined>;
+    changeKv: typeof changeKv;
+    /** The error a refusal is: what the code throws to tell whoever asked, not a fault. */
+    refusal: (message: string) => Error;
+};
+/**
+ * What a definition declares, as the platform reads a manifest (`readManifest`) — nothing of it trusted there. Printed
+ * into the sandbox's guest and imported by a space runtime, like the driver below: self-contained for that.
+ */
+export declare const describeFunctions: (definition: unknown) => Record<string, unknown>;
+/**
+ * A space's functions, driven: one invocation of a definition — a task or a route, with a `ctx` whose every method is
+ * a call to the platform.
+ *
+ * The one driver there is. The sandbox's guest is handed this function's SOURCE and runs it inside the isolate
+ * (`isolate.ts`), and a space runtime imports it and runs it in its own process — so code behaves the same in both, down
+ * to `ctx`. Self-contained by contract for that: no import, nothing of this module's, only what `environment` brings.
+ */
+export declare const createFunctionsDriver: (environment: FunctionsDriverEnvironment) => {
+    invoke: (definition: unknown, invocation: Record<string, unknown>) => Promise<unknown>;
+    log: (...values: unknown[]) => void;
+};