@plitzi/sdk-server 0.37.2 → 0.37.4

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

@@ -0,0 +1,51 @@
+/** One entry of a list: what it is called, where it sorts, and what it carries. */
+export type KvListEntry = {
+    id: string;
+    score: number;
+    value: unknown;
+};
+export type KvListRange = {
+    /** How many entries to skip first. 0 when absent. */
+    offset?: number;
+    /** How many to answer. All of them when absent. */
+    limit?: number;
+    /** `desc` — the highest score first — when absent. */
+    order?: 'asc' | 'desc';
+};
+/**
+ * The most a list holds. A list is one value of the store, read and written whole, so it is for what a page shows at
+ * once — the latest twenty, a leaderboard, a gallery — not for a table.
+ */
+export declare const MAX_LIST_ENTRIES = 500;
+/**
+ * Its largest size, as JSON. Every store holds far more; this is what a list is read and written whole for — a page's
+ * worth of entries, each an id and what the page shows — and past it, a list is being used as a table.
+ */
+export declare const MAX_LIST_BYTES = 128000;
+export declare const listIdProblem: (id: unknown) => string | undefined;
+/** The entries a stored list holds — none for a key that holds nothing, or something that is not a list. */
+export declare const parseList: (raw: string | undefined) => KvListEntry[];
+export type KvListPutOptions = {
+    /** How many to keep, the highest scores; what falls past it is dropped. {@link MAX_LIST_ENTRIES} at most. */
+    keep?: number;
+    /**
+     * Replace an entry already there only with a score at least as high — a player's best, or the latest of two writes
+     * that arrived out of order. Otherwise the one there stays and nothing is written.
+     */
+    higherOnly?: boolean;
+};
+/** What a put did: whether the entry went in, and what `keep` dropped to make room. */
+export type KvListPut = {
+    stored: boolean;
+    dropped: KvListEntry[];
+};
+/**
+ * The list with `entry` in it — replacing the one with its id — sorted and cut to the highest `keep`, and what the cut
+ * dropped; `undefined` when `higherOnly` keeps the one there. Refused, with what to do instead, when the result would
+ * be larger than a list may be.
+ */
+export declare const withEntry: (entries: KvListEntry[], entry: KvListEntry, { keep, higherOnly }?: KvListPutOptions) => {
+    kept: KvListEntry[];
+    dropped: KvListEntry[];
+} | undefined;
+export declare const rangeOf: (entries: KvListEntry[], { offset, limit, order }?: KvListRange) => KvListEntry[];

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

