@k2b/cloud 0.27.0 → 0.29.0

package/src/services/notifications/quiet.ts

@@ -0,0 +1,153 @@
+import { dates } from "@k2b/stdlib";
+import { sql } from "bun";
+import type { MutationResult } from "../../contracts/shared";
+import {
+  NOTIFICATION_DO_NOT_DISTURB_MAX_DAYS,
+  type NotificationQuietHours,
+  NotificationQuietHoursSchema,
+  type NotificationQuietSettings,
+  type NotificationQuietState,
+  type UpdateNotificationQuietSettings,
+} from "../../contracts/user-notifications";
+import { normalizeTimeZone } from "../../shared/time";
+
+const DAY_MS = 24 * 60 * 60_000;
+/** How far ahead `until` looks. A schedule that stays quiet for longer has no end worth naming. */
+const LOOKAHEAD_DAYS = 8;
+
+type QuietInput = { doNotDisturbUntil: Date | null; quietHours: NotificationQuietHours };
+type Interval = { start: number; end: number };
+
+const pad2 = (value: number): string => String(value).padStart(2, "0");
+
+/**
+ * The quiet-hours intervals that touch `[from - 1 day, from + days]`, as instants. Each period belongs to the
+ * local day it starts on; wall-clock times are converted per date, so a period keeps its local times across
+ * daylight-saving changes. A time inside a skipped hour moves forward like the clock does. In a repeated hour a
+ * start takes the first occurrence and an end the second, so the period covers every instant the clock shows a
+ * time inside it.
+ */
+const quietHourIntervals = (hours: NotificationQuietHours, from: number, days: number): Interval[] => {
+  if (hours.periods.length === 0) return [];
+  const timeZone = normalizeTimeZone(hours.timeZone);
+  const [localDate = ""] = dates.instantToZonedInput(new Date(from), timeZone).split("T");
+  const [year, month, day] = localDate.split("-").map(Number) as [number, number, number];
+  const instant = (offset: number, time: string, disambiguation: "compatible" | "later"): number => {
+    const date = new Date(Date.UTC(year, month - 1, day + offset));
+    const wallClock = `${date.getUTCFullYear()}-${pad2(date.getUTCMonth() + 1)}-${pad2(date.getUTCDate())}T${time}`;
+    return Date.parse(dates.zonedDateTimeToInstant(wallClock, timeZone, { disambiguation }));
+  };
+  const intervals: Interval[] = [];
+  for (let offset = -1; offset <= days; offset += 1) {
+    const isoWeekday = new Date(Date.UTC(year, month - 1, day + offset)).getUTCDay() || 7;
+    for (const period of hours.periods) {
+      if (!period.days.includes(isoWeekday)) continue;
+      const start = instant(offset, period.start, "compatible");
+      const end = instant(period.end > period.start ? offset : offset + 1, period.end, "later");
+      if (end > start) intervals.push({ start, end });
+    }
+  }
+  return intervals;
+};
+
+/**
+ * Follow quiet hours from `from` across overlapping and adjoining periods. Returns `from` when it is not quiet
+ * and null when the quiet time does not end within the lookahead, for example with every day fully quiet.
+ */
+const quietHoursEnd = (hours: NotificationQuietHours, from: number): number | null => {
+  const intervals = quietHourIntervals(hours, from, LOOKAHEAD_DAYS);
+  const horizon = from + LOOKAHEAD_DAYS * DAY_MS;
+  let until = from;
+  for (;;) {
+    const ends = intervals.filter((interval) => interval.start <= until && until < interval.end).map((interval) => interval.end);
+    if (ends.length === 0) return until;
+    until = Math.max(...ends);
+    if (until > horizon) return null;
+  }
+};
+
+/**
+ * Whether browser notifications are held back at `now`, why, and until when. Do not disturb names the reason
+ * while it lasts; `until` also covers quiet hours that continue when it ends.
+ */
+export const notificationQuietState = (input: QuietInput, now: Date = new Date()): NotificationQuietState => {
+  const at = now.getTime();
+  const iso = (instant: number | null) => (instant === null ? null : new Date(instant).toISOString());
+  const doNotDisturbUntil = input.doNotDisturbUntil?.getTime() ?? null;
+  if (doNotDisturbUntil !== null && doNotDisturbUntil > at) {
+    return { active: true, reason: "doNotDisturb", until: iso(quietHoursEnd(input.quietHours, doNotDisturbUntil)), nextStart: null };
+  }
+  const until = quietHoursEnd(input.quietHours, at);
+  if (until !== at) return { active: true, reason: "quietHours", until: iso(until), nextStart: null };
+  const starts = quietHourIntervals(input.quietHours, at, LOOKAHEAD_DAYS)
+    .map((interval) => interval.start)
+    .filter((start) => start > at && start <= at + LOOKAHEAD_DAYS * DAY_MS);
+  return { active: false, reason: null, until: null, nextStart: iso(starts.length > 0 ? Math.min(...starts) : null) };
+};
+
+type QuietRow = { do_not_disturb_until: Date | null; time_zone: string; periods: unknown };
+
+/** Parse a stored row defensively: a schedule that no longer validates silences nothing. */
+export const quietInputFromRow = (row: QuietRow | undefined, fallbackTimeZone = "UTC"): QuietInput => {
+  const parsed = row ? NotificationQuietHoursSchema.safeParse({ timeZone: row.time_zone, periods: row.periods }) : null;
+  return {
+    doNotDisturbUntil: row?.do_not_disturb_until ?? null,
+    quietHours: parsed?.success ? parsed.data : { timeZone: normalizeTimeZone(row?.time_zone ?? fallbackTimeZone), periods: [] },
+  };
+};
+
+const toSettings = (input: QuietInput, now = new Date()): NotificationQuietSettings => ({
+  doNotDisturbUntil:
+    input.doNotDisturbUntil && input.doNotDisturbUntil.getTime() > now.getTime() ? input.doNotDisturbUntil.toISOString() : null,
+  quietHours: input.quietHours,
+  state: notificationQuietState(input, now),
+});
+
+/** The person's quiet settings and current state. Without saved quiet hours, `fallbackTimeZone` is offered. */
+const getQuietSettings = async (userId: string, fallbackTimeZone = "UTC"): Promise<NotificationQuietSettings> => {
+  const [row] = await sql<QuietRow[]>`
+    SELECT do_not_disturb_until, time_zone, periods FROM notifications.quiet_times WHERE user_id = ${userId}::uuid
+  `;
+  return toSettings(quietInputFromRow(row, fallbackTimeZone));
+};
+
+const updateQuietSettings = async (config: {
+  userId: string;
+  update: UpdateNotificationQuietSettings;
+  fallbackTimeZone?: string;
+}): Promise<MutationResult<NotificationQuietSettings>> => {
+  const { doNotDisturbUntil, quietHours } = config.update;
+  const until = doNotDisturbUntil ? new Date(doNotDisturbUntil) : null;
+  if (until && until.getTime() <= Date.now()) {
+    return { ok: false, error: "Do not disturb must end in the future", status: 400 };
+  }
+  if (until && until.getTime() > Date.now() + NOTIFICATION_DO_NOT_DISTURB_MAX_DAYS * DAY_MS) {
+    return { ok: false, error: "Do not disturb must end within a year", status: 400 };
+  }
+  const timeZone = normalizeTimeZone(quietHours?.timeZone ?? config.fallbackTimeZone);
+  const periods = quietHours ? JSON.stringify(quietHours.periods) : "[]";
+  await sql`
+    INSERT INTO notifications.quiet_times (user_id, do_not_disturb_until, time_zone, periods, updated_at)
+    VALUES (${config.userId}::uuid, ${until}::timestamptz, ${timeZone}, (${periods}::text)::jsonb, now())
+    ON CONFLICT (user_id) DO UPDATE SET
+      do_not_disturb_until = CASE WHEN ${doNotDisturbUntil !== undefined} THEN EXCLUDED.do_not_disturb_until
+        ELSE notifications.quiet_times.do_not_disturb_until END,
+      time_zone = CASE WHEN ${quietHours !== undefined} THEN EXCLUDED.time_zone ELSE notifications.quiet_times.time_zone END,
+      periods = CASE WHEN ${quietHours !== undefined} THEN EXCLUDED.periods ELSE notifications.quiet_times.periods END,
+      updated_at = now()
+  `;
+  return { ok: true, data: await getQuietSettings(config.userId, config.fallbackTimeZone) };
+};
+
+/** The quiet state of an event's recipient, or null when the recipient is not a Cloud user. */
+export const quietStateForEvent = async (eventId: string, now = new Date()): Promise<NotificationQuietState | null> => {
+  const [row] = await sql<QuietRow[]>`
+    SELECT q.do_not_disturb_until, q.time_zone, q.periods
+    FROM notifications.events e
+    JOIN notifications.quiet_times q ON q.user_id = e.recipient_user_id
+    WHERE e.id = ${eventId}::uuid
+  `;
+  return row ? notificationQuietState(quietInputFromRow(row), now) : null;
+};
+
+export const userQuietTimes = { get: getQuietSettings, update: updateQuietSettings } as const;

