@open-mercato/events 0.6.8-develop.6918.1.7b3f32b0c8 → 0.6.8-develop.6925.1.cefa200fa4

package/src/__tests__/dispatch-queued.test.ts

@@ -0,0 +1,191 @@
+import { createEventBus } from '@open-mercato/events/index'
+import type { SubscriberDescriptor } from '@open-mercato/events/types'
+
+/**
+ * `dispatchQueued` is the events worker's only way to reach subscribers. The
+ * worker used to keep its own registry built from `getCliModules()`, which is
+ * populated exclusively by the `mercato` bin - so a worker started any other way
+ * dispatched nothing and completed the job silently. Selection now lives here, on
+ * the bus that already holds every registered subscriber, which also guarantees
+ * the inline-skip and the worker dispatch read one single-delivery decision.
+ */
+describe('EventBus.dispatchQueued', () => {
+  const origFlag = process.env.OM_EVENTS_SINGLE_DELIVERY
+
+  afterEach(() => {
+    if (origFlag === undefined) {
+      delete process.env.OM_EVENTS_SINGLE_DELIVERY
+    }
+    else {
+      process.env.OM_EVENTS_SINGLE_DELIVERY = origFlag
+    }
+  })
+
+  function makeBus(subs: SubscriberDescriptor[]) {
+    const bus = createEventBus({ resolve: ((name: string) => name) as never })
+    bus.registerModuleSubscribers(subs)
+    return bus
+  }
+
+  function makeSub(
+    id: string,
+    event: string,
+    persistent: boolean,
+    sink: string[],
+  ): SubscriberDescriptor {
+    return { id, event, persistent, handler: () => { sink.push(id) } }
+  }
+
+  test('single-delivery on: pattern-matches and keeps persistent subscribers only', async () => {
+    process.env.OM_EVENTS_SINGLE_DELIVERY = 'true'
+    const calls: string[] = []
+    const bus = makeBus([
+      makeSub('exact-persistent', 'user.created', true, calls),
+      makeSub('exact-ephemeral', 'user.created', false, calls),
+      makeSub('wildcard-persistent', '*', true, calls),
+      makeSub('wildcard-ephemeral', '*', false, calls),
+      makeSub('other-event', 'user.deleted', true, calls),
+    ])
+
+    const results = await bus.dispatchQueued('user.created', { id: '1' })
+
+    expect(calls.sort()).toEqual(['exact-persistent', 'wildcard-persistent'])
+    expect(results.map((r) => r.subscriberId).sort()).toEqual(['exact-persistent', 'wildcard-persistent'])
+    expect(results.every((r) => r.error === undefined)).toBe(true)
+  })
+
+  test('selection ignores OM_EVENTS_SINGLE_DELIVERY (producer/worker env skew)', async () => {
+    // A worker whose env has the flag OFF must still select persistent
+    // subscribers by pattern. Reading the flag here used to fall back to
+    // exact-match, which re-ran ephemeral subscribers the producer had already
+    // run inline and never reached wildcard persistent subscribers - the failure
+    // this change exists to remove, reintroduced under env skew.
+    process.env.OM_EVENTS_SINGLE_DELIVERY = 'false'
+    const calls: string[] = []
+    const bus = makeBus([
+      makeSub('exact-persistent', 'user.created', true, calls),
+      makeSub('exact-ephemeral', 'user.created', false, calls),
+      makeSub('wildcard-persistent', '*', true, calls),
+    ])
+
+    await bus.dispatchQueued('user.created', {})
+
+    expect(calls.sort()).toEqual(['exact-persistent', 'wildcard-persistent'])
+  })
+
+  test('returns handler failures instead of swallowing them', async () => {
+    process.env.OM_EVENTS_SINGLE_DELIVERY = 'true'
+    const bus = makeBus([
+      {
+        id: 'boom',
+        event: 'user.created',
+        persistent: true,
+        handler: () => { throw new Error('handler exploded') },
+      },
+      { id: 'ok', event: 'user.created', persistent: true, handler: () => {} },
+    ])
+
+    const results = await bus.dispatchQueued('user.created', {})
+
+    const failed = results.find((r) => r.subscriberId === 'boom')
+    const succeeded = results.find((r) => r.subscriberId === 'ok')
+    expect((failed?.error as Error).message).toBe('handler exploded')
+    expect(succeeded?.error).toBeUndefined()
+  })
+
+  test('reports a rejection with an undefined reason as a failure', async () => {
+    // `Promise.allSettled` sets `reason: undefined` for `throw undefined` and
+    // `Promise.reject()`, so an outcome inferred from `error !== undefined` would
+    // score this as a success and let the worker complete the job.
+    process.env.OM_EVENTS_SINGLE_DELIVERY = 'true'
+    const bus = makeBus([
+      {
+        id: 'throws-undefined',
+        event: 'user.created',
+        persistent: true,
+        handler: () => { throw undefined },
+      },
+      {
+        id: 'rejects-undefined',
+        event: 'user.created',
+        persistent: true,
+        handler: () => Promise.reject(),
+      },
+    ])
+
+    const results = await bus.dispatchQueued('user.created', {})
+
+    expect(results.map((r) => ({ id: r.subscriberId, ok: r.ok })).sort((a, b) => a.id.localeCompare(b.id)))
+      .toEqual([
+        { id: 'rejects-undefined', ok: false },
+        { id: 'throws-undefined', ok: false },
+      ])
+    expect(results.every((r) => r.error === undefined)).toBe(true)
+  })
+
+  test('forwards trusted scope and the concrete event name to wildcard subscribers', async () => {
+    process.env.OM_EVENTS_SINGLE_DELIVERY = 'true'
+    const seen: Array<Record<string, unknown>> = []
+    const bus = makeBus([
+      {
+        id: 'wildcard',
+        event: '*',
+        persistent: true,
+        handler: (_payload, ctx) => {
+          seen.push({
+            eventName: ctx.eventName,
+            tenantId: ctx.tenantId,
+            organizationId: ctx.organizationId,
+          })
+        },
+      },
+    ])
+
+    await bus.dispatchQueued('customers.deal.won', {}, { tenantId: 't1', organizationId: 'o1' })
+
+    expect(seen).toEqual([{ eventName: 'customers.deal.won', tenantId: 't1', organizationId: 'o1' }])
+  })
+
+  test('falls back to the registered pattern when a subscriber has no id', async () => {
+    process.env.OM_EVENTS_SINGLE_DELIVERY = 'true'
+    const bus = createEventBus({ resolve: ((name: string) => name) as never })
+    bus.on('user.created', () => {}, { persistent: true })
+
+    const results = await bus.dispatchQueued('user.created', {})
+
+    expect(results).toEqual([{ subscriberId: 'user.created', ok: true }])
+  })
+
+  test('prefers the caller-supplied resolver over the bus creation one', async () => {
+    // The events worker passes its per-job `ctx.resolve` so subscribers bind to
+    // that job's container. Under `OM_BOOTSTRAP_CACHE` the bus may be a cached
+    // instance whose captured resolver still points at the container that
+    // bootstrapped first, which would share one `em` across concurrent jobs.
+    process.env.OM_EVENTS_SINGLE_DELIVERY = 'true'
+    let resolved: unknown = null
+    const bus = createEventBus({ resolve: ((name: string) => `bus:${name}`) as never })
+    bus.on('user.created', (_payload, ctx) => { resolved = ctx.resolve('em') }, { persistent: true })
+
+    await bus.dispatchQueued('user.created', {}, undefined, ((name: string) => `job:${name}`) as never)
+
+    expect(resolved).toBe('job:em')
+  })
+
+  test('falls back to the bus resolver when the caller supplies none', async () => {
+    process.env.OM_EVENTS_SINGLE_DELIVERY = 'true'
+    let resolved: unknown = null
+    const bus = createEventBus({ resolve: ((name: string) => `bus:${name}`) as never })
+    bus.on('user.created', (_payload, ctx) => { resolved = ctx.resolve('em') }, { persistent: true })
+
+    await bus.dispatchQueued('user.created', {})
+
+    expect(resolved).toBe('bus:em')
+  })
+
+  test('returns an empty result set when nothing matches', async () => {
+    process.env.OM_EVENTS_SINGLE_DELIVERY = 'true'
+    const bus = makeBus([makeSub('other', 'user.deleted', true, [])])
+
+    expect(await bus.dispatchQueued('user.created', {})).toEqual([])
+  })
+})