@@ -0,0 +1,52 @@
+//#region src/modules/actions/runtime/kvList.ts
+/**
+* The most a list holds. A list is one value of the store, read and written whole, so it is for what a page shows at
+* once — the latest twenty, a leaderboard, a gallery — not for a table.
+*/
+var MAX_LIST_ENTRIES = 500;
+/**
+* Its largest size, as JSON. Every store holds far more; this is what a list is read and written whole for — a page's
+* worth of entries, each an id and what the page shows — and past it, a list is being used as a table.
+*/
+var MAX_LIST_BYTES = 128e3;
+var ID = /^[A-Za-z0-9:_.@-]{1,128}$/;
+var listIdProblem = (id) => typeof id === "string" && ID.test(id) ? void 0 : "A list entry’s id is 1-128 of A-Z a-z 0-9 : _ . @ -";
+var isRecord = (value) => typeof value === "object" && value !== null;
+var isEntry = (value) => isRecord(value) && typeof value.id === "string" && typeof value.score === "number";
+/** The entries a stored list holds — none for a key that holds nothing, or something that is not a list. */
+var parseList = (raw) => {
+	if (raw === void 0) return [];
+	try {
+		const value = JSON.parse(raw);
+		return Array.isArray(value) ? value.filter(isEntry) : [];
+	} catch {
+		return [];
+	}
+};
+/** Highest score first; entries that tie keep a stable order, by id. */
+var byScore = (a, b) => b.score - a.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+/**
+* The list with `entry` in it — replacing the one with its id — sorted and cut to the highest `keep`, and what the cut
+* dropped; `undefined` when `higherOnly` keeps the one there. Refused, with what to do instead, when the result would
+* be larger than a list may be.
+*/
+var withEntry = (entries, entry, { keep = 500, higherOnly = false } = {}) => {
+	const there = entries.find((existing) => existing.id === entry.id);
+	if (higherOnly && there && there.score > entry.score) return;
+	const sorted = [...entries.filter((existing) => existing.id !== entry.id), entry].sort(byScore);
+	const cut = Math.min(Math.max(0, Math.floor(keep)), 500);
+	const kept = sorted.slice(0, cut);
+	const bytes = Buffer.byteLength(JSON.stringify(kept));
+	if (bytes > 128e3) throw new Error(`A list is at most ${MAX_LIST_BYTES} bytes and this one would be ${bytes}: keep fewer entries (\`keep\`), or store less in each one — an id and what a page shows, with the rest under its own key`);
+	return {
+		kept,
+		dropped: sorted.slice(cut)
+	};
+};
+var rangeOf = (entries, { offset = 0, limit, order = "desc" } = {}) => {
+	const ordered = order === "asc" ? entries.toReversed() : entries;
+	const start = Math.max(0, Math.floor(offset));
+	return ordered.slice(start, limit === void 0 ? void 0 : start + Math.max(0, Math.floor(limit)));
+};
+//#endregion
+export { MAX_LIST_BYTES, MAX_LIST_ENTRIES, listIdProblem, parseList, rangeOf, withEntry };

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

