@open-mercato/events 0.8.1-develop.7296.1.2111d779db → 0.9.0

package/src/bus.ts

@@ -7,9 +7,16 @@ import { matchEventPattern } from '@open-mercato/shared/lib/events/patterns'
 import { getRedisUrlOrThrow } from '@open-mercato/shared/lib/redis/connection'
 import {
   isBroadcastEvent,
+  isCoalescedBroadcastEvent,
   isCrossProcessBroadcastEvent,
   isPrivateCrossProcessEventEmitter,
 } from '@open-mercato/shared/modules/events'
+import {
+  BROADCAST_FLUSH_DEADLINE_MS,
+  flushPendingBroadcasts,
+  resolveBroadcastCoalesceIntervalMs,
+  submitBroadcast,
+} from './broadcast-coalescer'
 import {
   inferModuleIdFromResourceId,
   withModuleResourceUsage,
@@ -95,6 +102,95 @@ function resolveCrossProcessEmitOptions(
   }
 }
 
+function collectStringScopes(input: unknown): string[] {
+  if (!Array.isArray(input)) return []
+  const values: string[] = []
+  for (const value of input) {
+    if (typeof value !== 'string') continue
+    const trimmed = value.trim()
+    if (!trimmed) continue
+    values.push(trimmed)
+  }
+  return values
+}
+
+// Sorted so an audience keys identically however the caller ordered it, and
+// explicitly comparator-ed per the #3620 guard.
+function sortScopes(scopes: Set<string>): string[] {
+  return Array.from(scopes).sort((left, right) => left.localeCompare(right))
+}
+
+/**
+ * Coalescing key for the browser dispatch of one event.
+ *
+ * Built from the raw union of every dimension the SSE audience filter
+ * (`matchesAudience` in `events/api/stream/route.ts`) reads — tenant,
+ * organization, recipient user and recipient role — taken from BOTH the
+ * trusted `options` and the payload, without calling `resolveCrossProcessEmitOptions`
+ * or any other resolver. Those resolvers pick one source to trust for delivery
+ * semantics; the key instead has to key on every dimension a connection can be
+ * filtered by, or one audience's emit would silently replace another
+ * audience's pending delivery — recipient/role targeting and a portal-only
+ * event (which carries no trusted `options` scope at all) included.
+ *
+ * Options and payload scope stay in separate segments, never merged: the three
+ * filters each read a different source, so `options` org A + payload org B must
+ * not key like the reverse. The options tenant segment encodes PRESENCE, not
+ * just value — the backoffice `hasTrustedScope` is a presence test, so `{}` and
+ * `{ tenantId: undefined }` take different filter branches and must not share
+ * a key.
+ *
+ * Scope is part of the key by necessity, not for granularity: a key with no
+ * scope segments would let a burst in one tenant suppress another tenant's
+ * delivery and then deliver the first tenant's payload in its place.
+ */
+function buildBroadcastCoalesceKey(event: string, payload: EventPayload, options?: EmitOptions): string {
+  const data = (payload ?? {}) as Record<string, unknown>
+
+  const payloadTenantId = normalizePayloadScope(data.tenantId) ?? ''
+  const optionsTenantToken = options && Object.prototype.hasOwnProperty.call(options, 'tenantId')
+    ? `=${normalizePayloadScope(options.tenantId) ?? ''}`
+    : 'absent'
+
+  const optionsOrganizationScopes = new Set<string>()
+  const optionsOrganizationId = normalizePayloadScope(options?.organizationId)
+  if (optionsOrganizationId) optionsOrganizationScopes.add(optionsOrganizationId)
+  for (const organizationId of collectStringScopes(options?.organizationIds)) {
+    optionsOrganizationScopes.add(organizationId)
+  }
+
+  const payloadOrganizationScopes = new Set<string>()
+  const payloadOrganizationId = normalizePayloadScope(data.organizationId)
+  if (payloadOrganizationId) payloadOrganizationScopes.add(payloadOrganizationId)
+  for (const organizationId of collectStringScopes(data.organizationIds)) {
+    payloadOrganizationScopes.add(organizationId)
+  }
+
+  const recipientUserScopes = new Set<string>()
+  const recipientUserId = normalizePayloadScope(data.recipientUserId)
+  if (recipientUserId) recipientUserScopes.add(recipientUserId)
+  for (const userId of collectStringScopes(data.recipientUserIds)) {
+    recipientUserScopes.add(userId)
+  }
+
+  const recipientRoleScopes = new Set<string>()
+  const recipientRoleId = normalizePayloadScope(data.recipientRoleId)
+  if (recipientRoleId) recipientRoleScopes.add(recipientRoleId)
+  for (const roleId of collectStringScopes(data.recipientRoleIds)) {
+    recipientRoleScopes.add(roleId)
+  }
+
+  return [
+    event,
+    payloadTenantId,
+    optionsTenantToken,
+    sortScopes(payloadOrganizationScopes).join(','),
+    sortScopes(optionsOrganizationScopes).join(','),
+    sortScopes(recipientUserScopes).join(','),
+    sortScopes(recipientRoleScopes).join(','),
+  ].join('::')
+}
+
 function getGlobalEventTaps(): Set<GlobalEventTap> {
   const existing = (globalThis as Record<string, unknown>)[GLOBAL_EVENT_TAPS_KEY]
   if (existing instanceof Set) {
@@ -139,6 +235,7 @@ type EventJobData = {
 // base dir is cwd-relative, so it stays per-bus.
 const EVENTS_PRODUCER_QUEUE_KEY = '__openMercatoEventsProducerQueues__'
 const EVENTS_PRODUCER_SHUTDOWN_KEY = '__openMercatoEventsProducerShutdown__'
+const BROADCAST_COALESCER_SHUTDOWN_KEY = '__openMercatoBroadcastCoalescerShutdown__'
 
 function isSharedProducerEnabled(): boolean {
   return parseBooleanWithDefault(process.env.OM_EVENTS_SHARED_PRODUCER, true)
@@ -168,6 +265,52 @@ function registerProducerShutdownHook(): void {
   ;(globalThis as Record<string, unknown>)[EVENTS_PRODUCER_SHUTDOWN_KEY] = true
 }
 
+/**
+ * Deliver the tail of any in-flight coalesced burst on the way out, so stopping
+ * a worker mid-import does not leave browsers a window behind. Registered
+ * independently of the producer hook: coalescing is in play whether or not this
+ * process ever opened an async producer queue.
+ *
+ * `beforeExit` matters as much as the signals here. The trailing timer is
+ * unref'd so a pending browser delivery never holds a process open, which means
+ * a short-lived emitter — a CLI import, a one-shot script — reaches a natural
+ * exit with the tail still queued and no signal ever fired. `beforeExit` runs
+ * exactly when the loop has drained, which is precisely that case.
+ *
+ * `createEventBus` calls this in every process that bootstraps DI — the app,
+ * every worker, and every `mercato` CLI command — so a bare `process.once`
+ * listener here would take away Node's default SIGINT/SIGTERM exit process-wide:
+ * once ANY listener is registered for a signal, Node stops exiting on it, and
+ * this listener only flushes, never exits. A one-shot CLI command (seed,
+ * import, reindex) with no graceful-shutdown handler of its own would then
+ * swallow the first Ctrl+C or SIGTERM and keep running until SIGKILL. The
+ * per-signal handler below flushes, then restores the default behavior itself
+ * — by re-raising the signal — but only when it was the last listener
+ * (`once` already removed itself before this body runs): a process with its
+ * own graceful-shutdown handler (the queue worker, `mercato server`) keeps
+ * that handler in charge of the actual exit, and this hook just adds the flush
+ * alongside it. Every flush here is capped at BROADCAST_FLUSH_DEADLINE_MS, so a
+ * hung dispatch cannot hold a stop until SIGKILL.
+ */
+function registerBroadcastCoalescerShutdownHook(): void {
+  if ((globalThis as Record<string, unknown>)[BROADCAST_COALESCER_SHUTDOWN_KEY]) return
+  const handleSignal = (signal: NodeJS.Signals) => {
+    void flushPendingBroadcasts({ deadlineMs: BROADCAST_FLUSH_DEADLINE_MS })
+      .catch(() => {})
+      .finally(() => {
+        if (process.listenerCount(signal) === 0) {
+          process.kill(process.pid, signal)
+        }
+      })
+  }
+  process.once('SIGTERM', () => handleSignal('SIGTERM'))
+  process.once('SIGINT', () => handleSignal('SIGINT'))
+  process.once('beforeExit', () => {
+    void flushPendingBroadcasts({ deadlineMs: BROADCAST_FLUSH_DEADLINE_MS }).catch(() => {})
+  })
+  ;(globalThis as Record<string, unknown>)[BROADCAST_COALESCER_SHUTDOWN_KEY] = true
+}
+
 /**
  * Creates an event bus instance.
  *
@@ -199,6 +342,8 @@ function registerProducerShutdownHook(): void {
  * ```
  */
 export function createEventBus(opts: CreateBusOptions): EventBus {
+  registerBroadcastCoalescerShutdownHook()
+
   // In-memory listeners for immediate event delivery
   const listeners = new Map<string, Set<RegisteredSubscriber>>()
   // Subscribers registered as persistent (worker-dispatched). Used by the
@@ -439,15 +584,61 @@ export function createEventBus(opts: CreateBusOptions): EventBus {
     payload: EventPayload,
     options?: EmitOptions
   ): Promise<void> {
-    const taps = getGlobalEventTaps()
-    for (const tap of taps) {
+    const runGlobalTaps = async (): Promise<void> => {
+      const taps = getGlobalEventTaps()
+      for (const tap of taps) {
+        try {
+          await Promise.resolve(tap(event, payload, options))
+        } catch (error) {
+          logger.error('Global tap error', { event, err: error })
+        }
+      }
+    }
+
+    // Resolved at call time, never hoisted. Private coordination always requires
+    // trusted envelope scope and module provenance. Legacy declared browser events
+    // may promote their typed scope for raw EventBus compatibility; tenant-managed
+    // workflow adapters pass authoritative scope in options, which always wins over
+    // payload values. Computing it lazily keeps the non-coalesced path resolving
+    // scope at exactly the point it always did — after inline delivery — so an
+    // event that did not opt in cannot observe this change at all.
+    const publishToOtherProcesses = async (): Promise<void> => {
+      const crossProcessOptions = resolveCrossProcessEmitOptions(event, payload, options)
+      if (
+        !isCrossProcessBroadcastEvent(event)
+        || !hasTrustedTenantScope(crossProcessOptions)
+        || !isPrivateCrossProcessEventEmitter(event, crossProcessOptions?.emitterModuleId)
+      ) return
       try {
-        await Promise.resolve(tap(event, payload, options))
+        await publishCrossProcessEvent(event, payload, crossProcessOptions)
       } catch (error) {
-        logger.error('Global tap error', { event, err: error })
+        logger.error('Cross-process publish error', { event, err: error })
       }
     }
 
+    // Global taps are not a browser-only sink — `registerGlobalEventTap` is a
+    // public export that any process-local listener can use (the create-app
+    // template's qa-events route captures events for integration tests through
+    // it, and third-party modules can too), not just the two SSE endpoints. What
+    // both taps and the SSE bridges have in common is that neither carries domain
+    // meaning on its own, so an opted-in event may coalesce this dispatch — and
+    // with it every tap's delivery — without touching subscriber, webhook or
+    // queue semantics below. A tap on a coalesced event sees the same suppressed,
+    // trailing-flush-guaranteed stream the browser does, not one call per record.
+    const coalesceBrowserDelivery = isCoalescedBroadcastEvent(event)
+      && resolveBroadcastCoalesceIntervalMs() > 0
+    if (coalesceBrowserDelivery) {
+      await submitBroadcast(
+        buildBroadcastCoalesceKey(event, payload, options),
+        async () => {
+          await runGlobalTaps()
+          await publishToOtherProcesses()
+        },
+      )
+    } else {
+      await runGlobalTaps()
+    }
+
     // Deliver to in-memory handlers first. Under single-delivery, persistent
     // subscribers are skipped inline on a persistent emit because the events
     // worker will dispatch them from the queue.
@@ -468,21 +659,10 @@ export function createEventBus(opts: CreateBusOptions): EventBus {
       inlinePersistentFailed = delivered.persistentFailures > 0
     }
 
-    // Private coordination always requires trusted envelope scope and module
-    // provenance. Legacy declared browser events may promote their typed scope
-    // for raw EventBus compatibility; tenant-managed workflow adapters pass
-    // authoritative scope in options, which always wins over payload values.
-    const crossProcessOptions = resolveCrossProcessEmitOptions(event, payload, options)
-    if (
-      isCrossProcessBroadcastEvent(event)
-      && hasTrustedTenantScope(crossProcessOptions)
-      && isPrivateCrossProcessEventEmitter(event, crossProcessOptions?.emitterModuleId)
-    ) {
-      try {
-        await publishCrossProcessEvent(event, payload, crossProcessOptions)
-      } catch (error) {
-        logger.error('Cross-process publish error', { event, err: error })
-      }
+    // Already dispatched with the taps when this event coalesces its browser
+    // delivery; otherwise it publishes here, exactly where it always has.
+    if (!coalesceBrowserDelivery) {
+      await publishToOtherProcesses()
     }
 
     // If persistent, also enqueue for async processing

package/src/index.ts

@@ -1,2 +1,12 @@
 export * from './types'
 export * from './bus'
+// Named export list, not `export *`: `resetBroadcastCoalescerForTests` is a
+// test-only helper the `./broadcast-coalescer` subpath export already covers;
+// re-exporting it from the package root would make it a supported surface
+// under BACKWARD_COMPATIBILITY.md.
+export {
+  BROADCAST_FLUSH_DEADLINE_MS,
+  flushPendingBroadcasts,
+  resolveBroadcastCoalesceIntervalMs,
+  submitBroadcast,
+} from './broadcast-coalescer'

package/src/modules/events/api/__tests__/route.test.ts

@@ -21,6 +21,15 @@ jest.mock('@open-mercato/shared/modules/events', () => ({
       label: 'Order Placed',
       category: 'crud',
     },
+    {
+      id: 'catalog.product.created',
+      module: 'catalog',
+      entity: 'product',
+      label: 'Product Created',
+      category: 'crud',
+      clientBroadcast: true,
+      broadcastCoalescing: true,
+    },
     {
       id: 'webhooks.delivery.lifecycle',
       module: 'webhooks',
@@ -53,20 +62,24 @@ describe('GET /api/events (core events module route)', () => {
     const res = await GET(makeReq())
     expect(res.status).toBe(200)
     const body = (await res.json()) as { data: Array<{ id: string }>; total: number }
-    expect(body.total).toBe(2)
-    expect(body.data.map((e) => e.id)).toEqual(['customers.person.created', 'sales.order.placed'])
+    expect(body.total).toBe(3)
+    expect(body.data.map((e) => e.id)).toEqual([
+      'customers.person.created',
+      'sales.order.placed',
+      'catalog.product.created',
+    ])
   })
 
   it('respects excludeTriggerExcluded=false and returns trigger-excluded events too', async () => {
     const res = await GET(makeReq('http://localhost/api/events?excludeTriggerExcluded=false'))
     const body = (await res.json()) as { total: number }
-    expect(body.total).toBe(3)
+    expect(body.total).toBe(4)
   })
 
   it('filters by category', async () => {
     const res = await GET(makeReq('http://localhost/api/events?category=crud'))
     const body = (await res.json()) as { total: number; data: Array<{ category: string }> }
-    expect(body.total).toBe(2)
+    expect(body.total).toBe(3)
     expect(body.data.every((e) => e.category === 'crud')).toBe(true)
   })
 
@@ -94,4 +107,14 @@ describe('GET /api/events (core events module route)', () => {
     expect(untyped).toBeDefined()
     expect(untyped?.payloadSchema).toBeUndefined()
   })
+
+  it('round-trips broadcastCoalescing for events that declare it and omits it otherwise', async () => {
+    const res = await GET(makeReq())
+    const body = (await res.json()) as { data: Array<{ id: string; broadcastCoalescing?: boolean }> }
+    const coalesced = body.data.find((e) => e.id === 'catalog.product.created')
+    expect(coalesced?.broadcastCoalescing).toBe(true)
+    const notCoalesced = body.data.find((e) => e.id === 'sales.order.placed')
+    expect(notCoalesced).toBeDefined()
+    expect(notCoalesced?.broadcastCoalescing).toBeUndefined()
+  })
 })

package/src/modules/events/api/route.ts

@@ -40,6 +40,7 @@ const eventDefinitionSchema = z.object({
   clientBroadcast: z.boolean().optional(),
   crossProcessBroadcast: z.boolean().optional(),
   portalBroadcast: z.boolean().optional(),
+  broadcastCoalescing: z.boolean().optional(),
   payloadSchema: eventPayloadSchemaSchema.optional(),
 })