package/src/__tests__/queued-delivery-roundtrip.test.ts

@@ -0,0 +1,178 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import { createEventBus } from '@open-mercato/events/index'
+import handle from '@open-mercato/events/modules/events/workers/events.worker'
+import type { EventBus } from '@open-mercato/events/types'
+
+/**
+ * Full round trip: persistent emit -> local file queue -> events worker -> subscriber,
+ * in a process where the CLI module registry was NEVER registered.
+ *
+ * That is the exact shape of the bug this suite pins. The worker used to build its
+ * subscriber map from `getCliModules()`, which only the `mercato` bin populates, so
+ * this round trip ended with the job marked COMPLETED and the subscriber never run -
+ * silently, because the bus had already skipped it inline under single-delivery.
+ */
+describe('queued persistent delivery round trip (no CLI module registry)', () => {
+  const origCwd = process.cwd()
+  const origExternalWorker = process.env.OM_EVENTS_EXTERNAL_WORKER
+  const origFlag = process.env.OM_EVENTS_SINGLE_DELIVERY
+  const origStrategy = process.env.QUEUE_STRATEGY
+  let tmp: string
+
+  beforeEach(() => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'events-roundtrip-'))
+    process.chdir(tmp)
+    process.env.OM_EVENTS_EXTERNAL_WORKER = 'true'
+    delete process.env.OM_EVENTS_SINGLE_DELIVERY
+    delete process.env.QUEUE_STRATEGY
+  })
+
+  afterEach(() => {
+    process.chdir(origCwd)
+    if (origExternalWorker === undefined) {
+      delete process.env.OM_EVENTS_EXTERNAL_WORKER
+    }
+    else {
+      process.env.OM_EVENTS_EXTERNAL_WORKER = origExternalWorker
+    }
+    if (origFlag === undefined) {
+      delete process.env.OM_EVENTS_SINGLE_DELIVERY
+    }
+    else {
+      process.env.OM_EVENTS_SINGLE_DELIVERY = origFlag
+    }
+    if (origStrategy === undefined) {
+      delete process.env.QUEUE_STRATEGY
+    }
+    else {
+      process.env.QUEUE_STRATEGY = origStrategy
+    }
+    try { fs.rmSync(tmp, { recursive: true, force: true }) } catch {}
+  })
+
+  function readQueuedJobs(): Array<{ id: string; payload: unknown }> {
+    const queueFile = path.join(path.resolve('.mercato/queue', 'events'), 'queue.json')
+    return JSON.parse(fs.readFileSync(queueFile, 'utf8'))
+  }
+
+  // Mirrors the context `createPerJobWorkerHandler` builds: `resolve` bound to a
+  // per-job request container that carries the bootstrapped event bus.
+  function workerContext(bus: EventBus) {
+    return {
+      jobId: 'job-1',
+      attemptNumber: 1,
+      queueName: 'events',
+      resolve: <T = unknown>(name: string): T => {
+        if (name === 'eventBus') {
+          return bus as unknown as T
+        }
+        throw new Error(`No mock for ${name}`)
+      },
+    }
+  }
+
+  it('delivers a wildcard persistent subscriber that inline delivery deliberately skipped', async () => {
+    const ran: Array<{ event?: string; payload: unknown; tenantId?: string | null }> = []
+    const bus = createEventBus({ resolve: ((name: string) => name) as never })
+    bus.registerModuleSubscribers([
+      {
+        id: 'webhooks:outbound-dispatch',
+        event: '*',
+        persistent: true,
+        handler: (payload, ctx) => {
+          ran.push({ event: ctx.eventName, payload, tenantId: ctx.tenantId })
+        },
+      },
+    ])
+
+    await bus.emit('customers.deal.won', { id: 'deal-9' }, { persistent: true, tenantId: 't1' })
+
+    // Single-delivery intends the inline skip; the worker is the sole dispatcher.
+    expect(ran).toEqual([])
+
+    const jobs = readQueuedJobs()
+    expect(jobs).toHaveLength(1)
+
+    await handle(jobs[0] as never, workerContext(bus) as never)
+
+    expect(ran).toEqual([
+      { event: 'customers.deal.won', payload: { id: 'deal-9' }, tenantId: 't1' },
+    ])
+  })
+
+  it('fails the job loudly when the worker container carries no event bus', async () => {
+    const bus = createEventBus({ resolve: ((name: string) => name) as never })
+    bus.registerModuleSubscribers([
+      { id: 'sub', event: '*', persistent: true, handler: () => {} },
+    ])
+
+    await bus.emit('customers.deal.won', { id: 'deal-9' }, { persistent: true })
+    const [job] = readQueuedJobs()
+
+    const contextWithoutBus = {
+      jobId: 'job-1',
+      attemptNumber: 1,
+      queueName: 'events',
+      resolve: <T = unknown>(name: string): T => { throw new Error(`No mock for ${name}`) },
+    }
+
+    await expect(handle(job as never, contextWithoutBus as never)).rejects.toThrow(
+      /no "eventBus" in the job container/,
+    )
+  })
+
+  it('does not re-run subscribers the emitting process already delivered inline', async () => {
+    // Explicit opt-out: the producer delivers inline and stamps the job, so a
+    // worker draining the queue must skip it.
+    process.env.OM_EVENTS_SINGLE_DELIVERY = 'false'
+    const ran: string[] = []
+    const bus = createEventBus({ resolve: ((name: string) => name) as never })
+    bus.registerModuleSubscribers([
+      { id: 'sub', event: 'customers.deal.won', persistent: true, handler: () => { ran.push('sub') } },
+    ])
+
+    await bus.emit('customers.deal.won', { id: 'deal-9' }, { persistent: true })
+    expect(ran).toEqual(['sub'])
+
+    const [job] = readQueuedJobs()
+    await handle(job as never, workerContext(bus) as never)
+
+    expect(ran).toEqual(['sub'])
+  })
+
+  it('fails the job when a subscriber rejects with an undefined reason', async () => {
+    const bus = createEventBus({ resolve: ((name: string) => name) as never })
+    bus.registerModuleSubscribers([
+      { id: 'silent', event: '*', persistent: true, handler: () => { throw undefined } },
+    ])
+
+    await bus.emit('customers.deal.won', { id: 'deal-9' }, { persistent: true })
+    const [job] = readQueuedJobs()
+
+    await expect(handle(job as never, workerContext(bus) as never)).rejects.toThrow(
+      '[internal] 1/1 subscriber(s) failed for event "customers.deal.won": silent',
+    )
+  })
+
+  it('surfaces a failing subscriber so the queue retries the job', async () => {
+    const bus = createEventBus({ resolve: ((name: string) => name) as never })
+    bus.registerModuleSubscribers([
+      {
+        id: 'flaky',
+        event: '*',
+        persistent: true,
+        handler: () => { throw new Error('downstream unavailable') },
+      },
+    ])
+
+    await bus.emit('customers.deal.won', { id: 'deal-9' }, { persistent: true })
+    const [job] = readQueuedJobs()
+
+    await expect(handle(job as never, workerContext(bus) as never)).rejects.toThrow(
+      '[internal] 1/1 subscriber(s) failed for event "customers.deal.won": flaky',
+    )
+  })
+})

