@znight/messaging 0.0.0-stage → 0.1.1

package/src/errors.ts

@@ -0,0 +1,95 @@
+import { ErrorCode, ZnightError } from '@znight/core'
+
+const NON_RETRYABLE = Symbol.for('znight.messaging.nonRetryable')
+
+/**
+ * Thrown by a handler to dead-letter the message immediately, without further attempts (invalid
+ * business data, permanent failure...). Subclass it for domain errors.
+ *
+ * ```ts
+ * if (order.total < 0) throw new NonRetryableError('Negative order total')
+ * ```
+ */
+export class NonRetryableError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'NonRetryableError'
+  }
+}
+Object.defineProperty(NonRetryableError.prototype, NON_RETRYABLE, { value: true })
+
+/**
+ * Whether retrying `error` is pointless: a {@link NonRetryableError} (also recognised across copies of
+ * this package, through a global symbol brand).
+ */
+export function isNonRetryable(error: unknown): boolean {
+  return (
+    error instanceof NonRetryableError ||
+    (error !== null && typeof error === 'object' && (error as Record<symbol, unknown>)[NON_RETRYABLE] === true)
+  )
+}
+
+/** One failed check of a `@Message(schema)` validation. */
+export interface MessageValidationIssue {
+  /** Dotted path of the invalid value (`items.0.quantity`), empty for the root. */
+  readonly path: string
+  readonly message: string
+}
+
+/** The payload does not match the `@Message(schema)` of the handler. Never retried. */
+export class MessageValidationError extends NonRetryableError {
+  readonly issues: readonly MessageValidationIssue[]
+
+  constructor(label: string, issues: readonly MessageValidationIssue[]) {
+    super(`Invalid ${label}: ${formatIssues(issues)}`)
+    this.name = 'MessageValidationError'
+    this.issues = issues
+  }
+}
+
+/** The body cannot be decoded (malformed JSON...). Never retried. */
+export class MessageDecodeError extends NonRetryableError {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'MessageDecodeError'
+  }
+}
+
+/** No `@OnMessage` handler of the consumer matches the message type. Never retried. */
+export class NoHandlerError extends NonRetryableError {
+  readonly messageType: string | undefined
+
+  constructor(consumer: string, type: string | undefined) {
+    super(
+      type === undefined
+        ? `${consumer} has no default @OnMessage() handler for a message without type`
+        : `${consumer} has no @OnMessage handler for message type "${type}"`,
+    )
+    this.name = 'NoHandlerError'
+    this.messageType = type
+  }
+}
+
+/** A delivery arrived after its last allowed attempt (e.g. redelivered after a dead-letter failure). */
+export class AttemptsExhaustedError extends NonRetryableError {
+  constructor(attempt: number, maxAttempts: number) {
+    super(`Delivery attempt ${attempt} exceeds the ${maxAttempts} attempt(s) allowed by the retry policy`)
+    this.name = 'AttemptsExhaustedError'
+  }
+}
+
+function formatIssues(issues: readonly MessageValidationIssue[]): string {
+  const shown = issues.slice(0, 5).map(issue => (issue.path === '' ? issue.message : `${issue.path}: ${issue.message}`))
+  const more = issues.length > 5 ? ` (+${issues.length - 5} more)` : ''
+  return `${shown.join('; ')}${more}`
+}
+
+/** A messaging configuration error (ZNIGHT011): invalid consumer, retry policy, driver options... */
+export function consumerError(message: string, hints?: readonly string[]): ZnightError {
+  return new ZnightError(ErrorCode.InvalidConsumer, message, hints === undefined ? {} : { hints })
+}
+
+/** An operation on the broker or a driver that is not available (not connected, closed...). */
+export function brokerUnavailableError(message: string, cause?: unknown): ZnightError {
+  return new ZnightError(ErrorCode.LifecycleFailed, message, cause === undefined ? {} : { cause })
+}

package/src/headers.ts

