@plitzi/sdk-server 0.37.2 → 0.37.4

package/dist/modules/functions/driver.js

@@ -0,0 +1,150 @@
+//#region src/modules/functions/driver.ts
+/**
+* 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.
+*/
+var describeFunctions = (definition) => {
+	const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+	const listOf = (value) => Array.isArray(value) ? value : [];
+	const found = isRecord(definition) ? definition : {};
+	return {
+		hosts: listOf((isRecord(found.allow) ? found.allow : {}).hosts),
+		tasks: listOf(found.tasks).map((task) => isRecord(task) ? {
+			namespace: task.namespace,
+			action: task.action,
+			title: task.title,
+			description: task.description,
+			params: task.params
+		} : {}),
+		routes: isRecord(found.routes) ? Object.keys(found.routes) : []
+	};
+};
+/**
+* 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.
+*/
+var createFunctionsDriver = (environment) => {
+	const { call, signal, responseOf, requestOf, wireOfResponse, refusal } = environment;
+	const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+	const isCallable = (value) => typeof value === "function";
+	const listOf = (value) => Array.isArray(value) ? value : [];
+	/** A value as the wire can carry it; how a line reads is the platform's (`lineOf`), not the driver's. */
+	const wireValue = (value) => {
+		if (value instanceof Error) return `${value.name}: ${value.message}`;
+		if (value === void 0 || typeof value === "function" || typeof value === "symbol" || typeof value === "bigint") return typeof value;
+		return value;
+	};
+	/** `ctx.log`, and whatever else the code writes a line with: onto its step, never failing the code for it. */
+	const log = (...values) => {
+		call({
+			op: "log",
+			values: values.map(wireValue)
+		}).catch(() => void 0);
+	};
+	const contextOf = (invocation) => {
+		const facts = isRecord(invocation.context) ? invocation.context : {};
+		const kvCall = (method) => (...args) => call({
+			op: "kv",
+			method,
+			args
+		});
+		const kv = {
+			get: kvCall("get"),
+			set: kvCall("set"),
+			delete: kvCall("delete"),
+			increment: kvCall("increment"),
+			swap: (key, expected, next, ttlSeconds) => kvCall("swap")(key, expected, next, ttlSeconds).then((written) => written === true),
+			listPut: kvCall("listPut"),
+			listRange: kvCall("listRange"),
+			listRemove: kvCall("listRemove"),
+			change: (key, change, lifetime) => environment.changeKv(kv, key, change, {
+				lifetime,
+				refusal
+			})
+		};
+		return {
+			...facts,
+			kv,
+			fetch: async (url, init = {}) => {
+				const answer = await call({
+					op: "fetch",
+					url: String(url),
+					init
+				});
+				return responseOf(isRecord(answer) ? answer : {});
+			},
+			publish: async (topic, type, data) => {
+				await call({
+					op: "publish",
+					topic,
+					type,
+					data
+				});
+			},
+			grant: (topic, ttlSeconds) => call({
+				op: "grant",
+				topic,
+				ttlSeconds
+			}),
+			revoke: async (topic, grant) => {
+				await call({
+					op: "revoke",
+					topic,
+					grant
+				});
+			},
+			rateLimit: (bucket, limit) => call({
+				op: "rateLimit",
+				bucket,
+				limit
+			}),
+			sign: (value) => call({
+				op: "sign",
+				value
+			}),
+			verify: (value, signature) => call({
+				op: "verify",
+				value,
+				signature
+			}),
+			log,
+			emit: (chunk) => {
+				call({
+					op: "emit",
+					chunk
+				}).catch(() => void 0);
+			},
+			signal
+		};
+	};
+	/** One invocation: what a task returned (`null` for nothing), or the wire response a route answered. */
+	const invoke = async (definition, invocation) => {
+		const found = isRecord(definition) ? definition : {};
+		const ctx = contextOf(invocation);
+		if (invocation.kind === "task") {
+			const task = listOf(found.tasks).find((entry) => isRecord(entry) && `${String(entry.namespace)}.${String(entry.action)}` === invocation.name);
+			if (!isRecord(task) || !isCallable(task.run)) throw new Error(`This space's functions have no task "${String(invocation.name)}"`);
+			const value = await task.run(isRecord(invocation.params) ? invocation.params : {}, ctx);
+			return value === void 0 ? null : value;
+		}
+		const handler = (isRecord(found.routes) ? found.routes : {})[String(invocation.key)];
+		if (!isCallable(handler)) throw new Error(`This space's functions have no route "${String(invocation.key)}"`);
+		const request = requestOf(isRecord(invocation.request) ? invocation.request : {});
+		const wire = await wireOfResponse(await handler(request, {
+			...ctx,
+			params: invocation.params
+		}));
+		if (!wire) throw new Error(`Route "${String(invocation.key)}" answered something that is not a Response`);
+		return wire;
+	};
+	return {
+		invoke,
+		log
+	};
+};
+//#endregion
+export { createFunctionsDriver, describeFunctions };

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

