@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/dist/files/bind-referenced-files.write.js

@@ -5,6 +5,7 @@ import { ValidationError } from "../errors/index.js";
 import { fileRefIdsOf } from "./bind-pending-file-refs.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";
 import { findImplicitEntityTable } from "./record-write-check.js";
 const MAX_PAGE_SIZE = 500;
 const DEFAULT_PAGE_SIZE = 200;
@@ -50,40 +51,48 @@ function loadRecordPage(db, { entity, table }, { entityIds, afterId, limit }) {
             : afterId !== undefined && { id: { gt: afterId } }),
     }, { orderBy: { col: "id", direction: "asc" }, ...(entityIds === undefined && { limit }) });
 }
-// Unbound, same tenant, uploaded by the record's creator (or the system), and either
-// unclaimed or pending for exactly this entity field.
+// Unbound and same tenant. The record's creator may bind their own unclaimed or pending upload.
+// A system-generated file carries no owner of its own, so it binds only where it is already
+// pending for exactly this entity field — an unclaimed one could otherwise be pulled into any
+// record that merely names its id.
 function isBindableToRecord(fileRef, target) {
     const uploader = fileRef["insertedById"];
-    return (typeof uploader === "string" &&
-        (uploader === target.record["insertedById"] || uploader === SYSTEM_USER_ID) &&
-        fileRef["tenantId"] === target.tenantId &&
-        fileRef["entityId"] === null &&
-        (fileRef["entityType"] === null ||
-            (fileRef["entityType"] === target.entityType && fileRef["fieldName"] === target.fieldName)));
+    if (typeof uploader !== "string" ||
+        fileRef["tenantId"] !== target.tenantId ||
+        fileRef["entityId"] !== null) {
+        return false;
+    }
+    const isPendingForTarget = fileRef["entityType"] === target.entityType && fileRef["fieldName"] === target.fieldName;
+    if (uploader === target.record["insertedById"]) {
+        return fileRef["entityType"] === null || isPendingForTarget;
+    }
+    return uploader === SYSTEM_USER_ID && isPendingForTarget;
 }
 // The binding follows only the record's declared file fields; the caller names
 // no file ids. The record's creator must have uploaded the file themselves (or the