package/src/services/notifications/runtime.ts

@@ -3,7 +3,7 @@ import { lazySync } from "../../_internal/process-sync";
 import { logger, trace } from "../logging";
 import { createRuntimeLifecycle, createRuntimeTaskTracker, stopRuntimeJobs } from "../runtime-lifecycle";
 
-import { processNotificationDelivery, recoverNotificationDeliveries } from "./dispatcher";
+import { processNotificationDelivery, reconcileNotificationMessages, recoverNotificationDeliveries } from "./dispatcher";
 
 type DeliveryMessage = { deliveryId: string };
 
@@ -58,10 +58,10 @@ const handleDelivery = async (context: JobContext<DeliveryMessage>): Promise<voi
       spanKey: trace.syncSpanKey("job", "cloud-notification-deliveries", context.jobId),
       attributes: { "cloud.notification.delivery_id": context.input.deliveryId },
     },
-    () => processNotificationDelivery(context.input.deliveryId),
+    () => processNotificationDelivery(context.input.deliveryId, context.signal),
   );
   if (result.activatedIds?.length) await enqueueNotificationDeliveries(result.activatedIds);
-  if (result.status === "retry") context.resubmit({ delayMs: result.retryAfterMs });
+  if (result.status === "retry" || result.status === "pending") context.resubmit({ delayMs: result.retryAfterMs });
 };
 
 type RuntimeOptions = { concurrency?: number; recoveryIntervalMs?: number };