@@ -23,5 +23,13 @@ export type KvStoreConfig = {
  *    table.
  * 3. **Nothing is caught.** This is not a cache: a miss means the rate limit did not count and the idempotency key
  *    was not seen, so an adapter that cannot answer fails the run rather than being read as "no value".
+ *
+ * A list is one value, changed only by `swap`: read, change, write back if nobody wrote in between, and read again if
+ * somebody did. Every adapter can do that much, so lists work on all of them without a command of their own. They
+ * live under `list:` rather than beside the values, so no key a flow writes can be one.
  */
+/** What every key is prefixed with unless the store was given another. */
+export declare const DEFAULT_KV_PREFIX = "kv:";
+/** Where a list lives, after the prefix: its own segment, so a list and a value of the same name never meet. */
+export declare const LIST_SEGMENT = "list:";
 export declare const createKvStore: (adapter: ActionKvAdapter, { prefix }?: KvStoreConfig) => ActionKvStore;

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

@@ -1,23 +1,20 @@
-//#region src/modules/actions/runtime/kvStore.ts
-/**
-* The `kv` tasks, over whatever a deployment gave them to write into.
-*
-* The adapter is transport: strings in, strings out. Everything a counter's BEHAVIOUR depends on is here, in one
-* place, for every deployment at once — which is the point of the split. Three rules:
-*
-* 1. **Values round-trip through JSON**, so a flow reads back what it wrote instead of its own `toString`. A value
-*    written by something else is answered as the string it is rather than failing.
-* 2. **A counter's TTL is set once, by whoever created it, and never extended.** A window refreshed on every hit
-*    never closes while traffic keeps arriving — which is a rate limit that stops limiting exactly when it is
-*    being leant on. The counter is the one that created it precisely when the increment returns its own amount,
-*    so this needs no conditional-expire support from the adapter and works the same on Redis, Memcached or a
-*    table.
-* 3. **Nothing is caught.** This is not a cache: a miss means the rate limit did not count and the idempotency key
-*    was not seen, so an adapter that cannot answer fails the run rather than being read as "no value".
-*/
+import { ActionRefusal } from "./errors.js";
+import { changeKv } from "./kvChange.js";
+import { listIdProblem, parseList, rangeOf, withEntry } from "./kvList.js";
+/** Where a list lives, after the prefix: its own segment, so a list and a value of the same name never meet. */
+var LIST_SEGMENT = "list:";
+var refusal = (message) => new ActionRefusal(message);
 var createKvStore = (adapter, { prefix = "kv:" } = {}) => {
 	const prefixed = (key) => `${prefix}${key}`;
-	return {
+	const listKey = (list) => `${prefix}${LIST_SEGMENT}${list}`;
+	/** Applies `change` to the list and writes it back unless somebody wrote first — then reads again. */
+	const changeList = async (list, change) => {
+		return await changeKv(adapter, listKey(list), (raw) => {
+			const next = change(parseList(raw));
+			return next ? JSON.stringify(next) : void 0;
+		}, { refusal }) !== void 0;
+	};
+	const store = {
 		get: async (key) => {
 			const raw = await adapter.get(prefixed(key));
 			if (raw === void 0) return;
@@ -34,8 +31,37 @@ var createKvStore = (adapter, { prefix = "kv:" } = {}) => {
 			const value = await adapter.increment(full, amount);
 			if (ttlSeconds !== void 0 && value === amount) await adapter.expire(full, ttlSeconds);
 			return value;
-		}
+		},
+		swap: (key, expected, next, ttlSeconds) => adapter.swap(prefixed(key), expected === void 0 ? void 0 : JSON.stringify(expected), JSON.stringify(next), ttlSeconds),
+		listPut: async (list, entry, options = {}) => {
+			const problem = listIdProblem(entry.id);
+			if (problem) throw new Error(problem);
+			if (!Number.isFinite(entry.score)) throw new Error("A list entry’s score is a number");
+			let put = {
+				stored: false,
+				dropped: []
+			};
+			await changeList(list, (entries) => {
+				const next = withEntry(entries, entry, options);
+				put = next ? {
+					stored: true,
+					dropped: next.dropped
+				} : {
+					stored: false,
+					dropped: []
+				};
+				return next?.kept;
+			});
+			return put;
+		},
+		listRange: async (list, range) => rangeOf(parseList(await adapter.get(listKey(list))), range),
+		listRemove: (list, id) => changeList(list, (entries) => entries.some((entry) => entry.id === id) ? entries.filter((entry) => entry.id !== id) : void 0),
+		change: (key, change, lifetime) => changeKv(store, key, change, {
+			lifetime,
+			refusal
+		})
 	};
+	return store;
 };
 //#endregion
-export { createKvStore };
+export { LIST_SEGMENT, createKvStore };

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

@@ -1,2 +1,5 @@
+import { StoreMethods } from '../../../core/server/fleet/channel';
 import { ActionKvAdapter } from '../types';
+/** Every method of the store, for the copy a server's workers share (see `fleet/stores.ts`). */
+export declare const KV_METHODS: StoreMethods<ActionKvAdapter>;
 export declare const createMemoryKv: () => ActionKvAdapter;

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

@@ -11,6 +11,15 @@
 */
 /** How many writes go by before the map is swept. Cheap enough to be unnoticeable, often enough to bound it. */
 var SWEEP_EVERY = 256;
+/** Every method of the store, for the copy a server's workers share (see `fleet/stores.ts`). */
+var KV_METHODS = {
+	get: true,
+	set: true,
+	delete: true,
+	increment: true,
+	expire: true,
+	swap: true
+};
 var createMemoryKv = () => {
 	const entries = /* @__PURE__ */ new Map();
 	let writes = 0;
@@ -70,8 +79,17 @@ var createMemoryKv = () => {
 				expiresAt: expiry(ttlSeconds)
 			});
 			return Promise.resolve();
+		},
+		swap: (key, expected, next, ttlSeconds) => {
+			if (read(key)?.value !== expected) return Promise.resolve(false);
+			entries.set(key, {
+				value: next,
+				expiresAt: expiry(ttlSeconds)
+			});
+			sweep();
+			return Promise.resolve(true);
 		}
 	};
 };
 //#endregion
-export { createMemoryKv };
+export { KV_METHODS, createMemoryKv };

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

@@ -1,9 +1,7 @@
 import { ActionKvStore } from '../types';