@@ -0,0 +1,15 @@
+import { FunctionsSource } from './build';
+import { FunctionsDefinition } from './contract';
+/**
+ * A `functions/` directory as a source — the files the platform's rule counts, by their path inside it: what a space's
+ * functions are saved as, and what `loadFunctions` builds.
+ */
+export declare const readFunctionsDir: (dir: string | URL) => Promise<FunctionsSource>;
+/**
+ * A server's own functions from a directory — a project's `functions/`, the working copy `plitzi functions` keeps —
+ * built exactly as the platform builds a space's (the same rules, one bundle) and loaded natively, for
+ * `createServer({ functions: { native } })`. The same on `node src/main.ts` and on a compiled server: nothing here
+ * depends on how the server itself runs. A directory with nothing in it is no functions; one that does not build, or
+ * whose `index.ts` exports no definition, stops the server with where it is wrong.
+ */
+export declare const loadFunctions: (dir: string | URL) => Promise<FunctionsDefinition[]>;

package/dist/modules/functions/load.js

@@ -0,0 +1,45 @@
+import { buildFunctions } from "./build.js";
+import { readFunctionsSource } from "@plitzi/sdk-shared/actions";
+import { fileURLToPath } from "node:url";
+import { readFile, readdir } from "node:fs/promises";
+//#region src/modules/functions/load.ts
+var nodeReader = {
+	list: async (dir) => (await readdir(dir, { withFileTypes: true })).map((entry) => ({
+		name: entry.name,
+		directory: entry.isDirectory()
+	})),
+	read: (file) => readFile(file, "utf8")
+};
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Whether a module's default export has a definition's shape: what a server can register without surprises. */
+var isFunctionsDefinition = (value) => {
+	if (!isRecord(value)) return false;
+	const { tasks, routes, allow } = value;
+	const tasksOk = tasks === void 0 || Array.isArray(tasks) && tasks.every((task) => isRecord(task) && typeof task.run === "function");
+	const routesOk = routes === void 0 || isRecord(routes) && Object.values(routes).every((route) => typeof route === "function");
+	const allowOk = allow === void 0 || isRecord(allow) && (allow.hosts === void 0 || Array.isArray(allow.hosts) && allow.hosts.every((host) => typeof host === "string"));
+	return tasksOk && routesOk && allowOk;
+};
+/**
+* A `functions/` directory as a source — the files the platform's rule counts, by their path inside it: what a space's
+* functions are saved as, and what `loadFunctions` builds.
+*/
+var readFunctionsDir = (dir) => readFunctionsSource(typeof dir === "string" ? dir : fileURLToPath(dir), nodeReader);
+/**
+* A server's own functions from a directory — a project's `functions/`, the working copy `plitzi functions` keeps —
+* built exactly as the platform builds a space's (the same rules, one bundle) and loaded natively, for
+* `createServer({ functions: { native } })`. The same on `node src/main.ts` and on a compiled server: nothing here
+* depends on how the server itself runs. A directory with nothing in it is no functions; one that does not build, or
+* whose `index.ts` exports no definition, stops the server with where it is wrong.
+*/
+var loadFunctions = async (dir) => {
+	const source = await readFunctionsDir(dir);
+	if (!Object.keys(source).length) return [];
+	const { code } = await buildFunctions(source);
+	const loaded = await import(`data:text/javascript;base64,${Buffer.from(code).toString("base64")}`);
+	const definition = isRecord(loaded) ? loaded.default : void 0;
+	if (!isFunctionsDefinition(definition)) throw new Error("functions/index.ts exports its definition by default: export default defineFunctions({ … })");
+	return [definition];
+};
+//#endregion
+export { loadFunctions, readFunctionsDir };

package/dist/modules/functions/load.test.d.ts

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

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