@@ -79,6 +79,12 @@ const recover = (): Promise<void> => {
       } catch (error) {
         log.error("Delivery recovery failed", { error: error instanceof Error ? error.message : String(error) });
       }
+      // Message history must never hold back delivery recovery.
+      try {
+        await reconcileNotificationMessages();
+      } catch (error) {
+        log.error("Notification message reconciliation failed", { error: error instanceof Error ? error.message : String(error) });
+      }
     }) ?? Promise.resolve()
   ).finally(() => {
     recovery = undefined;

package/src/services/notifications/user.ts

@@ -14,6 +14,7 @@ import type {
 import { normalizeLocale } from "../../shared/locale";
 import { toPgTextArray } from "../postgres";
 import { listNotificationChannels } from "./channels";
+import { userQuietTimes } from "./quiet";
 
 type PreferenceRow = {
   id: string;
@@ -164,6 +165,10 @@ const publicDeliveryError = (code: string | null, status: NotificationDeliverySt
       return { code, message: "This delivery channel is currently unavailable." };
     case "no_endpoint":
       return { code, message: "No registered destination is available for this channel." };
+    case "do_not_disturb":
+      return { code, message: "Held back because do not disturb was on." };
+    case "quiet_hours":
+      return { code, message: "Held back during your quiet hours." };
     case "fallback_not_needed":
       return { code, message: "Another preferred channel delivered this notification." };
     case "lease_recovered":
@@ -245,4 +250,5 @@ const listHistory = async (config: {
 export const userNotifications = {
   preferences: { list: listPreferences, set: setPreference, reset: resetPreference },
   history: { list: listHistory },
+  quiet: userQuietTimes,
 } as const;

package/src/services/outgoing-mail/admin.ts

@@ -0,0 +1,84 @@
+import { sql } from "bun";
+import {
+  type AdminMailFilter,
+  type AdminMailRecord,
+  AdminMailRecordSchema,
+  type MailPage,
+  type MailPageParams,
+} from "../../contracts/outgoing-mail";
+import { audit } from "../audit";
+import { cleanupMailAttachments, publishMailSettled } from "./dispatcher";
+import { adminMessageRecord, type MessageRow, outgoingMailMessages } from "./messages";
+import { type MailAuditContext, OutgoingMailError } from "./store";
+
+const get = async (id: string): Promise<AdminMailRecord> => {
+  const record = await outgoingMailMessages.metadata(id);
+  if (!record) throw new OutgoingMailError("message_unknown", "Outgoing mail message does not exist.", 404);
+  return record;
+};
+const cancel = async (id: string, context: MailAuditContext): Promise<AdminMailRecord> => {
+  const row = await sql.begin(async (tx) => {
+    const [row] = await tx<MessageRow[]>`UPDATE outgoing_mail.messages SET status = 'cancelled', error_code = 'cancelled_by_admin',
+      error_message = 'Cancelled by an administrator.', next_attempt_at = NULL, updated_at = now() WHERE id = ${id}::uuid AND status = 'queued'
+      RETURNING *, created_at::text AS cursor_created_at`;
+    if (!row) {
+      if (!(await outgoingMailMessages.read(id, undefined, tx)))
+        throw new OutgoingMailError("message_unknown", "Outgoing mail message does not exist.", 404);
+      throw new OutgoingMailError("message_not_queued", "Only queued outgoing mail can be cancelled.", 409);
+    }
+    await audit.record(
+      {
+        ...context,
+        action: "outgoing_mail.message.cancel",
+        outcome: "allowed",
+        target: { type: "outgoing_mail_message", id },
+        metadata: { appId: row.app_id, profile: row.profile_key },
+      },
+      tx,
+    );
+    return row;
+  });
+  await cleanupMailAttachments(id).catch(() => {});
+  await publishMailSettled(id).catch(() => {});
+  return adminMessageRecord(row);
+};
+export const outgoingMailLog = {
+  get,
+  cancel,
+  async cancelBatch(batchId: string, context: MailAuditContext): Promise<{ batchId: string; cancelled: number }> {
+    const cancelled = await sql.begin(async (tx) => {
+      const apps = await tx<{ app_id: string }[]>`SELECT DISTINCT app_id FROM outgoing_mail.messages WHERE batch_id = ${batchId}::uuid`;
+      if (!apps.length) throw new OutgoingMailError("batch_unknown", "Outgoing mail batch does not exist.", 404);
+      const rows = await tx<{ id: string }[]>`UPDATE outgoing_mail.messages SET status = 'cancelled', error_code = 'cancelled_by_admin',
+        error_message = 'Cancelled by an administrator.', next_attempt_at = NULL, updated_at = now()
+        WHERE batch_id = ${batchId}::uuid AND status = 'queued' RETURNING id`;
+      await audit.record(
+        {
+          ...context,
+          action: "outgoing_mail.batch.cancel",
+          outcome: "allowed",
+          target: { type: "outgoing_mail_batch", id: batchId },
+          metadata: { appIds: apps.map((row) => row.app_id), count: rows.length },
+        },
+        tx,
+      );
+      return rows;
+    });
+    for (const row of cancelled) {
+      await cleanupMailAttachments(row.id).catch(() => {});
+      await publishMailSettled(row.id).catch(() => {});
+    }
+    return { batchId, cancelled: cancelled.length };
+  },
+  content: outgoingMailMessages.content,
+  list: async (filter: AdminMailFilter, page: MailPageParams): Promise<MailPage<AdminMailRecord>> => {
+    const result = await outgoingMailMessages.list(filter, page, true);
+    return {
+      ...result,
+      items: result.items.map((item) => {
+        // The metadata mapper deliberately omits content; validate its public boundary.
+        return AdminMailRecordSchema.parse(item);
+      }),
+    };
+  },
+};

package/src/services/outgoing-mail/attachments.ts

@@ -0,0 +1,135 @@
+import { createHash } from "node:crypto";
+import { type ObjectRef, StoreFullError } from "@k2b/sync";
+import type { MailAttachment, MailRecord } from "../../contracts/outgoing-mail";
+import { OutgoingMailError } from "./store";
+import { mailAttachments } from "./sync";
+
+export type UploadedAttachments = { metadata: MailRecord["attachments"]; refs: ObjectRef[] };
+export const MAIL_ATTACHMENT_UPLOAD_MS = 60_000;
+export const cancelMailStreams = (attachments: unknown = []): void => {
+  if (!Array.isArray(attachments)) return;
+  for (const attachment of attachments) {
+    if (
+      attachment &&
+      typeof attachment === "object" &&
+      "content" in attachment &&
+      attachment.content instanceof ReadableStream &&
+      !attachment.content.locked
+    )
+      void attachment.content.cancel().catch(() => {});
+  }
+};
+export const deleteMailObjects = async (refs: readonly ObjectRef[]): Promise<void> => {
+  // Sequential deletion bounds load even for a large attachment collection.
+  for (const ref of refs) await mailAttachments().delete({ tenantId: ref.tenantId, key: ref.key });
+};
+const contentStream = (content: MailAttachment["content"]): ReadableStream<Uint8Array> => {
+  if (content instanceof ReadableStream) return content;
+  if (content instanceof Blob) return content.stream();
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(content);
+      controller.close();
+    },
+  });
+};
+export const uploadMailAttachments = async (
+  id: string,
+  attachments: readonly MailAttachment[],
+  limit: number,
+  uploadDeadline?: number,
+): Promise<UploadedAttachments> => {
+  const result: UploadedAttachments = { metadata: [], refs: [] };
+  let total = 0;
+  const controller = new AbortController();
+  // The caller's signal cancels the wait only. All attachments share one bounded upload.
+  if (uploadDeadline !== undefined && uploadDeadline <= Date.now() && attachments.length) {
+    cancelMailStreams(attachments);
+    throw new OutgoingMailError("mail_unavailable", "Attachment upload timed out.");
+  }
+  const timer = setTimeout(
+    () => controller.abort(new Error("Attachment upload timed out")),
+    uploadDeadline === undefined ? MAIL_ATTACHMENT_UPLOAD_MS : Math.max(0, uploadDeadline - Date.now()),
+  );
+  try {
+    for (const [index, attachment] of attachments.entries()) {
+      const hash = createHash("sha256");
+      let size = 0;
+      let exceeded = false;
+      const key = `${id}-${index}`;
+      try {
+        const stream = contentStream(attachment.content).pipeThrough(
+          new TransformStream<Uint8Array, Uint8Array>({
+            transform(chunk, output) {
+              total += chunk.byteLength;
+              size += chunk.byteLength;
+              if (total > limit) {
+                exceeded = true;
+                throw new OutgoingMailError("attachments_too_large", "Attachments exceed the profile's total byte limit.");
+              }
+              hash.update(chunk);
+              output.enqueue(chunk);
+            },
+          }),
+          { signal: controller.signal },
+        );
+        const ref = await mailAttachments().put({ tenantId: id, key, body: stream, signal: controller.signal });
+        result.refs.push(ref);
+        result.metadata.push({ filename: attachment.filename, contentType: attachment.contentType, size, sha256: hash.digest("hex") });
+      } catch (error) {
+        // A failed put can have written chunks before the final metadata was published.
+        await mailAttachments()
+          .delete({ tenantId: id, key })
+          .catch(() => {});
+        if (exceeded) throw new OutgoingMailError("attachments_too_large", "Attachments exceed the profile's total byte limit.");
+        if (
+          error instanceof StoreFullError ||
+          (error instanceof Error &&
+            /maximum bytes|maximum storage|insufficient (?:storage|resources)|storage resources|store.*full|resource limits exceeded/i.test(
+              error.message,
+            ))
+        )
+          throw new OutgoingMailError("attachment_storage_full", "Outgoing mail attachment storage is full.");
+        throw error;
+      }
+    }
+    return result;
+  } catch (error) {
+    await deleteMailObjects(result.refs).catch(() => {});
+    cancelMailStreams(attachments);
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    controller.abort();
+  }
+};
+
+/** Verify before SMTP DATA; open a second, verified stream for nodemailer. */
+export const verifyMailAttachment = async (
+  ref: ObjectRef,
+  metadata: MailRecord["attachments"][number],
+  signal?: AbortSignal,
+): Promise<void> => {
+  const object = await mailAttachments().get(ref, { signal });
+  if (!object) throw new OutgoingMailError("attachment_lost", "An outgoing mail attachment is missing or changed.");
+  const reader = object.body.getReader();
+  const hash = createHash("sha256");
+  let size = 0;
+  try {
+    while (true) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      size += chunk.value.byteLength;
+      if (size > metadata.size) throw new Error("Attachment size mismatch");
+      hash.update(chunk.value);
+    }
+    if (size !== metadata.size || hash.digest("hex") !== metadata.sha256) throw new Error("Attachment digest mismatch");
+  } catch (error) {
+    if (signal?.aborted || (error instanceof Error && /stalled|timeout|timed out|connection/i.test(error.message)))
+      throw new Error("Attachment verification was interrupted.");
+    throw new OutgoingMailError("attachment_lost", "An outgoing mail attachment is missing or changed.");
+  } finally {
+    await reader.cancel().catch(() => {});
+    reader.releaseLock();
+  }
+};

package/src/services/outgoing-mail/bulk.ts

@@ -0,0 +1,11 @@
+export const MAIL_RECOVERY_MS = 30_000;
+export const mailSlotMs = (pacePerMinute: number): number => 60_000 / pacePerMinute;
+export const mailBacklogFull = (queued: number, added: number, pacePerMinute: number): boolean =>
+  added > 0 && queued + added > pacePerMinute * 1440;
+export const mailBatchId = (proposed: string, rows: readonly ({ batch_id: string | null } | undefined)[]): string => {
+  const previous = rows[0]?.batch_id;
+  return previous && rows.every((row) => row?.batch_id === previous) ? previous : proposed;
+};
+// Later submissions join a coalesced continuation, so long backoffs must not hide fresh mail.
+export const mailNextDrainDelay = (now: number, slot: number, due: number): number =>
+  Math.min(MAIL_RECOVERY_MS, Math.max(0, Math.max(slot, due) - now));