@plitzi/sdk-server 0.37.1 → 0.37.3

package/dist/modules/actions/runtime/taskContext.d.ts

@@ -0,0 +1,33 @@
+import { createEmailSender } from './email';
+import { createRedactor } from './scope';
+import { createSigning } from './signing';
+import { ActionKvStore, ActionRunRequest, ActionsConfig, ActionTaskContext, ResolvedActionLimits } from '../types';
+/**
+ * Counts outbound calls, refuses past the budget, caps what one answer may carry back, and stamps the run's
+ * lineage on every one of them.
+ *
+ * The budget stops a loop from turning one run into a hundred requests. The lineage header is what makes the
+ * OTHER loop detectable: an action whose HTTP step reaches its own space's webhook arrives carrying the chain
+ * that led there, and the run it would start refuses itself. It names the space's own actions to a backend that
+ * space configured, which is the cost of catching a cycle nothing else can see.
+ *
+ * Every ceiling lives HERE rather than in each task, because this is the only door a task has to the outside
+ * world — a task that had to remember to count its own bytes is a task that will forget.
+ */
+export declare const createRunFetch: (base: typeof fetch, signal: AbortSignal, limits: ResolvedActionLimits, lineage: string[]) => typeof fetch;
+/** What a task's context is made of that outlives one run: the server's stores and the run's redactor. */
+export type TaskContextDeps = {
+    kv: ActionKvStore;
+    email: ReturnType<typeof createEmailSender>;
+    redactor: ReturnType<typeof createRedactor>;
+    /** Absent when the deployment gave no `signingSecret`: its spaces then sign nothing. */
+    signing?: ReturnType<typeof createSigning>;
+};
+/** Who and what the context is for — a run's request, or anything shaped like one (a function's route). */
+export type TaskContextRequest = Pick<ActionRunRequest, 'runId' | 'spaceId' | 'environment' | 'trigger' | 'user' | 'callerId' | 'at' | 'emit'>;
+/**
+ * What a task runs with — the one place it is made, for a step of a run and for a function answering a route alike:
+ * every secret it resolves registered with the redactor, the space's `kv` namespace, the run's outbound budget, the
+ * space's channels. Everything but `log`, which is the STEP's: each step keeps what it logged.
+ */
+export declare const taskContextFor: (config: ActionsConfig, { kv, email, redactor, signing }: TaskContextDeps, request: TaskContextRequest, signal: AbortSignal, runFetch: typeof fetch) => (scope: Record<string, unknown>) => Omit<ActionTaskContext, "log">;

package/dist/modules/actions/runtime/taskContext.js