@@ -0,0 +1,29 @@
+import { FunctionsSource } from './build';
+import { FunctionLimits } from './protocol';
+import { ActionRunResult } from '../actions';
+import { FunctionsProblem } from '@plitzi/sdk-shared';
+export type LocalFunctionsOptions = {
+    /** Credentials `ctx.fetch` may name, by id — a project's own, from its environment; none by default. */
+    credentials?: Record<string, Record<string, string>>;
+    /** As the platform's: a plan's limits, for code that must fit them there. */
+    limits?: Partial<FunctionLimits>;
+    fetchImpl?: typeof fetch;
+};
+export type LocalFunctions = {
+    /** Builds and checks the source as the platform does, and keeps it as what `tryTask` runs. */
+    load: (source: FunctionsSource) => Promise<{
+        ok: true;
+        tasks: string[];
+    } | {
+        ok: false;
+        problems: FunctionsProblem[];
+    }>;
+    /** One task of what was loaded, in an isolate, with its value, logs and error — the platform's Try, here. */
+    tryTask: (task: string, params: Record<string, unknown>) => Promise<ActionRunResult>;
+};
+/**
+ * A space's functions run on this machine exactly as the platform runs them — the same build, the same checks, the same
+ * isolates and limits, `ctx` over the same actions module — so what works here works there. `kv` lives as long as this
+ * does. What `plitzi functions dev` is made of; needs `isolated-vm` and `core-js` installed, as any runner does.
+ */
+export declare const createLocalFunctions: ({ credentials, limits, fetchImpl }?: LocalFunctionsOptions) => LocalFunctions;

package/dist/modules/functions/local.js

@@ -0,0 +1,61 @@
+import { functionsInHand } from "./space.js";
+import { createActionsModule } from "../actions/index.js";
+import { functionTryEntry } from "./tryEntry.js";
+import { createIsolateRunner } from "./sandbox/isolate.js";
+import { randomUUID } from "node:crypto";
+//#region src/modules/functions/local.ts
+/** Who a local run is for: somebody signed in, with nothing to forward. */
+var LOCAL_USER = {
+	id: 0,
+	username: "local",
+	email: "local@localhost",
+	verified: true,
+	permissions: [],
+	roles: [],
+	token: ""
+};
+/**
+* A space's functions run on this machine exactly as the platform runs them — the same build, the same checks, the same
+* isolates and limits, `ctx` over the same actions module — so what works here works there. `kv` lives as long as this
+* does. What `plitzi functions dev` is made of; needs `isolated-vm` and `core-js` installed, as any runner does.
+*/
+var createLocalFunctions = ({ credentials = {}, limits, fetchImpl } = {}) => {
+	const runner = createIsolateRunner({ concurrency: 1 });
+	let loaded;
+	const module = createActionsModule({
+		lookups: {
+			getAction: () => Promise.resolve(void 0),
+			getCredential: (_spaceId, identifier) => Promise.resolve(Object.hasOwn(credentials, identifier) ? credentials[identifier] : void 0),
+			getFunctions: () => Promise.resolve(loaded)
+		},
+		functions: {
+			runner,
+			...limits ? { limits } : {}
+		},
+		jobs: false,
+		...fetchImpl ? { fetchImpl } : {}
+	});
+	return {
+		load: async (source) => {
+			const prepared = await module.prepareFunctions(source);
+			if (!prepared.ok) return prepared;
+			loaded = functionsInHand(prepared.functions);
+			return {
+				ok: true,
+				tasks: prepared.functions.manifest.tasks.map((task) => `${task.namespace}.${task.action}`)
+			};
+		},
+		tryTask: (task, params) => module.runAction({
+			entry: functionTryEntry(task, params),
+			input: {},
+			callerId: "local",
+			user: LOCAL_USER,
+			spaceId: 0,
+			environment: "main",
+			trigger: "call",
+			runId: randomUUID()
+		})
+	};
+};
+//#endregion
+export { createLocalFunctions };

package/dist/modules/functions/local.test.d.ts

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

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

