@open-mercato/webhooks 0.6.7-develop.6726.1.983ae8a07e → 0.6.7-develop.6749.1.6b54c56dfe

package/src/modules/webhooks/lib/__tests__/module-webhook-registry.test.ts

@@ -0,0 +1,53 @@
+import type { WebhookHandler } from '@open-mercato/shared/lib/webhooks'
+import {
+  registerWebhookHandlerEntries,
+  registerWebhookSourceEntries,
+} from '../module-webhook-registry'
+import {
+  clearWebhookHandlers,
+  clearWebhookSources,
+  listWebhookHandlers,
+  listWebhookSources,
+} from '../inbound-registry'
+
+const noopHandler: WebhookHandler = async () => undefined
+
+beforeEach(() => {
+  clearWebhookSources()
+  clearWebhookHandlers()
+})
+
+it('flattens module source entries into the source registry', () => {
+  registerWebhookSourceEntries([
+    {
+      moduleId: 'gateway_stripe',
+      sources: [
+        { key: 'stripe', label: 'Stripe', verifier: async () => true, eventTypeExtractor: () => '' },
+      ],
+    },
+    { moduleId: 'inbox_ops', sources: [
+      { key: 'resend', label: 'Resend', verifier: async () => true, eventTypeExtractor: () => '' },
+    ] },
+  ])
+  expect(listWebhookSources().map((s) => s.key).sort()).toEqual(['resend', 'stripe'])
+})
+
+it('flattens module handler entries into the handler registry', () => {
+  registerWebhookHandlerEntries([
+    {
+      moduleId: 'gateway_stripe',
+      handlers: [
+        { meta: { source: 'stripe', event: 'payment_intent.succeeded', id: 'a' }, handler: async () => ({ default: noopHandler }) },
+        { meta: { source: 'stripe', event: 'charge.refunded', id: 'b' }, handler: async () => ({ default: noopHandler }) },
+      ],
+    },
+  ])
+  expect(listWebhookHandlers().map((e) => e.meta.id).sort()).toEqual(['a', 'b'])
+})
+
+it('tolerates entries with no sources/handlers', () => {
+  registerWebhookSourceEntries([{ moduleId: 'empty', sources: [] }])
+  registerWebhookHandlerEntries([{ moduleId: 'empty', handlers: [] }])
+  expect(listWebhookSources()).toEqual([])
+  expect(listWebhookHandlers()).toEqual([])
+})

package/src/modules/webhooks/lib/inbound-dispatch.ts

