@cosmicdrift/kumiko-samples 0.392.2 → 0.394.0

package/packages/bundled-features/src/inbound-mail-foundation/quarantine-retry.ts

@@ -0,0 +1,137 @@
+// Quarantine retry: mails flagged by retry-quarantined-message are loaded from the provider again
+// after a successful sync. A mail that now goes through leaves the quarantine; one that fails again
+// stays in it (flag reset, so it is not retried on every tick). An outage (provider, KMS, file
+// storage) is not the mail's failure: the flag stays and the retry runs after the recovery.
+
+import { ENCRYPTION_UNAVAILABLE_CODE } from "@cosmicdrift/kumiko-framework/crypto";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { deleteMany, selectMany, updateMany } from "@cosmicdrift/kumiko-framework/db";
+import { errorCodeOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { inboundMessageAggregateId } from "./aggregate-id.ts";
+import { InboundMailFoundationHandlers } from "./constants.ts";
+import { describeError } from "./describe-error.ts";
+import { isFileStorageWriteFailure } from "./file-storage-failure.ts";
+import { clearIngestFailures } from "./ingest-failures.ts";
+import { ingestPayloadOf } from "./ingest-payload.ts";
+import {
+  type NormalizedInboundMessage,
+  normalizeRawInboundMessage,
+} from "./normalize-inbound-message.ts";
+import { inboundMessagesProjectionTable } from "./projection.ts";
+import { quarantineTable } from "./quarantine-entities.ts";
+import type { DispatchWrite } from "./supervisor-ingest.ts";
+import type { InboundMailContext, InboundMailProviderPlugin, MailAccountRecord } from "./types.ts";
+
+const RETRY_BUDGET_PER_TICK = 20;
+
+function isOutageFailure(error: unknown): boolean {
+  return isFileStorageWriteFailure(error) || errorCodeOf(error) === ENCRYPTION_UNAVAILABLE_CODE;
+}
+
+// A mail with a header-only entry gets its content attached, one without any entry is ingested in full.
+function reloadMessage(
+  dispatchWrite: DispatchWrite,
+  account: MailAccountRecord,
+  msg: NormalizedInboundMessage,
+  hasHeaderRow: boolean,
+): ReturnType<DispatchWrite> {
+  return hasHeaderRow
+    ? dispatchWrite({
+        handlerQn: InboundMailFoundationHandlers.attachMessageContent,
+        tenantId: account.tenantId,
+        payload: {
+          accountId: account.id,
+          providerMessageId: msg.providerMessageId,
+          outcome: "fetched",
+          bodyText: msg.bodyText,
+          bodyTextTruncated: msg.bodyTextTruncated,
+          ...(msg.rawMime != null && { rawMime: msg.rawMime }),
+          ...(msg.bodyHtml !== null && { bodyHtml: msg.bodyHtml }),
+          attachments: msg.attachments,
+          skippedAttachments: msg.skippedAttachments,
+        },
+      })
+    : dispatchWrite({
+        handlerQn: InboundMailFoundationHandlers.ingestMessage,
+        tenantId: account.tenantId,
+        payload: ingestPayloadOf(account, msg, {
+          providerCursor: "quarantine-retry",
+          bodyRef: "",
+        }),
+      });
+}
+
+export async function retryQuarantinedMessages(args: {
+  readonly db: DbConnection;
+  readonly dispatchWrite: DispatchWrite;
+  readonly providerCtx: InboundMailContext;
+  readonly account: MailAccountRecord;
+  readonly plugin: InboundMailProviderPlugin;
+  readonly accessToken?: string | undefined;
+  readonly signal?: AbortSignal | undefined;
+  readonly log: (line: string) => void;
+}): Promise<void> {
+  const { db, account, plugin, dispatchWrite, log } = args;
+  // skip: the provider cannot reload single mails.
+  if (!plugin.fetchContent) return;
+  const requested = await selectMany<{ providerMessageId: string }>(
+    db,
+    quarantineTable,
+    { accountId: account.id, retryRequestedAt: { ne: null } },
+    { fields: ["providerMessageId"], limit: RETRY_BUDGET_PER_TICK },
+  );
+  // skip: nothing was asked for.
+  if (requested.length === 0) return;
+  const ids = requested.map((row) => row.providerMessageId);
+  const done = new Set<string>();
+  const held = new Set<string>();
+  try {
+    const result = await plugin.fetchContent(args.providerCtx, account, ids, {
+      ...(args.accessToken !== undefined && { accessToken: args.accessToken }),
+      ...(args.signal !== undefined && { signal: args.signal }),
+    });
+    const existing = new Set(
+      (
+        await selectMany<{ id: string }>(
+          db,
+          inboundMessagesProjectionTable,
+          {
+            tenantId: account.tenantId,
+            id: { in: ids.map((id) => inboundMessageAggregateId(account.id, id)) },
+          },
+          { fields: ["id"] },
+        )
+      ).map((row) => row.id),
+    );
+    for (const raw of result.messages) {
+      const msg = normalizeRawInboundMessage(raw);
+      const hasHeaderRow = existing.has(
+        inboundMessageAggregateId(account.id, msg.providerMessageId),
+      );
+      const outcome = await reloadMessage(dispatchWrite, account, msg, hasHeaderRow);
+      if (outcome.isSuccess) done.add(msg.providerMessageId);
+      else if (isOutageFailure(outcome.error)) held.add(msg.providerMessageId);
+    }
+  } catch (err) {
+    log(`inbound-mail: account ${account.id} quarantine retry failed: ${describeError(err)}`);
+    for (const id of ids) held.add(id);
+  }
+  const doneIds = [...done];
+  if (doneIds.length > 0) {
+    await deleteMany(db, quarantineTable, {
+      accountId: account.id,
+      providerMessageId: { in: doneIds },
+    });
+    await clearIngestFailures(db, account.id, doneIds);
+  }
+  const failed = ids.filter((id) => !done.has(id) && !held.has(id));
+  if (failed.length > 0) {
+    await updateMany(
+      db,
+      quarantineTable,
+      { retryRequestedAt: null },
+      { accountId: account.id, providerMessageId: { in: failed } },
+    );
+    log(`inbound-mail: account ${account.id} ${failed.length} quarantined mail(s) still failing`);
+  }
+}

package/packages/bundled-features/src/inbound-mail-foundation/quarantine-screens.ts

@@ -0,0 +1,66 @@
+import {
+  i18nKey,
+  MAX_LIST_LIMIT,
+  type ProjectionListScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InboundMailFoundationHandlers, InboundMailFoundationQueries } from "./constants.ts";
+import type { InboundMailRoles } from "./mail-roles.ts";
+import { MAIL_QUARANTINE_SCREEN_ID } from "./screens.ts";
+
+export const QUARANTINE_REASON_OPTION_KEY_PREFIX = "inboundMail.quarantine.reason.";
+
+// Same roles as the handlers; the bound query shows each caller only the mailboxes they may manage.
+// dormant: reached through the row action "Quarantine" of the mailbox list.
+export function createMailQuarantineScreen({
+  memberRoles,
+}: InboundMailRoles): ProjectionListScreenDefinition {
+  return {
+    id: MAIL_QUARANTINE_SCREEN_ID,
+    type: "projectionList",
+    agent: { expose: false },
+    query: InboundMailFoundationQueries.listQuarantine,
+    pagination: false,
+    pageSize: MAX_LIST_LIMIT,
+    columns: [
+      { field: "sender", label: i18nKey("inboundMail.quarantine.col.sender"), sortable: false },
+      { field: "subject", label: i18nKey("inboundMail.quarantine.col.subject"), sortable: false },
+      {
+        field: "reason",
+        label: i18nKey("inboundMail.quarantine.col.reason"),
+        sortable: false,
+        renderer: { format: "enumOption", keyPrefix: QUARANTINE_REASON_OPTION_KEY_PREFIX },
+      },
+      {
+        field: "accountName",
+        label: i18nKey("inboundMail.quarantine.col.mailbox"),
+        sortable: false,
+        hideOnNarrow: true,
+      },
+      {
+        field: "quarantinedAt",
+        label: i18nKey("inboundMail.quarantine.col.date"),
+        sortable: false,
+        renderer: { format: "timestamp" },
+      },
+    ],
+    rowActions: [
+      {
+        kind: "writeHandler",
+        id: "retry",
+        label: i18nKey("inboundMail.quarantine.retry"),
+        handler: InboundMailFoundationHandlers.retryQuarantinedMessage,
+        payload: { map: { accountId: "accountId", providerMessageId: "providerMessageId" } },
+        visible: { field: "retryRequestedAt", eq: null },
+      },
+      {
+        kind: "writeHandler",
+        id: "acknowledge",
+        label: i18nKey("inboundMail.quarantine.acknowledge"),
+        handler: InboundMailFoundationHandlers.acknowledgeQuarantine,
+        payload: { map: { accountId: "accountId", providerMessageId: "providerMessageId" } },
+      },
+    ],
+    access: { roles: [...memberRoles] },
+    dormant: true,
+  };
+}

package/packages/bundled-features/src/inbound-mail-foundation/quarantine.ts

@@ -0,0 +1,72 @@
+// Quarantine of poison mails: messages the supervisor cannot ingest (unparseable MIME, payload the
+// ingest handler rejects for good, or repeated hard failures). A quarantined id counts as seen, so the
+// cursor moves on instead of retrying the same mail forever. Rows carry ids only, no mail content.
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { fetchOne, insertOne, selectMany } from "@cosmicdrift/kumiko-framework/db";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { type QuarantineReasonCode, quarantineTable } from "./quarantine-entities.ts";
+
+const LOOKUP_CHUNK_SIZE = 1000;
+export const QUARANTINE_ACKNOWLEDGED_RETENTION_DAYS = 90;
+
+type QuarantineTarget = {
+  readonly tenantId: string;
+  readonly accountId: string;
+  readonly providerMessageId: string;
+};
+
+/** Returns true when a new row was written, false when the message was already quarantined. */
+export async function quarantineMessage(
+  db: DbConnection,
+  target: QuarantineTarget,
+  reasonCode: QuarantineReasonCode,
+): Promise<boolean> {
+  const key = { accountId: target.accountId, providerMessageId: target.providerMessageId };
+  if (await fetchOne<{ id: string }>(db, quarantineTable, key)) return false;
+  try {
+    await insertOne(db, quarantineTable, {
+      id: crypto.randomUUID(),
+      tenantId: target.tenantId,
+      ...key,
+      reasonCode,
+      quarantinedAt: Temporal.Now.instant().toString(),
+    });
+    return true;
+  } catch (err) {
+    // A concurrent worker quarantined the same message between the check and the insert.
+    if (await fetchOne<{ id: string }>(db, quarantineTable, key)) return false;
+    throw err;
+  }
+}
+
+export async function quarantinedMessageIds(
+  db: DbConnection,
+  accountId: string,
+  providerMessageIds: readonly string[],
+): Promise<ReadonlySet<string>> {
+  const ids = new Set<string>();
+  for (let start = 0; start < providerMessageIds.length; start += LOOKUP_CHUNK_SIZE) {
+    const rows = await selectMany<{ providerMessageId: string }>(
+      db,
+      quarantineTable,
+      {
+        accountId,
+        providerMessageId: { in: providerMessageIds.slice(start, start + LOOKUP_CHUNK_SIZE) },
+      },
+      { fields: ["providerMessageId"] },
+    );
+    for (const row of rows) ids.add(row.providerMessageId);
+  }
+  return ids;
+}
+
+export async function hasOpenQuarantine(db: DbConnection, accountId: string): Promise<boolean> {
+  const rows = await selectMany<{ id: string }>(
+    db,
+    quarantineTable,
+    { accountId, acknowledgedAt: null },
+    { fields: ["id"], limit: 1 },
+  );
+  return rows.length > 0;
+}

package/packages/bundled-features/src/inbound-mail-foundation/retention-job.ts

@@ -0,0 +1,78 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { FeatureRegistrar } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createFileProviderForTenant,
+  deleteFileRefsBoundToRecord,
+  type FileStorageProvider,
+} from "@cosmicdrift/kumiko-framework/files";
+import { INBOUND_MESSAGE_AGGREGATE_TYPE } from "./events.ts";
+import { runInboundMailRetention } from "./retention-sweep.ts";
+
+export function registerInboundMailRetentionJob(r: FeatureRegistrar<"inbound-mail-foundation">) {
+  // Data-Retention — perTenant fan-out (one run per tenant, like
+  // data-retention:retention-cleanup): runInboundMailRetention's raw query
+  // helpers need the unfiltered runner, so the handler declares escapeHatch
+  // and reaches for ctx.db.unsafeRaw(). Without this cron, read_inbound_messages
+  // + the bodies grow unbounded (GDPR Art. 5).
+  const INBOUND_MAIL_RETENTION_REASON =
+    "inbound-mail retention runs raw deletes; every statement filters by this run's tenantId";
+  r.job({
+    name: "inbound-mail-retention",
+    trigger: { cron: "0 3 * * *" },
+    perTenant: true,
+    concurrency: "skip",
+    escapeHatch: { reason: INBOUND_MAIL_RETENTION_REASON },
+    handler: async (_payload, ctx) => {
+      if (!ctx.registry) {
+        throw new Error("inbound-mail-retention: ctx.registry required (JobContext incomplete)");
+      }
+      const tenantId = ctx.systemUser?.tenantId ?? ctx._tenantId;
+      if (tenantId === undefined) {
+        // skip: cron fired without a perTenant fan-out tenant — nothing scoped
+        return;
+      }
+      const T = (await import("@cosmicdrift/kumiko-framework/time")).getTemporal();
+      const retentionDb = ctx.db.unsafeRaw() as DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
+
+      // Original (.eml/.html) objects live in file-foundation; the provider is lazy and
+      // memoized so a tenant without purgeable mails never builds it.
+      let providerPromise: Promise<FileStorageProvider> | null = null;
+      const deleteBodyObject = async (bodyRef: string): Promise<void> => {
+        if (!providerPromise) {
+          providerPromise = createFileProviderForTenant(
+            { config: ctx.config, registry: ctx.registry, secrets: ctx.services.secrets },
+            tenantId,
+          );
+        }
+        const provider = await providerPromise;
+        await provider.delete(bodyRef);
+      };
+
+      const { systemUser } = ctx;
+      const deleteAttachments = systemUser
+        ? async (messageId: string): Promise<void> => {
+            await deleteFileRefsBoundToRecord({
+              db: ctx.db,
+              user: systemUser,
+              entityType: INBOUND_MESSAGE_AGGREGATE_TYPE,
+              entityId: messageId,
+            });
+          }
+        : undefined;
+
+      const report = await runInboundMailRetention({
+        db: retentionDb,
+        tenantId,
+        now: T.Now.instant(),
+        deleteBodyObject,
+        ...(deleteAttachments ? { deleteAttachments } : {}),
+      });
+      if (report.bodyObjectErrors > 0) {
+        // biome-ignore lint/suspicious/noConsole: operator-visibility for failed body deletes
+        console.warn(
+          `[inbound-mail-foundation:inbound-mail-retention] tenant=${tenantId} bodyObjectErrors=${report.bodyObjectErrors}`,
+        );
+      }
+    },
+  });
+}