+export declare const namespaceKv: (store: ActionKvStore, spaceId: number) => ActionKvStore;
 /**
- * Prefixes every key with the space that wrote it.
- *
- * A shared store with unprefixed keys is one space reading — or overwriting — another's counters, which is the
- * cross-tenant leak this whole design exists to avoid. Done at the runner rather than in each task so a
- * deployment's own tasks inherit it too.
+ * Every key a space's store holds, as patterns over the adapter's keys (`createKvStore`'s `prefix`, `kv:` unless it was
+ * given another) — for whoever has to let all of them go at once: a space that is deleted, or reset to how it started.
  */
-export declare const namespaceKv: (store: ActionKvStore, spaceId: number) => ActionKvStore;
+export declare const spaceKvPatterns: (spaceId: number, prefix?: string) => string[];

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

@@ -1,3 +1,4 @@
+import { LIST_SEGMENT } from "./kvStore.js";
 //#region src/modules/actions/runtime/namespaceKv.ts
 /**
 * Prefixes every key with the space that wrote it.
@@ -6,14 +7,25 @@
 * cross-tenant leak this whole design exists to avoid. Done at the runner rather than in each task so a
 * deployment's own tasks inherit it too.
 */
+var spaceScope = (spaceId) => `action:${spaceId}:`;
 var namespaceKv = (store, spaceId) => {
-	const scoped = (key) => `action:${spaceId}:${key}`;
+	const scoped = (key) => `${spaceScope(spaceId)}${key}`;
 	return {
 		get: (key) => store.get(scoped(key)),
 		set: (key, value, ttlSeconds) => store.set(scoped(key), value, ttlSeconds),
 		delete: (key) => store.delete(scoped(key)),
-		increment: (key, amount, ttlSeconds) => store.increment(scoped(key), amount, ttlSeconds)
+		increment: (key, amount, ttlSeconds) => store.increment(scoped(key), amount, ttlSeconds),
+		swap: (key, expected, next, ttlSeconds) => store.swap(scoped(key), expected, next, ttlSeconds),
+		listPut: (list, entry, options) => store.listPut(scoped(list), entry, options),
+		listRange: (list, range) => store.listRange(scoped(list), range),
+		listRemove: (list, id) => store.listRemove(scoped(list), id),
+		change: (key, change, lifetime) => store.change(scoped(key), change, lifetime)
 	};
 };
+/**
+* Every key a space's store holds, as patterns over the adapter's keys (`createKvStore`'s `prefix`, `kv:` unless it was
+* given another) — for whoever has to let all of them go at once: a space that is deleted, or reset to how it started.
+*/
+var spaceKvPatterns = (spaceId, prefix = "kv:") => [`${prefix}${spaceScope(spaceId)}*`, `${prefix}${LIST_SEGMENT}${spaceScope(spaceId)}*`];
 //#endregion
-export { namespaceKv };
+export { namespaceKv, spaceKvPatterns };

package/dist/modules/actions/runtime/namespaceKv.test.d.ts

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

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

@@ -1,17 +1,13 @@
 import { findTriggerNode, triggerParams } from "./triggers.js";
 import { ActionRunError } from "./errors.js";
 import { applyFields } from "./scope.js";