@@ -0,0 +1,147 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type {
+  WebhookHandlerContext,
+  WebhookHandlerPayload,
+  WebhookHandlerResult,
+} from '@open-mercato/shared/lib/webhooks'
+import { WebhookIngestionEntity } from '../data/entities'
+import { emitWebhooksEvent } from '../events'
+import { resolveWebhookHandlers } from './inbound-registry'
+
+const MAX_HANDLER_RESULTS = 50
+const MAX_ERROR_MESSAGE_LENGTH = 1024
+
+export type InboundDispatchJob = {
+  ingestionId: string
+  sourceKey: string
+  eventType: string
+  tenantId: string
+  organizationId: string
+}
+
+function truncateError(message: string): string {
+  return message.length > MAX_ERROR_MESSAGE_LENGTH
+    ? `${message.slice(0, MAX_ERROR_MESSAGE_LENGTH)}…`
+    : message
+}
+
+function moduleOfHandler(handlerId: string): string {
+  const separatorIndex = handlerId.indexOf(':')
+  return separatorIndex > 0 ? handlerId.slice(0, separatorIndex) : handlerId
+}
+
+/**
+ * Process a queued inbound-dispatch job: load the ingestion, run every matching
+ * handler independently (a failing handler never blocks the others), record
+ * per-handler results, and emit lifecycle events. The payload and headers are
+ * read from the (decrypted) ingestion row rather than carried on the job, so the
+ * queue never stores the raw webhook body. Idempotent — a job whose ingestion is
+ * already `processed` returns early, and a retry after a partial failure re-runs
+ * only the handlers that have not already succeeded.
+ */
+export async function processInboundDispatchJob(
+  em: EntityManager,
+  job: InboundDispatchJob,
+  ctx: WebhookHandlerContext,
+): Promise<void> {
+  const startedAtMs = Date.now()
+  const ingestion = await findOneWithDecryption(
+    em,
+    WebhookIngestionEntity,
+    {
+      id: job.ingestionId,
+      tenantId: job.tenantId,
+      organizationId: job.organizationId,
+    },
+    {},
+  )
+
+  if (!ingestion || ingestion.status === 'processed') return
+
+  ingestion.status = 'processing'
+  await em.flush()
+
+  const handlers = resolveWebhookHandlers(job.sourceKey, job.eventType)
+  const payload: WebhookHandlerPayload = {
+    data: ingestion.payload,
+    eventType: job.eventType,
+    sourceKey: job.sourceKey,
+    headers: ingestion.headers ?? {},
+    ingestionId: job.ingestionId,
+    tenantId: job.tenantId,
+    organizationId: job.organizationId,
+  }
+
+  const previousResults = Array.isArray(ingestion.handlerResults) ? ingestion.handlerResults : []
+  const alreadySucceeded = new Map(
+    previousResults
+      .filter((result) => result?.status === 'success')
+      .map((result) => [result.handlerId, result]),
+  )
+
+  const results: WebhookHandlerResult[] = []
+  let failedCount = 0
+
+  for (const entry of handlers) {
+    const previousSuccess = alreadySucceeded.get(entry.meta.id)
+    if (previousSuccess) {
+      results.push(previousSuccess)
+      continue
+    }
+
+    const handlerStartedMs = Date.now()
+    const handlerStartedAt = new Date(handlerStartedMs).toISOString()
+    try {
+      const mod = await entry.handler()
+      await mod.default(payload, ctx)
+      results.push({
+        handlerId: entry.meta.id,
+        module: moduleOfHandler(entry.meta.id),
+        status: 'success',
+        durationMs: Date.now() - handlerStartedMs,
+        startedAt: handlerStartedAt,
+      })
+    } catch (error) {
+      failedCount += 1
+      const message = truncateError(error instanceof Error ? error.message : String(error))
+      results.push({
+        handlerId: entry.meta.id,
+        module: moduleOfHandler(entry.meta.id),
+        status: 'failed',
+        errorMessage: message,
+        durationMs: Date.now() - handlerStartedMs,
+        startedAt: handlerStartedAt,
+      })
+      await emitWebhooksEvent('webhooks.inbound.handler_failed', {
+        ingestionId: job.ingestionId,
+        sourceKey: job.sourceKey,
+        eventType: job.eventType,
+        handlerId: entry.meta.id,
+        errorMessage: message,
+        tenantId: job.tenantId,
+        organizationId: job.organizationId,
+      })
+    }
+  }
+
+  ingestion.handlerCount = handlers.length
+  ingestion.handlerResults = results.slice(0, MAX_HANDLER_RESULTS)
+  ingestion.status = failedCount > 0 ? 'failed' : 'processed'
+  ingestion.processedAt = new Date()
+  ingestion.durationMs = Date.now() - startedAtMs
+  ingestion.errorMessage = failedCount > 0
+    ? `${failedCount}/${handlers.length} handlers failed`
+    : null
+  await em.flush()
+
+  await emitWebhooksEvent('webhooks.inbound.processed', {
+    ingestionId: job.ingestionId,
+    sourceKey: job.sourceKey,
+    eventType: job.eventType,
+    handlerCount: handlers.length,
+    failedCount,
+    tenantId: job.tenantId,
+    organizationId: job.organizationId,
+  })
+}

package/src/modules/webhooks/lib/inbound-registry.ts