@@ -0,0 +1,70 @@
+/**
+ * Header names used by Znight on the wire. They are plain message headers (AMQP headers, SQS message
+ * attributes, Kafka record headers), so non-Znight producers and consumers can read and write them.
+ */
+export const MessagingHeaders: {
+  /** Znight message id (Kafka and SQS; AMQP uses the `message-id` property). */
+  readonly Id: 'x-znight-id'
+  /** Message type used to select the handler (Kafka and SQS; AMQP uses the `type` property). */
+  readonly Type: 'x-znight-type'
+  /** Content type of the body (Kafka and SQS; AMQP uses the `content-type` property). */
+  readonly ContentType: 'content-type'
+  /** 1-based attempt number carried by republished retries (RabbitMQ, Kafka). */
+  readonly Attempt: 'x-znight-attempt'
+  /** Epoch milliseconds before which a Kafka retry record must not be processed. */
+  readonly NotBefore: 'x-znight-not-before'
+  /** Body encoding when the transport only carries text (SQS: `base64` for binary payloads). */
+  readonly Encoding: 'x-znight-encoding'
+  /** Why the message was dead-lettered (`DeadLetterReason`). */
+  readonly DeadLetterReason: 'x-znight-dead-letter-reason'
+  /** Message of the error that dead-lettered the message (truncated). */
+  readonly Error: 'x-znight-error'
+  /** Queue the dead-lettered message was consumed from. */
+  readonly OriginalQueue: 'x-znight-original-queue'
+  /** Number of attempts made before the message was dead-lettered. */
+  readonly Attempts: 'x-znight-attempts'
+  /** Kafka consumer group that dead-lettered the record. */
+  readonly ConsumerGroup: 'x-znight-consumer-group'
+} = Object.freeze({
+  Id: 'x-znight-id',
+  Type: 'x-znight-type',
+  ContentType: 'content-type',
+  Attempt: 'x-znight-attempt',
+  NotBefore: 'x-znight-not-before',
+  Encoding: 'x-znight-encoding',
+  DeadLetterReason: 'x-znight-dead-letter-reason',
+  Error: 'x-znight-error',
+  OriginalQueue: 'x-znight-original-queue',
+  Attempts: 'x-znight-attempts',
+  ConsumerGroup: 'x-znight-consumer-group',
+})
+
+/** A record safe to fill with untrusted keys (`__proto__` is stored as a regular key). */
+export function headerRecord(): Record<string, string> {
+  return Object.create(null) as Record<string, string>
+}
+
+/**
+ * Reads a header: exact name first, then a case-insensitive match. Used by the code generated for
+ * `@Headers('name')` parameters.
+ */
+export function messageHeader(
+  message: { readonly headers: Readonly<Record<string, string>> },
+  name: string,
+): string | undefined {
+  const headers = message.headers
+  if (Object.hasOwn(headers, name)) return headers[name]
+  const lower = name.toLowerCase()
+  for (const key of Object.keys(headers)) {
+    if (key.toLowerCase() === lower) return headers[key]
+  }
+  return undefined
+}
+
+/** Parses the {@link MessagingHeaders.Attempt} header: a positive integer, `1` when absent or invalid. */
+export function attemptFromHeaders(headers: Readonly<Record<string, string>>): number {
+  const value = Object.hasOwn(headers, MessagingHeaders.Attempt) ? headers[MessagingHeaders.Attempt] : undefined
+  if (value === undefined) return 1
+  const attempt = Number(value)
+  return Number.isSafeInteger(attempt) && attempt >= 1 ? attempt : 1
+}

package/src/hooks.ts

@@ -0,0 +1,2 @@
+/** Instrumentation event of the `messaging:publish` hook (declared in `@znight/core`). */
+export type { MessagePublishEvent } from '@znight/core'

package/src/index.ts