@@ -0,0 +1,24 @@
+import { FunctionsManifest } from '@plitzi/sdk-shared';
+export declare const ROUTE_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE"];
+export type RouteMethod = (typeof ROUTE_METHODS)[number];
+export type RouteKey = {
+    method: RouteMethod;
+    segments: string[];
+};
+/**
+ * A route key, `'<METHOD> /<path>'`: literal segments and `:params`, served under `/api/`. Anything else — a query, a
+ * wildcard, `..` — is not a key, so what a space may answer is only ever a path it spelled out.
+ */
+export declare const parseRouteKey: (key: string) => RouteKey | undefined;
+export type ManifestReading = {
+    manifest: FunctionsManifest;
+    problems: string[];
+};
+/**
+ * Reads what a bundle said it declares, and every rule it must meet — the one validator, at save and nowhere else
+ * afterwards, because what is stored is only ever what passed it.
+ *
+ * `reserved` is every namespace this deployment's own tasks use: a space's task may take none of them, so a step that
+ * names a platform task always runs the platform's.
+ */
+export declare const readManifest: (value: unknown, reserved: ReadonlySet<string>) => ManifestReading;

package/dist/modules/functions/manifest.js

@@ -0,0 +1,163 @@
+import { taskName, taskNameProblem } from "../actions/tasks/registry.js";
+//#region src/modules/functions/manifest.ts
+var ROUTE_METHODS = [
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE"
+];
+var SEGMENT = /^(:[a-zA-Z][a-zA-Z0-9]*|[A-Za-z0-9._~-]+)$/;
+var isRouteMethod = (method) => ROUTE_METHODS.some((known) => known === method);
+/**
+* A route key, `'<METHOD> /<path>'`: literal segments and `:params`, served under `/api/`. Anything else — a query, a
+* wildcard, `..` — is not a key, so what a space may answer is only ever a path it spelled out.
+*/
+var parseRouteKey = (key) => {
+	const [method = "", path = "", ...rest] = key.trim().split(/\s+/);
+	if (rest.length || !isRouteMethod(method) || !path.startsWith("/")) return;
+	const segments = path.slice(1).split("/");
+	if (!segments.every((segment) => SEGMENT.test(segment) && segment !== "." && segment !== "..")) return;
+	return {
+		method,
+		segments
+	};
+};
+var HOST = /^(\*\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/;
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var stringOf = (value) => typeof value === "string" ? value : void 0;
+var optionsOf = (value) => Array.isArray(value) ? value.flatMap((option) => {
+	const label = isRecord(option) ? stringOf(option.label) : void 0;
+	const optionValue = isRecord(option) ? stringOf(option.value) : void 0;
+	return label !== void 0 && optionValue !== void 0 ? [{
+		label,
+		value: optionValue
+	}] : [];
+}) : void 0;
+/**
+* One param, rebuilt from what the bundle said rather than trusted: only the serializable shapes a step editor draws.
+* A computed `type`, `when` or `options` is code, and a bundle's code runs in the sandbox, never in the builder.
+*/
+var paramOf = (value) => {
+	if (!isRecord(value)) return "is not an object";
+	const base = {
+		...typeof value.canBind === "boolean" ? { canBind: value.canBind } : {},
+		...typeof value.label === "string" ? { label: value.label } : {},
+		...typeof value.when === "boolean" ? { when: value.when } : {}
+	};
+	const defaultValue = value.defaultValue;
+	switch (value.type) {
+		case "text":
+		case "textarea": return {
+			...base,
+			type: value.type,
+			...typeof defaultValue === "string" || typeof defaultValue === "number" ? { defaultValue } : {}
+		};
+		case "codemirror-text":
+		case "codemirror-json": return {
+			...base,
+			type: value.type,
+			...typeof defaultValue === "string" ? { defaultValue } : {}
+		};
+		case "boolean": return {
+			...base,
+			type: "boolean",
+			...typeof defaultValue === "boolean" ? { defaultValue } : {}
+		};
+		case "elements": return {
+			...base,
+			type: "elements",
+			...Array.isArray(defaultValue) ? { defaultValue: defaultValue.filter((id) => typeof id === "string") } : {},
+			...typeof value.elementType === "string" ? { elementType: value.elementType } : {}
+		};
+		case "select": {
+			const options = optionsOf(value.options);
+			if (!options?.length) return "is a select with no options";
+			return {
+				...base,
+				type: "select",
+				options,
+				...typeof defaultValue === "string" ? { defaultValue } : {}
+			};
+		}
+		default: return `has a type the builder cannot draw ("${String(value.type)}"): text, textarea, codemirror-text, codemirror-json, boolean, elements or select`;
+	}
+};
+/**
+* Reads what a bundle said it declares, and every rule it must meet — the one validator, at save and nowhere else
+* afterwards, because what is stored is only ever what passed it.
+*
+* `reserved` is every namespace this deployment's own tasks use: a space's task may take none of them, so a step that
+* names a platform task always runs the platform's.
+*/
+var readManifest = (value, reserved) => {
+	const problems = [];
+	const raw = isRecord(value) ? value : {};
+	const hosts = Array.isArray(raw.hosts) ? raw.hosts.filter((host) => typeof host === "string") : [];
+	hosts.filter((host) => !HOST.test(host)).forEach((host) => {
+		problems.push(`allow.hosts: "${host}" is not a hostname (a name like api.example.com, or *.example.com)`);
+	});
+	const tasks = [];
+	const names = /* @__PURE__ */ new Set();
+	(Array.isArray(raw.tasks) ? raw.tasks : []).forEach((entry, index) => {
+		const task = isRecord(entry) ? entry : {};
+		const namespace = stringOf(task.namespace) ?? "";
+		const action = stringOf(task.action) ?? "";
+		const title = stringOf(task.title) ?? "";
+		const where = namespace && action ? `Task "${namespace}.${action}"` : `tasks[${String(index)}]`;
+		const nameProblem = taskNameProblem({
+			namespace,
+			action
+		}, reserved);
+		if (nameProblem) {
+			problems.push(nameProblem);
+			return;
+		}
+		const name = taskName({
+			namespace,
+			action
+		});
+		if (names.has(name)) {
+			problems.push(`${where} is declared twice`);
+			return;
+		}
+		names.add(name);
+		if (!title) problems.push(`${where} has no title`);
+		const params = {};
+		Object.entries(isRecord(task.params) ? task.params : {}).forEach(([key, param]) => {
+			const read = paramOf(param);
+			if (typeof read === "string") problems.push(`${where}: param "${key}" ${read}`);
+			else params[key] = read;
+		});
+		const description = stringOf(task.description);
+		tasks.push({
+			namespace,
+			action,
+			title,
+			...description ? { description } : {},
+			params
+		});
+	});
+	const routes = Array.isArray(raw.routes) ? raw.routes.filter((route) => typeof route === "string") : [];
+	const routed = /* @__PURE__ */ new Set();
+	routes.forEach((route) => {
+		const key = parseRouteKey(route);
+		if (!key) {
+			problems.push(`Route "${route}" is not "<GET|POST|PUT|PATCH|DELETE> /<path>" of literal segments and :params`);
+			return;
+		}
+		const shape = `${key.method} /${key.segments.map((segment) => segment.startsWith(":") ? ":" : segment).join("/")}`;
+		if (routed.has(shape)) problems.push(`Route "${route}" answers the same requests as another one`);
+		routed.add(shape);
+	});
+	return {
+		manifest: {
+			hosts,
+			tasks,
+			routes
+		},
+		problems
+	};
+};
+//#endregion
+export { ROUTE_METHODS, parseRouteKey, readManifest };

package/dist/modules/functions/manifest.test.d.ts

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

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

@@ -0,0 +1,8 @@
+import { FunctionsDefinition } from './contract';
+import { ActionTask } from '../actions/types';
+/**
+ * A server's own functions, loaded as they are: trusted code the deployment ships — a self-hosted server's, or a
+ * platform's own — run in the process with the run's context narrowed to what a function may see. The same code a
+ * space runs in the sandbox, loaded without one.
+ */
+export declare const nativeTasks: (definitions?: readonly FunctionsDefinition[]) => ActionTask<Record<string, unknown>>[];

package/dist/modules/functions/native.js

@@ -0,0 +1,21 @@
+import { functionContextFor } from "./context.js";
+//#region src/modules/functions/native.ts
+/**
+* A server's own functions, loaded as they are: trusted code the deployment ships — a self-hosted server's, or a
+* platform's own — run in the process with the run's context narrowed to what a function may see. The same code a
+* space runs in the sandbox, loaded without one.
+*/
+var nativeTasks = (definitions = []) => definitions.flatMap((definition) => (definition.tasks ?? []).map((task) => {
+	const contextFor = (ctx) => functionContextFor(ctx, definition.allow?.hosts ?? []);
+	const { run, params } = task;
+	return {
+		namespace: task.namespace,
+		action: task.action,
+		title: task.title,
+		...task.description ? { description: task.description } : {},
+		params,
+		run: (values, ctx) => run(values, contextFor(ctx))
+	};
+}));
+//#endregion
+export { nativeTasks };

package/dist/modules/functions/native.test.d.ts

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