@open-mercato/events 0.6.8-develop.6917.1.af45bc96e2 → 0.6.8-develop.6924.1.a8d208fcdc

package/src/modules/events/workers/events.worker.ts

@@ -1,8 +1,9 @@
 import type { QueuedJob, JobContext, WorkerMeta } from '@open-mercato/queue'
-import { getCliModules } from '@open-mercato/shared/modules/registry'
-import { matchEventPattern } from '@open-mercato/shared/lib/events/patterns'
 import { createLogger } from '@open-mercato/shared/lib/logger'
-import { isSingleDeliveryRequested } from '../../../single-delivery'
+import type { EventBus, QueuedDispatchResult } from '../../../types'
+
+/** An `EventBus` proven at runtime to implement the optional `dispatchQueued`. */
+type DispatchCapableBus = EventBus & Required<Pick<EventBus, 'dispatchQueued'>>
 
 export const EVENTS_QUEUE_NAME = 'events'
 
@@ -23,6 +24,12 @@ type EventJobPayload = {
     tenantId?: string | null
     organizationId?: string | null
   }
+  /**
+   * Producer stamp: the emitting process already ran the persistent subscribers
+   * inline because single-delivery was reconciled off there. Dispatching again
+   * here would double-run them, so the job is a no-op.
+   */
+  persistentDeliveredInline?: boolean
 }
 
 type HandlerContext = {
@@ -32,119 +39,124 @@ type HandlerContext = {
   organizationId?: string | null
 }
 
-type SubscriberEntry = {
-  id: string
-  event: string
-  persistent?: boolean
-  handler: (payload: unknown, ctx: unknown) => Promise<void> | void
-}
-
-/**
- * Mirror of the event bus single-delivery flag. When enabled, the worker owns
- * dispatch of every persistent subscriber and matches by pattern so wildcard
- * (`event: '*'`) persistent subscribers are finally reached. Defaults ON;
- * reconciled by the server bootstrap against worker availability and read from
- * the same env var as the bus so the two always agree within a process.
- */
-function isSingleDeliveryEnabled(): boolean {
-  return isSingleDeliveryRequested()
-}
-
 /**
- * Resolves the subscribers to run for a queued event.
- * - Legacy (flag off): exact-match lookup of every subscriber for the event.
- * - Single-delivery (flag on): persistent subscribers whose pattern matches the
- *   event, including wildcards, so they run exactly once here instead of inline.
+ * Resolves the DI event bus that owns subscriber dispatch for this job.
+ *
+ * The worker deliberately has no subscriber registry of its own. It used to build
+ * one from `getCliModules()`, which is populated only by the `mercato` bin, so any
+ * process that started a worker another way dispatched zero subscribers and
+ * completed the job silently - dropping webhook deliveries, workflow event
+ * triggers and business-rule triggers with no error and no log. The per-job
+ * request container already carries a bus with every module subscriber registered,
+ * so that is the single source of truth. When it is missing, fail the job loudly
+ * rather than repeat the silent drop.
  */
-function resolveSubscribers(
-  listeners: Map<string, SubscriberEntry[]>,
-  event: string,
-): SubscriberEntry[] {
-  if (!isSingleDeliveryEnabled()) {
-    return listeners.get(event) ?? []
+function resolveEventBus(ctx: HandlerContext, event: string): DispatchCapableBus {
+  let bus: unknown
+  try {
+    bus = ctx.resolve('eventBus')
+  } catch (error) {
+    throw new Error(
+      `[internal] Events worker cannot dispatch "${event}": no "eventBus" in the job container ` +
+      `(${error instanceof Error ? error.message : String(error)}). The events worker must run inside a ` +
+      `bootstrapped process, e.g. \`mercato queue worker events\` or \`mercato queue worker --all\`. ` +
+      `Failing the job so it retries instead of dropping the event's subscribers.`,
+    )
   }
-  const matched: SubscriberEntry[] = []
-  for (const [pattern, subs] of listeners) {
-    if (!matchEventPattern(event, pattern)) continue
-    for (const sub of subs) {
-      if (sub.persistent) matched.push(sub)
-    }
+  if (!bus || typeof (bus as EventBus).dispatchQueued !== 'function') {
+    throw new Error(
+      `[internal] Events worker cannot dispatch "${event}": the resolved "eventBus" has no ` +
+      `dispatchQueued(). Either the bus failed to initialize and the degraded no-op fallback is in ` +
+      `place, or a stale @open-mercato/events build is loaded alongside a newer one. Failing the job ` +
+      `so it retries instead of dropping the event's subscribers.`,
+    )
   }
-  return matched
+  return bus as DispatchCapableBus
 }
 
-// Cached listener map - built once on first use
-let cachedListenerMap: Map<string, SubscriberEntry[]> | null = null
-
-/**
- * Clear the cached listener map (for testing purposes).
- */
-export function clearListenerCache(): void {
-  cachedListenerMap = null
-}
-
-// Build listener map from module subscribers
-function buildListenerMap(): Map<string, SubscriberEntry[]> {
-  const listeners = new Map<string, SubscriberEntry[]>()
-  for (const mod of getCliModules()) {
-    const subs = (mod as { subscribers?: SubscriberEntry[] }).subscribers
-    if (!subs) continue
-    for (const sub of subs) {
-      if (!listeners.has(sub.event)) listeners.set(sub.event, [])
-      listeners.get(sub.event)!.push(sub)
-    }
+function reportFailures(event: string, results: QueuedDispatchResult[]): void {
+  // Keyed on `ok`, never on `error !== undefined`: a handler can reject with
+  // `undefined`, which would otherwise be scored as a success and the job
+  // completed despite a failed subscriber.
+  const failures = results.filter((result) => !result.ok)
+  if (failures.length === 0) {
+    return
   }
-  return listeners
-}
 
-// Get cached listener map, building on first access
-function getListenerMap(): Map<string, SubscriberEntry[]> {
-  if (!cachedListenerMap) {
-    cachedListenerMap = buildListenerMap()
+  for (const failure of failures) {
+    logger.error('Subscriber failed for event', {
+      event,
+      subscriberId: failure.subscriberId,
+      err: failure.error,
+    })
   }
-  return cachedListenerMap
+
+  const failedIds = failures.map((failure) => failure.subscriberId).join(', ')
+  throw new Error(
+    `[internal] ${failures.length}/${results.length} subscriber(s) failed for event "${event}": ${failedIds}`,
+  )
 }
 
+// Event names already reported as having no subscriber. The empty-result case is
+// worth surfacing once - it is the residual silent-loss path - but an install
+// carrying none of the wildcard persistent subscribers (webhooks outbound,
+// workflow triggers, business-rule triggers) would otherwise log one `warn` per
+// queued event forever, and a warning that fires in steady state is one operators
+// learn to skip past.
+const eventsReportedWithoutSubscribers = new Set<string>()
+
 /**
  * Events worker handler.
- * Dispatches queued events to registered module subscribers.
+ * Dispatches queued events to the subscribers registered on the DI event bus.
  * Each subscriber is isolated - failures in one don't affect others.
  */
 export default async function handle(
   job: QueuedJob<EventJobPayload>,
   ctx: JobContext & HandlerContext
 ): Promise<void> {
-  const { event, payload, options } = job.payload
-  const listeners = getListenerMap()
-  const subscribers = resolveSubscribers(listeners, event)
-
-  if (!subscribers || subscribers.length === 0) return
-
-  const handlerCtx = {
-    resolve: ctx.resolve,
-    eventName: event,
-    tenantId: options?.tenantId ?? null,
-    organizationId: options?.organizationId ?? null,
+  const { event, payload, options, persistentDeliveredInline } = job.payload
+  if (persistentDeliveredInline) {
+    return
   }
 
-  const results = await Promise.allSettled(
-    subscribers.map((sub) => Promise.resolve(sub.handler(payload, handlerCtx)))
+  const bus = resolveEventBus(ctx, event)
+  // `ctx.resolve` is the per-job request container `createPerJobWorkerHandler`
+  // built for this job. Handing it to the bus keeps subscribers on that job's
+  // `em` instead of whichever container happened to construct the bus.
+  const results = await bus.dispatchQueued(
+    event,
+    payload,
+    {
+      tenantId: options?.tenantId ?? null,
+      organizationId: options?.organizationId ?? null,
+    },
+    ctx.resolve,
   )
 
-  const errors: Array<{ subscriberId: string; error: unknown }> = []
-  for (let i = 0; i < results.length; i++) {
-    const result = results[i]
-    if (result.status === 'rejected') {
-      const sub = subscribers[i]
-      logger.error('Subscriber failed for event', { event, subscriberId: sub.id, err: result.reason })
-      errors.push({ subscriberId: sub.id, error: result.reason })
+  // A resolvable bus with an empty registry is the residual silent-loss path:
+  // `core/bootstrap.ts` logs and continues when `getModules()` fails, leaving a
+  // valid bus with no subscribers, and this job would then complete green.
+  // Zero subscribers is legitimate for an event nobody listens to, so this
+  // cannot throw - but at job-dispatch time it is more often a bug than a no-op,
+  // so make it visible rather than silent. Once per event name: see the note on
+  // `eventsReportedWithoutSubscribers`.
+  if (results.length === 0) {
+    const alreadyReported = eventsReportedWithoutSubscribers.has(event)
+    eventsReportedWithoutSubscribers.add(event)
+    if (alreadyReported) {
+      logger.debug('Queued event dispatched to zero subscribers', { event, jobId: ctx.jobId })
+      return
     }
+    logger.warn('Queued event dispatched to zero subscribers', { event, jobId: ctx.jobId })
+    return
   }
 
-  if (errors.length > 0) {
-    const failedIds = errors.map((e) => e.subscriberId).join(', ')
-    throw new Error(
-      `${errors.length}/${subscribers.length} subscriber(s) failed for event "${event}": ${failedIds}`
-    )
-  }
+  reportFailures(event, results)
 }
+
+/**
+ * @deprecated The worker no longer keeps a listener cache; subscriber resolution
+ * lives on the DI event bus. Kept as a no-op for one minor so existing callers
+ * (tests, custom worker harnesses) keep compiling.
+ */
+export function clearListenerCache(): void {}

package/src/single-delivery.ts

@@ -19,19 +19,29 @@ type EnvSource = Record<string, string | undefined>
  * persistent subscribers are reached), ephemeral subscribers still run inline.
  * This is the correct behavior; the legacy dual-dispatch (inline AND worker)
  * double-ran exact-match persistent subscribers and never reached wildcard
- * persistent subscribers in the worker. Set the env to a false token to opt back
- * into legacy dual-dispatch.
+ * persistent subscribers in the worker. Set the env to a false token to run
+ * persistent subscribers inline instead. That is no longer dual-dispatch: the
+ * producer stamps the queued job with what it already delivered, so the worker
+ * skips it. Either way a persistent emit runs its subscribers exactly once.
  *
- * The server bootstrap reconciles this against worker availability (see
- * {@link reconcileSingleDelivery}) and may rewrite the env to `false` for a
- * process that would otherwise skip inline delivery with no worker to drain the
- * queue. The bus and the events worker both read the (possibly reconciled) env,
- * so they always agree within a process.
+ * The `mercato server` bootstrap may rewrite the env to `false` for a process it
+ * knows runs no worker (see {@link reconcileSingleDelivery}). The bus does NOT
+ * second-guess the flag itself: the queue is durable, so a persistent emit with
+ * no worker yet is delayed, not lost, and a worker started later drains the
+ * backlog. The bus and the events worker read the same env, so they always agree
+ * within a process.
  */
 export function isSingleDeliveryRequested(env: EnvSource = process.env): boolean {
   return parseBooleanWithDefault(env[EVENTS_SINGLE_DELIVERY_ENV], true)
 }
 
+/**
+ * @deprecated Not read at runtime by this package - the bus never reconciles the
+ * flag against worker availability. The live consumer is the `mercato server`
+ * bootstrap, which mirrors this logic in
+ * `packages/cli/src/lib/events-single-delivery.ts` (the CLI cannot import this
+ * package). Kept for one minor because it is published API.
+ */
 export function isExternalWorkerAcknowledged(env: EnvSource = process.env): boolean {
   return parseBooleanWithDefault(env[EVENTS_EXTERNAL_WORKER_ENV], false)
 }
@@ -49,12 +59,18 @@ export type SingleDeliveryReconciliation = {
  * the events worker dispatches them. If no worker drains the queue, those
  * persistent side effects (notifications, queued emails, indexing) never run.
  *
- * The durable queue already covers transient worker downtime — a job persists
+ * The durable queue already covers transient worker downtime - a job persists
  * and drains when a worker returns. The dangerous case is a process configured
  * to run with NO events worker at all (auto-spawn off and no external worker).
  * For that case this fails safe: it disables single-delivery so persistent
- * subscribers run inline (dual-dispatch) and side effects are never dropped,
- * and surfaces a loud warning telling the operator how to opt back in.
+ * subscribers run inline, and surfaces a loud warning telling the operator how
+ * to move the work back off the request path.
+ *
+ * @deprecated Not read at runtime by this package - the bus never reconciles the
+ * flag against worker availability. The live consumer is the `mercato server`
+ * bootstrap, which mirrors this logic in
+ * `packages/cli/src/lib/events-single-delivery.ts` (the CLI cannot import this
+ * package). Kept for one minor because it is published API.
  */
 export function reconcileSingleDelivery(input: {
   requested: boolean
@@ -68,8 +84,8 @@ export function reconcileSingleDelivery(input: {
       `[events] ${EVENTS_SINGLE_DELIVERY_ENV} is on (default) but this process auto-spawns no events worker ` +
       `(AUTO_SPAWN_WORKERS=off) and ${EVENTS_EXTERNAL_WORKER_ENV} is not set. Persistent subscribers would be ` +
       `skipped inline with nothing to drain the queue, silently dropping notifications, queued emails, and ` +
-      `indexing. Falling back to legacy inline dual-dispatch for safety. To keep single-delivery, run an events ` +
-      `worker (\`mercato queue worker events\`) and set ${EVENTS_EXTERNAL_WORKER_ENV}=true, or enable ` +
-      `AUTO_SPAWN_WORKERS.`,
+      `indexing. Running them inline instead, on the caller's request path. To move this work back off ` +
+      `the request path, run an events worker (\`mercato queue worker events\`) and set ` +
+      `${EVENTS_EXTERNAL_WORKER_ENV}=true, or enable AUTO_SPAWN_WORKERS.`,
   }
 }

package/src/types.ts

@@ -55,6 +55,20 @@ export type SubscriberDescriptor = {
   handler: SubscriberHandler
 }
 
+/** Outcome of one subscriber run during a queued dispatch */
+export type QueuedDispatchResult = {
+  /** Subscriber id, falling back to its registered event pattern when unnamed */
+  subscriberId: string
+  /**
+   * Whether the handler settled successfully. This is the authoritative outcome:
+   * a handler can reject with `undefined` (`throw undefined`, `Promise.reject()`),
+   * so `error` alone cannot distinguish failure from success.
+   */
+  ok: boolean
+  /** The rejection reason when `ok` is false. May itself be `undefined`. */
+  error?: unknown
+}
+
 // ============================================================================
 // Event Bus Types
 // ============================================================================
@@ -140,6 +154,45 @@ export interface EventBus {
    */
   registerModuleSubscribers(subs: SubscriberDescriptor[]): void
 
+  /**
+   * Dispatch a queued event to the subscribers the events worker owns.
+   *
+   * Optional so this stays an ADDITIVE-ONLY change to a contract surface
+   * (`BACKWARD_COMPATIBILITY.md`): a custom `EventBus` written before this
+   * release still satisfies the interface. The events worker runtime-guards for
+   * it and throws an actionable error when it is absent, so the fail-loud
+   * behaviour does not depend on the type.
+   *
+   * Selects every subscriber whose registered pattern matches `event` and is
+   * marked `persistent`, so wildcard (`event: '*'`) persistent subscribers are
+   * reached. The selection does not depend on `OM_EVENTS_SINGLE_DELIVERY`:
+   * whether inline delivery already ran is carried by the job's
+   * `persistentDeliveredInline` stamp, so a producer and a worker that disagree
+   * about the flag still agree about the job.
+   *
+   * Unlike inline delivery, handler failures are returned rather than swallowed:
+   * the caller aggregates them and throws so the queue can retry the job.
+   *
+   * @param event - Event name from the queued job
+   * @param payload - Event payload data
+   * @param options - Trusted scope recorded on the queued job
+   * @param resolve - DI resolver handed to the dispatched subscribers, defaulting
+   *   to the one the bus was created with. The events worker passes its per-job
+   *   `ctx.resolve`, so subscribers bind to the container that job runs in rather
+   *   than the one that happened to build the bus. That distinction only bites
+   *   under `OM_BOOTSTRAP_CACHE`, where the cached bus is replayed into later
+   *   request containers while its captured resolver stays bound to the first —
+   *   but the worker already holds the correct handle, so there is no reason to
+   *   depend on the two coinciding.
+   * @returns One entry per dispatched subscriber, `error` set on failure
+   */
+  dispatchQueued?(
+    event: string,
+    payload: EventPayload,
+    options?: EmitOptions,
+    resolve?: <T = unknown>(name: string) => T,
+  ): Promise<QueuedDispatchResult[]>
+
   /**
    * Clear all events from the persistent queue.
    *