-// system generated it), otherwise a foreign reference would pull someone else's
-// private upload into the referencing user's record and make it readable there.
+// system generated it for exactly this field), otherwise a foreign reference would pull
+// someone else's private upload into the referencing user's record and make it readable there.
 export const bindReferencedFilesWrite = defineWriteHandler({
     name: "bindReferencedFiles",
     schema: payloadSchema,
     access: { roles: [SYSTEM_ROLE, "SystemAdmin"] },
     // Maintenance backfill run by ops or system jobs, not a task an assistant performs.
     agent: { expose: false },
-    description: "Binds the files a record references through its declared file fields to that record, so readers of the record see them through record access. Covers files uploaded before pending-upload binding existed (entityId null) and records created without a save lifecycle (custom handlers, system jobs). Binds only files uploaded by the record's creator or generated by the system; skips files already bound elsewhere, uploaded by someone else, of another tenant or missing; never rebinds.",
+    description: "Binds the files a record references through its declared file fields to that record, so readers of the record see them through record access. Covers files uploaded before pending-upload binding existed (entityId null) and records created without a save lifecycle (custom handlers, system jobs). Binds only files uploaded by the record's creator or generated by the system for exactly this field; skips files already bound elsewhere, uploaded by someone else, of another tenant or missing; never rebinds.",
     handler: async (event, ctx) => {
         const { entityType, entityIds, limit } = event.payload;
         const { fileFieldNames, ...source } = resolveFileBearingEntity(ctx.registry, entityType);
         const records = await loadRecordPage(ctx.db, source, event.payload);
+        const referencedIds = records.flatMap((record) => fileFieldNames.flatMap((fieldName) => fileRefIdsOf(record[fieldName])));
+        const fileRefRows = await loadFileRefRows(ctx.db, referencedIds, event.user.tenantId);
         const executor = getFileRefExecutor();
         let bound = 0;
         let skipped = 0;
         for (const record of records) {
             for (const fieldName of fileFieldNames) {
                 for (const fileRefId of fileRefIdsOf(record[fieldName])) {
-                    const row = await executor.detail({ id: fileRefId }, event.user, ctx.db);
-                    if (row === null ||
+                    const row = fileRefRows.get(fileRefId);
+                    if (row === undefined ||
                         !isBindableToRecord(row, {
                             record,
                             entityType,

package/dist/files/create-file-ref-from-bytes.d.ts

@@ -1,8 +1,8 @@
 import type { TenantDb } from "../db/tenant-db.js";
-import type { Registry, SessionUser, WriteResult } from "../engine/types/index.js";
-import { type CreatedFileRef } from "./create-file-ref.js";
+import type { BeforeTransactionResult, Registry, SessionUser, WriteResult } from "../engine/types/index.js";
+import { type CreatedFileRef, type UploadedFileBytes } from "./create-file-ref.js";
 import type { FileContext } from "./file-handle.js";
-export type { CreatedFileRef };
+export type { CreatedFileRef, UploadedFileBytes };
 export type CreateFileRefContext = {
     readonly db: TenantDb;
     readonly files?: FileContext | undefined;
@@ -20,3 +20,6 @@ export type CreateFileRefInput = {
     };
 };
 export declare function createFileRefFromBytes(ctx: CreateFileRefContext, input: CreateFileRefInput): Promise<WriteResult<CreatedFileRef>>;
+export type UploadFileBytesContext = Pick<CreateFileRefContext, "db" | "files" | "registry" | "user">;
+export declare function uploadFileBytesBeforeTransaction(ctx: UploadFileBytesContext, input: CreateFileRefInput): Promise<BeforeTransactionResult<UploadedFileBytes>>;
+export declare function createFileRefFromUploadedBytes(ctx: Pick<CreateFileRefContext, "db" | "user">, uploaded: UploadedFileBytes): Promise<WriteResult<CreatedFileRef>>;

package/dist/files/create-file-ref-from-bytes.js

@@ -1,6 +1,9 @@
+import { fetchOne } from "../bun-db/query.js";
 import { FrameworkReasons, InternalError, UnprocessableError, writeFailure, } from "../errors/index.js";
-import { DEFAULT_MAX_UPLOAD_SIZE, storeFileAsFileRef, } from "./create-file-ref.js";
+import { createFileRefRow, DEFAULT_MAX_UPLOAD_SIZE, storeFileAsFileRef, writeAcceptedFileBytes, } from "./create-file-ref.js";
+import { fileRefsTable } from "./file-ref-table.js";
 import { readFilesRouteOptions } from "./file-routes.js";
+import { assertSafeStorageKey } from "./types.js";
 // Server-side counterpart of POST /files for handlers/jobs that produce bytes
 // themselves (generated PDFs, exports). Same validation, storage layout and
 // fileRef.created event as an upload; the tenant is always ctx.user.tenantId.
@@ -30,10 +33,70 @@ export async function createFileRefFromBytes(ctx, input) {
         case "created":
             return { isSuccess: true, data: outcome.fileRef };
         case "rejected":
-            return writeFailure(new UnprocessableError(FrameworkReasons.fileRejected, {
-                details: { error: outcome.error },
-            }));
+            return fileRejectedFailure(outcome.error);
         case "failed":
             return outcome.failure;
     }
 }
+function fileRejectedFailure(error) {
+    return writeFailure(new UnprocessableError(FrameworkReasons.fileRejected, { details: { error } }));
+}
+// Pre-transaction half of createFileRefFromBytes: validates and writes the binary while no
+// transaction holds a connection. Pair it with createFileRefFromUploadedBytes inside the handler.
+// A crash between this phase and the commit leaves the bytes in storage; nothing sweeps them.
+export async function uploadFileBytesBeforeTransaction(ctx, input) {
+    const { files } = ctx;
+    if (!files) {
+        return writeFailure(new InternalError({
+            message: "uploadFileBytesBeforeTransaction: ctx.files is unavailable — mount a file-provider feature to store files",
+        }));
+    }
+    const outcome = await writeAcceptedFileBytes({
+        user: ctx.user,
+        registry: ctx.registry,
+        defaultMaxUploadSize: readFilesRouteOptions(ctx.registry).maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE,
+        writeBytes: (key, data, mimeType) => files.ref(key).write(data, mimeType),
+    }, {
+        fileName: input.fileName,
+        declaredMimeType: input.mimeType,
+        data: input.data,
+        entityType: input.attachTo?.entityType,
+        entityId: input.attachTo?.entityId,
+        fieldName: input.attachTo?.fieldName,
+    });
+    if (outcome.kind === "rejected")
+        return fileRejectedFailure(outcome.error);
+    const { uploaded } = outcome;
+    return {
+        isSuccess: true,
+        data: uploaded,
+        // Also runs after a failed COMMIT whose outcome is unknown: a committed row must keep its binary.
+        release: async () => {
+            const committedRow = await fetchOne(ctx.db, fileRefsTable, {
+                storageKey: uploaded.storageKey,
+            });
+            if (!committedRow)
+                await files.ref(uploaded.storageKey).delete();
+        },
+    };
+}
+// Transaction half: creates the fileRef row for bytes uploadFileBytesBeforeTransaction wrote.
+export async function createFileRefFromUploadedBytes(ctx, uploaded) {
+    const ownPrefix = `${ctx.user.tenantId}/`;
+    if (!uploaded.storageKey.startsWith(ownPrefix)) {
+        return writeFailure(new InternalError({
+            message: "createFileRefFromUploadedBytes: storageKey is outside the caller's tenant prefix",
+        }));
+    }
+    try {
+        assertSafeStorageKey(uploaded.storageKey);
+    }
+    catch (error) {
+        return writeFailure(new InternalError({
+            message: "createFileRefFromUploadedBytes: unsafe storageKey",
+            ...(error instanceof Error && { cause: error }),
+        }));
+    }
+    const row = await createFileRefRow({ user: ctx.user, tenantDb: ctx.db }, uploaded);
+    return "failure" in row ? row.failure : { isSuccess: true, data: row.fileRef };
+}

package/dist/files/create-file-ref.d.ts

@@ -36,6 +36,22 @@ export type CreatedFileRef = {
     readonly size: number;
     readonly storageKey: string;
 };
+export type UploadedFileBytes = {
+    readonly storageKey: string;
+    readonly fileName: string;
+    readonly mimeType: string;
+    readonly size: number;
+    readonly entityType?: string | undefined;
+    readonly entityId?: string | undefined;
+    readonly fieldName?: string | undefined;
+};
+export type UploadBytesOutcome = {
+    readonly kind: "uploaded";
+    readonly uploaded: UploadedFileBytes;
+} | {
+    readonly kind: "rejected";
+    readonly error: string;
+};
 export type StoreFileOutcome = {
     readonly kind: "created";
     readonly fileRef: CreatedFileRef;
@@ -46,5 +62,11 @@ export type StoreFileOutcome = {
     readonly kind: "failed";
     readonly failure: WriteFailure;
 };
+export declare function writeAcceptedFileBytes(deps: Pick<StoreFileDeps, "user" | "registry" | "defaultMaxUploadSize" | "writeBytes">, input: StoreFileInput): Promise<UploadBytesOutcome>;
+export declare function createFileRefRow(deps: Pick<StoreFileDeps, "user" | "tenantDb">, uploaded: UploadedFileBytes): Promise<{
+    readonly fileRef: CreatedFileRef;
+} | {
+    readonly failure: WriteFailure;
+}>;
 export declare function storeFileAsFileRef(deps: StoreFileDeps, input: StoreFileInput): Promise<StoreFileOutcome>;
 export {};

package/dist/files/create-file-ref.js

@@ -92,44 +92,72 @@ function acceptFile(deps, input) {
         extension: undefined,
     };
 }
-// The one upload pipeline behind POST /files and createFileRefFromBytes.
-export async function storeFileAsFileRef(deps, input) {
+// Upload step: validates and writes the binary. Outside any transaction on purpose — network/disk
+// I/O doesn't belong inside a PG connection's tx window.
+export async function writeAcceptedFileBytes(deps, input) {
     const { fileName, data, entityType, entityId, fieldName } = input;
     const accepted = acceptFile(deps, input);
     if (accepted.kind === "rejected")
         return accepted;
     const { mimeType, extension } = accepted;
-    const fileRefId = generateId();
     const storageKey = buildStorageKey(deps.user.tenantId, entityType ?? "unattached", entityId, fieldName ?? "file", fileName, generateId(), extension);
-    // Write binary FIRST (outside the tx — network/disk I/O doesn't belong
-    // inside a PG connection's tx window). A failed create deletes the bytes
-    // again below; a later rollback of an enclosing transaction cannot, so
-    // those are orphaned for the cleanup-jobs to sweep. Losing a row on
-    // append-failure is acceptable; a committed row with a missing binary is not.
     await deps.writeBytes(storageKey, data, mimeType);
-    // id is explicit so the response + storageKey stay consistent; tenantId,
-    // insertedAt and insertedById are set by applyEntityEvent from the event metadata.
+    return {
+        kind: "uploaded",
+        uploaded: {
+            storageKey,
+            fileName,
+            mimeType,
+            size: data.byteLength,
+            entityType,
+            entityId,
+            fieldName,
+        },
+    };
+}
+// Row step: id is explicit so the response + storageKey stay consistent; tenantId, insertedAt and
+// insertedById are set by applyEntityEvent from the event metadata.
+export async function createFileRefRow(deps, uploaded) {
+    const fileRefId = generateId();
     const result = await getFileRefExecutor().create({
         id: fileRefId,
-        storageKey,
-        fileName,
-        mimeType,
-        size: data.byteLength,
-        entityType: entityType ?? null,
-        entityId: entityId ?? null,
-        fieldName: fieldName ?? null,
+        storageKey: uploaded.storageKey,
+        fileName: uploaded.fileName,
+        mimeType: uploaded.mimeType,
+        size: uploaded.size,
+        entityType: uploaded.entityType ?? null,
+        entityId: uploaded.entityId ?? null,
+        fieldName: uploaded.fieldName ?? null,
     }, deps.user, deps.tenantDb);
-    if (!result.isSuccess) {
+    if (!result.isSuccess)
+        return { failure: result };
+    return {
+        fileRef: {
+            id: fileRefId,
+            fileName: uploaded.fileName,
+            mimeType: uploaded.mimeType,
+            size: uploaded.size,
+            storageKey: uploaded.storageKey,
+        },
+    };
+}
+// The one upload pipeline behind POST /files and createFileRefFromBytes.
+export async function storeFileAsFileRef(deps, input) {
+    const upload = await writeAcceptedFileBytes(deps, input);
+    if (upload.kind === "rejected")
+        return upload;
+    // A failed create deletes the bytes again; a later rollback of an enclosing transaction or a
+    // crash cannot, so those bytes stay in storage (no job sweeps an original without a fileRef row).
+    // Losing a row on append-failure is acceptable; a committed row with a missing binary is not.
+    const row = await createFileRefRow(deps, upload.uploaded);
+    if ("failure" in row) {
         try {
-            await deps.deleteBytes(storageKey);
+            await deps.deleteBytes(upload.uploaded.storageKey);
         }
         catch {
-            // skip: the create failure is the error worth reporting; leftover bytes are swept by cleanup-jobs.
+            // skip: the create failure is the error worth reporting; the leftover bytes stay in storage.
         }
-        return { kind: "failed", failure: result };
+        return { kind: "failed", failure: row.failure };
     }
-    return {
-        kind: "created",
-        fileRef: { id: fileRefId, fileName, mimeType, size: data.byteLength, storageKey },
-    };
+    return { kind: "created", fileRef: row.fileRef };
 }

package/dist/files/file-handle.d.ts

@@ -1,5 +1,5 @@
 import type { FileContext, FileHandle } from "@cosmicdrift/kumiko-types/file-handle-types";
-import type { FileStorageProvider } from "./types.js";
+import { type FileStorageProvider } from "./types.js";
 export type { FileContext, FileHandle };
 export declare function createFileHandle(key: string, getProvider: () => Promise<FileStorageProvider>): FileHandle;
 export declare function createFileContext(resolve: () => Promise<FileStorageProvider>, tenantId?: string): FileContext;

package/dist/files/file-handle.js

@@ -11,6 +11,7 @@
 // `foo/bar.medium-<16 hex>.jpg`. The suffix must be a `variantSuffix(...)` so
 // the erasure sweep recognizes it. Stable, reversible, no extra lookup tables.
 import { isDerivativeSuffix } from "../derivatives/variant-key.js";
+import { assertSafeStorageKey } from "./types.js";
 // `getProvider` is a lazily-resolved, memoized accessor — the provider is
 // resolved (config + s3.secretAccessKey secret read) only when a handle method
 // actually does I/O, never on every request that merely builds a ctx.
@@ -54,6 +55,13 @@ export function createFileContext(resolve, tenantId) {
             }
             return createFileHandle(key, getProvider);
         },
+        /** Validates only the storage key shape (assertSafeStorageKey), no tenant prefix: keys
+         *  may outlive a tenant handover. The caller must ensure the fileRef row came from a
+         *  tenant-filtered read. */
+        refFromFileRef: (row) => {
+            assertSafeStorageKey(row.storageKey);
+            return createFileHandle(row.storageKey, getProvider);
+        },
         list: async (prefix) => {
             if (tenantId !== undefined && !prefix.startsWith(`${tenantId}/`)) {
                 throw new Error(`FileContext.list: prefix must start with "${tenantId}/"`);

package/dist/files/file-routes.js

@@ -74,7 +74,7 @@ export function readFilesRouteOptions(registry) {
     if (exp && typeof exp === "object" && "routeOptions" in exp) {
         const ro = exp.routeOptions;
         if (ro && typeof ro === "object") {
-            // @cast-boundary feature-exports: engine-payload (unknown) → known shape
+            // @cast-boundary feature-exports — typeof-checked read-back from untyped feature.exports
             return ro;
         }
     }
@@ -261,7 +261,7 @@ export function createFileRoutes(options) {
             tenantId: user.tenantId,
         });
         const result = await derivatives.variant(id, spec, name);
-        const data = await files.ref(result.storageKey).read();
+        const data = await files.refFromFileRef(result).read();
         // No Content-Length/Content-Disposition: fileRef.size is the ORIGINAL's
         // size, and a variant is rendered for display, not for download.
         // storageKey embeds specHash(spec), so the URL is content-stable until

package/dist/files/index.d.ts

@@ -1,5 +1,5 @@
-export type { CreatedFileRef, CreateFileRefContext, CreateFileRefInput, } from "./create-file-ref-from-bytes.js";
-export { createFileRefFromBytes } from "./create-file-ref-from-bytes.js";
+export type { CreatedFileRef, CreateFileRefContext, CreateFileRefInput, UploadedFileBytes, UploadFileBytesContext, } from "./create-file-ref-from-bytes.js";
+export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytesBeforeTransaction, } from "./create-file-ref-from-bytes.js";
 export { createFilesFeature } from "./feature.js";
 export type { FileContext, FileHandle } from "./file-handle.js";
 export { createFileContext, deriveKey, storageKeyStemPrefix } from "./file-handle.js";

package/dist/files/index.js

@@ -1,4 +1,4 @@
-export { createFileRefFromBytes } from "./create-file-ref-from-bytes.js";
+export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytesBeforeTransaction, } from "./create-file-ref-from-bytes.js";
 export { createFilesFeature } from "./feature.js";
 // `createFileHandle` is an implementation detail — construct handles via
 // `createFileContext(provider).ref(key)`, which is the AppContext surface.

package/dist/files/load-save-file-refs.d.ts

@@ -0,0 +1,10 @@
+import type { TenantDb } from "../db/tenant-db.js";
+import { type Registry, type SaveContext, type SessionUser } from "../engine/types/index.js";
+export type FileRefRows = ReadonlyMap<string, Readonly<Record<string, unknown>>>;
+export declare function loadSaveFileRefs(args: {
+    readonly registry: Registry;
+    readonly result: SaveContext;
+    readonly user: SessionUser;
+    readonly db: TenantDb;
+}): Promise<FileRefRows>;
+export declare function loadFileRefRows(db: TenantDb, ids: readonly string[], tenantId: SessionUser["tenantId"]): Promise<FileRefRows>;

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

@@ -0,0 +1,47 @@
+import { selectMany } from "../db/query.js";
+import { tenantDbRunner } from "../db/tenant-db-runner.js";
+import { isFileField, } from "../engine/types/index.js";
+import { getStreamVersions } from "../event-store/event-store.js";
+import { fileRefIdsOf } from "./bind-pending-file-refs.js";
+import { FILE_REF_ENTITY_NAME } from "./file-ref-entity.js";
+import { fileRefsTable } from "./file-ref-table.js";
+// One query for every fileRef a save names, restricted to the writer's own tenant and live
+// rows: the tenant check and the pending-upload binding both work from this map instead of
+// reading each row again inside the write transaction.
+export async function loadSaveFileRefs(args) {
+    const { registry, result, user, db } = args;
+    const entity = result.entityName === undefined ? undefined : registry.getEntity(result.entityName);
+    // skip: saves of unregistered or unnamed aggregates declare no file fields
+    if (entity === undefined)
+        return new Map();
+    // skip: without the files feature the file_refs table is not part of the schema
+    if (registry.getEntity(FILE_REF_ENTITY_NAME) === undefined)
+        return new Map();
+    const ids = new Set();
+    for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
+        if (!isFileField(fieldDef))
+            continue;
+        for (const id of fileRefIdsOf(result.changes[fieldName]))
+            ids.add(id);
+    }
+    return loadFileRefRows(db, [...ids], user.tenantId);
+}
+// One query for the given live fileRefs of one tenant. Each row carries the stream version as
+// `version`: the binding update needs it as expectedVersion, and events without a projection
+// effect (e.g. ingest requests) advance the stream but not the row's version column.
+export async function loadFileRefRows(db, ids, tenantId) {
+    // skip: nothing referenced, nothing to load
+    if (ids.length === 0)
+        return new Map();
+    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);
+        return [id, streamVersion === undefined ? row : { ...row, version: streamVersion }];
+    }));
+}

package/dist/files/local-provider.js

@@ -2,6 +2,7 @@ import { createReadStream, createWriteStream } from "node:fs";
 import { mkdir, readdir, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { pipeline } from "node:stream/promises";
+import { errorCodeOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { assertSafeStorageKey } from "./types.js";
 // Local-filesystem backend — intended for dev + tests. Production deploys
 // pick an object-store provider (S3/R2/…). mimeType is ignored here; the
@@ -112,7 +113,7 @@ export function createLocalProvider(basePath) {
                 entries = await readdir(walkRoot, { recursive: true, withFileTypes: true });
             }
             catch (err) {
-                const code = err.code;
+                const code = errorCodeOf(err);
                 if (code === "ENOENT" || code === "ENOTDIR")
                     return [];
                 throw err;

package/dist/files/purge-expired-file-ref-bytes.d.ts

@@ -4,11 +4,14 @@ import { deleteMany, type WhereObject } from "../db/query.js";
 import type { TenantDb } from "../db/tenant-db.js";
 export declare const EXPIRED_FILE_REF_PURGE_BATCH = 500;
 type PurgeLog = Pick<Logger, "warn"> | undefined;
+type PurgeTable = Parameters<typeof deleteMany>[1];
 export declare function purgeExpiredFileRefsWithBytes(args: {
     readonly db: TenantDb;
-    readonly table: Parameters<typeof deleteMany>[1];
+    readonly table: PurgeTable;
     readonly where: WhereObject;
+    readonly expiredBefore: Temporal.Instant;
     readonly files: FileContext | undefined;
     readonly log: PurgeLog;
+    readonly pageSize?: number;
 }): Promise<void>;
 export {};

package/dist/files/purge-expired-file-ref-bytes.js

@@ -1,34 +1,60 @@
 import { deleteMany, selectMany } from "../db/query.js";
 import { deleteStoredFileAndDerivatives } from "../derivatives/delete-stored-file.js";
 export const EXPIRED_FILE_REF_PURGE_BATCH = 500;
+const PAGE_ORDER = [
+    { col: "deletedAt", direction: "asc" },
+    { col: "id", direction: "asc" },
+];
+// Keyset page over (deletedAt, id): rows at the cursor's instant with a larger id first, then
+// strictly later instants. `where` already bounds deletedAt by the cutoff; the later-instants
+// query repeats that bound next to the cursor.
+async function selectNextPage(args) {
+    const { db, table, where, expiredBefore, cursor, pageSize } = args;
+    const options = { orderBy: PAGE_ORDER, limit: pageSize };
+    if (cursor === undefined)
+        return selectMany(db, table, where, options);
+    const sameInstant = await selectMany(db, table, { ...where, deletedAt: cursor.deletedAt, id: { gt: cursor.id } }, options);
+    if (sameInstant.length >= pageSize)
+        return sameInstant;
+    const later = await selectMany(db, table, { ...where, deletedAt: { gt: cursor.deletedAt, lt: expiredBefore } }, { ...options, limit: pageSize - sameInstant.length });
+    return [...sameInstant, ...later];
+}
 // Deletes the bytes (original + derivatives) of expired soft-deleted fileRef rows, then the
 // rows. Bytes first and fail-closed: once the row is gone nobody knows the storageKey, so a
-// row whose bytes could not be removed stays and the next run retries it.
+// row whose bytes could not be removed stays and the next run retries it. A run walks the
+// expired rows page by page along (deletedAt, id), so rows that keep failing cannot hide the
+// rows behind them; the run ends on the first empty page.
 export async function purgeExpiredFileRefsWithBytes(args) {
-    const { db, table, where, files, log } = args;
+    const { db, table, where, expiredBefore, files, log } = args;
+    const pageSize = args.pageSize ?? EXPIRED_FILE_REF_PURGE_BATCH;
     if (!files) {
         log?.warn("[soft-delete-cleanup] no file storage available, expired fileRef rows kept");
         return;
     }
-    const rows = await selectMany(db, table, where, {
-        orderBy: [{ col: "deletedAt", direction: "asc" }],
-        limit: EXPIRED_FILE_REF_PURGE_BATCH,
-    });
-    const purgedIds = [];
     const store = { list: files.list, delete: (key) => files.ref(key).delete() };
-    for (const row of rows) {
-        try {
-            const failedKeys = await deleteStoredFileAndDerivatives(row.storageKey, store, "soft-delete-cleanup:fileRef");
-            if (failedKeys.length === 0) {
-                purgedIds.push(row.id);
-                continue;
+    let cursor;
+    for (;;) {
+        const rows = await selectNextPage({ db, table, where, expiredBefore, cursor, pageSize });
+        const lastRow = rows[rows.length - 1];
+        // skip: an empty page means every expired row has been visited
+        if (lastRow === undefined)
+            return;
+        cursor = lastRow;
+        const purgedIds = [];
+        for (const row of rows) {
+            try {
+                const failedKeys = await deleteStoredFileAndDerivatives(row.storageKey, store, "soft-delete-cleanup:fileRef");
+                if (failedKeys.length === 0) {
+                    purgedIds.push(row.id);
+                    continue;
+                }
+                log?.warn(`[soft-delete-cleanup] bytes of fileRef ${row.id} not fully deleted, row kept`);
+            }
+            catch (err) {
+                log?.warn(`[soft-delete-cleanup] bytes of fileRef ${row.id} not deleted, row kept: ${err instanceof Error ? err.message : String(err)}`);
             }
-            log?.warn(`[soft-delete-cleanup] bytes of fileRef ${row.id} not fully deleted, row kept`);
-        }
-        catch (err) {
-            log?.warn(`[soft-delete-cleanup] bytes of fileRef ${row.id} not deleted, row kept: ${err instanceof Error ? err.message : String(err)}`);
         }
+        if (purgedIds.length > 0)
+            await deleteMany(db, table, { ...where, id: { in: purgedIds } });
     }
-    if (purgedIds.length > 0)
-        await deleteMany(db, table, { ...where, id: { in: purgedIds } });
 }

package/dist/i18n/index.d.ts

@@ -1,5 +1,5 @@
 import type { Registry } from "../engine/types/index.js";
-export { hasMailTranslations, mailT, registerMailTranslations, resolveMailLocale, } from "./mail-registry.js";
+export { hasMailTranslationKey, hasMailTranslations, listMailLocales, mailT, registerMailTranslations, resolveMailLocale, } from "./mail-registry.js";
 export { canonicalizeLocaleTag, DEFAULT_LOCALE, isValidLocaleTag, pickAcceptLanguage, resolveHeaderLocale, } from "./request-locale.js";
 export { SETTINGS_HUB_I18N } from "./settings-hub-keys.js";
 export type I18nOptions = {

package/dist/i18n/index.js

@@ -1,5 +1,5 @@
 import { resolveTranslationValue } from "../ui-types/plural.js";
-export { hasMailTranslations, mailT, registerMailTranslations, resolveMailLocale, } from "./mail-registry.js";
+export { hasMailTranslationKey, hasMailTranslations, listMailLocales, mailT, registerMailTranslations, resolveMailLocale, } from "./mail-registry.js";
 export { canonicalizeLocaleTag, DEFAULT_LOCALE, isValidLocaleTag, pickAcceptLanguage, resolveHeaderLocale, } from "./request-locale.js";
 export { SETTINGS_HUB_I18N } from "./settings-hub-keys.js";
 export function createI18n(registry, options) {

package/dist/i18n/mail-registry.d.ts

@@ -1,5 +1,7 @@
 import { type TranslationValue } from "../ui-types/plural.js";
 export declare function registerMailTranslations(locale: string, bundle: Readonly<Record<string, TranslationValue>>): void;
+export declare function listMailLocales(): readonly string[];
+export declare function hasMailTranslationKey(locale: string, key: string): boolean;
 export declare function hasMailTranslations(locale: string): boolean;
 export declare function mailT(locale: string, key: string, params?: Readonly<Record<string, string | number>>): string;
 /** Locale key mailT would actually use (exact → root → en). Use for appUrl

package/dist/i18n/mail-registry.js

@@ -4,6 +4,13 @@ export function registerMailTranslations(locale, bundle) {
     const prev = tables.get(locale) ?? {};
     tables.set(locale, { ...prev, ...bundle });
 }
+export function listMailLocales() {
+    return [...tables.keys()];
+}
+// Own key only, without the root/en fallback mailT applies.
+export function hasMailTranslationKey(locale, key) {
+    return tables.get(locale)?.[key] !== undefined;
+}
 export function hasMailTranslations(locale) {
     const root = locale.split("-")[0] ?? locale;
     return tables.has(locale) || tables.has(root);

package/dist/jobs/index.d.ts

@@ -1,2 +1,2 @@
-export type { JobLogEntry, JobMeta, JobOutcomeMeta, JobQueuedMeta, JobRunner, JobRunnerOptions, JobSubjectValue, } from "./job-runner.js";
+export type { JobDroppedMeta, JobLogEntry, JobMeta, JobOutcomeMeta, JobQueuedMeta, JobRunner, JobRunnerOptions, JobSubjectValue, } from "./job-runner.js";
 export { createJobRunner, serializeJobSubject } from "./job-runner.js";

package/dist/jobs/job-runner.d.ts

@@ -29,6 +29,9 @@ export type JobQueuedMeta = {
     readonly tenantId: string;
     readonly subject: string | null;
 };
+export type JobDroppedMeta = {
+    readonly tenantId: string;
+};
 export type JobOutcomeMeta = {
     readonly tenantId: string;
     readonly finalAttempt: boolean;
@@ -66,6 +69,6 @@ export type JobRunnerOptions = {
     onJobComplete?: (jobName: string, jobId: string, duration: number, logs: JobLogEntry[], outcome?: JobOutcomeMeta) => void;
     onJobFailed?: (jobName: string, jobId: string, error: string, logs: JobLogEntry[], outcome?: JobOutcomeMeta) => void;
     onJobQueued?: (jobName: string, jobId: string, meta: JobQueuedMeta) => void;
-    onJobDropped?: (jobName: string, jobId: string) => void;
+    onJobDropped?: (jobName: string, jobId: string, meta: JobDroppedMeta) => void;
 };
 export declare function createJobRunner(options: JobRunnerOptions): JobRunner;