@@ -0,0 +1,124 @@
+import { ActionRunError } from "./errors.js";
+import { namespaceKv } from "./namespaceKv.js";
+//#region src/modules/actions/runtime/taskContext.ts
+/**
+* Holds an answer to what the run is allowed to carry.
+*
+* Two checks rather than one, because a body arrives in two ways. `Content-Length` is refused before a byte is
+* read, which is the cheap half; a chunked answer that declares nothing is counted AS it streams and errored the
+* moment it goes over — so the ceiling holds for a backend that lies about its size or never states one.
+*
+* The cap is on one response and not on the run: it exists so that a single answer cannot be unbounded, which is
+* a different failure from a flow that makes many small calls (that is `maxRequests`).
+*/
+var capped = (response, maxBytes) => {
+	const declared = Number(response.headers.get("content-length") ?? "");
+	if (Number.isFinite(declared) && declared > maxBytes) throw new ActionRunError("over_capacity", `Response is larger than the ${maxBytes} byte budget`);
+	if (!response.body) return response;
+	let seen = 0;
+	const counted = response.body.pipeThrough(new TransformStream({ transform: (chunk, controller) => {
+		seen += chunk.byteLength;
+		if (seen > maxBytes) {
+			controller.error(new ActionRunError("over_capacity", `Response exceeded the ${maxBytes} byte budget`));
+			return;
+		}
+		controller.enqueue(chunk);
+	} }));
+	return new Response(counted, {
+		status: response.status,
+		statusText: response.statusText,
+		headers: response.headers
+	});
+};
+/**
+* Counts outbound calls, refuses past the budget, caps what one answer may carry back, and stamps the run's
+* lineage on every one of them.
+*
+* The budget stops a loop from turning one run into a hundred requests. The lineage header is what makes the
+* OTHER loop detectable: an action whose HTTP step reaches its own space's webhook arrives carrying the chain
+* that led there, and the run it would start refuses itself. It names the space's own actions to a backend that
+* space configured, which is the cost of catching a cycle nothing else can see.
+*
+* Every ceiling lives HERE rather than in each task, because this is the only door a task has to the outside
+* world — a task that had to remember to count its own bytes is a task that will forget.
+*/
+var createRunFetch = (base, signal, limits, lineage) => {
+	let issued = 0;
+	return async (input, init) => {
+		issued += 1;
+		if (issued > limits.maxRequests) throw new ActionRunError("over_capacity", `Action exceeded its ${limits.maxRequests} outbound request budget`);
+		const headers = new Headers(init?.headers);
+		headers.set("X-Plitzi-Action-Lineage", lineage.join(","));
+		return capped(await base(input, {
+			...init,
+			headers,
+			signal: init?.signal ?? signal
+		}), limits.maxResponseBytes);
+	};
+};
+/**
+* What a task runs with — the one place it is made, for a step of a run and for a function answering a route alike:
+* every secret it resolves registered with the redactor, the space's `kv` namespace, the run's outbound budget, the
+* space's channels. Everything but `log`, which is the STEP's: each step keeps what it logged.
+*/
+var taskContextFor = (config, { kv, email, redactor, signing }, request, signal, runFetch) => (scope) => {
+	const { realtime } = config;
+	return {
+		runId: request.runId,
+		spaceId: request.spaceId,
+		environment: request.environment,
+		trigger: request.trigger,
+		user: request.user,
+		callerId: request.callerId,
+		signal,
+		scope,
+		/**
+		* The secret a STEP asked for, resolved inside that step and never in the flow scope.
+		*
+		* There is no allow-list to check it against, deliberately: an action is authored by someone who may edit
+		* every action in the space, so a list they can edit is not a boundary — it only ever told the redactor what
+		* to look for, and the redactor now learns from what was actually resolved. What IS a boundary is that a
+		* credential reaches only the params of the step that named it, which is `renderTaskParams`' whole job.
+		*/
+		credential: async (identifier) => {
+			const credential = await config.lookups.getCredential?.(request.spaceId, identifier);
+			if (credential) redactor.add(credential);
+			return credential;
+		},
+		connector: async (connectorId) => {
+			const manifest = await config.lookups.getConnector?.(request.spaceId, connectorId, request.at);
+			if (!manifest) return;
+			const credential = manifest.credential ? await config.lookups.getCredential?.(request.spaceId, manifest.credential) : void 0;
+			if (credential) redactor.add(credential);
+			return {
+				manifest,
+				credential
+			};
+		},
+		fetch: runFetch,
+		kv: namespaceKv(kv, request.spaceId),
+		dbDrivers: config.dbDrivers ?? [],
+		email,
+		emit: (chunk) => request.emit?.(redactor.redact(chunk)),
+		...signing?.({
+			spaceId: request.spaceId,
+			environment: request.environment
+		}),
+		...realtime ? {
+			publish: (topic, type, data) => realtime.publish({
+				spaceId: request.spaceId,
+				environment: request.environment
+			}, topic, type, data),
+			grant: (topic, ttlSeconds) => realtime.grant({
+				spaceId: request.spaceId,
+				environment: request.environment
+			}, topic, ttlSeconds),
+			revoke: (topic, grant) => realtime.revoke({
+				spaceId: request.spaceId,
+				environment: request.environment
+			}, topic, grant)
+		} : {}
+	};
+};
+//#endregion
+export { createRunFetch, taskContextFor };

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

@@ -4,6 +4,8 @@ import { emailTasks } from "./email.js";
 import { flowTasks, streamTasks } from "./flow.js";
 import { httpTasks } from "./http.js";
 import { kvTasks } from "./kv.js";
+import { listTasks } from "./list.js";
+import { realtimeTasks } from "./realtime.js";
 import { transformTasks } from "./transform.js";
 //#region src/modules/actions/tasks/builtins.ts
 /**
@@ -21,8 +23,10 @@ var builtinTasks = [
 	...connectorTasks,
 	...authTasks,
 	...kvTasks,
+	...listTasks,
 	...emailTasks,
-	...streamTasks
+	...streamTasks,
+	...realtimeTasks
 ];
 //#endregion
 export { builtinTasks };

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;