@znight/messaging 0.0.0-stage → 0.1.0

package/src/consumers.ts

@@ -0,0 +1,260 @@
+/**
+ * Preparation and validation of the consumers declared in the metadata (boot time, ZNIGHT011).
+ */
+import type { Container, Token } from '@znight/core'
+import type { MessagingDriver } from './driver.ts'
+import type { ConsumerDefinition, MessageHandlerDefinition, MessagingMetadata } from './metadata.ts'
+import type { RetryOptions, RetryPolicy } from './retry.ts'
+
+import { displayName } from '@znight/core'
+
+import { consumerError } from './errors.ts'
+import { isPositiveInteger } from './internal/async.ts'
+import {
+  assertRetrySupported,
+  DEFAULT_RETRY_POLICY,
+  isInProcessDelay,
+  NO_RETRY_POLICY,
+  normalizeRetry,
+  retryDelays,
+} from './retry.ts'
+
+/** A handler ready to be dispatched to. */
+export interface PreparedHandler {
+  readonly definition: MessageHandlerDefinition
+  readonly method: string
+  readonly policy: RetryPolicy
+}
+
+/** A validated consumer. */
+export interface PreparedConsumer {
+  readonly definition: ConsumerDefinition
+  readonly token: Token
+  /** Display name of the consumer class. */
+  readonly name: string
+  readonly queue: string
+  readonly concurrency: number
+  readonly deadLetterQueue: string | undefined
+  readonly errorHandler: string | undefined
+  readonly maxAttempts: number
+  /** Native delays the runtime may request (sorted, unique). */
+  readonly retryDelays: readonly number[]
+  readonly driverOptions: Readonly<Record<string, unknown>>
+  /** Selects the handler of a message type (exact, then patterns, then the default handler). */
+  select(type: string | undefined): PreparedHandler | undefined
+}
+
+/** Plugin-level defaults applied to every consumer. */
+export interface ConsumerDefaults {
+  readonly retry: RetryPolicy
+  readonly concurrency: number
+  readonly deadLetter: ((queue: string) => string) | false | undefined
+}
+
+/** Normalizes `defaults.retry` of the plugin. */
+export function defaultRetryPolicy(retry: RetryOptions | false | undefined): RetryPolicy {
+  if (retry === undefined) return DEFAULT_RETRY_POLICY
+  if (retry === false) return NO_RETRY_POLICY
+  return normalizeRetry(retry, 'MessagingPlugin defaults.retry')
+}
+
+/**
+ * Validates `metadata.extensions.messaging` against the container and the driver capabilities.
+ *
+ * @throws ZnightError ZNIGHT011 describing the first invalid consumer.
+ */
+export function prepareConsumers(
+  metadata: MessagingMetadata | undefined,
+  container: Container,
+  driver: MessagingDriver,
+  defaults: ConsumerDefaults,
+): PreparedConsumer[] {
+  if (metadata === undefined) return []
+  if (metadata === null || typeof metadata !== 'object' || !Array.isArray(metadata.consumers)) {
+    throw consumerError('Invalid messaging metadata: "consumers" must be an array', [
+      'Regenerate the metadata with the @znight/messaging compiler extension',
+    ])
+  }
+  const byQueue = new Map<string, string>()
+  const prepared: PreparedConsumer[] = []
+  for (const definition of metadata.consumers) {
+    const consumer = prepareConsumer(definition, container, driver, defaults)
+    const previous = byQueue.get(consumer.queue)
+    if (previous !== undefined) {
+      throw consumerError(`${previous} and ${consumer.name} both consume "${consumer.queue}"`, [
+        'A queue is consumed by a single @Consumer class: merge the handlers, or route by type with @OnMessage(type)',
+      ])
+    }
+    byQueue.set(consumer.queue, consumer.name)
+    prepared.push(consumer)
+  }
+  return prepared
+}
+
+function prepareConsumer(
+  definition: ConsumerDefinition,
+  container: Container,
+  driver: MessagingDriver,
+  defaults: ConsumerDefaults,
+): PreparedConsumer {
+  if (
+    definition === null ||
+    typeof definition !== 'object' ||
+    typeof definition.token !== 'string' ||
+    definition.token === ''
+  ) {
+    throw consumerError('Invalid consumer definition: missing provider token')
+  }
+  const token = definition.token
+  const name = displayName(token)
+  if (typeof definition.queue !== 'string' || definition.queue === '') {
+    throw consumerError(`@Consumer ${name}: the queue must be a non-empty string`)
+  }
+  if (!container.has(token)) {
+    throw consumerError(`@Consumer ${name}: no provider is registered for ${token}`, [
+      'Regenerate the metadata: the consumer class must be a compiled provider',
+    ])
+  }
+  const options = definition.options ?? {}
+  const { concurrency: rawConcurrency, deadLetter, ...driverOptions } = options
+  const concurrency = rawConcurrency ?? defaults.concurrency
+  if (!isPositiveInteger(concurrency)) {
+    throw consumerError(`@Consumer ${name}: "concurrency" must be a positive integer, got ${String(concurrency)}`)
+  }
+  if (deadLetter !== undefined && deadLetter !== false && (typeof deadLetter !== 'string' || deadLetter === '')) {
+    throw consumerError(`@Consumer ${name}: "deadLetter" must be a queue name or false, got ${String(deadLetter)}`)
+  }
+  if (deadLetter === definition.queue) {
+    throw consumerError(`@Consumer ${name}: the dead-letter queue cannot be the consumed queue "${definition.queue}"`)
+  }
+
+  const handlers = definition.handlers
+  if (!Array.isArray(handlers) || handlers.length === 0) {
+    throw consumerError(`@Consumer ${name} has no @OnMessage handler`, [
+      'Decorate at least one method with @OnMessage()',
+    ])
+  }
+  const exact = new Map<string, PreparedHandler>()
+  const patterns: { readonly regex: RegExp; readonly handler: PreparedHandler }[] = []
+  let fallback: PreparedHandler | undefined
+  let maxAttempts = 1
+  const nativeDelays = new Set<number>()
+  for (const handlerDefinition of handlers) {
+    const handler = prepareHandler(handlerDefinition, name, driver, defaults.retry)
+    maxAttempts = Math.max(maxAttempts, handler.policy.attempts)
+    for (const delay of retryDelays(handler.policy)) {
+      if (!isInProcessDelay(delay, driver.capabilities)) nativeDelays.add(delay)
+    }
+    const type = handlerDefinition.type
+    if (type === undefined) {
+      if (fallback !== undefined) {
+        throw consumerError(
+          `@Consumer ${name}: ${fallback.method}() and ${handler.method}() are both default @OnMessage() handlers`,
+          ['Give one of them a message type: @OnMessage("order.created")'],
+        )
+      }
+      fallback = handler
+    } else if (type.includes('*')) {
+      if (patterns.some(entry => entry.handler.definition.type === type)) {
+        throw duplicateType(name, type)
+      }
+      patterns.push({ regex: patternToRegExp(type), handler })
+    } else {
+      if (exact.has(type)) throw duplicateType(name, type)
+      exact.set(type, handler)
+    }
+  }
+
+  const errorHandler = definition.errorHandler
+  if (errorHandler !== undefined) {
+    if (typeof errorHandler !== 'string' || errorHandler === '') {
+      throw consumerError(`@Consumer ${name}: invalid @OnError method name ${String(errorHandler)}`)
+    }
+    const providers = container.metadata.providers
+    const provider = Object.hasOwn(providers, token) ? providers[token] : undefined
+    const prototype = provider?.class?.prototype as Record<string, unknown> | undefined
+    if (prototype !== undefined && typeof prototype[errorHandler] !== 'function') {
+      throw consumerError(`@Consumer ${name}: the @OnError method ${errorHandler}() does not exist`)
+    }
+  }
+
+  return {
+    definition,
+    token,
+    name,
+    queue: definition.queue,
+    concurrency,
+    deadLetterQueue: resolveDeadLetter(definition.queue, deadLetter, defaults.deadLetter, driver),
+    errorHandler,
+    maxAttempts,
+    retryDelays: [...nativeDelays].sort((a, b) => a - b),
+    driverOptions,
+    select(type: string | undefined): PreparedHandler | undefined {
+      if (type === undefined) return fallback
+      const handler = exact.get(type)
+      if (handler !== undefined) return handler
+      for (const entry of patterns) if (entry.regex.test(type)) return entry.handler
+      return fallback
+    },
+  }
+}
+
+function prepareHandler(
+  definition: MessageHandlerDefinition,
+  consumer: string,
+  driver: MessagingDriver,
+  defaultPolicy: RetryPolicy,
+): PreparedHandler {
+  if (
+    definition === null ||
+    typeof definition !== 'object' ||
+    typeof definition.method !== 'string' ||
+    definition.method === ''
+  ) {
+    throw consumerError(`@Consumer ${consumer}: invalid @OnMessage handler definition`)
+  }
+  const where = `${consumer}.${definition.method}()`
+  if (typeof definition.invoke !== 'function') {
+    throw consumerError(`${where}: the handler has no invoker`, ['Regenerate the metadata'])
+  }
+  if (definition.type !== undefined && (typeof definition.type !== 'string' || definition.type === '')) {
+    throw consumerError(`${where}: the @OnMessage type must be a non-empty string`)
+  }
+  const policy = definition.retry === undefined ? defaultPolicy : normalizeRetry(definition.retry, `@Retry on ${where}`)
+  assertRetrySupported(
+    policy,
+    driver.capabilities,
+    driver.name,
+    definition.retry === undefined ? `${where} (default retry policy)` : `@Retry on ${where}`,
+  )
+  return { definition, method: definition.method, policy }
+}
+
+function duplicateType(consumer: string, type: string): Error {
+  return consumerError(`@Consumer ${consumer}: several @OnMessage handlers for type "${type}"`)
+}
+
+/** `order.*` → `/^order\..*$/`: `*` matches any sequence of characters. */
+function patternToRegExp(pattern: string): RegExp {
+  const source = pattern
+    .split('*')
+    .map(part => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
+    .join('.*')
+  return new RegExp(`^${source}$`, 's')
+}
+
+function resolveDeadLetter(
+  queue: string,
+  option: string | false | undefined,
+  defaults: ((queue: string) => string) | false | undefined,
+  driver: MessagingDriver,
+): string | undefined {
+  if (option === false) return undefined
+  if (typeof option === 'string') return option
+  if (defaults === false) return undefined
+  const name = defaults === undefined ? driver.deadLetterName(queue) : defaults(queue)
+  if (typeof name !== 'string' || name === '' || name === queue) {
+    throw consumerError(`Invalid dead-letter queue name for "${queue}": ${String(name)}`)
+  }
+  return name
+}

package/src/decorators.ts

@@ -0,0 +1,131 @@
+/**
+ * Marker decorators of `@znight/messaging`. Like every Znight decorator they do nothing at runtime:
+ * the compiler extension (`@znight/messaging/compiler`) reads them from the source code and generates
+ * `metadata.extensions.messaging`. Arguments marked _static_ must be statically evaluable (literals,
+ * `const` references); _value_ arguments (schemas) may also be references to exported bindings.
+ */
+import type { ClassMarker, MethodMarker, ParameterMarker, Scope } from '@znight/core'
+import type { InboundMessage } from './message.ts'
+import type { RetryOptions } from './retry.ts'
+import type { StandardSchemaV1 } from './standard-schema.ts'
+
+/** Options of {@link Consumer} (static). */
+export interface ConsumerOptions {
+  /** Queue (RabbitMQ, SQS) or topic (Kafka) to consume. */
+  readonly queue: string
+  /** Scope of the consumer provider. Default: `singleton`; `request` creates one instance per message. */
+  readonly scope?: Scope
+  /** Maximum number of messages handled concurrently. Default: plugin `defaults.concurrency` (1). */
+  readonly concurrency?: number
+  /** Dead-letter queue/topic, or `false` to disable dead-lettering. Default: driver naming (`<queue>.dlq`). */
+  readonly deadLetter?: string | false
+  /** Driver-specific options (e.g. Kafka `groupId`). */
+  readonly [driverOption: string]: unknown
+}
+
+/** Result of an `@OnError` method: `'ack'` acknowledges (swallows) the message, anything else dead-letters it. */
+// biome-ignore lint/suspicious/noConfusingVoidType: lets error handlers without return statement type-check
+export type ErrorHandlerResult = 'ack' | undefined | void
+
+/**
+ * Signature of an `@OnError` method. Declared as a method signature so that parameters may be
+ * narrowed (`onError(error: Error, message: InboundMessage<Order>)`).
+ */
+export type ErrorHandlerMethod = ErrorHandlerSignature['onError']
+
+interface ErrorHandlerSignature {
+  onError(error: unknown, message: InboundMessage): ErrorHandlerResult | Promise<ErrorHandlerResult>
+}
+
+/** Marker usable on an `@OnError` method: checks its signature. */
+export type ErrorHandlerMarker = <F extends ErrorHandlerMethod>(
+  target: object,
+  propertyKeyOrContext: string | symbol | ClassMethodDecoratorContext<unknown, F>,
+  descriptor?: TypedPropertyDescriptor<F>,
+) => void
+
+function marker(): void {
+  // intentionally empty: decorators are compile-time markers
+}
+
+const classMarker: ClassMarker = marker
+const methodMarker: MethodMarker = marker
+const parameterMarker: ParameterMarker = marker
+const errorHandlerMarker: ErrorHandlerMarker = marker
+
+/**
+ * Declares a message consumer: a provider (singleton by default) whose `@OnMessage` methods handle
+ * the messages of `queue`. Arguments are static.
+ *
+ * ```ts
+ * @Consumer('orders')
+ * export class OrderConsumer {
+ *   constructor(private readonly orders: OrderService) {}
+ *
+ *   @OnMessage('order.created')
+ *   @Retry({ attempts: 5, backoff: 'exponential', delay: 500 })
+ *   async created(@Message(OrderCreated) event: OrderCreated) {
+ *     await this.orders.process(event)
+ *   }
+ * }
+ * ```
+ */
+export function Consumer(queue: string): ClassMarker
+export function Consumer(options: ConsumerOptions): ClassMarker
+export function Consumer(_queueOrOptions: string | ConsumerOptions): ClassMarker {
+  return classMarker
+}
+
+/**
+ * Declares a message handler. With `type` (static), it handles the messages of that type (exact
+ * match, or a pattern where `*` matches any sequence: `'order.*'`); without type it is the consumer's
+ * default handler (messages without type, or whose type no other handler matches). A message no
+ * handler matches is dead-lettered (reason `no-handler`).
+ */
+export function OnMessage(_type?: string): MethodMarker {
+  return methodMarker
+}
+
+/**
+ * Retry policy of a handler (static options). `attempts` counts the first delivery:
+ * `{ attempts: 3 }` means one delivery plus two retries. Without `@Retry`, the plugin's
+ * `defaults.retry` applies (3 attempts, exponential from 1 s).
+ */
+export function Retry(_options: RetryOptions): MethodMarker {
+  return methodMarker
+}
+
+/**
+ * Declares the consumer's error handler, called once a message will not be retried anymore (last
+ * attempt failed, `NonRetryableError`, invalid payload, no matching handler). Returning `'ack'`
+ * acknowledges the message; returning anything else (or throwing) dead-letters it.
+ *
+ * ```ts
+ * @OnError()
+ * onError(error: unknown, message: InboundMessage) {
+ *   if (message.type?.startsWith('legacy.')) return 'ack'
+ * }
+ * ```
+ */
+export function OnError(): ErrorHandlerMarker {
+  return errorHandlerMarker
+}
+
+/**
+ * Injects the message payload. With a Standard Schema (Zod, Valibot...), the payload is validated and
+ * the parameter receives the schema output; an invalid payload is dead-lettered without retry
+ * (reason `validation`). The schema is a _value_ argument (inline, or an exported binding).
+ */
+export function Message(_schema?: StandardSchemaV1): ParameterMarker {
+  return parameterMarker
+}
+
+/** Injects all the message headers, or the value of one header (`string | undefined`). `name` is static. */
+export function Headers(_name?: string): ParameterMarker {
+  return parameterMarker
+}
+
+/** Injects the {@link InboundMessage} (id, type, attempt, headers, raw message, abort signal...). */
+export function Ctx(): ParameterMarker {
+  return parameterMarker
+}

package/src/driver.ts

@@ -0,0 +1,142 @@
+import type { CoreLogger } from '@znight/core'
+import type { DeadLetterReason, OutboundMessage } from './message.ts'
+
+/**
+ * What a driver can do. `MessagingPlugin` validates every `@Retry` policy against it at boot: a
+ * delay is either waited in-process (`<= maxInProcessDelayMs`) or delegated to the broker
+ * (`nativeDelay`, `<= maxNativeDelayMs`); otherwise the application fails to start (ZNIGHT011).
+ */
+export interface DriverCapabilities {
+  /** The broker can redeliver a message after a delay (SQS visibility, RabbitMQ TTL queue, Kafka retry topic). */
+  readonly nativeDelay: boolean
+  /** Longest native redelivery delay, in milliseconds (`0` without native delay). */
+  readonly maxNativeDelayMs: number
+  /**
+   * Longest delay the runtime may wait in-process while holding a delivery before asking the
+   * broker to redeliver it (the message stays locked: prefetch slot, SQS lease...).
+   */
+  readonly maxInProcessDelayMs: number
+  /**
+   * How attempts are counted: `native` (broker delivery count: SQS `ApproximateReceiveCount`,
+   * RabbitMQ quorum `x-delivery-count`) or `header` (`x-znight-attempt` on republished retries).
+   */
+  readonly deliveryCount: 'native' | 'header'
+  /** Longest `publish(..., { delay })`, in milliseconds (`0`: delayed publishing unsupported). */
+  readonly maxPublishDelayMs: number
+}
+
+/** Services a driver receives when it connects. */
+export interface DriverContext {
+  /** Logger for background failures (polling errors, connection loss...). */
+  readonly logger: CoreLogger
+}
+
+/** Redelivery request of a failed delivery. */
+export interface RetryRequest {
+  /** Attempt number of the redelivery (failed attempt + 1). */
+  readonly attempt: number
+  /** Delay before the redelivery, in milliseconds (`0`: as soon as possible). */
+  readonly delayMs: number
+  /** Error of the failed attempt. */
+  readonly error: unknown
+}
+
+/** Dead-letter request of a delivery. */
+export interface DeadLetterRequest {
+  /**
+   * Destination queue/topic, `undefined` when dead-lettering is disabled for the consumer: the driver
+   * then rejects the message natively (RabbitMQ `nack` without requeue, so a queue DLX applies) or
+   * discards it.
+   */
+  readonly queue: string | undefined
+  readonly reason: DeadLetterReason
+  readonly error: unknown
+  /** Attempts made. */
+  readonly attempt: number
+}
+
+/**
+ * A message received by a driver, with the operations settling it. The runtime calls exactly one
+ * settlement operation (`ack`, `retry`, `deadLetter` or `release`), possibly followed by `release`
+ * when the first one failed. Each operation resolves once the broker acknowledged it.
+ */
+export interface DriverDelivery {
+  readonly id: string
+  readonly body: Uint8Array | string
+  readonly contentType: string | undefined
+  /** Headers as strings (non-string values converted). */
+  readonly headers: Readonly<Record<string, string>>
+  readonly type: string | undefined
+  readonly key: string | undefined
+  /** 1-based attempt of this delivery. */
+  readonly attempt: number
+  readonly redelivered: boolean
+  /** Production time (epoch ms), when known. */
+  readonly timestamp: number | undefined
+  /** Driver-native message. */
+  readonly raw: unknown
+  /** The message was handled: remove it from the queue / commit it. */
+  ack(): Promise<void>
+  /**
+   * Redeliver the message as attempt `request.attempt` after `request.delayMs`. The redelivery must be
+   * durable (confirmed) before the original is acknowledged.
+   */
+  retry(request: RetryRequest): Promise<void>
+  /** Move the message to the dead-letter destination (publish with confirmation, then acknowledge). */
+  deadLetter(request: DeadLetterRequest): Promise<void>
+  /**
+   * Give the message back to the broker for a later redelivery without settling it (shutdown,
+   * failed dead-lettering). Must never lose the message.
+   */
+  release(): Promise<void>
+}
+
+/**
+ * Handles one delivery. The returned promise settles once the delivery was settled: drivers use it
+ * for back-pressure (never more than `concurrency` pending promises per subscription).
+ */
+export type DeliveryHandler = (delivery: DriverDelivery) => Promise<void>
+
+/** Options of {@link MessagingDriver.subscribe}. */
+export interface SubscribeOptions {
+  /** Display name of the consumer class (logs, errors). */
+  readonly consumer: string
+  /** Maximum number of deliveries handled concurrently (prefetch, receive batch size...). */
+  readonly concurrency: number
+  /** Dead-letter destination, `undefined` when disabled. Drivers verify it exists at subscribe time. */
+  readonly deadLetterQueue: string | undefined
+  /** Largest number of attempts among the consumer's handlers (e.g. checked against SQS `maxReceiveCount`). */
+  readonly maxAttempts: number
+  /** Native retry delays (ms) the runtime may request: lets drivers prepare delay queues. Sorted, unique. */
+  readonly retryDelays: readonly number[]
+  /** Driver-specific options of `@Consumer({ queue, ...options })`. */
+  readonly options: Readonly<Record<string, unknown>>
+}
+
+/** An active subscription. */
+export interface Subscription {
+  /** Stops receiving new deliveries. Deliveries already handed to the runtime can still be settled. */
+  cancel(): Promise<void>
+  /** Releases the subscription's resources, once in-flight deliveries settled. Idempotent. */
+  close(): Promise<void>
+}
+
+/**
+ * A broker integration. Drivers live in subpath exports (`@znight/messaging/rabbitmq`, `/sqs`,
+ * `/kafka`, `/memory`) so their client libraries stay optional peers.
+ */
+export interface MessagingDriver {
+  /** Short name (`rabbitmq`, `sqs`, `kafka`, `memory`), exposed as `InboundMessage.driver`. */
+  readonly name: string
+  readonly capabilities: DriverCapabilities
+  /** Connects to the broker (called in `onBootstrap`). */
+  connect(context: DriverContext): Promise<void>
+  /** Starts consuming `queue`. Verifies the destination and its dead-letter configuration. */
+  subscribe(queue: string, handler: DeliveryHandler, options: SubscribeOptions): Promise<Subscription>
+  /** Publishes a message; resolves once the broker confirmed it. */
+  publish(queue: string, message: OutboundMessage): Promise<void>
+  /** Closes every subscription and the connection. Idempotent. */
+  close(): Promise<void>
+  /** Default dead-letter destination of `queue` (`orders.dlq`, `orders-dlq`...). */
+  deadLetterName(queue: string): string
+}