@cosmicdrift/kumiko-framework 0.372.0 → 0.374.0

package/dist/files/bind-pending-file-refs.d.ts

@@ -1,6 +1,6 @@
 import type { TenantDb } from "../db/tenant-db.ts";
 import { type Registry, type SaveContext, type SessionUser } from "../engine/types/index.ts";
-import type { FileRefRows } from "./load-save-file-refs.ts";
+import { type FileRefRows } from "./load-save-file-refs.ts";
 export declare function fileRefIdsOf(value: unknown): readonly string[];
 export declare function bindPendingFileRefs(args: {
     readonly registry: Registry;
@@ -9,3 +9,33 @@ export declare function bindPendingFileRefs(args: {
     readonly db: TenantDb;
     readonly fileRefRows: FileRefRows;
 }): Promise<void>;
+export type PendingFileRef = {
+    readonly id: string;
+    readonly storageKey: string;
+    readonly mimeType: string;
+    readonly size: number;
+    readonly version: number;
+};
+type PendingFileRefLookup = {
+    readonly fileRefId: string;
+    readonly entityName: string;
+    readonly fieldName: string;
+    readonly user: SessionUser;
+    readonly db: TenantDb;
+};
+export declare function loadPendingFileRef(lookup: PendingFileRefLookup): Promise<PendingFileRef | undefined>;
+export type BindPendingFileRefOutcome = "bound" | "not-pending" | "version-conflict";
+/**
+ * Binds one of the caller's own pending uploads to a record from a custom handler, with the
+ * same ownership predicate as the save pipeline. Anonymous callers never own an upload.
+ *
+ * The helper checks the upload, not the target: the caller must already be authorized to write
+ * `entityId` itself (for example a record the handler just wrote); `canWriteRecord` is not checked.
+ *
+ * A parallel bind of the same fileRef loses with "version-conflict" (or "not-pending" once the
+ * winner has committed); anything else throws.
+ */
+export declare function bindPendingFileRef(args: PendingFileRefLookup & {
+    readonly entityId: string;
+}): Promise<BindPendingFileRefOutcome>;
+export {};

package/dist/files/bind-pending-file-refs.js

@@ -1,7 +1,9 @@
+import { isAnonymousSessionUser } from "../engine/system-user.js";
 import { isFileField, isUuid, } from "../engine/types/index.js";
 import { reraiseAsKumikoError } from "../errors/index.js";
 import { getFileRefExecutor } from "./create-file-ref.js";
 import { FILE_REF_ENTITY_NAME } from "./file-ref-entity.js";
+import { loadFileRefRows } from "./load-save-file-refs.js";
 export function fileRefIdsOf(value) {
     if (typeof value === "string")
         return isUuid(value) ? [value] : [];
@@ -15,6 +17,16 @@ function isPendingUploadFor(row, entityName, fieldName, user) {
         row["fieldName"] === fieldName &&
         row["insertedById"] === user.id);
 }
+function streamVersionOf(row) {
+    return typeof row["version"] === "number" ? row["version"] : undefined;
+}
+async function bindPendingRow(args) {
+    const { row, fileRefId, entityName, fieldName, entityId, user, db } = args;
+    if (!isPendingUploadFor(row, entityName, fieldName, user))
+        return { kind: "not-pending" };
+    const bound = await getFileRefExecutor().update({ id: fileRefId, version: streamVersionOf(row), changes: { entityId } }, user, db);
+    return bound.isSuccess ? { kind: "bound" } : { kind: "failed", error: bound.error };
+}
 // A form (or a server handler via createFileRefFromBytes) uploads before the
 // record references the file, so its fileRefs carry entityType + fieldName but
 // no entityId. Binding them in the save's own transaction makes record-bound
@@ -35,7 +47,6 @@ export async function bindPendingFileRefs(args) {
     // skip: without the files feature the file_refs table is not part of the schema
     if (registry.getEntity(FILE_REF_ENTITY_NAME) === undefined)
         return;
-    const executor = getFileRefExecutor();
     for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
         if (!isFileField(fieldDef))
             continue;
@@ -43,12 +54,75 @@ export async function bindPendingFileRefs(args) {
         // ones bound earlier; only the ids this save names can be pending uploads.
         for (const fileRefId of fileRefIdsOf(result.changes[fieldName])) {
             const row = fileRefRows.get(fileRefId);
-            if (row === undefined || !isPendingUploadFor(row, entityName, fieldName, user))
+            if (row === undefined)
                 continue;
-            const version = typeof row["version"] === "number" ? row["version"] : undefined;
-            const bound = await executor.update({ id: fileRefId, version, changes: { entityId: String(result.id) } }, user, db);
-            if (!bound.isSuccess)
-                throw reraiseAsKumikoError(bound.error);
+            const outcome = await bindPendingRow({
+                row,
+                fileRefId,
+                entityName,
+                fieldName,
+                entityId: String(result.id),
+                user,
+                db,
+            });
+            if (outcome.kind === "failed")
+                throw reraiseAsKumikoError(outcome.error);
         }
     }
 }
+async function loadPendingRow(lookup) {
+    const { fileRefId, entityName, fieldName, user, db } = lookup;
+    // Every anonymous visitor shares one user id, so insertedById cannot tell their uploads apart.
+    if (isAnonymousSessionUser(user))
+        return undefined;
+    if (!isUuid(fileRefId))
+        return undefined;
+    const row = (await loadFileRefRows(db, [fileRefId], user.tenantId)).get(fileRefId);
+    return row !== undefined && isPendingUploadFor(row, entityName, fieldName, user)
+        ? row
+        : undefined;
+}
+// fileName is left out on purpose: it is personal data and may be encrypted; read it through
+// the fileRef executor's detail when it is needed.
+export async function loadPendingFileRef(lookup) {
+    const row = await loadPendingRow(lookup);
+    if (row === undefined)
+        return undefined;
+    const { storageKey, mimeType, size } = row;
+    const version = streamVersionOf(row);
+    if (typeof storageKey !== "string" ||
+        typeof mimeType !== "string" ||
+        typeof size !== "number" ||
+        version === undefined) {
+        return undefined;
+    }
+    return { id: lookup.fileRefId, storageKey, mimeType, size, version };
+}
+const CONCURRENT_BIND_ERROR_CODES = ["version_conflict", "unique_violation"];
+/**
+ * Binds one of the caller's own pending uploads to a record from a custom handler, with the
+ * same ownership predicate as the save pipeline. Anonymous callers never own an upload.
+ *
+ * The helper checks the upload, not the target: the caller must already be authorized to write
+ * `entityId` itself (for example a record the handler just wrote); `canWriteRecord` is not checked.
+ *
+ * A parallel bind of the same fileRef loses with "version-conflict" (or "not-pending" once the
+ * winner has committed); anything else throws.
+ */
+export async function bindPendingFileRef(args) {
+    const row = await loadPendingRow(args);
+    // Without a stream version the update would run unversioned and could overwrite a concurrent bind.
+    if (row === undefined || streamVersionOf(row) === undefined)
+        return "not-pending";
+    const outcome = await bindPendingRow({ ...args, row });
+    switch (outcome.kind) {
+        case "bound":
+            return "bound";
+        case "not-pending":
+            return "not-pending";
+        case "failed":
+            if (CONCURRENT_BIND_ERROR_CODES.includes(outcome.error.code))
+                return "version-conflict";
+            throw reraiseAsKumikoError(outcome.error);
+    }
+}

package/dist/files/index.d.ts

@@ -1,3 +1,5 @@
+export type { BindPendingFileRefOutcome, PendingFileRef } from "./bind-pending-file-refs.ts";
+export { bindPendingFileRef, loadPendingFileRef } from "./bind-pending-file-refs.ts";
 export type { CreatedFileRef, CreateFileRefContext, CreateFileRefInput, UploadedFileBytes, UploadFileBytesContext, } from "./create-file-ref-from-bytes.ts";
 export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytesBeforeTransaction, } from "./create-file-ref-from-bytes.ts";
 export { createFilesFeature, FILES_FEATURE } from "./feature.ts";

package/dist/files/index.js

@@ -1,3 +1,4 @@
+export { bindPendingFileRef, loadPendingFileRef } from "./bind-pending-file-refs.js";
 export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytesBeforeTransaction, } from "./create-file-ref-from-bytes.js";
 export { createFilesFeature, FILES_FEATURE } from "./feature.js";
 // `createFileHandle` is an implementation detail — construct handles via