@@ -0,0 +1,92 @@
+import { matchWebhookEventPattern } from '@open-mercato/shared/lib/events/patterns'
+import type {
+  WebhookHandlerRegistryEntry,
+  WebhookSourceConfig,
+} from '@open-mercato/shared/lib/webhooks'
+
+const WEBHOOK_SOURCES_KEY = '__openMercatoWebhookSources__'
+const WEBHOOK_HANDLERS_KEY = '__openMercatoWebhookHandlers__'
+
+type GlobalState = typeof globalThis & {
+  [WEBHOOK_SOURCES_KEY]?: Map<string, WebhookSourceConfig>
+  [WEBHOOK_HANDLERS_KEY]?: WebhookHandlerRegistryEntry[]
+}
+
+function getSourceRegistry(): Map<string, WebhookSourceConfig> {
+  const globalState = globalThis as GlobalState
+  if (!globalState[WEBHOOK_SOURCES_KEY]) {
+    globalState[WEBHOOK_SOURCES_KEY] = new Map<string, WebhookSourceConfig>()
+  }
+  return globalState[WEBHOOK_SOURCES_KEY]
+}
+
+function getHandlerRegistry(): WebhookHandlerRegistryEntry[] {
+  const globalState = globalThis as GlobalState
+  if (!globalState[WEBHOOK_HANDLERS_KEY]) {
+    globalState[WEBHOOK_HANDLERS_KEY] = []
+  }
+  return globalState[WEBHOOK_HANDLERS_KEY]
+}
+
+export function registerWebhookSource(config: WebhookSourceConfig): () => void {
+  const registry = getSourceRegistry()
+  registry.set(config.key, config)
+  return () => {
+    if (registry.get(config.key) === config) registry.delete(config.key)
+  }
+}
+
+export function setWebhookSources(configs: WebhookSourceConfig[]): void {
+  const registry = getSourceRegistry()
+  registry.clear()
+  for (const config of configs) registry.set(config.key, config)
+}
+
+export function getWebhookSource(sourceKey: string): WebhookSourceConfig | undefined {
+  return getSourceRegistry().get(sourceKey)
+}
+
+export function listWebhookSources(): WebhookSourceConfig[] {
+  return Array.from(getSourceRegistry().values())
+}
+
+export function clearWebhookSources(): void {
+  getSourceRegistry().clear()
+}
+
+export function registerWebhookHandler(entry: WebhookHandlerRegistryEntry): () => void {
+  const registry = getHandlerRegistry()
+  registry.push(entry)
+  return () => {
+    const index = registry.indexOf(entry)
+    if (index >= 0) registry.splice(index, 1)
+  }
+}
+
+export function setWebhookHandlers(entries: WebhookHandlerRegistryEntry[]): void {
+  const registry = getHandlerRegistry()
+  registry.length = 0
+  registry.push(...entries)
+}
+
+export function listWebhookHandlers(): WebhookHandlerRegistryEntry[] {
+  return [...getHandlerRegistry()]
+}
+
+export function clearWebhookHandlers(): void {
+  getHandlerRegistry().length = 0
+}
+
+/**
+ * Resolve the handlers that match an inbound webhook's source key and event type.
+ * Event matching reuses the outbound prefix-wildcard semantics (`*`, `payment_intent.*`).
+ */
+export function resolveWebhookHandlers(
+  sourceKey: string,
+  eventType: string,
+): WebhookHandlerRegistryEntry[] {
+  return getHandlerRegistry().filter((entry) => {
+    if (entry.meta.source !== sourceKey) return false
+    return matchWebhookEventPattern(eventType, entry.meta.event)
+  })
+}

package/src/modules/webhooks/lib/module-webhook-registry.ts

@@ -0,0 +1,33 @@
+import type {
+  WebhookHandlerRegistryEntry,
+  WebhookSourceConfig,
+} from '@open-mercato/shared/lib/webhooks'
+import { setWebhookHandlers, setWebhookSources } from './inbound-registry'
+
+export type WebhookSourceModuleEntry = {
+  moduleId: string
+  sources: WebhookSourceConfig[]
+}
+
+export type WebhookHandlerModuleEntry = {
+  moduleId: string
+  handlers: WebhookHandlerRegistryEntry[]
+}
+
+/**
+ * Bootstrap-time registration for module-declared webhook sources.
+ * Driven by the `webhooks.sources` generator plugin via
+ * `bootstrap-registrations.generated.ts` — modules contribute a
+ * `webhook-sources.ts` and are wired here without bootstrap.ts edits.
+ */
+export function registerWebhookSourceEntries(entries: WebhookSourceModuleEntry[]): void {
+  setWebhookSources(entries.flatMap((entry) => entry.sources ?? []))
+}
+
+/**
+ * Bootstrap-time registration for module-declared webhook handlers.
+ * Driven by the `webhooks.handlers` generator plugin.
+ */
+export function registerWebhookHandlerEntries(entries: WebhookHandlerModuleEntry[]): void {
+  setWebhookHandlers(entries.flatMap((entry) => entry.handlers ?? []))
+}

