@babelqueue/pulsar 1.1.0 → 1.3.0

package/dist/index.d.cts

@@ -20,7 +20,7 @@ import { Envelope, HeaderCarrier, IncomingEnvelope } from '@babelqueue/core';
  *     });
  *     const consumer = new PulsarConsumer(sub, {
  *       "urn:babel:orders:created": async (env) => { ... },
- *     });
+ *     }, { subscriptionType: "Shared" }); // declare it (or pass `client` together with `topic`): see PulsarConsumerOptions
  *     await consumer.run();
  *
  * This implements §5 of the broker-bindings contract: the canonical envelope is the message
@@ -28,9 +28,23 @@ import { Envelope, HeaderCarrier, IncomingEnvelope } from '@babelqueue/core';
  * `bq-trace-id` = trace_id, `bq-message-id` = meta.id, plus `bq-schema-version` /
  * `bq-source-lang` / `bq-attempts`. The envelope is unchanged (`schema_version` stays 1);
  * Pulsar is purely additive. A failed handler `negativeAcknowledge`s the message, so it is
- * redelivered (at-least-once) and `getRedeliveryCount()` is incremented; the authoritative
- * attempt count is the body's `bq-attempts`, reconciled to `max(bq-attempts,
- * getRedeliveryCount())` — no −1, because Pulsar's redelivery count is 0-based.
+ * redelivered (at-least-once) and `getRedeliveryCount()` is incremented — up to `maxAttempts`
+ * deliveries (default 3, ADR-0036): the message that exhausts them is written to `<queue>.dlq`
+ * (when a `deadLetterProducer` is given) or acknowledged and dropped. A body that does not decode
+ * into an envelope (including an object with no valid identity) is poison: it never reaches a
+ * handler, and with dead-lettering on it is recorded in `<queue>.dlq` in the ADR-0035 shape without
+ * retry. Per §5.2 / §5.7 the
+ * consumer routes on the `bq-job` property (the body's URN is used only when the property is
+ * absent or blank) and takes `attempts` from the authoritative `bq-attempts` property (the
+ * body's value is used only when the property is absent or not a plain ASCII-decimal integer
+ * that fits a 32-bit int), reconciled to `max(bq-attempts, getRedeliveryCount())` — no −1,
+ * because Pulsar's redelivery count is 0-based. The handler still receives the body's envelope.
+ *
+ * **Version gate (§5.7 step 3).** Before the body is decoded the consumer reads the
+ * `bq-schema-version` property. A missing or blank value (empty or only ASCII whitespace) changes nothing; any value other than
+ * the core's supported `SCHEMA_VERSION` (`"2"`, `"x"`, `"01"`, ...) rejects the message undecoded
+ * through the same path as a non-conformant envelope — `onError` (with an error naming the
+ * version, and an empty envelope since nothing was decoded) and a `negativeAcknowledge`.
  *
  * **Out-of-band headers (ADR-0028).** A `headers` carrier (e.g. a W3C `traceparent` for cross-hop
  * span linkage) rides as additional native Pulsar **message properties** beside the contract `bq-*`
@@ -70,10 +84,27 @@ interface PulsarReceivedMessage {
  * satisfies it structurally; a fake satisfies it in tests.
  */
 interface PulsarConsumerClient {
+    /**
+     * The topic the subscription reads. pulsar-client's `Consumer` has **no** such method (only its `Producer`
+     * does), so with it the topic comes from the {@link PulsarConsumerOptions.topic} option; a custom
+     * subscription wrapper may provide this to make `topic` unnecessary.
+     */
+    getTopic?(): string;
     receive(timeoutMs?: number): Promise<PulsarReceivedMessage>;
     acknowledge(message: PulsarReceivedMessage): Promise<void> | void;
     negativeAcknowledge(message: PulsarReceivedMessage): Promise<void> | void;
 }
+/**
+ * The subset of the Pulsar client this adapter calls to build its own retry producer. A `Client` from
+ * `pulsar-client` satisfies it structurally.
+ */
+interface PulsarClientLike {
+    createProducer(config: {
+        topic: string;
+    }): Promise<PulsarProducer>;
+}
+/** The subscription type, as pulsar-client names it (`Key_Shared` is accepted as an alias of `KeyShared`). */
+type PulsarSubscriptionType = "Exclusive" | "Shared" | "Failover" | "KeyShared" | "Key_Shared";
 /**
  * Project the envelope's contract fields onto native Pulsar message properties
  * (string→string): `bq-job` = URN, `bq-trace-id` = trace_id, `bq-message-id` = meta.id, plus
@@ -137,24 +168,125 @@ interface PulsarConsumerOptions {
     onError?: (error: unknown, envelope: IncomingEnvelope, message: PulsarReceivedMessage) => void;
     /** Per-receive timeout in ms (default 1000). A timeout yields an empty poll, not an error. */
     receiveTimeoutMs?: number;
+    /**
+     * Optional diagnostic hook, called when the `bq-job` property and the body's URN differ (the
+     * property wins and the message is routed on it). `envelope` is the body's envelope. Separate
+     * from {@link PulsarConsumerOptions.onError}: it is not an error, and anything it throws (or
+     * rejects with) is swallowed — it never changes how the message is handled or acknowledged.
+     */
+    onRoutingMismatch?: (propertyUrn: string, bodyUrn: string, envelope: IncomingEnvelope) => unknown;
+    /**
+     * The total number of deliveries a message gets, the first included (default 3; `1` = no retry;
+     * ADR-0036 decision 1). A failing handler, an unmapped URN without {@link onUnknownUrn} and a poison
+     * body with dead-lettering off are retried (`negativeAcknowledge`) while `reconciled attempts + 1`
+     * is below it; the delivery that reaches it is dead-lettered (when {@link deadLetterProducer} is
+     * set) or acknowledged and dropped. Must be an integer of at least 1.
+     */
+    maxAttempts?: number;
+    /**
+     * A producer on the dead-letter topic (by convention `<queue>.dlq`). Dead-lettering is on exactly
+     * when it is set; the SDK does not use Pulsar's native `DeadLetterPolicy`. The original message is
+     * acknowledged only after the record was sent; a failed send leaves it negatively acknowledged so
+     * it is redelivered and the write is tried again.
+     */
+    deadLetterProducer?: PulsarProducer;
+    /**
+     * A producer on the consumer's **own** topic. A retry re-publishes the message to that topic with
+     * `bq-attempts` (and the body's `attempts`) raised to the counted value and then acknowledges the
+     * original — the Go model. The count then lives in the message itself, so the bound holds on every
+     * subscription type. Optional when {@link client} is given (the consumer builds the producer itself);
+     * a failed re-publish leaves the original negatively acknowledged (never lost).
+     *
+     * Without a producer or a client a retry is a `negativeAcknowledge`, which advances the native
+     * redelivery count only on `Shared` / `Key_Shared`: on `Exclusive` / `Failover` it stays 0 and the retry
+     * would never reach `maxAttempts`, so that combination is rejected at construction (see
+     * {@link subscriptionType}).
+     */
+    retryProducer?: PulsarProducer;
+    /**
+     * The Pulsar client the consumer builds its retry producer from, lazily on the first retry, on
+     * {@link topic}. Needs `topic` (pulsar-client's `Consumer` cannot tell its topic). Ignored when
+     * {@link retryProducer} is given.
+     */
+    client?: PulsarClientLike;
+    /**
+     * The topic the retry producer is created on — the topic the consumer reads. Required together with
+     * {@link client} (a pulsar-client `Consumer` has no `getTopic()`); a subscription wrapper that provides
+     * `getTopic()` makes it optional.
+     */
+    topic?: string;
+    /**
+     * The subscription type the consumer was created with. `Exclusive` and `Failover` cannot bound a
+     * nack-driven retry (a negative acknowledgement does not advance the redelivery count there), so with
+     * `maxAttempts > 1` they require a {@link retryProducer} or a {@link client}. **Not declaring it counts as
+     * `Exclusive`** (pulsar-client's own default, and the fail-closed choice): without a `retryProducer` or a
+     * `client` the constructor throws `BabelQueueError`. Declare `"Shared"` or `"Key_Shared"` to keep the
+     * `negativeAcknowledge` retry without a producer.
+     */
+    subscriptionType?: PulsarSubscriptionType;
+    /**
+     * The queue name written to `dead_letter.original_queue` of a poison record (a decodable envelope
+     * uses its own `meta.queue`). Defaults to the {@link deadLetterProducer} topic without its `.dlq`
+     * suffix.
+     */
+    queue?: string;
+    /** Receives the "message dropped" and "dead-letter write failed" warnings (default `console.warn`). */
+    onWarn?: (message: string) => void;
 }
+/** Default total number of deliveries (ADR-0036 decision 1). */
+declare const DEFAULT_MAX_ATTEMPTS = 3;
 /**
  * Receives from a Pulsar subscription, decodes + validates each message, routes it to the
  * handler for its URN, and acknowledges it on success. A throwing handler
  * `negativeAcknowledge`s the message — the broker redelivers it and increments
- * `getRedeliveryCount()` (at-least-once); `attempts` is reconciled to
- * `max(bq-attempts, getRedeliveryCount())` for the handler.
+ * `getRedeliveryCount()` (at-least-once; with a `retryProducer` the message is instead re-published with
+ * `bq-attempts` + 1, which also bounds `Exclusive` / `Failover` subscriptions) — until `maxAttempts` deliveries are used up; the last one is
+ * dead-lettered to `<queue>.dlq` or acknowledged and dropped (ADR-0036). Routing uses the `bq-job`
+ * property (body URN as the fallback); `attempts` is the `bq-attempts` property (body value as the
+ * fallback) reconciled to `max(.., getRedeliveryCount())` for the handler.
  */
 declare class PulsarConsumer {
     private readonly consumer;
     private readonly handlers;
     private readonly options;
+    private readonly maxAttempts;
+    private builtRetryProducer;
+    private readonly warn;
     constructor(consumer: PulsarConsumerClient, handlers: BabelHandlers, options?: PulsarConsumerOptions);
+    /**
+     * Setup check: on `Exclusive` / `Failover` (and an undeclared type) a negative acknowledgement does not advance the native
+     * redelivery count, so a retry needs a re-publish. Fail loudly here instead of looping at run time.
+     */
+    private checkRetryBound;
+    private retryTopic;
+    /** The retry producer: the one given, else one built (once) from the client; undefined when neither exists. */
+    private resolveRetryProducer;
     /** Receive one message (up to the receive timeout), route + settle it. Returns 1, or 0 on timeout. */
     poll(): Promise<number>;
     /** Poll until `signal` aborts. */
     run(signal?: AbortSignal): Promise<void>;
     private handle;
+    /**
+     * The settle decision of a retryable outcome (ADR-0036 decisions 1 and 2). `counted` is the reconciled
+     * attempts plus one for this delivery. A poison body with dead-lettering on is recorded without retry;
+     * every other outcome retries (`negativeAcknowledge`: the native redelivery count advances, so the
+     * next delivery counts one more) while `counted < maxAttempts`, then dead-letters or drops.
+     */
+    private settle;
+    /**
+     * Retry one delivery. With a {@link PulsarConsumerOptions.retryProducer}: re-publish to the consumer's
+     * own topic carrying `bq-attempts = counted` (reconcile = max(bq-attempts, RedeliveryCount) on the next
+     * delivery), then acknowledge the original — only after the send succeeded. Otherwise `negativeAcknowledge`.
+     */
+    private retry;
+    private retryMessage;
+    /**
+     * Write the DLQ record, then acknowledge the original — only after the send succeeded. A failed send
+     * leaves the original negatively acknowledged, so it is redelivered and the write is tried again.
+     */
+    private deadLetter;
+    private deadLetterMessage;
+    private notifyRoutingMismatch;
 }
 
-export { type BabelHandler, type BabelHandlers, type PublishOptions, PulsarConsumer, type PulsarConsumerClient, type PulsarConsumerOptions, type PulsarProducer, type PulsarProducerMessage, PulsarPublisher, type PulsarReceivedMessage, headersOf, pulsarProperties, toPulsarMessage };
+export { type BabelHandler, type BabelHandlers, DEFAULT_MAX_ATTEMPTS, type PublishOptions, type PulsarClientLike, PulsarConsumer, type PulsarConsumerClient, type PulsarConsumerOptions, type PulsarProducer, type PulsarProducerMessage, PulsarPublisher, type PulsarReceivedMessage, type PulsarSubscriptionType, headersOf, pulsarProperties, toPulsarMessage };

package/dist/index.d.ts

@@ -20,7 +20,7 @@ import { Envelope, HeaderCarrier, IncomingEnvelope } from '@babelqueue/core';
  *     });
  *     const consumer = new PulsarConsumer(sub, {
  *       "urn:babel:orders:created": async (env) => { ... },
- *     });
+ *     }, { subscriptionType: "Shared" }); // declare it (or pass `client` together with `topic`): see PulsarConsumerOptions
  *     await consumer.run();
  *
  * This implements §5 of the broker-bindings contract: the canonical envelope is the message
@@ -28,9 +28,23 @@ import { Envelope, HeaderCarrier, IncomingEnvelope } from '@babelqueue/core';
  * `bq-trace-id` = trace_id, `bq-message-id` = meta.id, plus `bq-schema-version` /
  * `bq-source-lang` / `bq-attempts`. The envelope is unchanged (`schema_version` stays 1);
  * Pulsar is purely additive. A failed handler `negativeAcknowledge`s the message, so it is
- * redelivered (at-least-once) and `getRedeliveryCount()` is incremented; the authoritative
- * attempt count is the body's `bq-attempts`, reconciled to `max(bq-attempts,
- * getRedeliveryCount())` — no −1, because Pulsar's redelivery count is 0-based.
+ * redelivered (at-least-once) and `getRedeliveryCount()` is incremented — up to `maxAttempts`
+ * deliveries (default 3, ADR-0036): the message that exhausts them is written to `<queue>.dlq`
+ * (when a `deadLetterProducer` is given) or acknowledged and dropped. A body that does not decode
+ * into an envelope (including an object with no valid identity) is poison: it never reaches a
+ * handler, and with dead-lettering on it is recorded in `<queue>.dlq` in the ADR-0035 shape without
+ * retry. Per §5.2 / §5.7 the
+ * consumer routes on the `bq-job` property (the body's URN is used only when the property is
+ * absent or blank) and takes `attempts` from the authoritative `bq-attempts` property (the
+ * body's value is used only when the property is absent or not a plain ASCII-decimal integer
+ * that fits a 32-bit int), reconciled to `max(bq-attempts, getRedeliveryCount())` — no −1,
+ * because Pulsar's redelivery count is 0-based. The handler still receives the body's envelope.
+ *
+ * **Version gate (§5.7 step 3).** Before the body is decoded the consumer reads the
+ * `bq-schema-version` property. A missing or blank value (empty or only ASCII whitespace) changes nothing; any value other than
+ * the core's supported `SCHEMA_VERSION` (`"2"`, `"x"`, `"01"`, ...) rejects the message undecoded
+ * through the same path as a non-conformant envelope — `onError` (with an error naming the
+ * version, and an empty envelope since nothing was decoded) and a `negativeAcknowledge`.
  *
  * **Out-of-band headers (ADR-0028).** A `headers` carrier (e.g. a W3C `traceparent` for cross-hop
  * span linkage) rides as additional native Pulsar **message properties** beside the contract `bq-*`
@@ -70,10 +84,27 @@ interface PulsarReceivedMessage {
  * satisfies it structurally; a fake satisfies it in tests.
  */
 interface PulsarConsumerClient {
+    /**
+     * The topic the subscription reads. pulsar-client's `Consumer` has **no** such method (only its `Producer`
+     * does), so with it the topic comes from the {@link PulsarConsumerOptions.topic} option; a custom
+     * subscription wrapper may provide this to make `topic` unnecessary.
+     */
+    getTopic?(): string;
     receive(timeoutMs?: number): Promise<PulsarReceivedMessage>;
     acknowledge(message: PulsarReceivedMessage): Promise<void> | void;
     negativeAcknowledge(message: PulsarReceivedMessage): Promise<void> | void;
 }
+/**
+ * The subset of the Pulsar client this adapter calls to build its own retry producer. A `Client` from
+ * `pulsar-client` satisfies it structurally.
+ */
+interface PulsarClientLike {
+    createProducer(config: {
+        topic: string;
+    }): Promise<PulsarProducer>;
+}
+/** The subscription type, as pulsar-client names it (`Key_Shared` is accepted as an alias of `KeyShared`). */
+type PulsarSubscriptionType = "Exclusive" | "Shared" | "Failover" | "KeyShared" | "Key_Shared";
 /**
  * Project the envelope's contract fields onto native Pulsar message properties
  * (string→string): `bq-job` = URN, `bq-trace-id` = trace_id, `bq-message-id` = meta.id, plus
@@ -137,24 +168,125 @@ interface PulsarConsumerOptions {
     onError?: (error: unknown, envelope: IncomingEnvelope, message: PulsarReceivedMessage) => void;
     /** Per-receive timeout in ms (default 1000). A timeout yields an empty poll, not an error. */
     receiveTimeoutMs?: number;
+    /**
+     * Optional diagnostic hook, called when the `bq-job` property and the body's URN differ (the
+     * property wins and the message is routed on it). `envelope` is the body's envelope. Separate
+     * from {@link PulsarConsumerOptions.onError}: it is not an error, and anything it throws (or
+     * rejects with) is swallowed — it never changes how the message is handled or acknowledged.
+     */
+    onRoutingMismatch?: (propertyUrn: string, bodyUrn: string, envelope: IncomingEnvelope) => unknown;
+    /**
+     * The total number of deliveries a message gets, the first included (default 3; `1` = no retry;
+     * ADR-0036 decision 1). A failing handler, an unmapped URN without {@link onUnknownUrn} and a poison
+     * body with dead-lettering off are retried (`negativeAcknowledge`) while `reconciled attempts + 1`
+     * is below it; the delivery that reaches it is dead-lettered (when {@link deadLetterProducer} is
+     * set) or acknowledged and dropped. Must be an integer of at least 1.
+     */
+    maxAttempts?: number;
+    /**
+     * A producer on the dead-letter topic (by convention `<queue>.dlq`). Dead-lettering is on exactly
+     * when it is set; the SDK does not use Pulsar's native `DeadLetterPolicy`. The original message is
+     * acknowledged only after the record was sent; a failed send leaves it negatively acknowledged so
+     * it is redelivered and the write is tried again.
+     */
+    deadLetterProducer?: PulsarProducer;
+    /**
+     * A producer on the consumer's **own** topic. A retry re-publishes the message to that topic with
+     * `bq-attempts` (and the body's `attempts`) raised to the counted value and then acknowledges the
+     * original — the Go model. The count then lives in the message itself, so the bound holds on every
+     * subscription type. Optional when {@link client} is given (the consumer builds the producer itself);
+     * a failed re-publish leaves the original negatively acknowledged (never lost).
+     *
+     * Without a producer or a client a retry is a `negativeAcknowledge`, which advances the native
+     * redelivery count only on `Shared` / `Key_Shared`: on `Exclusive` / `Failover` it stays 0 and the retry
+     * would never reach `maxAttempts`, so that combination is rejected at construction (see
+     * {@link subscriptionType}).
+     */
+    retryProducer?: PulsarProducer;
+    /**
+     * The Pulsar client the consumer builds its retry producer from, lazily on the first retry, on
+     * {@link topic}. Needs `topic` (pulsar-client's `Consumer` cannot tell its topic). Ignored when
+     * {@link retryProducer} is given.
+     */
+    client?: PulsarClientLike;
+    /**
+     * The topic the retry producer is created on — the topic the consumer reads. Required together with
+     * {@link client} (a pulsar-client `Consumer` has no `getTopic()`); a subscription wrapper that provides
+     * `getTopic()` makes it optional.
+     */
+    topic?: string;
+    /**
+     * The subscription type the consumer was created with. `Exclusive` and `Failover` cannot bound a
+     * nack-driven retry (a negative acknowledgement does not advance the redelivery count there), so with
+     * `maxAttempts > 1` they require a {@link retryProducer} or a {@link client}. **Not declaring it counts as
+     * `Exclusive`** (pulsar-client's own default, and the fail-closed choice): without a `retryProducer` or a
+     * `client` the constructor throws `BabelQueueError`. Declare `"Shared"` or `"Key_Shared"` to keep the
+     * `negativeAcknowledge` retry without a producer.
+     */
+    subscriptionType?: PulsarSubscriptionType;
+    /**
+     * The queue name written to `dead_letter.original_queue` of a poison record (a decodable envelope
+     * uses its own `meta.queue`). Defaults to the {@link deadLetterProducer} topic without its `.dlq`
+     * suffix.
+     */
+    queue?: string;
+    /** Receives the "message dropped" and "dead-letter write failed" warnings (default `console.warn`). */
+    onWarn?: (message: string) => void;
 }
+/** Default total number of deliveries (ADR-0036 decision 1). */
+declare const DEFAULT_MAX_ATTEMPTS = 3;
 /**
  * Receives from a Pulsar subscription, decodes + validates each message, routes it to the
  * handler for its URN, and acknowledges it on success. A throwing handler
  * `negativeAcknowledge`s the message — the broker redelivers it and increments
- * `getRedeliveryCount()` (at-least-once); `attempts` is reconciled to
- * `max(bq-attempts, getRedeliveryCount())` for the handler.
+ * `getRedeliveryCount()` (at-least-once; with a `retryProducer` the message is instead re-published with
+ * `bq-attempts` + 1, which also bounds `Exclusive` / `Failover` subscriptions) — until `maxAttempts` deliveries are used up; the last one is
+ * dead-lettered to `<queue>.dlq` or acknowledged and dropped (ADR-0036). Routing uses the `bq-job`
+ * property (body URN as the fallback); `attempts` is the `bq-attempts` property (body value as the
+ * fallback) reconciled to `max(.., getRedeliveryCount())` for the handler.
  */
 declare class PulsarConsumer {
     private readonly consumer;
     private readonly handlers;
     private readonly options;
+    private readonly maxAttempts;
+    private builtRetryProducer;
+    private readonly warn;
     constructor(consumer: PulsarConsumerClient, handlers: BabelHandlers, options?: PulsarConsumerOptions);
+    /**
+     * Setup check: on `Exclusive` / `Failover` (and an undeclared type) a negative acknowledgement does not advance the native
+     * redelivery count, so a retry needs a re-publish. Fail loudly here instead of looping at run time.
+     */
+    private checkRetryBound;
+    private retryTopic;
+    /** The retry producer: the one given, else one built (once) from the client; undefined when neither exists. */
+    private resolveRetryProducer;
     /** Receive one message (up to the receive timeout), route + settle it. Returns 1, or 0 on timeout. */
     poll(): Promise<number>;
     /** Poll until `signal` aborts. */
     run(signal?: AbortSignal): Promise<void>;
     private handle;
+    /**
+     * The settle decision of a retryable outcome (ADR-0036 decisions 1 and 2). `counted` is the reconciled
+     * attempts plus one for this delivery. A poison body with dead-lettering on is recorded without retry;
+     * every other outcome retries (`negativeAcknowledge`: the native redelivery count advances, so the
+     * next delivery counts one more) while `counted < maxAttempts`, then dead-letters or drops.
+     */
+    private settle;
+    /**
+     * Retry one delivery. With a {@link PulsarConsumerOptions.retryProducer}: re-publish to the consumer's
+     * own topic carrying `bq-attempts = counted` (reconcile = max(bq-attempts, RedeliveryCount) on the next
+     * delivery), then acknowledge the original — only after the send succeeded. Otherwise `negativeAcknowledge`.
+     */
+    private retry;
+    private retryMessage;
+    /**
+     * Write the DLQ record, then acknowledge the original — only after the send succeeded. A failed send
+     * leaves the original negatively acknowledged, so it is redelivered and the write is tried again.
+     */
+    private deadLetter;
+    private deadLetterMessage;
+    private notifyRoutingMismatch;
 }
 
-export { type BabelHandler, type BabelHandlers, type PublishOptions, PulsarConsumer, type PulsarConsumerClient, type PulsarConsumerOptions, type PulsarProducer, type PulsarProducerMessage, PulsarPublisher, type PulsarReceivedMessage, headersOf, pulsarProperties, toPulsarMessage };
+export { type BabelHandler, type BabelHandlers, DEFAULT_MAX_ATTEMPTS, type PublishOptions, type PulsarClientLike, PulsarConsumer, type PulsarConsumerClient, type PulsarConsumerOptions, type PulsarProducer, type PulsarProducerMessage, PulsarPublisher, type PulsarReceivedMessage, type PulsarSubscriptionType, headersOf, pulsarProperties, toPulsarMessage };