package/dist/files/load-save-file-refs.js

@@ -33,12 +33,14 @@ export async function loadFileRefRows(db, ids, tenantId) {
     // skip: nothing referenced, nothing to load
     if (ids.length === 0)
         return new Map();
+    // Versions before rows: a bind committing in between leaves a stale row paired with an older
+    // version, so the binding update conflicts instead of overwriting the winner's entityId.
+    const streamVersions = await getStreamVersions(tenantDbRunner(db), [...ids], db.tenantId);
     const rows = await selectMany(db, fileRefsTable, {
         id: { in: [...ids] },
         tenantId,
         isDeleted: false,
     });
-    const streamVersions = await getStreamVersions(tenantDbRunner(db), rows.map((row) => String(row["id"])), db.tenantId);
     return new Map(rows.map((row) => {
         const id = String(row["id"]);
         const streamVersion = streamVersions.get(id);

package/dist/i18n/required-surface-keys.js

@@ -45,6 +45,19 @@ function pushKey(out, value, treatAsKey = false) {
 function editFieldName(f) {
     return typeof f === "string" ? f : f.field;
 }
+// Placeholder, affix texts and the fill button label of a field spec; a `{ field }`
+// affix reads another form field and is no key.
+function pushEditFieldTextKeys(out, spec, treatAsKey = false) {
+    // skip: shorthand field name carries no texts
+    if (typeof spec === "string")
+        return;
+    pushKey(out, spec.placeholder, treatAsKey);
+    for (const affix of [spec.prefix, spec.suffix]) {
+        if (typeof affix === "string")
+            pushKey(out, affix, treatAsKey);
+    }
+    pushKey(out, spec.fillAction?.label, treatAsKey);
+}
 // Group titles are translated exactly like the section title (computeEditViewModel).
 function pushSectionTitles(out, section, treatAsKey = false) {
     pushKey(out, section.title, treatAsKey);
@@ -67,15 +80,20 @@ function pushActionFormShapedKeys(out, featureName, step) {
         pushSectionTitles(out, section);
         for (const f of sectionFieldSpecs(section)) {
             out.add(fieldLabelKey(featureName, ACTION_FORM_ENTITY, editFieldName(f)));
+            pushEditFieldTextKeys(out, f);
         }
     }
 }
 function pushRowActionKeys(out, action) {
     pushKey(out, action.label);
-    if (action.kind === "writeHandler" || action.kind === undefined) {
+    if (action.kind === "writeHandler" ||
+        action.kind === "clientAction" ||
+        action.kind === undefined) {
         pushKey(out, action.confirm);
         pushKey(out, action.confirmLabel);
     }
+    if (action.kind === "clientAction")
+        pushKey(out, action.successMessage);
     if (action.kind === "drawer") {
         pushKey(out, action.title);
         pushKey(out, action.subtitle);
@@ -90,6 +108,8 @@ function pushDashboardScreenKeys(out, dashboard) {
         pushKey(out, option.label);
     pushKey(out, dashboard.scope?.badge);
     pushKey(out, dashboard.scope?.notice);
+    for (const action of dashboard.actions ?? [])
+        pushRowActionKeys(out, action);
 }
 function pushDashboardPanelKeys(out, panel) {
     // skip: custom-Panel übersetzt sich selbst, kein Key hier
@@ -98,8 +118,12 @@ function pushDashboardPanelKeys(out, panel) {
     pushKey(out, panel.label);
     if (panel.kind === "chart" || panel.kind === "stat-group")
         pushKey(out, panel.subtitle);
-    if (panel.kind === "chart")
+    if (panel.kind === "text")
+        pushDashboardTextBlockKeys(out, panel);
+    if (panel.kind === "chart") {
+        pushKey(out, panel.unit);
         pushDashboardChartRangeKeys(out, panel);
+    }
     if (panel.kind === "chart" ||
         panel.kind === "list" ||
         panel.kind === "feed" ||
@@ -107,6 +131,9 @@ function pushDashboardPanelKeys(out, panel) {
         pushKey(out, panel.emptyLabel);
         pushKey(out, panel.emptyHint);
     }
+    pushDashboardChildLabelKeys(out, panel);
+}
+function pushDashboardChildLabelKeys(out, panel) {
     if (panel.kind === "stat-group") {
         for (const stat of panel.stats)
             pushKey(out, stat.label);
@@ -119,6 +146,20 @@ function pushDashboardPanelKeys(out, panel) {
         }
     }
 }
+function pushDashboardTextBlockKeys(out, panel) {
+    for (const block of panel.blocks) {
+        // skip: code is shown verbatim, not translated
+        if (block.kind === "code")
+            continue;
+        if (block.kind === "list") {
+            for (const item of block.items)
+                pushKey(out, item);
+        }
+        else {
+            pushKey(out, block.text);
+        }
+    }
+}
 function pushDashboardChartRangeKeys(out, panel) {
     for (const option of panel.ranges?.options ?? [])
         pushKey(out, option.label);
@@ -243,6 +284,7 @@ export function requiredKeysFromScreen(featureName, screen, options = {}) {
                     continue; // rejected at boot, unreachable here
                 pushSectionTitles(out, section);
                 for (const f of sectionFieldSpecs(section)) {
+                    pushEditFieldTextKeys(out, f);
                     const fieldName = editFieldName(f);
                     const override = edit.fieldLabels?.[fieldName];
                     if (override !== undefined)
@@ -260,6 +302,8 @@ export function requiredKeysFromScreen(featureName, screen, options = {}) {
             pushKey(out, form.summary?.subtitle);
             for (const action of form.footerActions ?? [])
                 pushKey(out, action.label);
+            for (const link of form.successLinks ?? [])
+                pushKey(out, link.label);
             for (const fieldName of Object.keys(form.fields)) {
                 const override = form.fieldLabels?.[fieldName];
                 if (override !== undefined)
@@ -276,6 +320,7 @@ export function requiredKeysFromScreen(featureName, screen, options = {}) {
                     continue; // rejected at boot, unreachable here
                 pushSectionTitles(out, section);
                 for (const f of sectionFieldSpecs(section)) {
+                    pushEditFieldTextKeys(out, f);
                     const fieldName = editFieldName(f);
                     const override = form.fieldLabels?.[fieldName];
                     if (override !== undefined)
@@ -328,6 +373,7 @@ export function requiredKeysFromScreen(featureName, screen, options = {}) {
                 pushSectionTitles(out, section, treatDotFormAsKey);
                 pushKey(out, section.description, treatDotFormAsKey);
                 for (const f of sectionFieldSpecs(section)) {
+                    pushEditFieldTextKeys(out, f, treatDotFormAsKey);
                     const fieldName = editFieldName(f);
                     const override = config.fieldLabels?.[fieldName];
                     if (override !== undefined)
@@ -366,6 +412,7 @@ export function requiredKeysFromScreen(featureName, screen, options = {}) {
                     pushKey(out, section.submitLabel);
                     // kumiko-lint-ignore section-fields-raw writeForm sections carry no groups (EditWriteFormSection)
                     for (const f of section.fields) {
+                        pushEditFieldTextKeys(out, f);
                         const fieldName = editFieldName(f);
                         out.add(fieldLabelKey(featureName, WRITE_FORM_SECTION_ENTITY, fieldName));
                     }
@@ -373,6 +420,7 @@ export function requiredKeysFromScreen(featureName, screen, options = {}) {
                 }
                 pushSectionTitles(out, section);
                 for (const f of sectionFieldSpecs(section)) {
+                    pushEditFieldTextKeys(out, f);
                     const fieldName = editFieldName(f);
                     const override = detail.fieldLabels?.[fieldName];
                     if (override !== undefined)

package/dist/pipeline/dispatch-shared.js

@@ -5,7 +5,7 @@ import { createTenantDb, createUncheckedSystemDb, hasTenantColumn, runInOwnTrans
 import { createDerivativesContext } from "../derivatives/derivatives-context.js";
 import { mayOverrideTenant } from "../engine/cross-tenant.js";
 import { createSystemUser } from "../engine/system-user.js";
-import { isRateLimitDisabled, resolveAgentExposure } from "../engine/types/index.js";
+import { declaredRateLimitOptions, isRateLimitDisabled, resolveAgentExposure, } from "../engine/types/index.js";
 import { AccessDeniedError, FeatureDisabledError, FrameworkReasons, InternalError, memberResolutionReadOnlyDenied, RateLimitError, RateLimitUnavailableError, VersionConflictError, writeFailure, } from "../errors/index.js";
 import { archiveStream as archiveStreamHelper, isStreamArchived, restoreStream as restoreStreamHelper, } from "../event-store/archive.js";
 import { IdempotentAppendConflictError as EventStoreIdempotentAppendConflictError, VersionConflictError as EventStoreVersionConflictError, } from "../event-store/errors.js";
@@ -1107,16 +1107,28 @@ const DEFAULT_SYSTEM_SCOPE_RATE_LIMIT = {
     limit: 600,
     windowSeconds: 60,
 };
-function resolveEffectiveRateLimit(rateLimit, isSystemScope, user, resolver) {
-    if (rateLimit)
-        return rateLimit;
+function resolveEffectiveRateLimits(rateLimit, isSystemScope, user, resolver) {
+    const declared = declaredRateLimitOptions(rateLimit);
+    if (declared.length > 0)
+        return declared;
     if (!isSystemScope)
-        return undefined;
+        return [];
     if (!resolver)
-        return undefined;
+        return [];
     if (isSystemIdentity(user))
-        return undefined;
-    return DEFAULT_SYSTEM_SCOPE_RATE_LIMIT;
+        return [];
+    return [DEFAULT_SYSTEM_SCOPE_RATE_LIMIT];
+}
+// A single bucket keeps the plain enforce path; several go through one atomic
+// all-or-nothing call so a rejection by one bucket never charges the others.
+async function enforceBuckets(resolver, requests) {
+    const [only, ...rest] = requests;
+    // skip: no bucket to charge
+    if (!only)
+        return;
+    await (rest.length === 0
+        ? resolver.enforce(only.bucket, only.config)
+        : resolver.enforceAll(requests));
 }
 // L3 rate limit gate. Called by both query and write paths before
 // access-check. Reasoning:
@@ -1135,42 +1147,48 @@ export async function enforceRateLimit(ctx, rateLimit, handlerName, user, isSyst
     // skip: handler explicitly opts out via rateLimit: { disabled: true }
     if (isRateLimitDisabled(rateLimit))
         return;
-    const effective = resolveEffectiveRateLimit(rateLimit, isSystemScope, user, context.rateLimit);
+    const effective = resolveEffectiveRateLimits(rateLimit, isSystemScope, user, context.rateLimit);
     // skip: no rateLimit declared and not systemScope (or resolved to no-op) — nothing to enforce
-    if (!effective)
+    if (effective.length === 0)
         return;
     const reqCtx = requestContext.get();
-    const bucket = buildBucketKey(effective, {
-        handlerName,
-        user,
-        ip: reqCtx?.ip,
-    });
-    // skip: ip-bucket + no IP (non-HTTP entry point) — pass through before
-    // requiring a resolver; HTTP path always has an IP + L1/L2 middleware.
-    if (bucket.kind === "skip")
-        return;
-    if (!context.rateLimit) {
-        throw new InternalError({
-            message: `Handler "${handlerName}" declares rateLimit but no RateLimitResolver is configured. Load the rate-limiting feature or remove the option.`,
-        });
-    }
     // A nested dispatch re-hitting a bucket its entry dispatch already charged
     // (e.g. a per:"ip" handler delegating via queryAs) must not cost a second token.
     // The mark is set only after a successful enforce and includes the limit
     // parameters: a denied or failed check never lets a later nested call through,
     // and a nested handler with a stricter limit on the same bucket is still checked.
     const charged = reqCtx?.chargedRateLimitBuckets;
-    const chargedKey = `${bucket.key}|${effective.limit}|${effective.windowSeconds}|${effective.cost}`;
-    // skip: this exact bucket, limit and window was already charged by the entry dispatch
-    if (charged?.has(chargedKey))
+    const pending = [];
+    for (const option of effective) {
+        const bucket = buildBucketKey(option, { handlerName, user, ip: reqCtx?.ip });
+        // skip: ip-bucket + no IP (non-HTTP entry point) — pass through before
+        // requiring a resolver; HTTP path always has an IP + L1/L2 middleware.
+        if (bucket.kind === "skip")
+            continue;
+        const chargedKey = `${bucket.key}|${option.limit}|${option.windowSeconds}|${option.cost}`;
+        // skip: this exact bucket, limit and window was already charged by the entry dispatch
+        if (charged?.has(chargedKey))
+            continue;
+        pending.push({
+            request: {
+                bucket: bucket.key,
+                config: { limit: option.limit, windowSeconds: option.windowSeconds, cost: option.cost },
+            },
+            chargedKey,
+        });
+    }
+    // skip: every bucket was skipped or already charged — nothing left to enforce
+    if (pending.length === 0)
         return;
-    try {
-        await context.rateLimit.enforce(bucket.key, {
-            limit: effective.limit,
-            windowSeconds: effective.windowSeconds,
-            cost: effective.cost,
+    if (!context.rateLimit) {
+        throw new InternalError({
+            message: `Handler "${handlerName}" declares rateLimit but no RateLimitResolver is configured. Load the rate-limiting feature or remove the option.`,
         });
-        charged?.add(chargedKey);
+    }
+    try {
+        await enforceBuckets(context.rateLimit, pending.map(({ request }) => request));
+        for (const { chargedKey } of pending)
+            charged?.add(chargedKey);
     }
     catch (error) {
         // Backend failure (Redis down): fail closed as 503, same as L1/L2.
@@ -1203,6 +1221,7 @@ export async function enforcePayloadRateLimits(ctx, limits, handlerName, user, d
             message: `Handler "${handlerName}" declares additionalRateLimits but its payload is not an object.`,
         });
     }
+    const requests = [];
     for (const { per, limit, windowSeconds, cost, normalize } of limits) {
         const value = data[per.payloadField];
         // skip: optional field not sent — nothing to bucket on
@@ -1213,9 +1232,10 @@ export async function enforcePayloadRateLimits(ctx, limits, handlerName, user, d
                 message: `Handler "${handlerName}" additionalRateLimits payloadField "${per.payloadField}" is not a string.`,
             });
         }
-        const key = buildPayloadBucketKey(user.tenantId, handlerName, per.payloadField, digest(normalizePayloadBucketValue(value, normalize)));
-        await context.rateLimit.enforce(key, { limit, windowSeconds, cost });
+        const bucket = buildPayloadBucketKey(user.tenantId, handlerName, per.payloadField, digest(normalizePayloadBucketValue(value, normalize)));
+        requests.push({ bucket, config: { limit, windowSeconds, cost } });
     }
+    await enforceBuckets(context.rateLimit, requests);
 }
 // Build the per-hook context every auth-claims invocation gets. Claims
 // hooks run OUTSIDE any request transaction (login is itself the root

package/dist/rate-limit/index.d.ts

@@ -1,4 +1,4 @@
 export { type BucketContext, type BucketResult, buildBucketKey, buildPayloadBucketKey, createPayloadDigest, normalizePayloadBucketValue, } from "./bucket.ts";
 export { type AuthEndpointRateLimitOptions, authEndpointRateLimit, type GlobalIpRateLimitOptions, globalIpRateLimit, type HttpRouteRateLimitOptions, httpRouteRateLimit, } from "./middleware.ts";
-export { createRateLimitResolver, type RateLimitConfig, type RateLimitDecision, type RateLimitResolver, type RateLimitResolverOptions, } from "./resolver.ts";
+export { createRateLimitResolver, type RateLimitBucketRequest, type RateLimitConfig, type RateLimitDecision, type RateLimitResolver, type RateLimitResolverOptions, } from "./resolver.ts";
 export { createUnlimitedRateLimitResolver } from "./unlimited-resolver.ts";

package/dist/rate-limit/resolver.d.ts

@@ -1,6 +1,6 @@
 import type { RateLimitResolver } from "@cosmicdrift/kumiko-types/rate-limit-types";
 import type { Redis } from "ioredis";
-export type { RateLimitConfig, RateLimitDecision, RateLimitResolver, } from "@cosmicdrift/kumiko-types/rate-limit-types";
+export type { RateLimitBucketRequest, RateLimitConfig, RateLimitDecision, RateLimitResolver, } from "@cosmicdrift/kumiko-types/rate-limit-types";
 export type RateLimitResolverOptions = {
     readonly redis: Redis;
     readonly keyPrefix?: string;

package/dist/rate-limit/resolver.js

@@ -1,5 +1,5 @@
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import { RateLimitError } from "../errors/index.js";
+import { InternalError, RateLimitError } from "../errors/index.js";
 import { RedisKeys } from "../pipeline/redis-keys.js";
 import { toPublicBucketName } from "./bucket.js";
 // Token-Bucket rate limiter, atomic via Redis Lua. One round-trip per
@@ -105,6 +105,64 @@ end
 
 return { math.floor(tokens), retryAfterMs }
 `;
+// All-or-nothing variant for several buckets. Every bucket is refilled and
+// checked first; tokens are deducted only when each one has enough, so a
+// rejected request charges no bucket. Multi-key EVAL needs all keys in one
+// hash slot on Redis Cluster; the framework uses standalone Redis.
+//
+// KEYS[i]  — bucket keys
+// ARGV[1]  — nowMs
+// ARGV[2 + 4(i-1) .. 5 + 4(i-1)] — limit, refillRatePerMs, cost, ttlSeconds of KEYS[i]
+//
+// Returns the flat list { allAllowed (1|0), remaining_1, retryAfterMs_1, remaining_2, ... }.
+// retryAfterMs_i is 0 for buckets that had enough tokens.
+const TOKEN_BUCKET_ALL_LUA = `
+local nowMs = tonumber(ARGV[1])
+local count = #KEYS
+local tokens = {}
+local costs = {}
+local retries = {}
+local allAllowed = 1
+
+for i = 1, count do
+  local base = 2 + (i - 1) * 4
+  local limit = tonumber(ARGV[base])
+  local refillRatePerMs = tonumber(ARGV[base + 1])
+  costs[i] = tonumber(ARGV[base + 2])
+
+  local data = redis.call('HMGET', KEYS[i], 'tokens', 'ts')
+  local current = tonumber(data[1])
+  local ts = tonumber(data[2])
+  if current == nil then
+    current = limit
+  else
+    local elapsed = math.max(0, nowMs - ts)
+    current = math.min(limit, current + elapsed * refillRatePerMs)
+  end
+  tokens[i] = current
+
+  if current >= costs[i] then
+    retries[i] = 0
+  else
+    retries[i] = math.ceil((costs[i] - current) / refillRatePerMs)
+    allAllowed = 0
+  end
+end
+
+local result = { allAllowed }
+for i = 1, count do
+  if allAllowed == 1 then
+    tokens[i] = tokens[i] - costs[i]
+  end
+  local base = 2 + (i - 1) * 4
+  redis.call('HMSET', KEYS[i], 'tokens', tokens[i], 'ts', nowMs)
+  redis.call('EXPIRE', KEYS[i], tonumber(ARGV[base + 3]))
+  result[#result + 1] = math.floor(tokens[i])
+  result[#result + 1] = retries[i]
+end
+
+return result
+`;
 const REGISTERED = new WeakSet();
 function ensureCommand(redis) {
     if (!REGISTERED.has(redis)) {
@@ -116,6 +174,7 @@ function ensureCommand(redis) {
             numberOfKeys: 1,
             lua: TOKEN_BUCKET_PEEK_LUA,
         });
+        redis.defineCommand("kumikoRateLimitAll", { lua: TOKEN_BUCKET_ALL_LUA });
         REGISTERED.add(redis);
     }
     return redis; // @cast-boundary engine-bridge
@@ -154,6 +213,49 @@ export function createRateLimitResolver(opts) {
             resetAt: decision.resetAt.toString(),
         });
     }
+    async function enforceAll(requests) {
+        if (requests.length === 0)
+            return [];
+        const nowMs = now();
+        const keys = requests.map(({ bucket }) => `${prefix}${bucket}`);
+        // The script writes each key back once, so a repeated key would deduct only one of its costs.
+        const duplicate = keys.find((key, index) => keys.indexOf(key) !== index);
+        if (duplicate !== undefined) {
+            throw new InternalError({
+                message: `enforceAll received the bucket "${duplicate.slice(prefix.length)}" more than once — merge the requests into one.`,
+            });
+        }
+        const perBucketArgs = requests.flatMap(({ config }) => [
+            String(config.limit),
+            String(config.limit / (config.windowSeconds * 1000)),
+            String(config.cost ?? 1),
+            String(Math.max(1, config.windowSeconds * 2)),
+        ]);
+        const [allAllowedFlag, ...flat] = await client.kumikoRateLimitAll(keys.length, ...keys, String(nowMs), ...perBucketArgs);
+        const outcomes = requests.map(({ bucket, config }, index) => {
+            const retryAfterMs = flat[index * 2 + 1] ?? 0;
+            const decision = {
+                allowed: retryAfterMs === 0,
+                limit: config.limit,
+                remaining: flat[index * 2] ?? 0,
+                retryAfterSeconds: Math.ceil(retryAfterMs / 1000),
+                windowSeconds: config.windowSeconds,
+                resetAt: Temporal.Instant.fromEpochMilliseconds(nowMs + retryAfterMs),
+            };
+            return { bucket, retryAfterMs, decision };
+        });
+        if (allAllowedFlag === 1)
+            return outcomes.map(({ decision }) => decision);
+        const rejected = outcomes.reduce((worst, outcome) => outcome.retryAfterMs > worst.retryAfterMs ? outcome : worst);
+        throw new RateLimitError({
+            bucket: toPublicBucketName(rejected.bucket),
+            limit: rejected.decision.limit,
+            windowSeconds: rejected.decision.windowSeconds,
+            remaining: rejected.decision.remaining,
+            retryAfterSeconds: rejected.decision.retryAfterSeconds,
+            resetAt: rejected.decision.resetAt.toString(),
+        });
+    }
     async function peek(bucket, config) {
         const refillRatePerMs = config.limit / (config.windowSeconds * 1000);
         const nowMs = now();
@@ -171,5 +273,5 @@ export function createRateLimitResolver(opts) {
             resetAt,
         };
     }
-    return { check, enforce, peek };
+    return { check, enforce, enforceAll, peek };
 }

package/dist/rate-limit/unlimited-resolver.js

@@ -16,6 +16,7 @@ export function createUnlimitedRateLimitResolver() {
     return {
         check: async (_bucket, config) => fullBucket(config),
         enforce: async (_bucket, config) => fullBucket(config),
+        enforceAll: async (requests) => requests.map(({ config }) => fullBucket(config)),
         peek: async (_bucket, config) => fullBucket(config),
     };
 }

package/dist/ui-types/index.d.ts

@@ -9,7 +9,7 @@ export type { BooleanFieldDef, DateFieldDef, EmbeddedDerivedCellDef, EntityDefin
 export type { AccessRule, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, RoleAccessPersonalData, RoleAccessRule, } from "../engine/types/handlers.ts";
 export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.ts";
 export type { IconKey, NavDefinition, NavIconKey } from "../engine/types/nav.ts";
-export type { ActionFormFooterAction, ActionFormRedirect, ActionFormScreenDefinition, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartKind, DashboardChartMarkerKind, DashboardChartPanel, DashboardChartRangeOption, DashboardChartRanges, DashboardChartTone, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelEmptyState, DashboardPanelGate, DashboardPanelQueryOptions, DashboardPanelSpan, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScopeDefinition, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextParam, DashboardTimeRangeDefinition, DashboardValueFormat, EditExtensionSection, EditFieldPrefill, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EmbeddedListEditSpec, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityListExpandableRow, EntityListFacetConfig, EntityListFacetExtraOption, EntityListScreenDefinition, EntityWriteExcludedFields, FieldCondition, FieldIconKey, FieldRenderer, FormWidth, ListBadgeTone, ListColumnDisplay, ListColumnSpec, ListEmptyStateSpec, ListFacetSpec, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSubtitlePart, RelatedListGroupBy, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionDisplay, RowActionDrawer, RowActionMode, RowActionNavigate, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, } from "../engine/types/screen.ts";
+export type { ActionFormFooterAction, ActionFormLoad, ActionFormRedirect, ActionFormScreenDefinition, ActionFormSuccessLink, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartKind, DashboardChartMarkerKind, DashboardChartPanel, DashboardChartRangeOption, DashboardChartRanges, DashboardChartTone, DashboardCurrencyFormat, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelEmptyState, DashboardPanelGate, DashboardPanelQueryOptions, DashboardPanelSpan, DashboardPanelVisibility, DashboardProgressListPanel, DashboardProgressTone, DashboardRecordBinding, DashboardRefresh, DashboardRelativeTimeFormat, DashboardRelativeTimeParam, DashboardScopeDefinition, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextBlock, DashboardTextPanel, DashboardTextParam, DashboardTimeRangeDefinition, DashboardValueFormat, EditExtensionSection, EditFieldPrefill, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EmbeddedListEditSpec, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityListExpandableRow, EntityListFacetConfig, EntityListFacetExtraOption, EntityListScreenDefinition, EntityWriteExcludedFields, FieldAffix, FieldCondition, FieldFillAction, FieldIconKey, FieldRenderer, FormWidth, ListBadgeTone, ListColumnDisplay, ListColumnSpec, ListEmptyStateSpec, ListFacetSpec, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSubtitlePart, RelatedListGroupBy, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionClientAction, RowActionDisplay, RowActionDrawer, RowActionMode, RowActionNavigate, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, } from "../engine/types/screen.ts";
 export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "../engine/types/screen.ts";
 export type { TargetRef } from "../engine/types/target-ref.ts";
 export type { TreeAction, TreeNode, TreeNodeState } from "../engine/types/tree-node.ts";