@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/delivery/delivery-service.ts

@@ -0,0 +1,625 @@
+import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
+import type { DbConnection, DbRow } from "@cosmicdrift/kumiko-framework/db";
+import { createSystemDbView, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type {
+  EscapeHatchAuditSink,
+  NotifyPriority,
+  Registry,
+  TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createSystemUser } from "@cosmicdrift/kumiko-framework/engine";
+import type { JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
+import type { Logger } from "@cosmicdrift/kumiko-framework/logging";
+import { createEscapeHatchReporter } from "@cosmicdrift/kumiko-framework/pipeline";
+import { bridgeStub } from "@cosmicdrift/kumiko-framework/testing/handler-context";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import type { Redis } from "ioredis";
+import { hashUnsubscribeAddress } from "./address-opt-out.js";
+import { appendAttemptEvent, logAttempt } from "./attempt-log.js";
+import { buildChannelContext } from "./channel-context.js";
+import { DELIVERY_CHANNEL_EXTENSION, DeliveryJobs, deliveryPriorityRank } from "./constants.js";
+import { isAddressOptedOut } from "./db/queries/address-opt-outs.js";
+import { selectNotificationPreferences } from "./db/queries/preferences.js";
+import {
+  type ChannelContext,
+  type ChannelMessage,
+  type DeliveryChannel,
+  type DeliveryLogEntry,
+  type DeliveryService,
+  isDeliveryChannelPlugin,
+} from "./types.js";
+
+export type RateLimitConfig = {
+  readonly redis: Redis;
+  readonly maxPerHour: number; // per channel per tenant
+  readonly keyPrefix?: string;
+};
+
+export type KillSwitchResolver = (tenantId: TenantId, channelName: string) => Promise<boolean>;
+
+export type DeliveryServiceOptions = {
+  readonly db: DbConnection;
+  readonly registry: Registry;
+  readonly sseBroker?: SseBroker;
+  readonly channels: readonly DeliveryChannel[];
+  readonly tenantUserIdsQuery?: string;
+  readonly rateLimit?: RateLimitConfig;
+  readonly isChannelKilled?: KillSwitchResolver; // returns true if channel is disabled for tenant
+  // Redis handle used for idempotencyKey dedup. Falls back to rateLimit.redis.
+  // Must be present whenever callers rely on idempotencyKey, otherwise notify()
+  // throws at the callsite (silent no-op would be a correctness bug).
+  readonly idempotencyRedis?: Redis;
+  // Job runner for async (queued-mode) channels: email/push render+send run in
+  // the delivery.render → delivery.send jobs. When absent, queued channels fall
+  // back to synchronous inline delivery (job-less setups, unit tests).
+  readonly jobRunner?: JobRunner;
+  // Attributed escape-hatch audit for resolveUserIdsForTenant's ctx.systemDb —
+  // absent means an unattributed warn log (see fallbackEscapeHatchReporter).
+  readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
+  readonly log?: Logger;
+};
+
+// Build channel list from registry extension usages
+export function collectChannels(registry: Registry): DeliveryChannel[] {
+  const usages = registry.getExtensionUsages(DELIVERY_CHANNEL_EXTENSION);
+  return usages.map((usage) => {
+    if (!isDeliveryChannelPlugin(usage.options)) {
+      throw new Error(
+        `${DELIVERY_CHANNEL_EXTENSION} registration for "${usage.entityName}" has invalid options`,
+      );
+    }
+    return { name: usage.entityName, ...usage.options };
+  });
+}
+
+// `collectRenderers` entfernt 2026-05-19: notificationRenderer-Extension-Point
+// wurde nie konsumiert (channel-email nimmt renderer als Konstruktor-Option,
+// nicht aus Extension-Usages). Multi-Kind-Plugin-Pool lebt jetzt im
+// `renderer-foundation`-Bundle via `collectRendererPlugins`.
+
+export function createDeliveryService(options: DeliveryServiceOptions): DeliveryService {
+  const {
+    db,
+    registry,
+    sseBroker,
+    channels,
+    tenantUserIdsQuery,
+    rateLimit,
+    isChannelKilled,
+    idempotencyRedis,
+    jobRunner,
+    escapeHatchAuditSink,
+    log,
+  } = options;
+  const idemRedis = idempotencyRedis ?? rateLimit?.redis;
+
+  // Rate limit check: atomic INCR + TTL + over-limit rollback via server-side
+  // Lua. Runs single-threaded in Redis, so two parallel clients can't both
+  // observe `count <= max` and slip past. The prior non-atomic JS version
+  // could leave the counter stuck below the true hit count when two INCRs
+  // raced into simultaneous DECR rollbacks.
+  const RATE_LIMIT_LUA = `
+    local count = redis.call('INCR', KEYS[1])
+    if count == 1 then
+      redis.call('EXPIRE', KEYS[1], ARGV[1])
+    end
+    if count > tonumber(ARGV[2]) then
+      redis.call('DECR', KEYS[1])
+      return 0
+    end
+    return 1
+  `;
+
+  type RedisWithLua = Redis & {
+    deliveryRateLimitCheck: (key: string, ttl: string, max: string) => Promise<number>;
+  };
+
+  if (rateLimit) {
+    // Register the Lua script once per Redis client. Noop if already defined.
+    // @cast-boundary engine-bridge — defineCommand attaches the Lua method post-boot
+    const r = rateLimit.redis as Partial<Pick<RedisWithLua, "deliveryRateLimitCheck">> & Redis;
+    if (!r.deliveryRateLimitCheck) {
+      r.defineCommand("deliveryRateLimitCheck", { numberOfKeys: 1, lua: RATE_LIMIT_LUA });
+    }
+  }
+
+  async function checkRateLimit(
+    rl: RateLimitConfig,
+    tenantId: TenantId,
+    channelName: string,
+  ): Promise<boolean> {
+    const key = `${rl.keyPrefix ?? "delivery:rate"}:${tenantId}:${channelName}`;
+    // @cast-boundary engine-bridge — defineCommand attaches the Lua method shape at boot
+    const r = rl.redis as RedisWithLua;
+    const allowed = await r.deliveryRateLimitCheck(key, "3600", String(rl.maxPerHour));
+    return Number(allowed) === 1;
+  }
+
+  // Idempotency: returns true the first time a key is seen, false on
+  // subsequent calls within the TTL window. Opt-in via options.idempotencyKey
+  // so callers decide when dedup matters (e.g. webhook replays, button
+  // double-clicks). Requires a Redis handle — configured via idempotencyRedis
+  // or reused from rateLimit.redis. notify() throws if the key is used without
+  // a backing Redis, so misconfigurations fail loud instead of silently double-sending.
+  async function claimIdempotency(
+    tenantId: TenantId,
+    key: string,
+    ttlSec = 86400,
+  ): Promise<boolean> {
+    if (!idemRedis) {
+      throw new Error(
+        "Delivery idempotencyKey requires options.idempotencyRedis (or rateLimit.redis) to be configured",
+      );
+    }
+    const k = `delivery:idem:${tenantId}:${key}`;
+    const res = await idemRedis.set(k, "1", "EX", ttlSec, "NX");
+    return res === "OK";
+  }
+
+  async function resolveUserIdsForTenant(tenantId: TenantId): Promise<readonly string[]> {
+    if (!tenantUserIdsQuery) {
+      throw new Error("Tenant broadcast requires tenantUserIdsQuery in DeliveryServiceOptions");
+    }
+    const handler = registry.getQueryHandler(tenantUserIdsQuery);
+    if (!handler) {
+      throw new Error(`Tenant broadcast query "${tenantUserIdsQuery}" not found in registry`);
+    }
+    const systemUser = createSystemUser(tenantId);
+    const report = createEscapeHatchReporter({
+      handler: tenantUserIdsQuery,
+      tenantId,
+      actor: systemUser.id,
+      sink: escapeHatchAuditSink,
+      log,
+    });
+    // ctx.db/dbOutsideTransaction are tenant-filtered even for a systemScope handler:
+    // the dispatcher closes them off entirely there, so "system" mode would hand this
+    // path a cross-tenant read the dispatcher never allows. Cross-tenant reach only
+    // exists through the grant-carrying systemDb view below.
+    const isSystem = registry.isHandlerSystemScoped(tenantUserIdsQuery);
+    const tenantDb = createTenantDb(db, tenantId, "tenant", undefined, undefined, undefined, {
+      report,
+    });
+    // The dispatcher grants a systemScope handler's ctx.systemDb.unsafeRaw() ungated —
+    // the grant comes from the handler's own r.systemScope() registration, not from this
+    // caller. Only the systemDb view's own source TenantDb carries the grant, so it
+    // can't leak onto ctx.db.
+    const systemDbSourceTenantDb = isSystem
+      ? createTenantDb(db, tenantId, "system", undefined, undefined, undefined, {
+          report,
+          unsafeRaw: { reason: `r.systemScope() handler "${tenantUserIdsQuery}"` },
+        })
+      : undefined;
+    // Hand-built context, not routed through the dispatcher — this needs both
+    // db and dbOutsideTransaction wired directly.
+    // @cast-boundary engine-payload — generic query-handler return for typed convention
+    return (await handler.handler(
+      { type: tenantUserIdsQuery, payload: { tenantId }, user: systemUser },
+      {
+        db: tenantDb,
+        dbOutsideTransaction: tenantDb,
+        systemDb: systemDbSourceTenantDb
+          ? createSystemDbView(systemDbSourceTenantDb, undefined, report)
+          : undefined,
+        registry,
+        ...bridgeStub(),
+      },
+    )) as readonly string[];
+  }
+
+  // Single-shot terminal log (inline channels, skips, idempotency dups). Async
+  // attempts instead append a queued event up front and a terminal event from
+  // the send job — see deliverViaChannel + jobs.ts.
+  async function logDelivery(entry: DeliveryLogEntry): Promise<void> {
+    await logAttempt(db, registry, entry);
+  }
+
+  // Deliver one resolved (channel, address) pair. Inline channels (inApp) and
+  // the no-job-runner fallback render + send synchronously and log the terminal
+  // status. Queued channels (email/push) record a `queued` attempt up front and
+  // hand off to the delivery.render (or delivery.send) job, which appends the
+  // terminal event on the same attempt stream.
+  async function deliverViaChannel(args: {
+    channel: DeliveryChannel;
+    address: string;
+    message: ChannelMessage;
+    channelCtx: ChannelContext;
+    tenantId: TenantId;
+    recipientId: string | null;
+    notificationType: string;
+    priority: NotifyPriority;
+  }): Promise<void> {
+    const {
+      channel,
+      address,
+      message,
+      channelCtx,
+      tenantId,
+      recipientId,
+      notificationType,
+      priority,
+    } = args;
+
+    if (channel.mode === "queued" && jobRunner) {
+      // Async hand-off: record the attempt as queued, then dispatch the
+      // render/send job — the terminal sent/failed event is appended by the
+      // job, not here.
+      const deliveryAttemptId = generateId();
+      await appendAttemptEvent(db, registry, deliveryAttemptId, {
+        tenantId,
+        notificationType,
+        channel: channel.name,
+        recipientId,
+        recipientAddress: address,
+        status: "queued",
+        error: null,
+        priority,
+      });
+      await jobRunner.dispatch(
+        channel.render ? DeliveryJobs.render : DeliveryJobs.send,
+        {
+          channelName: channel.name,
+          address,
+          tenantId,
+          recipientId,
+          notificationType,
+          deliveryAttemptId,
+          priority,
+          message,
+        },
+        { priority: deliveryPriorityRank[priority] },
+      );
+    } else {
+      // Inline (inApp) or no-job-runner fallback: render + send synchronously.
+      const rendered = channel.render ? await channel.render(message, channelCtx) : undefined;
+      const result = await channel.send(address, message, channelCtx, rendered);
+      await logDelivery({
+        tenantId,
+        notificationType,
+        channel: channel.name,
+        recipientId,
+        recipientAddress: result.address ?? address,
+        status: result.status,
+        error: result.error ?? null,
+        priority,
+      });
+    }
+  }
+
+  function buildMessage(
+    notificationType: string,
+    data: Readonly<Record<string, unknown>> | undefined,
+    channelName: string,
+  ): ChannelMessage {
+    // Look up per-channel template from notification definition
+    const notifDef = registry.getAllNotifications().get(notificationType);
+    const templateFn = notifDef?.templates?.[channelName];
+
+    if (templateFn && data) {
+      const channelData = templateFn(data as DbRow);
+      // @cast-boundary engine-payload — generic notification.data + channel-template result
+      return {
+        notificationType,
+        title: (channelData["title"] as string) ?? (data["title"] as string) ?? notificationType,
+        body: channelData["body"] as string | undefined,
+        data: channelData,
+      };
+    }
+
+    // @cast-boundary engine-payload — generic notification.data shape
+    return {
+      notificationType,
+      title: (data?.["title"] as string) ?? notificationType,
+      body: data?.["body"] as string | undefined,
+      data,
+    };
+  }
+
+  // Shared by deliverToUser (resolved account address) and deliverDirect (a
+  // route address with no user account) — same suppression rule either way:
+  // no blind-index key configured means no hash, so nothing to look up.
+  async function isAddressSuppressed(
+    address: string,
+    tenantId: TenantId,
+    notificationType: string,
+    channelName: string,
+  ): Promise<boolean> {
+    const addressHash = hashUnsubscribeAddress(address);
+    if (addressHash === undefined) return false;
+    return isAddressOptedOut(db, tenantId, addressHash, notificationType, channelName);
+  }
+
+  // Check if user has disabled this notification+channel combo.
+  // Specificity order: exact > any wildcard. When only wildcards match and they
+  // disagree, "disabled wins" — the user has asked to be opted out somewhere,
+  // and an exact override is the way to punch through it. Without this rule
+  // the outcome would depend on row insertion order in the DB.
+  // Example:
+  //   { type: "*", channel: "inApp", enabled: false }         disables inApp globally
+  //   { type: "orderAssigned", channel: "*", enabled: true }  enables orderAssigned everywhere
+  //   → orderAssigned on inApp: disabled (conservative) unless an exact entry overrides.
+  async function isChannelEnabled(
+    userId: string,
+    tenantId: TenantId,
+    notificationType: string,
+    channelName: string,
+  ): Promise<boolean> {
+    const prefs = await selectNotificationPreferences(
+      db,
+      tenantId,
+      userId,
+      notificationType,
+      channelName,
+    );
+
+    if (prefs.length === 0) return true;
+
+    // Exact match (both specific) wins over any wildcard
+    const exact = prefs.find(
+      (p) => p.notificationType === notificationType && p.channel === channelName,
+    );
+    if (exact) return exact.enabled;
+
+    // Only wildcards matched: any disabled entry disables delivery (deterministic
+    // and conservative — DB ordering no longer decides the outcome).
+    return !prefs.some((p) => p.enabled === false);
+  }
+
+  async function deliverToUser(
+    userId: string,
+    notificationType: string,
+    data: Readonly<Record<string, unknown>> | undefined,
+    tenantId: TenantId,
+    priority: NotifyPriority,
+  ): Promise<void> {
+    const channelCtx = buildChannelContext(db, registry, sseBroker, tenantId);
+
+    for (const channel of channels) {
+      const message = buildMessage(notificationType, data, channel.name);
+
+      // Kill switch: tenant admin disabled this channel entirely
+      if (isChannelKilled) {
+        const killed = await isChannelKilled(tenantId, channel.name);
+        if (killed) {
+          await logDelivery({
+            tenantId,
+            notificationType,
+            channel: channel.name,
+            recipientId: userId,
+            recipientAddress: null,
+            status: "skipped",
+            error: "channel_disabled",
+            priority,
+          });
+          continue;
+        }
+      }
+
+      // Check preferences (critical priority skips preference check)
+      if (priority !== "critical") {
+        const enabled = await isChannelEnabled(userId, tenantId, notificationType, channel.name);
+        if (!enabled) {
+          await logDelivery({
+            tenantId,
+            notificationType,
+            channel: channel.name,
+            recipientId: userId,
+            recipientAddress: null,
+            status: "skipped",
+            error: "preference_disabled",
+            priority,
+          });
+          continue;
+        }
+      }
+
+      // Rate limiting
+      if (rateLimit) {
+        const allowed = await checkRateLimit(rateLimit, tenantId, channel.name);
+        if (!allowed) {
+          await logDelivery({
+            tenantId,
+            notificationType,
+            channel: channel.name,
+            recipientId: userId,
+            recipientAddress: null,
+            status: "skipped",
+            error: "rate_limited",
+            priority,
+          });
+          continue;
+        }
+      }
+
+      try {
+        const address = await channel.resolve(userId, channelCtx);
+        if (!address) {
+          await logDelivery({
+            tenantId,
+            notificationType,
+            channel: channel.name,
+            recipientId: userId,
+            recipientAddress: null,
+            status: "skipped",
+            error: "no_address",
+            priority,
+          });
+          continue;
+        }
+
+        if (
+          priority !== "critical" &&
+          (await isAddressSuppressed(address, tenantId, notificationType, channel.name))
+        ) {
+          await logDelivery({
+            tenantId,
+            notificationType,
+            channel: channel.name,
+            recipientId: userId,
+            recipientAddress: null,
+            status: "skipped",
+            error: "unsubscribed",
+            priority,
+          });
+          continue;
+        }
+
+        await deliverViaChannel({
+          channel,
+          address,
+          message,
+          channelCtx,
+          tenantId,
+          recipientId: userId,
+          notificationType,
+          priority,
+        });
+      } catch (err) {
+        await logDelivery({
+          tenantId,
+          notificationType,
+          channel: channel.name,
+          recipientId: userId,
+          recipientAddress: null,
+          status: "failed",
+          error: err instanceof Error ? err.message : String(err),
+          priority,
+        });
+      }
+    }
+  }
+
+  async function deliverDirect(
+    route: Readonly<Record<string, string>>,
+    notificationType: string,
+    data: Readonly<Record<string, unknown>> | undefined,
+    tenantId: TenantId,
+    priority: NotifyPriority,
+    recipientId: string | null,
+  ): Promise<void> {
+    const channelCtx = buildChannelContext(db, registry, sseBroker, tenantId);
+
+    // Direct routing skips preferences (no user account) but NOT rate limit
+    // — direct sends can still be abused (webhook replays, test harnesses).
+    for (const channel of channels) {
+      const address = route[channel.name];
+      const message = buildMessage(notificationType, data, channel.name);
+      if (!address) continue;
+
+      // Address opt-out (critical priority skips it, same rule as user
+      // preferences).
+      if (
+        priority !== "critical" &&
+        (await isAddressSuppressed(address, tenantId, notificationType, channel.name))
+      ) {
+        await logDelivery({
+          tenantId,
+          notificationType,
+          channel: channel.name,
+          recipientId,
+          // The recipient withdrew — suppressed attempts must not keep recording the address.
+          recipientAddress: null,
+          status: "skipped",
+          error: "unsubscribed",
+          priority,
+        });
+        continue;
+      }
+
+      if (rateLimit) {
+        const allowed = await checkRateLimit(rateLimit, tenantId, channel.name);
+        if (!allowed) {
+          await logDelivery({
+            tenantId,
+            notificationType,
+            channel: channel.name,
+            recipientId,
+            recipientAddress: address,
+            status: "skipped",
+            error: "rate_limited",
+            priority,
+          });
+          continue;
+        }
+      }
+
+      try {
+        await deliverViaChannel({
+          channel,
+          address,
+          message,
+          channelCtx,
+          tenantId,
+          recipientId,
+          notificationType,
+          priority,
+        });
+      } catch (err) {
+        await logDelivery({
+          tenantId,
+          notificationType,
+          channel: channel.name,
+          recipientId,
+          recipientAddress: address,
+          status: "failed",
+          error: err instanceof Error ? err.message : String(err),
+          priority,
+        });
+      }
+    }
+  }
+
+  return {
+    async notify(notificationType, options, _user, tenantId) {
+      const { to, route, data, idempotencyKey } = options;
+      const priority: NotifyPriority = options.priority ?? "normal";
+
+      if (idempotencyKey) {
+        const first = await claimIdempotency(tenantId, idempotencyKey);
+        if (!first) {
+          await logDelivery({
+            tenantId,
+            notificationType,
+            channel: "*",
+            recipientId: options.recipientId ?? null,
+            recipientAddress: null,
+            status: "skipped",
+            error: "duplicate_idempotency_key",
+            priority,
+          });
+          // skip: duplicate send deduped via idempotency key, logged above
+          return;
+        }
+      }
+
+      if (route) {
+        await deliverDirect(
+          route,
+          notificationType,
+          data,
+          tenantId,
+          priority,
+          options.recipientId ?? null,
+        );
+        // skip: direct route delivered, no recipient resolution needed
+        return;
+      }
+
+      if (to !== undefined) {
+        let userIds: readonly string[];
+
+        if (typeof to === "string") {
+          userIds = [to];
+        } else if ("tenant" in to) {
+          userIds = await resolveUserIdsForTenant(to.tenant);
+        } else {
+          userIds = to;
+        }
+
+        for (const userId of userIds) {
+          await deliverToUser(userId, notificationType, data, tenantId, priority);
+        }
+      }
+    },
+  };
+}

package/packages/bundled-features/src/delivery/events.ts

@@ -0,0 +1,24 @@
+// Event-payload schema for the deliveryAttempt aggregate. Shared between
+// delivery-feature.ts (registers it via r.defineEvent) and
+// delivery-service.ts (validates payloads before the low-level append()
+// — out-of-dispatcher writes otherwise skip schema enforcement).
+
+import * as z from "zod";
+import { DeliveryStatus } from "./constants.js";
+
+export const deliveryAttemptSchema = z.object({
+  notificationType: z.string(),
+  channel: z.string(),
+  recipientId: z.string().nullable(),
+  recipientAddress: z.string().nullable(),
+  status: z.enum([
+    DeliveryStatus.queued,
+    DeliveryStatus.sent,
+    DeliveryStatus.failed,
+    DeliveryStatus.skipped,
+  ]),
+  error: z.string().nullable(),
+  priority: z.enum(["critical", "normal", "low"]),
+});
+
+export type DeliveryAttemptPayload = z.infer<typeof deliveryAttemptSchema>;