@@ -0,0 +1,89 @@
+export type {
+  DeadLetterRequest,
+  DeliveryHandler,
+  DriverCapabilities,
+  DriverContext,
+  DriverDelivery,
+  MessagingDriver,
+  RetryRequest,
+  SubscribeOptions,
+  Subscription,
+} from './driver.ts'
+export type * from './hooks.ts'
+export type {
+  DeadLetterReason,
+  InboundMessage,
+  OutboundMessage,
+  PublishOptions,
+  PublishResult,
+} from './message.ts'
+export type * from './metadata.ts'
+export type { ConsumerState } from './runtime.ts'
+
+export { MessageBroker } from './broker.ts'
+export {
+  BINARY_CONTENT_TYPE,
+  bodyToBytes,
+  bodyToText,
+  type EncodedBody,
+  JSON_CONTENT_TYPE,
+  jsonCodec,
+  type MessageCodec,
+  mediaType,
+  TEXT_CONTENT_TYPE,
+} from './codec.ts'
+export {
+  Consumer,
+  type ConsumerOptions,
+  Ctx,
+  type ErrorHandlerMarker,
+  type ErrorHandlerMethod,
+  type ErrorHandlerResult,
+  Headers,
+  Message,
+  OnError,
+  OnMessage,
+  Retry,
+} from './decorators.ts'
+export {
+  AttemptsExhaustedError,
+  isNonRetryable,
+  MessageDecodeError,
+  MessageValidationError,
+  type MessageValidationIssue,
+  NoHandlerError,
+  NonRetryableError,
+} from './errors.ts'
+export { attemptFromHeaders, MessagingHeaders, messageHeader } from './headers.ts'
+export {
+  type ConsumerStatus,
+  type MessagingDefaults,
+  MessagingPlugin,
+  type MessagingPluginInstance,
+  type MessagingPluginOptions,
+} from './plugin.ts'
+export {
+  type BackoffStrategy,
+  computeRetryDelay,
+  DEFAULT_BACKOFF,
+  DEFAULT_RETRY_DELAY_MS,
+  DEFAULT_RETRY_POLICY,
+  normalizeRetry,
+  type RetryOptions,
+  type RetryPolicy,
+} from './retry.ts'
+export {
+  type InferSchemaInput,
+  type InferSchemaOutput,
+  isStandardSchema,
+  type StandardSchemaV1,
+  type StandardSchemaV1FailureResult,
+  type StandardSchemaV1Issue,
+  type StandardSchemaV1PathSegment,
+  type StandardSchemaV1Props,
+  type StandardSchemaV1Result,
+  type StandardSchemaV1SuccessResult,
+  type StandardSchemaV1Types,
+} from './standard-schema.ts'
+export { MessagingTokens } from './tokens.ts'
+export { validateMessage } from './validation.ts'

package/src/internal/async.ts