package/src/__tests__/single-delivery.test.ts

@@ -13,6 +13,7 @@ import type { SubscriberDescriptor } from '@open-mercato/events/types'
 describe('Event bus single-delivery (OM_EVENTS_SINGLE_DELIVERY)', () => {
   const origCwd = process.cwd()
   const origFlag = process.env.OM_EVENTS_SINGLE_DELIVERY
+  const origAutoSpawn = process.env.AUTO_SPAWN_WORKERS
   let tmp: string
 
   beforeEach(() => {
@@ -20,12 +21,21 @@ describe('Event bus single-delivery (OM_EVENTS_SINGLE_DELIVERY)', () => {
     process.chdir(tmp)
     delete process.env.QUEUE_STRATEGY
     delete process.env.EVENTS_STRATEGY
+    delete process.env.AUTO_SPAWN_WORKERS
   })
 
+  function restoreEnv(name: string, original: string | undefined): void {
+    if (original === undefined) {
+      delete process.env[name]
+      return
+    }
+    process.env[name] = original
+  }
+
   afterEach(() => {
     process.chdir(origCwd)
-    if (origFlag === undefined) delete process.env.OM_EVENTS_SINGLE_DELIVERY
-    else process.env.OM_EVENTS_SINGLE_DELIVERY = origFlag
+    restoreEnv('OM_EVENTS_SINGLE_DELIVERY', origFlag)
+    restoreEnv('AUTO_SPAWN_WORKERS', origAutoSpawn)
     try { fs.rmSync(tmp, { recursive: true, force: true }) } catch {}
   })
 
@@ -38,7 +48,12 @@ describe('Event bus single-delivery (OM_EVENTS_SINGLE_DELIVERY)', () => {
     return { id, event, persistent, handler: () => { sink.push(id) } }
   }
 
-  test('default (unset): a persistent subscriber is skipped inline (single-delivery is default-on)', async () => {
+  function readQueuedJobs(): Array<Record<string, unknown>> {
+    const queuePath = path.join(path.resolve('.mercato/queue', 'events'), 'queue.json')
+    return JSON.parse(fs.readFileSync(queuePath, 'utf8')) as Array<Record<string, unknown>>
+  }
+
+  test('flag unset (default on): a persistent subscriber is skipped inline', async () => {
     delete process.env.OM_EVENTS_SINGLE_DELIVERY
     const calls: string[] = []
     const bus = createEventBus({ resolve: ((name: string) => name) as never })
@@ -52,6 +67,7 @@ describe('Event bus single-delivery (OM_EVENTS_SINGLE_DELIVERY)', () => {
     // Default-on: the persistent subscriber is deferred to the worker; only the
     // ephemeral subscriber runs inline.
     expect(calls).toEqual(['ephemeral-sub'])
+    expect(readQueuedJobs()[0].payload).toMatchObject({ persistentDeliveredInline: false })
   })
 
   test('flag explicitly OFF (legacy opt-out): a persistent subscriber still runs inline', async () => {
@@ -62,8 +78,44 @@ describe('Event bus single-delivery (OM_EVENTS_SINGLE_DELIVERY)', () => {
 
     await bus.emit('demo', { a: 1 }, { persistent: true })
 
-    // Legacy dual-dispatch: inline delivery is preserved when explicitly opted out.
+    // Explicit opt-out: subscribers run inline. Not dual-dispatch - the queued job
+    // carries the stamp, so a worker draining the queue skips it.
     expect(calls).toEqual(['persistent-sub'])
+    expect(readQueuedJobs()[0].payload).toMatchObject({ persistentDeliveredInline: true })
+  })
+
+  test('flag OFF: a failed inline persistent subscriber leaves the job unstamped for the worker', async () => {
+    // Inline delivery logs-and-continues, so a persistent subscriber that throws
+    // there gets no retry of its own. Stamping the job would strand it: the
+    // worker would skip a job whose only run failed, silently downgrading
+    // persistent delivery to at-most-once. Leaving it unstamped hands the retry
+    // back to the queue.
+    process.env.OM_EVENTS_SINGLE_DELIVERY = 'false'
+    const bus = createEventBus({ resolve: ((name: string) => name) as never })
+    bus.registerModuleSubscribers([
+      { id: 'boom', event: 'demo', persistent: true, handler: () => { throw new Error('downstream down') } },
+    ])
+
+    await bus.emit('demo', { a: 1 }, { persistent: true })
+
+    expect(readQueuedJobs()[0].payload).toMatchObject({ persistentDeliveredInline: false })
+  })
+
+  test('flag OFF: a failed EPHEMERAL subscriber does not unstamp the job', async () => {
+    // Ephemeral subscribers are never worker-dispatched, so their failure must
+    // not hand the job to the worker - that would re-run the persistent ones.
+    process.env.OM_EVENTS_SINGLE_DELIVERY = 'false'
+    const calls: string[] = []
+    const bus = createEventBus({ resolve: ((name: string) => name) as never })
+    bus.registerModuleSubscribers([
+      { id: 'ephemeral-boom', event: 'demo', persistent: false, handler: () => { throw new Error('nope') } },
+      makeSub('persistent-ok', 'demo', true, calls),
+    ])
+
+    await bus.emit('demo', { a: 1 }, { persistent: true })
+
+    expect(calls).toEqual(['persistent-ok'])
+    expect(readQueuedJobs()[0].payload).toMatchObject({ persistentDeliveredInline: true })
   })
 
   test('flag ON: a persistent subscriber is skipped inline (deferred to the worker)', async () => {
@@ -96,7 +148,6 @@ describe('Event bus single-delivery (OM_EVENTS_SINGLE_DELIVERY)', () => {
 
   test('flag ON: persistent emit is still enqueued for the worker', async () => {
     process.env.OM_EVENTS_SINGLE_DELIVERY = 'true'
-    const queuePath = path.join(path.resolve('.mercato/queue', 'events'), 'queue.json')
     const calls: string[] = []
     const bus = createEventBus({ resolve: ((name: string) => name) as never })
     bus.registerModuleSubscribers([makeSub('persistent-sub', 'demo', true, calls)])
@@ -104,9 +155,10 @@ describe('Event bus single-delivery (OM_EVENTS_SINGLE_DELIVERY)', () => {
     await bus.emit('demo', { a: 1 }, { persistent: true })
 
     expect(calls).toEqual([])
-    const list = JSON.parse(fs.readFileSync(queuePath, 'utf8'))
+    const list = readQueuedJobs()
     expect(Array.isArray(list)).toBe(true)
     expect(list.length).toBeGreaterThanOrEqual(1)
+    expect(list[0].payload).toMatchObject({ persistentDeliveredInline: false })
   })
 
   test('flag ON: the queued job keeps the trusted scope from the emit options', async () => {
@@ -178,6 +230,9 @@ describe('Event bus enqueue-only persistent emit (deliverInline: false)', () =>
     const list = JSON.parse(fs.readFileSync(queuePath, 'utf8'))
     expect(Array.isArray(list)).toBe(true)
     expect(list.length).toBeGreaterThanOrEqual(1)
+    // Enqueue-only never delivers inline, so the worker must still dispatch it
+    // even though this process has no worker-availability signal.
+    expect(list[0].payload).toMatchObject({ persistentDeliveredInline: false })
   })
 
   test('deliverInline: false has no effect on a non-persistent emit', async () => {
@@ -191,10 +246,10 @@ describe('Event bus enqueue-only persistent emit (deliverInline: false)', () =>
     expect(calls).toEqual(['sub'])
   })
 
-  test('deliverInline unset under legacy opt-out preserves inline dual-dispatch', async () => {
+  test('deliverInline unset under explicit opt-out preserves inline delivery', async () => {
     // Isolate the deliverInline default from the single-delivery default by
     // explicitly opting out: a persistent emit with deliverInline unset still
-    // runs inline (legacy dual-dispatch).
+    // runs inline.
     process.env.OM_EVENTS_SINGLE_DELIVERY = 'false'
     const calls: string[] = []
     const bus = createEventBus({ resolve: ((name: string) => name) as never })