@plitzi/sdk-server 0.37.2 → 0.37.4

package/dist/modules/actions/tasks/flow.js

@@ -1,4 +1,6 @@
+import { ActionRefusal } from "../runtime/errors.js";
 import onAbort from "../../../helpers/onAbort.js";
+import { countRate } from "../runtime/rateLimit.js";
 //#region src/modules/actions/tasks/flow.ts
 var MAX_DELAY_MS = 5e3;
 /**
@@ -30,19 +32,31 @@ var delay = {
 		return { waited: waitMs };
 	}
 };
-/** Ends the run as failed, on purpose. The message reaches the trace, never the caller. */
+/**
+* Ends the run as failed, on purpose. The message reaches the trace — and, with `tellCaller`, the caller too, as the
+* run's `error`: a guard whose reason the page should show ("that name is taken") rather than a generic failure.
+*/
 var fail = {
 	namespace: "flow",
 	action: "fail",
 	title: "Fail",
-	params: { message: {
-		type: "text",
-		canBind: true,
-		defaultValue: "",
-		label: "Message"
-	} },
-	run: ({ message }) => {
-		throw new Error(message || "Action failed");
+	params: {
+		message: {
+			type: "text",
+			canBind: true,
+			defaultValue: "",
+			label: "Message"
+		},
+		tellCaller: {
+			type: "boolean",
+			canBind: true,
+			defaultValue: false,
+			label: "Tell the caller why"
+		}
+	},
+	run: ({ message, tellCaller }) => {
+		const text = message || "Action failed";
+		throw tellCaller === true || tellCaller === "true" ? new ActionRefusal(text) : new Error(text);
 	}
 };
 /**
@@ -121,7 +135,64 @@ var flowTasks = [
 	delay,
 	fail,
 	output,
-	onFailure
+	onFailure,
+	{
+		namespace: "flow",
+		action: "rateLimit",
+		title: "Rate Limit",
+		params: {
+			bucket: {
+				type: "text",
+				canBind: true,
+				defaultValue: "",
+				label: "Name (what is counted — \"comments\")"
+			},
+			limit: {
+				type: "text",
+				canBind: true,
+				defaultValue: "10",
+				label: "At most"
+			},
+			windowSeconds: {
+				type: "text",
+				canBind: true,
+				defaultValue: "60",
+				label: "Every (seconds)"
+			},
+			per: {
+				type: "select",
+				canBind: true,
+				defaultValue: "caller",
+				label: "Counted",
+				options: [{
+					label: "For each person",
+					value: "caller"
+				}, {
+					label: "For everyone together",
+					value: "everyone"
+				}]
+			},
+			message: {
+				type: "text",
+				canBind: true,
+				defaultValue: "",
+				label: "Refusal (what the caller is told)"
+			}
+		},
+		run: async ({ bucket, limit, windowSeconds, per, message }, ctx) => {
+			const perSeconds = Number(windowSeconds);
+			const { allowed, count, remaining } = await countRate(ctx.kv, ctx.callerId, bucket, {
+				most: Number(limit),
+				perSeconds,
+				per: per === "everyone" ? "everyone" : "caller"
+			});
+			if (!allowed) throw new ActionRefusal(message || `Too many at once — try again in ${String(perSeconds)} seconds`);
+			return {
+				count,
+				remaining
+			};
+		}
+	}
 ];
 var streamTasks = [emit];
 //#endregion

package/dist/modules/actions/tasks/helpers.js

@@ -1,4 +1,4 @@
-import { processTwig } from "@plitzi/sdk-shared/helpers/twigWrapper";
+import { processTwigParam } from "@plitzi/sdk-shared/helpers/twigWrapper";
 //#region src/modules/actions/tasks/helpers.ts
 /**
 * Renders a task's own params, with its own credential in scope.
@@ -22,7 +22,7 @@ var renderTaskParams = async (params, ctx, credentialId) => {
 		...credential ? { credential } : {}
 	};
 	return Object.entries(params).reduce((acum, [key, value]) => {
-		acum[key] = typeof value === "string" ? processTwig(value, scope, false, true) : value;
+		acum[key] = typeof value === "string" ? processTwigParam(value, scope) : value;
 		return acum;
 	}, {});
 };

package/dist/modules/actions/tasks/http.js

@@ -1,4 +1,4 @@
-import { assertOutboundAllowed } from "../../../helpers/outboundGuard.js";
+import { fetchOutbound } from "../../../helpers/outboundGuard.js";
 import { renderTaskParams } from "./helpers.js";
 //#region src/modules/actions/tasks/http.ts
 var BODYLESS = ["GET", "HEAD"];
@@ -81,7 +81,6 @@ var httpTasks = [{
 		} catch {
 			throw new Error("Request URL is not a valid absolute URL");
 		}
-		await assertOutboundAllowed(url);
 		const headers = Object.entries(parseJsonParam(params.headers, "Headers")).reduce((acum, [key, value]) => {
 			acum[key] = typeof value === "string" ? value : JSON.stringify(value);
 			return acum;
@@ -89,7 +88,7 @@ var httpTasks = [{
 		const hasBody = !BODYLESS.includes(method) && params.body !== "";
 		const declaresContentType = Object.keys(headers).some((name) => name.toLowerCase() === "content-type");
 		if (hasBody && !declaresContentType) headers["Content-Type"] = "application/json";
-		const response = await ctx.fetch(url.toString(), {
+		const response = await fetchOutbound(ctx.fetch, url, {
 			method,
 			headers,
 			body: hasBody ? JSON.stringify(parseJsonParam(params.body, "Body")) : void 0,

package/dist/modules/actions/tasks/kv.js

@@ -50,6 +50,45 @@ var kvTasks = [
 			};
 		}
 	},
+	{
+		namespace: "kv",
+		action: "setIf",
+		title: "Write Value If Unchanged",
+		params: {
+			key: {
+				type: "text",
+				canBind: true,
+				defaultValue: "",
+				label: "Key"
+			},
+			expected: {
+				type: "codemirror-text",
+				canBind: true,
+				defaultValue: "",
+				label: "Only if it holds (the value read; empty = only if it holds nothing)"
+			},
+			value: {
+				type: "codemirror-text",
+				canBind: true,
+				defaultValue: "",
+				label: "Value"
+			},
+			ttlSeconds: {
+				type: "text",
+				canBind: true,
+				defaultValue: "",
+				label: "TTL (seconds)"
+			}
+		},
+		run: async ({ key, expected, value, ttlSeconds }, ctx) => {
+			const ttl = ttlSeconds === "" ? void 0 : toNumber(ttlSeconds, 0) || void 0;
+			return {
+				key,
+				written: await ctx.kv.swap(key, expected === "" || expected === null ? void 0 : expected, value, ttl),
+				value: await ctx.kv.get(key) ?? null
+			};
+		}
+	},
 	{
 		namespace: "kv",
 		action: "increment",

package/dist/modules/actions/tasks/list.d.ts

@@ -0,0 +1,2 @@
+import { ActionTask } from '../types';
+export declare const listTasks: ActionTask<Record<string, unknown>>[];

package/dist/modules/actions/tasks/list.js

@@ -0,0 +1,145 @@
+import "../runtime/kvList.js";
+//#region src/modules/actions/tasks/list.ts
+var toNumber = (value, fallback) => {
+	if (value === void 0 || value === "") return fallback;
+	const parsed = typeof value === "number" ? value : Number(value);
+	return Number.isFinite(parsed) ? parsed : fallback;
+};
+/** What a typed value means: JSON when it reads as JSON, the text itself when it does not. A bound value as it is. */
+var valueOf = (value) => {
+	if (typeof value !== "string") return value ?? null;
+	if (value === "") return null;
+	try {
+		return JSON.parse(value);
+	} catch {
+		return value;
+	}
+};
+var nameParam = {
+	type: "text",
+	canBind: true,
+	defaultValue: "",
+	label: "List"
+};
+var listTasks = [
+	{
+		namespace: "list",
+		action: "put",
+		title: "Add To List",
+		params: {
+			list: nameParam,
+			id: {
+				type: "text",
+				canBind: true,
+				defaultValue: "",
+				label: "Entry id"
+			},
+			score: {
+				type: "text",
+				canBind: true,
+				defaultValue: "0",
+				label: "Score (highest first)"
+			},
+			value: {
+				type: "codemirror-json",
+				canBind: true,
+				defaultValue: "",
+				label: "Value"
+			},
+			keep: {
+				type: "text",
+				canBind: true,
+				defaultValue: "",
+				label: `Keep at most (≤ 500)`
+			},
+			higherOnly: {
+				type: "boolean",
+				canBind: true,
+				defaultValue: false,
+				label: "Only replace a lower score (a best score, the latest of two writes)"
+			}
+		},
+		run: async ({ list, id, score, value, keep, higherOnly }, ctx) => {
+			const sorted = toNumber(score, void 0);
+			if (sorted === void 0) throw new Error(`A score is a number, and "${String(score)}" is not one`);
+			const put = await ctx.kv.listPut(list, {
+				id,
+				score: sorted,
+				value: valueOf(value)
+			}, {
+				keep: toNumber(keep, void 0),
+				higherOnly: higherOnly === true || higherOnly === "true"
+			});
+			return {
+				list,
+				id,
+				stored: put.stored,
+				dropped: put.dropped.map((entry) => entry.id)
+			};
+		}
+	},
+	{
+		namespace: "list",
+		action: "range",
+		title: "Read List",
+		params: {
+			list: nameParam,
+			offset: {
+				type: "text",
+				canBind: true,
+				defaultValue: "0",
+				label: "Skip"
+			},
+			limit: {
+				type: "text",
+				canBind: true,
+				defaultValue: "20",
+				label: "How many"
+			},
+			order: {
+				type: "select",
+				canBind: true,
+				defaultValue: "desc",
+				label: "Order",
+				options: [{
+					label: "Highest score first",
+					value: "desc"
+				}, {
+					label: "Lowest score first",
+					value: "asc"
+				}]
+			}
+		},
+		run: async ({ list, offset, limit, order }, ctx) => {
+			return {
+				list,
+				entries: await ctx.kv.listRange(list, {
+					offset: toNumber(offset, 0),
+					limit: toNumber(limit, void 0),
+					order: order === "asc" ? "asc" : "desc"
+				})
+			};
+		}
+	},
+	{
+		namespace: "list",
+		action: "remove",
+		title: "Remove From List",
+		params: {
+			list: nameParam,
+			id: {
+				type: "text",
+				canBind: true,
+				defaultValue: "",
+				label: "Entry id"
+			}
+		},
+		run: async ({ list, id }, ctx) => ({
+			list,
+			id,
+			removed: await ctx.kv.listRemove(list, id)
+		})
+	}
+];
+//#endregion
+export { listTasks };

package/dist/modules/actions/tasks/realtime.d.ts

@@ -0,0 +1,2 @@
+import { ActionTask } from '../types';
+export declare const realtimeTasks: ActionTask<Record<string, unknown>>[];

package/dist/modules/actions/tasks/realtime.js

@@ -0,0 +1,104 @@
+import { DEFAULT_GRANT_SECONDS, MAX_GRANT_SECONDS } from "../../realtime/grants.js";
+//#region src/modules/actions/tasks/realtime.ts
+var parse = (value) => {
+	if (typeof value !== "string") return value;
+	try {
+		return JSON.parse(value);
+	} catch {
+		return value;
+	}
+};
+var realtimeTasks = [
+	{
+		namespace: "realtime",
+		action: "publish",
+		title: "Publish On Channel",
+		description: "Sends a message to every page subscribed to a topic of one of the space’s channels.",
+		params: {
+			topic: {
+				type: "text",
+				canBind: true,
+				defaultValue: "",
+				label: "Topic (board:{{ input.board }})"
+			},
+			type: {
+				type: "text",
+				canBind: true,
+				defaultValue: "",
+				label: "Type"
+			},
+			data: {
+				type: "codemirror-json",
+				canBind: true,
+				defaultValue: "{}",
+				label: "Data"
+			}
+		},
+		run: async ({ topic, type, data }, ctx) => {
+			if (!ctx.publish) throw new Error("This server has no realtime channels");
+			await ctx.publish(topic, type, parse(data));
+			return {
+				topic,
+				published: true
+			};
+		}
+	},
+	{
+		namespace: "realtime",
+		action: "grant",
+		title: "Grant Channel",
+		description: "Answers a grant that lets this visitor’s page open one topic of a private (`grant: true`) channel.",
+		params: {
+			topic: {
+				type: "text",
+				canBind: true,
+				defaultValue: "",
+				label: "Topic (room:{{ input.room }})"
+			},
+			ttlSeconds: {
+				type: "text",
+				canBind: true,
+				defaultValue: String(DEFAULT_GRANT_SECONDS),
+				label: `For how long (seconds, at most ${String(MAX_GRANT_SECONDS)})`
+			}
+		},
+		run: async ({ topic, ttlSeconds }, ctx) => {
+			if (!ctx.grant) throw new Error("This server has no realtime channels");
+			const seconds = ttlSeconds === "" ? void 0 : Number(ttlSeconds);
+			return {
+				topic,
+				grant: await ctx.grant(topic, Number.isFinite(seconds) ? seconds : void 0)
+			};
+		}
+	},
+	{
+		namespace: "realtime",
+		action: "revoke",
+		title: "Revoke Channel Grant",
+		description: "Takes back one grant to a private channel’s topic — or all of them — and lets go whoever is on it with one.",
+		params: {
+			topic: {
+				type: "text",
+				canBind: true,
+				defaultValue: "",
+				label: "Topic (room:{{ input.room }})"
+			},
+			grant: {
+				type: "text",
+				canBind: true,
+				defaultValue: "",
+				label: "Grant (empty = every grant for the topic)"
+			}
+		},
+		run: async ({ topic, grant }, ctx) => {
+			if (!ctx.revoke) throw new Error("This server has no realtime channels");
+			await ctx.revoke(topic, grant ? grant : void 0);
+			return {
+				topic,
+				revoked: grant ? "one" : "all"
+			};
+		}
+	}
+];
+//#endregion
+export { realtimeTasks };

package/dist/modules/actions/tasks/registry.d.ts

@@ -1,5 +1,14 @@
+import { FunctionsDefinition } from '../../functions/contract';
 import { ActionTask, ActionTaskRegistry } from '../types';
 export declare const taskName: (task: Pick<ActionTask, "namespace" | "action">) => string;
+/** The namespaces the platform's own tasks use: nobody else's task may take one. */
+export declare const RESERVED_NAMESPACES: ReadonlySet<string>;
+/**
+ * What is wrong with a task's name, or nothing — one rule for a deployment's tasks at boot and a space's own when its
+ * functions are built. A malformed name is unreachable from any document; one in a namespace taken by another task
+ * set silently changes what every action using that set does.
+ */
+export declare const taskNameProblem: (task: Pick<ActionTask, "namespace" | "action">, reserved?: ReadonlySet<string>) => string | undefined;
 /** The shipped tasks that are only real when the deployment supplied what they run through. */
 export type TaskRegistryOptions = {
     /** At least one database driver is registered, so `db.query` has an engine to run against. */
@@ -12,4 +21,4 @@ export type TaskRegistryOptions = {
  * name is unreachable from any document, and one shadowing a built-in silently changes what every existing action
  * in that deployment does. Both are invisible until a run misbehaves in production.
  */
-export declare const createTaskRegistry: (custom?: ActionTask<never>[], { db }?: TaskRegistryOptions) => ActionTaskRegistry;
+export declare const createTaskRegistry: (functions?: readonly FunctionsDefinition[], { db }?: TaskRegistryOptions) => ActionTaskRegistry;

package/dist/modules/actions/tasks/registry.js

@@ -1,9 +1,20 @@
 import { builtinTasks } from "./builtins.js";
 import { dbTasks } from "./db.js";
+import { nativeTasks } from "../../functions/native.js";
 //#region src/modules/actions/tasks/registry.ts
 var NAME_PATTERN = /^[a-z][a-zA-Z0-9]*$/;
 var taskName = (task) => `${task.namespace}.${task.action}`;
-var reservedNamespaces = new Set([...builtinTasks, ...dbTasks].map((task) => task.namespace));
+/** The namespaces the platform's own tasks use: nobody else's task may take one. */
+var RESERVED_NAMESPACES = new Set([...builtinTasks, ...dbTasks].map((task) => task.namespace));
+/**
+* What is wrong with a task's name, or nothing — one rule for a deployment's tasks at boot and a space's own when its
+* functions are built. A malformed name is unreachable from any document; one in a namespace taken by another task
+* set silently changes what every action using that set does.
+*/
+var taskNameProblem = (task, reserved = RESERVED_NAMESPACES) => {
+	if (!NAME_PATTERN.test(task.namespace) || !NAME_PATTERN.test(task.action)) return `Invalid task name "${taskName(task)}": expected camelCase namespace and action`;
+	if (reserved.has(task.namespace)) return `Namespace "${task.namespace}" is reserved by another task set`;
+};
 /**
 * Builds the set of tasks this server can run.
 *
@@ -11,15 +22,15 @@ var reservedNamespaces = new Set([...builtinTasks, ...dbTasks].map((task) => tas
 * name is unreachable from any document, and one shadowing a built-in silently changes what every existing action
 * in that deployment does. Both are invisible until a run misbehaves in production.
 */
-var createTaskRegistry = (custom = [], { db = false } = {}) => {
+var createTaskRegistry = (functions = [], { db = false } = {}) => {
 	const tasks = /* @__PURE__ */ new Map();
 	(db ? [...builtinTasks, ...dbTasks] : builtinTasks).forEach((task) => tasks.set(taskName(task), {
 		...task,
 		name: taskName(task)
 	}));
-	custom.forEach((task) => {
-		if (!NAME_PATTERN.test(task.namespace) || !NAME_PATTERN.test(task.action)) throw new Error(`[Actions] Invalid task name "${taskName(task)}": expected camelCase namespace and action`);
-		if (reservedNamespaces.has(task.namespace)) throw new Error(`[Actions] Namespace "${task.namespace}" is reserved by a built-in task set`);
+	nativeTasks(functions).forEach((task) => {
+		const problem = taskNameProblem(task);
+		if (problem) throw new Error(`[Actions] ${problem}`);
 		const name = taskName(task);
 		if (tasks.has(name)) throw new Error(`[Actions] Task "${name}" is registered twice`);
 		tasks.set(name, {
@@ -33,4 +44,4 @@ var createTaskRegistry = (custom = [], { db = false } = {}) => {
 	};
 };
 //#endregion
-export { createTaskRegistry, taskName };
+export { RESERVED_NAMESPACES, createTaskRegistry, taskName, taskNameProblem };

package/dist/modules/actions/transport/callHandler.js

@@ -1,3 +1,4 @@
+import { serverLog } from "../../../helpers/serverLog.js";
 import { triggerParams } from "../runtime/triggers.js";
 import { ActionRunError } from "../runtime/errors.js";
 import { precheckRun } from "../runtime/precheck.js";
@@ -215,6 +216,7 @@ var handleActionCall = async (deps) => {
 					runId: result.runId,
 					status: result.status,
 					output: result.output,
+					...result.error === void 0 ? {} : { error: result.error },
 					...outline ? { steps: result.steps } : {}
 				}
 			});
@@ -224,7 +226,8 @@ var handleActionCall = async (deps) => {
 		const payload = {
 			runId: result.runId,
 			status: result.status,
-			output: result.output
+			output: result.output,
+			...result.error === void 0 ? {} : { error: result.error }
 		};
 		if (outline) payload.steps = result.steps;
 		if (fullTrace) payload.trace = result.trace;
@@ -232,7 +235,7 @@ var handleActionCall = async (deps) => {
 	} catch (error) {
 		const reason = error instanceof ActionRunError ? error.reason : "failed";
 		const message = error instanceof ActionRunError ? error.message : "Action failed";
-		if (!(error instanceof ActionRunError)) console.error("[Actions] run failed:", error);
+		if (!(error instanceof ActionRunError)) serverLog.error("Actions", "run failed", error);
 		const steps = error instanceof ActionRunError && error.steps && await showsOutline() ? error.steps : void 0;
 		if (stream) {
 			stream.send({

package/dist/modules/actions/transport/catalogHandler.d.ts

@@ -1,8 +1,11 @@
 import { ActionsModule } from '../index';
-import { SSRResponseHelpers } from '@plitzi/sdk-shared';
+import { SpaceRevision, SSRResponseHelpers } from '@plitzi/sdk-shared';
 export type ActionCatalogDeps = {
     res: SSRResponseHelpers;
     module: ActionsModule;
+    /** The space asking, as of the revision it is serving: its own functions are part of what it can run. */
+    spaceId?: number;
+    at?: SpaceRevision;
 };
 /**
  * Serves the tasks this server can run.
@@ -15,4 +18,4 @@ export type ActionCatalogDeps = {
  * Session-gated by the pipeline: the catalog names a deployment's server-side capabilities, which is not something
  * to hand an anonymous visitor.
  */
-export declare const handleActionCatalog: ({ res, module }: ActionCatalogDeps) => void;
+export declare const handleActionCatalog: ({ res, module, spaceId, at }: ActionCatalogDeps) => Promise<void>;

package/dist/modules/actions/transport/catalogHandler.js

@@ -11,11 +11,12 @@ import { describeCatalog } from "../taskCatalog.js";
 * Session-gated by the pipeline: the catalog names a deployment's server-side capabilities, which is not something
 * to hand an anonymous visitor.
 */
-var handleActionCatalog = ({ res, module }) => {
+var handleActionCatalog = async ({ res, module, spaceId, at }) => {
+	const registry = spaceId === void 0 ? module.registry : await module.registryFor(spaceId, at);
 	res.setStatus(200);
 	res.setHeader("Content-Type", "application/json; charset=utf-8");
 	res.setHeader("Cache-Control", "no-store");
-	res.send(JSON.stringify({ tasks: describeCatalog(module.registry) }));
+	res.send(JSON.stringify({ tasks: describeCatalog(registry) }));
 };
 //#endregion
 export { handleActionCatalog };

package/dist/modules/actions/transport/stream.d.ts

@@ -10,12 +10,11 @@ export type ActionStream = {
     isOpen: () => boolean;
 };
 /**
- * Opens a Server-Sent Events response.
+ * Opens a run's Server-Sent Events response.
  *
- * Written straight to the RAW response, never through the response helpers: those compress the body, set a
- * Content-Length and end it in one go, which is precisely what a stream cannot do. `no-transform` says the same
- * thing to every proxy in between, and `X-Accel-Buffering: no` says it to nginx, which otherwise holds frames
- * until its buffer fills and turns a live stream into one late burst.
+ * The run's id travels on the response head rather than in a frame: a streaming step returns as soon as the stream
+ * OPENS — that is what makes it a stream — so anything it learns from a frame arrives after the flow has already
+ * carried on. The head is the one place a caller can read the id in time to cancel the run it just started.
  */
 export declare const openStream: (raw: RawResponse, onAbort: () => void, runId: string) => ActionStream;
 /** Whether this caller asked for a stream. The negotiation is the client's, so a page that cannot read one never