package/src/modules/webhooks/lib/queue.ts

@@ -2,13 +2,17 @@ import type { EntityManager } from '@mikro-orm/postgresql'
 import { createModuleQueue, type Queue } from '@open-mercato/queue'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 import type { WebhookDeliveryJob } from './delivery'
+import type { InboundDispatchJob } from './inbound-dispatch'
 
 const logger = createLogger('webhooks')
 
 const queues = new Map<string, Queue<WebhookDeliveryJob>>()
+const inboundQueues = new Map<string, Queue<InboundDispatchJob>>()
 const LOCAL_WORKER_PROMISE_KEY = '__openMercatoWebhookLocalWorkerPromise__'
+const LOCAL_INBOUND_WORKER_PROMISE_KEY = '__openMercatoWebhookLocalInboundWorkerPromise__'
 
 export const WEBHOOK_DELIVERIES_QUEUE = 'webhook-deliveries'
+export const WEBHOOK_INBOUND_DISPATCH_QUEUE = 'webhook-inbound-dispatch'
 
 export function getWebhookQueue(queueName: string = WEBHOOK_DELIVERIES_QUEUE): Queue<WebhookDeliveryJob> {
   const existing = queues.get(queueName)
@@ -61,3 +65,59 @@ export async function enqueueWebhookDelivery(job: WebhookDeliveryJob, delayMs?:
   await ensureLocalWebhookQueueWorkerStarted()
   return jobId
 }
+
+export function getInboundDispatchQueue(
+  queueName: string = WEBHOOK_INBOUND_DISPATCH_QUEUE,
+): Queue<InboundDispatchJob> {
+  const existing = inboundQueues.get(queueName)
+  if (existing) return existing
+
+  const concurrency = Math.max(1, Number.parseInt(process.env.WEBHOOK_INBOUND_QUEUE_CONCURRENCY ?? '5', 10) || 5)
+  const created = createModuleQueue<InboundDispatchJob>(queueName, { concurrency })
+
+  inboundQueues.set(queueName, created)
+  return created
+}
+
+async function ensureLocalInboundQueueWorkerStarted(): Promise<void> {
+  if (process.env.QUEUE_STRATEGY === 'async') return
+
+  const globalStore = globalThis as typeof globalThis & {
+    [LOCAL_INBOUND_WORKER_PROMISE_KEY]?: Promise<void>
+  }
+
+  if (globalStore[LOCAL_INBOUND_WORKER_PROMISE_KEY]) {
+    await globalStore[LOCAL_INBOUND_WORKER_PROMISE_KEY]
+    return
+  }
+
+  globalStore[LOCAL_INBOUND_WORKER_PROMISE_KEY] = (async () => {
+    const queue = getInboundDispatchQueue()
+
+    await queue.process(async (job) => {
+      const [{ createRequestContainer }, { processInboundDispatchJob }] = await Promise.all([
+        import('@open-mercato/shared/lib/di/container'),
+        import('./inbound-dispatch'),
+      ])
+
+      const container = await createRequestContainer()
+      const em = (container.resolve('em') as EntityManager).fork()
+      await processInboundDispatchJob(em, job.payload, {
+        resolve: <T,>(name: string) => container.resolve(name) as T,
+      })
+    })
+  })().catch((error) => {
+    delete globalStore[LOCAL_INBOUND_WORKER_PROMISE_KEY]
+    logger.error('Failed to start local inbound dispatch worker', { err: error })
+    throw error
+  })
+
+  await globalStore[LOCAL_INBOUND_WORKER_PROMISE_KEY]
+}
+
+export async function enqueueInboundDispatch(job: InboundDispatchJob): Promise<string> {
+  const queue = getInboundDispatchQueue()
+  const jobId = await queue.enqueue(job)
+  await ensureLocalInboundQueueWorkerStarted()
+  return jobId
+}