-import { triggerAccess, triggerInput } from "@plitzi/sdk-shared/actions";
+import { accessRefusal, triggerAccess, triggerInput } from "@plitzi/sdk-shared/actions";
 //#region src/modules/actions/runtime/precheck.ts
 var authorize = (access, kind, user) => {
 	if (kind === "schedule") return;
-	if (!access) throw new ActionRunError("forbidden", "This trigger declares no access rule");
-	if (access.mode === "public") return;
-	if (!user) throw new ActionRunError("unauthenticated", "This action requires a signed-in visitor");
-	if (access.mode === "role") {
-		const held = new Set(user.permissions);
-		if (access.permissions.some((permission) => !held.has(permission))) throw new ActionRunError("forbidden", "This action requires permissions the caller does not hold");
-	}
+	const refusal = accessRefusal(access, user);
+	if (refusal === "unauthenticated") throw new ActionRunError("unauthenticated", "This action requires a signed-in visitor");
+	if (refusal) throw new ActionRunError("forbidden", access ? "This action requires permissions the caller does not hold" : "This trigger declares no access rule");
 };
 /**
 * Everything that decides whether a run may happen at all, before it costs anything.

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

@@ -0,0 +1,19 @@
+import { ActionKvStore } from '../types';
+/** How much of something is allowed: `most` in every `perSeconds`, for each caller or for everyone together. */
+export type RateLimit = {
+    most: number;
+    perSeconds: number;
+    per?: 'caller' | 'everyone';
+};
+/** Where a limit stands after counting one more: whether that one was within it, and how many are left. */
+export type RateCount = {
+    allowed: boolean;
+    count: number;
+    remaining: number;
+};
+/**
+ * Counts one more of `bucket` in the current window and says whether it was within the limit — the one count behind
+ * the `flow.rateLimit` step and a function's `ctx.rateLimit`, so a flow and code limiting the same bucket count
+ * together. Refusing is the caller's: a step refuses the run, a function decides what to answer.
+ */
+export declare const countRate: (kv: ActionKvStore, callerId: string, bucket: string, { most, perSeconds, per }: RateLimit) => Promise<RateCount>;

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

@@ -0,0 +1,19 @@
+//#region src/modules/actions/runtime/rateLimit.ts
+/**
+* Counts one more of `bucket` in the current window and says whether it was within the limit — the one count behind
+* the `flow.rateLimit` step and a function's `ctx.rateLimit`, so a flow and code limiting the same bucket count
+* together. Refusing is the caller's: a step refuses the run, a function decides what to answer.
+*/
+var countRate = async (kv, callerId, bucket, { most, perSeconds, per = "caller" }) => {
+	if (!bucket || !Number.isInteger(most) || most < 1 || !Number.isInteger(perSeconds) || perSeconds < 1) throw new Error("A rate limit names what it counts, and allows a whole number of runs over whole seconds");
+	const window = Math.floor(Date.now() / (perSeconds * 1e3));
+	const who = per === "everyone" ? "everyone" : callerId;
+	const count = await kv.increment(`$rate:${bucket}:${who}:${String(window)}`, 1, perSeconds + 1);
+	return {
+		allowed: count <= most,
+		count,
+		remaining: Math.max(0, most - count)
+	};
+};
+//#endregion
+export { countRate };

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

@@ -0,0 +1,27 @@
+import { ActionKvAdapter } from '../types';
+/**
+ * The commands this adapter sends, typed by shape rather than by a client library: ioredis answers them as they are,
+ * and any client that speaks them does. `eval` is for `swap`, the one operation Redis has no single command for.
+ */
+export type RedisKvClient = {
+    get: (key: string) => Promise<string | null>;
+    set: {
+        (key: string, value: string): Promise<unknown>;
+        (key: string, value: string, mode: 'EX', seconds: number): Promise<unknown>;
+    };
+    del: (key: string) => Promise<number>;
+    incrby: (key: string, amount: number) => Promise<number>;
+    expire: (key: string, seconds: number) => Promise<number>;
+    eval: (script: string, keys: number, ...args: (string | number)[]) => Promise<unknown>;
+};
+export type RedisKvOptions = {
+    /** Put in front of every key, for a Redis that holds other things too. None when absent. */
+    prefix?: string;
+};
+/**
+ * An {@link ActionKvAdapter} over Redis: each operation one command, and `swap` one script.
+ *
+ * `client` may be a function, for a deployment whose connection comes and goes — it is asked on every call, and a
+ * client it cannot give is its to refuse (throwing), never this adapter's to read as "no value".
+ */
+export declare const createRedisKv: (client: RedisKvClient | (() => RedisKvClient), { prefix }?: RedisKvOptions) => ActionKvAdapter;

package/dist/modules/actions/runtime/redisKv.integration.test.d.ts

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

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