package/packages/bundled-features/src/inbound-mail-foundation/retention-sweep.ts

@@ -20,6 +20,18 @@
 //     directly through the table's tenant_id column (table-builder convention),
 //     without an Account join.
 //
+//   store_mail_ingest_failures (unmanaged): counters of mails the ingest could not take. A counter
+//     whose mail never failed again (it went through or was quarantined, which clear it) is stale
+//     after the seen retention.
+//
+//   store_mail_quarantine (unmanaged): acknowledged entries are purged after
+//     QUARANTINE_ACKNOWLEDGED_RETENTION_DAYS; unacknowledged ones stay, they
+//     keep the mailbox flagged until someone looked at them.
+//
+// Attachments are fileRefs bound to the mail row: they go with it (soft delete through the
+// fileRef executor; the generic soft-delete cleanup removes the bytes). A failure keeps the Row
+// for the next sweep, like a failed body delete.
+//
 // LIMITATION: the PII in the message events remains decryptable under the
 // TENANT subject key—per-Row retention does not shred a key. Actual Art.-17
 // erasure of event payloads happens only during tenant-destroy (key erasure).
@@ -35,7 +47,10 @@ import {
 import type { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import { seenMessageTable } from "./entities.ts";
 import { INBOUND_MESSAGE_AGGREGATE_TYPE } from "./events.ts";
+import { ingestFailureTable } from "./ingest-failures.ts";
 import { inboundMessagesProjectionTable } from "./projection.ts";
+import { QUARANTINE_ACKNOWLEDGED_RETENTION_DAYS } from "./quarantine.ts";
+import { quarantineTable } from "./quarantine-entities.ts";
 
 // Provides Temporal.Instant without forcing the caller to obtain it from
 // globalThis (same pattern as data-retention/keep-for.ts).
@@ -59,6 +74,8 @@ export interface InboundRetentionArgs {
   /** Deletes a file-storage body object by bodyRef key. Wired lazily by the job
    * (createFileProviderForTenant); if absent, no body is deleted. */
   readonly deleteBodyObject?: (bodyRef: string) => Promise<void>;
+  /** Removes the fileRefs bound to an expired mail (its attachments); wired by the job. */
+  readonly deleteAttachments?: (messageId: string) => Promise<void>;
 }
 
 export interface InboundRetentionReport {
@@ -66,6 +83,8 @@ export interface InboundRetentionReport {
   readonly bodyObjectsDeleted: number;
   readonly bodyObjectErrors: number;
   readonly seenPurged: number;
+  readonly quarantinePurged: number;
+  readonly ingestFailuresPurged: number;
 }
 
 export async function runInboundMailRetention(
@@ -79,7 +98,20 @@ export async function runInboundMailRetention(
   const messages = await purgeExpiredMessages(args, messageCutoff);
   const seenPurged = await purgeExpiredSeenAnchors(args.db, args.tenantId, seenCutoff);
 
-  return { ...messages, seenPurged };
+  const quarantineCutoff = args.now.subtract({
+    hours: QUARANTINE_ACKNOWLEDGED_RETENTION_DAYS * 24,
+  });
+  const quarantinePurged = await deleteMany(args.db, quarantineTable, {
+    tenantId: args.tenantId,
+    acknowledgedAt: { lt: quarantineCutoff },
+  });
+
+  const ingestFailuresPurged = await deleteMany(args.db, ingestFailureTable, {
+    tenantId: args.tenantId,
+    lastFailedAt: { lt: seenCutoff },
+  });
+
+  return { ...messages, seenPurged, quarantinePurged, ingestFailuresPurged };
 }
 
 type ExpiredMessageRow = { readonly id: string; readonly bodyRef: string | null };
@@ -87,7 +119,9 @@ type ExpiredMessageRow = { readonly id: string; readonly bodyRef: string | null
 async function purgeExpiredMessages(
   args: InboundRetentionArgs,
   cutoff: Instant,
-): Promise<Omit<InboundRetentionReport, "seenPurged">> {
+): Promise<
+  Omit<InboundRetentionReport, "seenPurged" | "quarantinePurged" | "ingestFailuresPurged">
+> {
   let messagesPurged = 0;
   let bodyObjectsDeleted = 0;
   let bodyObjectErrors = 0;
@@ -125,15 +159,16 @@ async function purgeExpiredMessages(
         archivedBy: ARCHIVED_BY,
         reason: REASON,
       });
-      if (row.bodyRef && args.deleteBodyObject) {
-        try {
+      try {
+        if (row.bodyRef && args.deleteBodyObject) {
           await args.deleteBodyObject(row.bodyRef);
           bodyObjectsDeleted++;
-        } catch {
-          bodyObjectErrors++;
-          failedIds.add(row.id);
-          continue;
         }
+        await args.deleteAttachments?.(row.id);
+      } catch {
+        bodyObjectErrors++;
+        failedIds.add(row.id);
+        continue;
       }
       ids.push(row.id);
     }