create-nexwire 4.2.4 → 4.3.0

package/hono/src/framework/notification/channels/mail.ts

@@ -0,0 +1,40 @@
+import { mail } from "@/framework/support/mail.js";
+import { resolveAuthProvider } from "@/framework/providers/adapter.js";
+import { redisClientIfReady } from "@/framework/redis/client.js";
+import { dispatchEvent } from "@/framework/events/dispatcher.js";
+import type { NotificationChannel } from "@/framework/notification/contracts.js";
+
+function escapeHtml(str: string) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+export const mailChannel: NotificationChannel = {
+  name: "mail",
+  async send(target, notification, options) {
+    if (!options.mail) return false;
+
+    let to = options.mail.to || null;
+    if (!to) {
+      try {
+        const provider = await resolveAuthProvider();
+        if (provider?.getUserContact) {
+          const contact = await provider.getUserContact(target.id);
+          if (contact?.email) to = contact.email as string;
+        }
+      } catch { }
+    }
+
+    if (!to) return false;
+
+    const subject = options.mail.subject || notification.title;
+    const html = options.mail.html || `<h2>${escapeHtml(notification.title)}</h2>${notification.body ? `<p>${escapeHtml(notification.body)}</p>` : ""}`;
+
+    if (redisClientIfReady()) {
+      await dispatchEvent("notification:mail", { to, subject, html }, { queue: "mail" });
+    } else {
+      await mail.sendMail({ to, subject, html });
+    }
+
+    return true;
+  }
+};

package/hono/src/framework/notification/contracts.ts

@@ -0,0 +1,29 @@
+import type { NotifiableTarget, NotificationRecord } from "@/framework/providers/contracts.js";
+
+export type NotificationTarget = number | string | NotifiableTarget;
+export type NormalizedTarget = { type: string; id: number | string };
+
+export type NotificationOptions = {
+  type?: string;
+  title: string;
+  body?: string;
+  link?: string;
+  data?: Record<string, unknown>;
+
+  // Built-in Channels
+  broadcast?: boolean;
+  mail?: {
+    to?: string;
+    subject?: string;
+    html?: string;
+  };
+
+  // Extensible: Add any custom channel options here (e.g., sms, push, discord)
+  sms?: { to?: string; message?: string };
+  push?: { token?: string; payload?: any };
+};
+
+export interface NotificationChannel {
+  name: string;
+  send(target: NormalizedTarget, notification: NotificationRecord, options: NotificationOptions): Promise<boolean>;
+}

package/hono/src/framework/notification/index.ts

@@ -1,39 +1,12 @@
-import { dispatchEvent } from "@/framework/events/dispatcher.js";
-import { resolveAuthProvider, resolveNotificationProvider } from "@/framework/providers/adapter.js";
-import type { NotifiableTarget, NotificationRecord } from "@/framework/providers/contracts.js";
-import { redisClientIfReady } from "@/framework/redis/client.js";
-import { mail } from "@/framework/support/mail.js";
+import type { NormalizedTarget, NotificationOptions, NotificationTarget } from "@/framework/notification/contracts.js";
+import { getChannels } from "@/framework/notification/registry.js";
+import { resolveNotificationProvider } from "@/framework/providers/adapter.js";
+import type { NotificationRecord } from "@/framework/providers/contracts.js";
 
 let missingProviderWarned = false;
 
-/** A numeric id (default auth), a string id (UUID/ULID), or an explicit target. */
-export type NotificationTarget = number | string | NotifiableTarget;
-
-/** Extra JSON metadata attached to the notification (e.g. entity IDs, links). */
-export type NotificationOptions = {
-  /** Notification category key (default: "info") */
-  type?: string;
-  /** Notification title */
-  title: string;
-  /** Notification body text */
-  body?: string;
-  /** Optional click-through URL */
-  link?: string;
-  /** Arbitrary JSON payload stored in `data` column */
-  data?: Record<string, unknown>;
-  /** Whether to broadcast the notification to the user's socket in realtime */
-  broadcast?: boolean;
-  /** Email delivery options */
-  mail?: {
-    /** Explicit recipient. Skips the auth provider contact lookup. */
-    to?: string;
-    subject?: string;
-    html?: string;
-  };
-};
-
 /** Turn the public target argument into the polymorphic owner pair. */
