@plitzi/sdk-server 0.35.5 → 0.35.7

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @plitzi/sdk-server
 
+## 0.35.7
+
+### Patch Changes
+
+- An SMTP failure says which credential it was, and a credential's values can be replaced from the builder.
+
+  - **`email.send` names the credential it could not send through:** `Could not send through the SMTP credential
+"ceniza-smtp": its SMTP host is on a private network…`. The host used to be in the sentence, and a run's trace
+    redacts every value of a credential it resolved, so the message read `The SMTP host "«redacted»"…`.
+  - **Credentials can be edited in the builder.** A pencil on each row opens the form with the name and the provider
+    fixed and nothing it holds shown: every value is entered again, and saving replaces all of them. SMTP credentials
+    are also labelled in the list.
+
+- Updated dependencies
+  - @plitzi/plitzi-sdk@0.35.7
+  - @plitzi/sdk-shared@0.35.7
+
+## 0.35.6
+
+### Patch Changes
+
+- A failed server action can give back what it already did.
+
+  - **`flow.onFailure` ("On Failure") marks where the undo begins.** A run that reaches it has succeeded and ends there.
+    A run whose step failed jumps to it and runs the steps after it, in order, each still asking its own `when` — the
+    failure may have come before the thing to undo was ever done — with `{{ failure.step }}` and `{{ failure.message }}`
+    in scope. The run still ends failed, with the failure it had; an undo step that fails too is added to it.
+  - **The undo runs on its own clock and budget:** 5 seconds (or the run's own timeout if shorter) and its own outbound
+    request budget, because the run's may be exactly what ran out, and a caller closing the connection does not stop it.
+    A run that hit its deadline is undone too.
+  - **`defineAction` writes it from `onFailure: [...]`**, after the answer. `validateActionDocument` refuses an output
+    step or a second handler after one, warns about a handler with nothing to undo or nothing that undoes, and reserves
+    `failure` as a step id. `FAILURE_HANDLER_TASK` is exported from `@plitzi/sdk-shared/actions`.
+
+- Updated dependencies
+  - @plitzi/plitzi-sdk@0.35.6
+  - @plitzi/sdk-shared@0.35.6
+
 ## 0.35.5
 
 ### Patch Changes

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

@@ -1,6 +1,6 @@
 import { triggerParams } from "./triggers.js";
-import { hasValidToken } from "@plitzi/sdk-shared/helpers/twigWrapper";
 import { parseCron, readSmtpCredential, triggerHasStaleVerify, triggerVerify } from "@plitzi/sdk-shared/actions";
+import { hasValidToken } from "@plitzi/sdk-shared/helpers/twigWrapper";
 //#region src/modules/actions/runtime/check.ts
 /** A value the check can reason about: a literal the author typed, not a template resolved at run time. */
 var literal = (value) => {

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

@@ -63,11 +63,11 @@ var createEmailSender = ({ kv, dailyLimitPerSpace = 200, allowPrivateHosts = fal
 		try {
 			addresses = await lookup(smtp.host);
 		} catch {
-			throw new Error(`The SMTP host "${smtp.host}" does not resolve`);
+			throw new Error("its SMTP host does not resolve");
 		}
 		const [first] = addresses;
-		if (addresses.length === 0) throw new Error(`The SMTP host "${smtp.host}" does not resolve`);
-		if (!allowPrivateHosts && (isBlockedHost(smtp.host) || addresses.some(({ address }) => isBlockedHost(address)))) throw new Error(`The SMTP host "${smtp.host}" is on a private network, which this server does not connect to`);
+		if (addresses.length === 0) throw new Error("its SMTP host does not resolve");
+		if (!allowPrivateHosts && (isBlockedHost(smtp.host) || addresses.some(({ address }) => isBlockedHost(address)))) throw new Error("its SMTP host is on a private network, which this server does not connect to");
 		return (delivery) => deliver({
 			address: first.address,
 			smtp: delivery.smtp,

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

@@ -8,6 +8,7 @@ import { createEmailSender } from "./email.js";
 import { createRedactor, projectUser } from "./scope.js";
 import { precheckRun } from "./precheck.js";
 import onAbort from "../../../helpers/onAbort.js";
+import { FAILURE_HANDLER_TASK } from "@plitzi/sdk-shared/actions";
 import { evaluateRuleGroup } from "@plitzi/sdk-shared/helpers/ruleEvaluator";
 import { hasValidToken, processTwig } from "@plitzi/sdk-shared/helpers/twigWrapper";
 //#region src/modules/actions/runtime/runAction.ts
@@ -16,6 +17,14 @@ var MAX_TWIG_RESOLUTION_PASSES = 5;
 *  boundaries a flow actually has, and it keeps a long run to sixty reads a minute. */
 var CANCEL_POLL_MS = 1e3;
 /**
+* The most a failed run's undo may take, on a clock of its own.
+*
+* Its own because the run's clock may be exactly what ran out: a run that hit its deadline has seats to give back
+* too. Short because the caller is still waiting for the failure, and giving back what a flow took is a handful of
+* writes, not another run. Never longer than the run itself was allowed.
+*/
+var UNDO_TIMEOUT_MS = 5e3;
+/**
 * The run's deadline, as a promise that loses patience.
 *
 * Aborting the controller is the polite half: a task that watches its signal stops, and the loop refuses to start
@@ -167,6 +176,21 @@ var errorNode = (action) => ({
 	flowId: "",
 	enabled: true
 });
+/**
+* Where a chain's undo begins, if it has one: the first `flow.onFailure` its steps reach.
+*
+* Per trigger, because each way in walks its own chain. Walked with a visited set: the validator refuses a chain that
+* comes back on itself, but a stored document is still customer input, and a lookup must not be what spins.
+*/
+var failureHandlerOf = (nodes, trigger) => {
+	const visited = /* @__PURE__ */ new Set();
+	let next = nodes[trigger.afterNode];
+	while (next && !visited.has(next.id)) {
+		if (next.action === FAILURE_HANDLER_TASK) return next;
+		visited.add(next.id);
+		next = nodes[next.afterNode];
+	}
+};
 var withDefaults = (task, params) => Object.entries(task.params).reduce((acum, [key, param]) => {
 	if (acum[key] === void 0 || acum[key] === "") acum[key] = param.defaultValue ?? "";
 	return acum;
@@ -229,15 +253,21 @@ var createActionRunner = (config, registry, baseFetch = fetch) => {
 		const deadline = createDeadline(request.emit ? limits.streamTimeoutMs : limits.timeoutMs, controller);
 		const releaseOuter = onAbort(request.signal, () => controller.abort());
 		const scopedKv = namespaceKv(kv, request.spaceId);
-		const runFetch = createRunFetch(baseFetch, controller.signal, limits, [...request.lineage ?? [], entry.id]);
-		const buildContext = (scope) => ({
+		const lineage = [...request.lineage ?? [], entry.id];
+		/**
+		* What a step runs with, for one abort signal and one outbound budget.
+		*
+		* Two of them per run at most: the flow's, and — only when it failed — the undo's, which must still be able to
+		* reach the outside world after the flow's signal was aborted or its request budget spent.
+		*/
+		const contextFor = (signal, runFetch) => (scope) => ({
 			runId,
 			spaceId: request.spaceId,
 			environment: request.environment,
 			trigger: request.trigger,
 			user: request.user,
 			callerId: request.callerId,
-			signal: controller.signal,
+			signal,
 			scope,
 			/**
 			* The secret a STEP asked for, resolved inside that step and never in the flow scope.
@@ -268,6 +298,7 @@ var createActionRunner = (config, registry, baseFetch = fetch) => {
 			email: emailSender,
 			emit: (chunk) => request.emit?.(redact(chunk))
 		});
+		const buildContext = contextFor(controller.signal, createRunFetch(baseFetch, controller.signal, limits, lineage));
 		const trace = [];
 		const startedAt = Date.now();
 		let failure;
@@ -304,11 +335,15 @@ var createActionRunner = (config, registry, baseFetch = fetch) => {
 		* hits its deadline answers, releases its slot and closes its connection while whatever step ignored the abort
 		* carries on in the background — which is the difference between a stuck STEP and a stuck server.
 		*/
+		const failureHandler = failureHandlerOf(document.nodes, triggerNode);
+		/** The step the flow was running when it stopped — what `{{ failure.step }}` names to the undo. */
+		let stepInFlight = "";
 		const runFlow = async () => {
 			let current = triggerNode;
 			let executed = 0;
 			let next = document.nodes[current.afterNode];
 			while (next) {
+				if (next.action === FAILURE_HANDLER_TASK) break;
 				if (controller.signal.aborted) {
 					status = "aborted";
 					break;
@@ -321,6 +356,7 @@ var createActionRunner = (config, registry, baseFetch = fetch) => {
 				executed += 1;
 				if (executed > limits.maxNodes) throw new ActionRunError("over_capacity", `Action exceeded its ${limits.maxNodes} step budget`);
 				const startTime = Date.now();
+				stepInFlight = next.id;
 				const outcome = await runNode(next, scope, registry, buildContext);
 				trace.push({
 					node: next,
@@ -337,6 +373,68 @@ var createActionRunner = (config, registry, baseFetch = fetch) => {
 				next = document.nodes[current.afterNode];
 			}
 		};
+		/**
+		* Gives back what a run that did not finish already did: the steps after `flow.onFailure`.
+		*
+		* On a clock and an outbound budget of its own, because the run's may be exactly what ran out, and deliberately
+		* NOT tied to the caller's connection — somebody closing the tab is the last reason to leave seats taken. Each step
+		* still asks its own `when`: the failure may have come before the thing to undo was ever done. Nothing it does
+		* changes the run's status or its answer; an undo that fails too is added to the failure, never put in its place.
+		*/
+		const undo = async (handler) => {
+			const undoController = new AbortController();
+			const undoDeadline = createDeadline(Math.min(limits.timeoutMs, UNDO_TIMEOUT_MS), undoController);
+			const buildUndoContext = contextFor(undoController.signal, createRunFetch(baseFetch, undoController.signal, limits, lineage));
+			scope.failure = {
+				step: stepInFlight,
+				message: failure ?? "",
+				status
+			};
+			trace.push({
+				node: handler,
+				status: "success",
+				result: redact(scope.failure),
+				postCallbacks: [],
+				startTime: Date.now(),
+				endTime: Date.now()
+			});
+			const runUndo = async () => {
+				let executed = 0;
+				let next = document.nodes[handler.afterNode];
+				while (next) {
+					executed += 1;
+					if (executed > limits.maxNodes) throw new ActionRunError("over_capacity", `Undoing the action exceeded its ${limits.maxNodes} step budget`);
+					const startTime = Date.now();
+					const outcome = await runNode(next, scope, registry, buildUndoContext);
+					trace.push({
+						node: next,
+						status: outcome.status,
+						result: redact(outcome.result),
+						postCallbacks: [],
+						startTime,
+						endTime: Date.now()
+					});
+					scope[next.id] = outcome.result;
+					next = document.nodes[next.afterNode];
+				}
+			};
+			try {
+				await Promise.race([runUndo(), undoDeadline.promise]);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				trace.push({
+					node: errorNode("undo"),
+					status: "failed",
+					result: redact({ error: message }),
+					postCallbacks: [],
+					startTime: Date.now(),
+					endTime: Date.now()
+				});
+				failure = `${failure ?? "Action failed"} — and undoing it failed too: ${message}`;
+			} finally {
+				undoDeadline.clear();
+			}
+		};
 		/** Set when the run ends in a way the CALLER has to hear as a status code rather than as a result. */
 		let fatal;
 		try {
@@ -380,6 +478,7 @@ var createActionRunner = (config, registry, baseFetch = fetch) => {
 			deadline.clear();
 			releaseOuter();
 		}
+		if (status !== "completed" && failureHandler?.enabled) await undo(failureHandler);
 		const output = returned ?? {};
 		await record({
 			runId,

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

@@ -54,12 +54,17 @@ var emailTasks = [{
 		if (!stored) throw new Error(`This space has no SMTP credential called "${identifier}" — add it in Credentials`);
 		const reading = readSmtpCredential(stored);
 		if (!("settings" in reading)) throw new Error(`Credential "${identifier}" is not a usable SMTP server: ${reading.problems.map((problem) => `${problem.key} — ${problem.message}`).join("; ")}`);
-		await ctx.email.send(ctx.spaceId, reading.settings, {
-			to: recipient,
-			subject: title,
-			text,
-			...answerTo === "" ? {} : { replyTo: answerTo }
-		}, ctx.signal);
+		try {
+			await ctx.email.send(ctx.spaceId, reading.settings, {
+				to: recipient,
+				subject: title,
+				text,
+				...answerTo === "" ? {} : { replyTo: answerTo }
+			}, ctx.signal);
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			throw new Error(`Could not send through the SMTP credential "${identifier}": ${reason}`, { cause: error });
+		}
 		return { sent: true };
 	}
 }];

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

@@ -46,6 +46,24 @@ var fail = {
 	}
 };
 /**
+* Where a flow's undo begins — read by the runner, never run as a step.
+*
+* A run that reaches it has succeeded and ends there. A run whose step failed before it jumps here instead and runs
+* the steps after it, each still asking its own `when` — the failure may have come before the thing to undo was ever
+* done — and still ends as failed, with the failure it had. What failed is in their scope as `{{ failure.step }}` and
+* `{{ failure.message }}`.
+*/
+var onFailure = {
+	namespace: "flow",
+	action: "onFailure",
+	title: "On Failure",
+	description: "The steps after this one run only when a step before it fails, to undo what the flow already did",
+	params: {},
+	run: () => {
+		throw new Error("On Failure marks where a failed run’s undo begins; the runner never runs it as a step");
+	}
+};
+/**
 * Declares what the caller gets back — and IS the declaration.
 *
 * The flow scope is not the answer: it holds every node's raw result, including whatever a fetch happened to
@@ -102,7 +120,8 @@ var emit = {
 var flowTasks = [
 	delay,
 	fail,
-	output
+	output,
+	onFailure
 ];
 var streamTasks = [emit];
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-server",
-  "version": "0.35.5",
+  "version": "0.35.7",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -58,8 +58,8 @@
   "type": "module",
   "sideEffects": false,
   "dependencies": {
-    "@plitzi/plitzi-sdk": "0.35.5",
-    "@plitzi/sdk-shared": "0.35.5",
+    "@plitzi/plitzi-sdk": "0.35.7",
+    "@plitzi/sdk-shared": "0.35.7",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.2",
     "jsonwebtoken": "^9.0.3",