@@ -0,0 +1,46 @@
+//#region src/modules/actions/runtime/redisKv.ts
+/**
+* Read and write as ONE step: Redis runs a script with nothing else in between, which is what makes it the
+* compare-and-set it has no command for. `ARGV[1]` says whether a value is expected at all — an absent key and one
+* holding the empty string are different things.
+*/
+var SWAP = `
+local current = redis.call('GET', KEYS[1])
+if ARGV[1] == 'absent' then
+  if current then return 0 end
+elseif current ~= ARGV[2] then
+  return 0
+end
+if ARGV[4] == '' then
+  redis.call('SET', KEYS[1], ARGV[3])
+else
+  redis.call('SET', KEYS[1], ARGV[3], 'EX', tonumber(ARGV[4]))
+end
+return 1
+`;
+/**
+* An {@link ActionKvAdapter} over Redis: each operation one command, and `swap` one script.
+*
+* `client` may be a function, for a deployment whose connection comes and goes — it is asked on every call, and a
+* client it cannot give is its to refuse (throwing), never this adapter's to read as "no value".
+*/
+var createRedisKv = (client, { prefix = "" } = {}) => {
+	const redis = typeof client === "function" ? client : () => client;
+	const key = (name) => `${prefix}${name}`;
+	return {
+		get: async (name) => await redis().get(key(name)) ?? void 0,
+		set: async (name, value, ttlSeconds) => {
+			await (ttlSeconds === void 0 ? redis().set(key(name), value) : redis().set(key(name), value, "EX", ttlSeconds));
+		},
+		delete: async (name) => {
+			await redis().del(key(name));
+		},
+		increment: (name, amount) => redis().incrby(key(name), amount),
+		expire: async (name, ttlSeconds) => {
+			await redis().expire(key(name), ttlSeconds);
+		},
+		swap: async (name, expected, next, ttlSeconds) => await redis().eval(SWAP, 1, key(name), expected === void 0 ? "absent" : "equals", expected ?? "", next, ttlSeconds === void 0 ? "" : ttlSeconds) === 1
+	};
+};
+//#endregion
+export { createRedisKv };

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

@@ -1,3 +1,4 @@
+import { serverLog } from "../../../helpers/serverLog.js";
 //#region src/modules/actions/runtime/report.ts
 /**
 * Reports a request that never became a run.
@@ -15,7 +16,7 @@ var reportReject = async (config, record) => {
 	try {
 		await config.action?.onReject?.(record);
 	} catch (error) {
-		console.error("[Actions] reject record failed:", error);
+		serverLog.error("Actions", "reject record failed", error);
 	}
 };
 //#endregion

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

@@ -1,7 +1,13 @@
-import { ActionRunRequest, ActionRunResult, ActionsConfig, ActionTaskRegistry } from '../types';
+import { TaskContextRequest } from './taskContext';
+import { ActionRunRequest, ActionRunResult, ActionsConfig, ActionTaskContext, ActionTaskRegistry } from '../types';
 export type ActionRunner = {
     runAction: (request: ActionRunRequest) => Promise<ActionRunResult>;
 };
+/**
+ * What a function answering a route runs with: the context a run's step gets — the same stores, the same redaction, the
+ * same outbound budget under the deployment's ceilings — for work that is not a flow.
+ */
+export type TaskContextSource = (request: TaskContextRequest, signal: AbortSignal, lineage: string[]) => Omit<ActionTaskContext, 'log'>;
 /**
  * Builds the runner every trigger goes through.
  *
@@ -9,4 +15,6 @@ export type ActionRunner = {
  * input contract — lives HERE rather than in a transport, because a deployment mounting its own trigger calls this
  * directly. A check in the endpoint would be a check a custom trigger silently skips.
  */
-export declare const createActionRunner: (config: ActionsConfig, registry: ActionTaskRegistry, baseFetch?: typeof fetch) => ActionRunner;
+export declare const createActionRunner: (config: ActionsConfig, registryFor: (request: ActionRunRequest) => ActionTaskRegistry | Promise<ActionTaskRegistry>, baseFetch?: typeof fetch) => ActionRunner & {
+    taskContext: TaskContextSource;
+};