-function normalizeTarget(target: NotificationTarget): Required<Pick<NotifiableTarget, "id">> & { type: string } {
+function normalizeTarget(target: NotificationTarget): NormalizedTarget {
   if (target !== null && typeof target === "object") {
     return {
       type: String(target.type || "user").trim() || "user",
@@ -44,13 +17,10 @@ function normalizeTarget(target: NotificationTarget): Required<Pick<NotifiableTa
 }
 
 /**
- * Why: Persists a notification through the registered provider.
- * When: A feature wants to record something for a user (or another notifiable).
+ * Why: Persists a notification to the database and triggers all active channels.
+ * When: A feature wants to record something for a user.
  * Where: Application code, through the framework facade.
- * How: The provider owns storage; broadcasting and email stay here so a custom
- *      store cannot silently disable them. A missing provider is reported once
- *      and returns `null` instead of throwing, matching the framework's
- *      "optional module" behaviour.
+ * How: The provider owns database storage. The channels handle delivery (mail, sms, ws).
  */
 export async function notify(target: NotificationTarget, options: NotificationOptions): Promise<NotificationRecord | null> {
   const provider = await resolveNotificationProvider();
@@ -65,6 +35,8 @@ export async function notify(target: NotificationTarget, options: NotificationOp
   }
 
   const normalizedTarget = normalizeTarget(target);
+
+  // 1. Save to Database via the Provider
   const normalized = await provider.create(normalizedTarget, {
     type: options.type,
     title: options.title,
@@ -73,62 +45,15 @@ export async function notify(target: NotificationTarget, options: NotificationOp
     data: options.data ?? null
   });
 
-  if (options.broadcast) {
-    await dispatchEvent("notification.created", normalized, {
-      broadcast: { users: [normalizedTarget.id] }
-    });
-  }
-
-  if (options.mail) {
-    await sendMailChannel(normalizedTarget, normalized, options);
-  }
+  // 2. Dispatch to all registered channels in parallel
+  const channels = getChannels();
+  await Promise.allSettled(
+    channels.map((channel) =>
+      channel.send(normalizedTarget, normalized, options).catch((err) => {
+        console.error(`[notification] Channel ${channel.name} failed:`, err);
+      })
+    )
+  );
 
   return normalized;
 }
-
-/** Deliver an email notification, either queued (if Redis is available) or direct. */
-async function sendMailChannel(
-  target: { type: string; id: number | string },
-  notification: NotificationRecord,
-  options: NotificationOptions
-) {
-  let to: string | null = options.mail?.to || null;
-
-  if (!to) {
-    try {
-      const provider = await resolveAuthProvider();
-      if (provider?.getUserContact) {
-        const contact = await provider.getUserContact(target.id);
-        if (contact?.email) to = contact.email as string;
-      }
-    } catch {}
-  }
-
-  if (!to) return;
-
-  const subject = options.mail?.subject || notification.title;
-  const html = options.mail?.html || defaultMailHtml(notification.title, notification.body);
-
-  if (redisClientIfReady()) {
-    await dispatchEvent(
-      "notification:mail",
-      {
-        to,
-        subject,
-        html
-      },
-      { queue: "mail" }
-    );
-  } else {
-    await mail.sendMail({ to, subject, html });
-  }
-}
-
-/** Generate a basic HTML email body from title and body text. */
-function defaultMailHtml(title: string, body: string | null) {
-  return `<h2>${escapeHtml(title)}</h2>${body ? `<p>${escapeHtml(body)}</p>` : ""}`;
-}
-
-function escapeHtml(str: string) {
-  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-}

package/hono/src/framework/notification/registry.ts

@@ -0,0 +1,15 @@
+import type { NotificationChannel } from "@/framework/notification/contracts.js";
+
+const channels = new Map<string, NotificationChannel>();
+
+export function registerChannel(channel: NotificationChannel) {
+  channels.set(channel.name, channel);
+}
+
+export function getChannels(): NotificationChannel[] {
+  return Array.from(channels.values());
+}
+
+export function clearChannels() {
+  channels.clear();
+}

package/hono/src/framework/providers/adapter.ts

@@ -18,6 +18,7 @@ async function loadDefaultProvider(): Promise<AuthProvider | null> {
   if (defaultProvider) return defaultProvider;
   if (defaultLoadAttempted) return null;
   defaultLoadAttempted = true;
+
   try {
     const userMod = await import("@/modules/auth/database/models/user.js").catch(() => null);
     if (!userMod?.users || !userMod?.refreshTokens) return null;
@@ -25,22 +26,28 @@ async function loadDefaultProvider(): Promise<AuthProvider | null> {
     const users = userMod.users;
     const refreshTokens = userMod.refreshTokens;
 
-    defaultProvider = {
-      async getUserById(id: number | string) {
-        try {
-          const user = await (db.query.users.findFirst as any)?.({
-            where: eq(users.id, id as any),
-            with: { role: true }
-          });
-          if (user) return user;
-        } catch {}
-        try {
-          const rows = await db.select().from(users).where(eq(users.id, id as any));
-          return rows?.[0] ?? null;
-        } catch {
-          return null;
-        }
-      },
+    // Define the core logic as standalone functions to avoid `this` context issues
+    const getUserById = async (id: number | string) => {
+      try {
+        const user = await (db.query.users.findFirst as any)?.({
+          where: eq(users.id, id as any),
+          with: { role: true }
+        });
+        if (user) return user;
+      } catch {}
+      try {
+        const rows = await db
+          .select()
+          .from(users)
+          .where(eq(users.id, id as any));
+        return rows?.[0] ?? null;
+      } catch {
+        return null;
+      }
+    };
+
+    const provider: AuthProvider = {
+      getUserById,
       async findRefreshToken(jti: string) {
         try {
           const token = await (db.query.refreshTokens.findFirst as any)?.({
@@ -89,7 +96,8 @@ async function loadDefaultProvider(): Promise<AuthProvider | null> {
       },
       async getUserContact(userId: number | string) {
         try {
-          const user = await this.getUserById(userId);
+          // Use the standalone function instead of `this.getUserById`
+          const user = await getUserById(userId);
           if (!user) return null;
           return {
             email: user.email ?? null,
@@ -101,6 +109,8 @@ async function loadDefaultProvider(): Promise<AuthProvider | null> {
         }
       }
     };
+
+    defaultProvider = provider;
     return defaultProvider;
   } catch {
     return null;

package/hono/src/framework/queue/queue.ts

@@ -1,8 +1,9 @@
 import { type Job, type JobsOptions, Queue, QueueEvents, Worker } from "bullmq";
 import { type DurableContext, type DurableJob, DurableWorker, RedisStateStore } from "bullmq-durable";
-import { queueConfig } from "@/config/index.js";
+import { queueConfig, redisConfig } from "@/config/index.js";
 import { discoverModuleFiles, importFile } from "@/framework/modules/discover.js";
 import { redisClientIfReady } from "@/framework/redis/client.js";
+import { logger } from "@/framework/support/logger.js";
 
 export type QueueJob = {
   name: string;
@@ -10,9 +11,7 @@ export type QueueJob = {
 };
 
 export type QueueHandler = (job: Job) => Promise<any>;
-
 export type DurableQueueHandler = (job: DurableJob, ctx: DurableContext) => Promise<any>;
-
 export type AnyQueueHandler = QueueHandler | DurableQueueHandler;
 
 const queues = new Map<string, Queue>();
@@ -48,6 +47,14 @@ function key(queue: string, job: string) {
   return `${queue}:${job}`;
 }
 
+/**
+ * Why: BullMQ manages its own connections. We pass the URL string,
+ * not the shared client, so BullMQ doesn't crash if the shared client dies.
+ */
+function connectionOptions() {
+  return { url: redisConfig.url };
+}
+
 /**
  * Why: Registers a job handler for a queue + job name.
  * When: Module job files are loaded during boot.
@@ -73,14 +80,14 @@ export function shouldQueue(job: string, queue: string, handler: AnyQueueHandler
  * How: Reuses shared Redis connection and memoized queue map.
  */
 export function getQueue(queue = "default") {
-  const client = redisClientIfReady();
-  if (!client) return null;
+  // Check if Redis is supposed to be enabled
+  if (!redisConfig.enabled) return null;
 
   if (!queues.has(queue)) {
     queues.set(
       queue,
       new Queue(queue, {
-        connection: client as any,
+        connection: connectionOptions(), // Let BullMQ handle its own connection
         prefix: queuePrefix(),
         defaultJobOptions: {
           attempts: 3,
@@ -197,15 +204,20 @@ export async function queueJob(
     return null;
   }
 
-  return await queue.add(job, data, {
-    delay: options.delay ? options.delay * 1000 : 0,
-    attempts: options.attempts ?? 3,
-    jobId: options.jobId,
-    priority: options.priority,
-    removeOnComplete: options.removeOnComplete ?? 1000,
-    removeOnFail: options.removeOnFail ?? 5000,
-    backoff: options.backoff ?? { type: "exponential", delay: 3000 }
-  });
+  try {
+    return await queue.add(job, data, {
+      delay: options.delay ? options.delay * 1000 : 0,
+      attempts: options.attempts ?? 3,
+      jobId: options.jobId,
+      priority: options.priority,
+      removeOnComplete: options.removeOnComplete ?? 1000,
+      removeOnFail: options.removeOnFail ?? 5000,
+      backoff: options.backoff ?? { type: "exponential", delay: 3000 }
+    });
+  } catch (error) {
+    logger.error(`Failed to queue job ${job}`, { error });
+    return null;
+  }
 }
 
 /**
@@ -234,7 +246,7 @@ export async function bootQueueJobs() {
  *      queue's keys on demand if any code path still dispatches to it.
  */
 export async function pruneStaleQueues(protectedQueues: string[] = []) {
-  if (!queueConfig.autoPruneQueues) return;
+  if (!queueConfig.autoPruneQueues || !redisConfig.enabled) return;
 
   const client = redisClientIfReady();
   if (!client) return;
@@ -264,13 +276,13 @@ export async function pruneStaleQueues(protectedQueues: string[] = []) {
         if (live !== 0) continue;
 
         await queue.obliterate({ force: true });
-        console.log(`Pruned stale queue "${name}"`);
+        logger.info(`Pruned stale queue "${name}"`);
       } catch (error: any) {
-        console.warn(`Could not prune stale queue "${name}": ${error?.message || error}`);
+        logger.warn(`Could not prune stale queue "${name}": ${error?.message || error}`);
       }
     }
   } catch (error: any) {
-    console.warn(`Could not scan queues for stale cleanup: ${error?.message || error}`);
+    logger.warn(`Could not scan queues for stale cleanup: ${error?.message || error}`);
   }
 }
 
@@ -282,23 +294,21 @@ export async function pruneStaleQueues(protectedQueues: string[] = []) {
  */
 export async function startQueueWorker(queueNames = ["default"]) {
   await bootQueueJobs();
-  const client = redisClientIfReady();
-  if (!client) throw new Error("Redis is required for queue workers");
+  if (!redisConfig.enabled) throw new Error("Redis is required for queue workers");
 
   for (const queueName of queueNames) {
-    // Already working this queue in this process: a second worker would add a
-    // second blocking connection and a second copy of every log line, and would
-    // never process a job the first one was not already getting.
     if (workedQueues.has(queueName)) continue;
     workedQueues.add(queueName);
 
     if (!events.has(queueName)) {
-      events.set(queueName, new QueueEvents(queueName, { connection: client as any, prefix: queuePrefix() }));
+      // Let BullMQ manage its own connection for events
+      events.set(queueName, new QueueEvents(queueName, { connection: connectionOptions(), prefix: queuePrefix() }));
     }
 
     const durable = [...durableHandlers.keys()].some((k) => k.startsWith(`${queueName}:`));
 
     if (durable) {
+      // Durable worker still needs a shared client for its state store in this specific lib
       const store = durableStateStoreIfReady();
       if (!store) throw new Error("Redis is required for durable queue workers");
 
@@ -311,20 +321,14 @@ export async function startQueueWorker(queueNames = ["default"]) {
       }
 
       const worker = new DurableWorker(queueName, map as never, {
-        connection: client as any,
+        connection: connectionOptions(),
         prefix: queuePrefix(),
         stateStore: store,
         concurrency: 10
       });
 
-      worker.on("completed", (job) => {
-        console.log(`[${new Date().toLocaleTimeString()}] Processed:  ${job.name} (${queueName})`);
-      });
-
-      worker.on("failed", (job, error) => {
-        const jobName = job?.name ?? "unknown";
-        console.log(`[${new Date().toLocaleTimeString()}] Failed:     ${jobName} (${queueName}) - ${error.message}`);
-      });
+      worker.on("completed", (job) => logger.info(`Processed: ${job.name} (${queueName})`));
+      worker.on("failed", (job, error) => logger.warn(`Failed: ${job?.name ?? "unknown"} (${queueName}) - ${error.message}`));
 
       workers.push(worker as unknown as Worker);
       continue;
@@ -333,22 +337,16 @@ export async function startQueueWorker(queueNames = ["default"]) {
     const worker = new Worker(
       queueName,
       async (job) => {
-        console.log(`[${new Date().toLocaleTimeString()}] Processing: ${job.name} (${queueName})`);
+        logger.info(`Processing: ${job.name} (${queueName})`);
         const handler = handlers.get(key(queueName, job.name));
         if (!handler) throw new Error(`No handler registered for ${queueName}:${job.name}`);
         return await handler(job);
       },
-      { connection: client as any, prefix: queuePrefix(), concurrency: 10 }
+      { connection: connectionOptions(), prefix: queuePrefix(), concurrency: 10 }
     );
 
-    worker.on("completed", (job) => {
-      console.log(`[${new Date().toLocaleTimeString()}] Processed:  ${job.name} (${queueName})`);
-    });
-
-    worker.on("failed", (job, error) => {
-      const jobName = job?.name ?? "unknown";
-      console.log(`[${new Date().toLocaleTimeString()}] Failed:     ${jobName} (${queueName}) - ${error.message}`);
-    });
+    worker.on("completed", (job) => logger.info(`Processed: ${job.name} (${queueName})`));
+    worker.on("failed", (job, error) => logger.warn(`Failed: ${job?.name ?? "unknown"} (${queueName}) - ${error.message}`));
 
     workers.push(worker);
   }
@@ -364,6 +362,7 @@ export async function startQueueWorker(queueNames = ["default"]) {
  *      Cache/session/rate-limit keys are intentionally left alone.
  */
 export async function clearQueue() {
+  if (!redisConfig.enabled) return;
   const client = redisClientIfReady();
   if (!client) return;
 

package/hono/src/framework/realtime/broadcast.ts

@@ -1,6 +1,8 @@
 import { env } from "@/env.js";
+import { createCircuitBreaker, isCircuitBreakerError } from "@/framework/circuit-breaker/cb.js";
 import { socketServer } from "@/framework/realtime/socket.js";
 import { redisClientIfReady } from "@/framework/redis/client.js";
+import { logger } from "@/framework/support/logger.js";
 
 export type BroadcastOptions = {
   users?: Array<string | number>;
@@ -10,6 +12,13 @@ export type BroadcastOptions = {
   all?: boolean;
 };
 
+// Circuit breaker for the pub/sub relay (used by workers that don't have Socket.IO)
+const broadcastBreaker = createCircuitBreaker({
+  name: "Realtime Broadcast Relay",
+  failureThreshold: 3,
+  resetTimeout: 30000
+});
+
 /**
  * Why: Emits realtime events to targeted audiences.
  * When: Domain events need websocket fan-out.
@@ -29,18 +38,33 @@ function emitViaIo(event: string, payload: any, options: BroadcastOptions) {
   for (const room of options.rooms || []) io.to(room).emit(event, payload);
 }
 
-export function broadcast(event: string, payload: any, options: BroadcastOptions = {}) {
+export async function broadcast(event: string, payload: any, options: BroadcastOptions = {}) {
   const io = socketServer();
 
+  // If this process has Socket.IO (the main API server), emit directly
   if (io) {
-    emitViaIo(event, payload, options);
+    try {
+      emitViaIo(event, payload, options);
+    } catch (error) {
+      logger.error("Failed to broadcast event via Socket.IO", { error, event });
+    }
     return;
   }
 
-  // No Socket.IO in this process — relay through Redis so the main process can broadcast
+  // If this is a background worker, relay through Redis
   const redis = redisClientIfReady();
   if (!redis) return;
 
-  const channel = `${env.REDIS_PREFIX}:broadcast`;
-  redis.publish(channel, JSON.stringify({ event, payload, options }));
+  try {
+    await broadcastBreaker.exec(async () => {
+      const channel = `${env.REDIS_PREFIX}:broadcast`;
+      await redis.publish(channel, JSON.stringify({ event, payload, options }));
+    });
+  } catch (error) {
+    if (isCircuitBreakerError(error)) {
+      logger.warn("Broadcast relay skipped: Circuit breaker is open");
+    } else {
+      logger.error("Failed to relay broadcast via Redis", { error, event });
+    }
+  }
 }