@@ -0,0 +1,115 @@
+/** Internal async helpers (not part of the public API). */
+
+/** Rejection reason of operations interrupted by an `AbortSignal`. */
+export class AbortedError extends Error {
+  constructor(message = 'The operation was aborted') {
+    super(message)
+    this.name = 'AbortError'
+  }
+}
+
+/**
+ * Longest delay of one timer (2^31 - 1 ms, about 24.8 days): longer `setTimeout` delays overflow and
+ * fire after 1 ms. Longer waits chain several timers.
+ */
+export const MAX_TIMER_DELAY_MS = 2_147_483_647
+
+/**
+ * Resolves after `ms` milliseconds (any duration: long waits chain timers), or rejects with
+ * {@link AbortedError} as soon as `signal` aborts.
+ */
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted === true) return Promise.reject(new AbortedError())
+  if (ms <= 0 && signal === undefined) return Promise.resolve()
+  return new Promise((resolve, reject) => {
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const onAbort = (): void => {
+      clearTimeout(timer)
+      reject(new AbortedError())
+    }
+    const arm = (remaining: number): void => {
+      const wait = Math.min(remaining, MAX_TIMER_DELAY_MS)
+      timer = setTimeout(() => {
+        if (remaining > wait) return arm(remaining - wait)
+        signal?.removeEventListener('abort', onAbort)
+        resolve()
+      }, wait)
+    }
+    arm(ms)
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+/**
+ * Counting semaphore. `acquire()` resolves when a permit is available, in FIFO order, or rejects with
+ * {@link AbortedError} when `signal` aborts while waiting.
+ */
+export class Semaphore {
+  #available: number
+  readonly #waiters: { resolve: () => void; reject: (error: unknown) => void }[] = []
+
+  constructor(permits: number) {
+    this.#available = permits
+  }
+
+  /** Permits currently available. */
+  get available(): number {
+    return this.#available
+  }
+
+  /** Number of callers waiting for a permit. */
+  get waiting(): number {
+    return this.#waiters.length
+  }
+
+  acquire(signal?: AbortSignal): Promise<void> {
+    if (signal?.aborted === true) return Promise.reject(new AbortedError())
+    if (this.#available > 0) {
+      this.#available--
+      return Promise.resolve()
+    }
+    return new Promise((resolve, reject) => {
+      const waiter = {
+        resolve: (): void => {
+          signal?.removeEventListener('abort', onAbort)
+          resolve()
+        },
+        reject,
+      }
+      const onAbort = (): void => {
+        const index = this.#waiters.indexOf(waiter)
+        if (index !== -1) this.#waiters.splice(index, 1)
+        reject(new AbortedError())
+      }
+      this.#waiters.push(waiter)
+      signal?.addEventListener('abort', onAbort, { once: true })
+    })
+  }
+
+  release(): void {
+    const next = this.#waiters.shift()
+    if (next === undefined) this.#available++
+    else next.resolve()
+  }
+}
+
+/** Message of any thrown value. */
+export function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message
+  if (typeof error === 'string') return error
+  try {
+    return String(error)
+  } catch {
+    return Object.prototype.toString.call(error)
+  }
+}
+
+/** Truncates `text` to `max` characters (with an ellipsis). */
+export function truncate(text: string, max: number): string {
+  return text.length <= max ? text : `${text.slice(0, Math.max(0, max - 1))}…`
+}
+
+/** Whether `value` is a positive integer. */
+export function isPositiveInteger(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value > 0
+}

package/src/message.ts

@@ -0,0 +1,96 @@
+/**
+ * A message being handled by a consumer. It is the value of the request-scoped external
+ * `@znight/messaging#InboundMessage` during a delivery (inject it into request-scoped providers, or
+ * receive it with `@Ctx()`).
+ *
+ * Delivery is **at-least-once**: the same message may be handled more than once (redelivery after a
+ * crash, a lost ack, a retry...). Handlers must be idempotent; {@link id} is stable across
+ * redeliveries when the producer set it (Znight producers always do).
+ */
+export interface InboundMessage<T = unknown> {
+  /** Message id: set by the producer (`MessageBroker.publish` generates a UUID), stable across redeliveries. */
+  readonly id: string
+  /** Queue (RabbitMQ, SQS) or topic (Kafka) the consumer subscribed to. */
+  readonly queue: string
+  /** Message type used to select the `@OnMessage(type)` handler, `undefined` when the producer set none. */
+  readonly type: string | undefined
+  /** Decoded payload (the schema output when the handler declares `@Message(schema)`). */
+  readonly payload: T
+  /** Message headers. Names are case-sensitive; non-string values are converted to strings. */
+  readonly headers: Readonly<Record<string, string>>
+  /** Partition / ordering key (Kafka record key, SQS FIFO message group), when any. */
+  readonly key: string | undefined
+  /** 1-based delivery attempt (broker delivery count or `x-znight-attempt` header). */
+  readonly attempt: number
+  /** Attempts allowed by the retry policy of the selected handler (`1` without retries). */
+  readonly maxAttempts: number
+  /** Whether the broker flagged the delivery as a redelivery. */
+  readonly redelivered: boolean
+  /** When the message was produced (epoch milliseconds), when the broker reports it. */
+  readonly timestamp: number | undefined
+  /** When this delivery was received (epoch milliseconds). */
+  readonly receivedAt: number
+  /** Content type of the body. */
+  readonly contentType: string | undefined
+  /** Encoded body, as received. */
+  readonly body: Uint8Array | string
+  /** Name of the driver that received the message (`rabbitmq`, `sqs`, `kafka`, `memory`). */
+  readonly driver: string
+  /** Driver-native message (amqplib `ConsumeMessage`, SQS `Message`, Kafka `Message`...). */
+  readonly raw: unknown
+  /** Aborted when the consumer stops: long-running handlers can use it to stop early. */
+  readonly signal: AbortSignal
+}
+
+/** Options of `MessageBroker.publish()`. */
+export interface PublishOptions {
+  /** Message type, used by consumers to select the `@OnMessage(type)` handler. */
+  readonly type?: string
+  /** Additional headers (string values). */
+  readonly headers?: Readonly<Record<string, string>>
+  /** Partition key (Kafka) or message group id (SQS FIFO queues). */
+  readonly key?: string
+  /** Delays the delivery by this many milliseconds (support and maximum depend on the driver). */
+  readonly delay?: number
+  /** Message id. Default: a random UUID. Set it to make publishing idempotent end-to-end. */
+  readonly id?: string
+  /** Content type, when the payload is already encoded (`Uint8Array` or `string`). */
+  readonly contentType?: string
+}
+
+/** Result of `MessageBroker.publish()`. */
+export interface PublishResult {
+  /** Id of the published message. */
+  readonly id: string
+}
+
+/**
+ * A message handed to a driver for publication: the payload is already encoded by the codec. The
+ * driver resolves `publish()` only once the broker confirmed the message (publisher confirms, SQS
+ * response, Kafka acks).
+ */
+export interface OutboundMessage {
+  readonly id: string
+  readonly type: string | undefined
+  readonly key: string | undefined
+  readonly headers: Readonly<Record<string, string>>
+  readonly body: Uint8Array | string
+  readonly contentType: string
+  /** Production time, epoch milliseconds. */
+  readonly timestamp: number
+  /** Requested delivery delay in milliseconds (`0`: immediate). */
+  readonly delayMs: number
+}
+
+/** Why a message was moved to the dead-letter queue (`x-znight-dead-letter-reason` header). */
+export type DeadLetterReason =
+  /** No `@OnMessage` handler matches the message type. */
+  | 'no-handler'
+  /** The body could not be decoded (malformed JSON...). */
+  | 'decode'
+  /** The `@Message(schema)` validation failed. */
+  | 'validation'
+  /** The handler threw a `NonRetryableError`. */
+  | 'non-retryable'
+  /** The last attempt allowed by the retry policy failed. */
+  | 'max-attempts'

package/src/metadata.ts

@@ -0,0 +1,65 @@
+/**
+ * Messaging section of the generated metadata (`__ZNIGHT_METADATA__.extensions.messaging`), produced
+ * by the `@znight/messaging/compiler` extension and consumed by `MessagingPlugin`.
+ * See docs/internals/architecture.md §9.2.
+ */
+import type { Token } from '@znight/core'
+import type { InboundMessage } from './message.ts'
+import type { RetryPolicy } from './retry.ts'
+
+/** Messaging metadata of the application. */
+export interface MessagingMetadata {
+  readonly consumers: readonly ConsumerDefinition[]
+}
+
+/**
+ * Options of a consumer: `concurrency` and `deadLetter` are read by the runtime, every other key is a
+ * driver option (e.g. Kafka `groupId`) forwarded to `MessagingDriver.subscribe`.
+ */
+export interface ConsumerRuntimeOptions {
+  /** Maximum number of messages handled concurrently by this consumer. Default: plugin `defaults.concurrency`. */
+  readonly concurrency?: number
+  /** Dead-letter destination, or `false` to disable dead-lettering. Default: the plugin/driver naming. */
+  readonly deadLetter?: string | false
+  readonly [driverOption: string]: unknown
+}
+
+/** One `@Consumer` class. */
+export interface ConsumerDefinition {
+  /** Provider token of the consumer class. */
+  readonly token: Token
+  /** Queue (RabbitMQ, SQS) or topic (Kafka) consumed. */
+  readonly queue: string
+  /** `@Consumer({ queue, ...options })` without `queue` and `scope`. */
+  readonly options?: ConsumerRuntimeOptions
+  /** `@OnMessage` methods, in declaration order. */
+  readonly handlers: readonly MessageHandlerDefinition[]
+  /** Name of the `@OnError` method, if any: `(error, message) => void | 'ack'`. */
+  readonly errorHandler?: string
+}
+
+/** One `@OnMessage` method. */
+export interface MessageHandlerDefinition {
+  /** Method name (logs, hook events). */
+  readonly method: string
+  /**
+   * `@OnMessage(type)`: the message type handled (exact match, or a pattern where `*` matches any
+   * sequence of characters). Without type, the handler is the consumer's default handler.
+   */
+  readonly type?: string
+  /** `@Retry` policy, normalized. Default: the plugin's `defaults.retry`. */
+  readonly retry?: RetryPolicy
+  /**
+   * Calls the handler: extracts and validates the parameters from the message
+   * (`@Message(schema)` → `validateMessage(schema, m.payload)`, `@Headers(name)` →
+   * `messageHeader(m, name)`, `@Ctx()` → `m`).
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: generated invokers receive the concrete consumer class
+  readonly invoke: (consumer: any, message: InboundMessage) => unknown
+}
+
+declare module '@znight/core' {
+  interface ZnightExtensionsMetadata {
+    readonly messaging?: MessagingMetadata
+  }
+}