npm - @babelqueue/sqs - Versions diffs - 1.1.0 → 1.2.1 - Mend

@babelqueue/sqs 1.1.0 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md CHANGED Viewed

@@ -54,11 +54,43 @@ For LocalStack/ElasticMQ, point the `SQS` client's `endpoint` there.
 | `meta.created_at` | `MessageAttributes.bq-created-at` (Number, ms) |
 | `attempts` | reconciled to `ApproximateReceiveCount − 1` on receive |
 | reserve / ack | visibility timeout → `DeleteMessage` |
-Retry is **SQS-native**: a throwing handler leaves the message undeleted, so SQS
-redelivers it after the visibility timeout (at-least-once). The loop never stops on a
-bad message — use `onError` / `onUnknownUrn` to observe. The envelope is unchanged
-(`schema_version` stays `1`); SQS is purely additive.
+| release (nack) | `ChangeMessageVisibility(ReceiptHandle, VisibilityTimeout = releaseDelay)` |
+Retry is **SQS-native** (contract §3.5): a throwing handler's message is never deleted;
+it is released with `ChangeMessageVisibility`, so SQS redelivers it after
+`releaseDelay` seconds (**default `0`** — visible again immediately; a number or a
+function of `attempts`, clamped to `0…43200`). If the release call itself fails, the
+error goes to `onError` and the message is redelivered after the visibility timeout
+(at-least-once). A `DeleteMessage` that fails *after* a successful handler is not a
+handler failure: it reaches `onError` as an `SqsDeleteError` (broker error in `cause`)
+and the message is **not** released — it returns only after its visibility timeout, so
+dedupe on `meta.id` if the side effect must not repeat. The loop never stops on a bad message — use `onError` /
+`onUnknownUrn` to observe. The envelope is unchanged (`schema_version` stays `1`); SQS
+is purely additive.
+**Version gate (§3.7).** Before the body is decoded the consumer reads the `bq-schema-version`
+message attribute. A missing or blank value (empty or only ASCII whitespace) changes nothing; any
+other value that is not exactly `"1"` (`"2"`, `"x"`, `"01"`, `" 1"` — never trimmed) rejects the
+message **undecoded**: it reaches `onError` (with an empty envelope) and is left undeleted, so it is
+redelivered and the `RedrivePolicy` below moves it to the DLQ.
+> **Poison messages — configure a `RedrivePolicy`.** With the `0 s` default, a handler
+> that always fails is retried back-to-back until the queue's native `RedrivePolicy`
+> (`maxReceiveCount`) moves the message to its dead-letter queue. Without one, such a
+> message loops forever. Give every consumed queue a `RedrivePolicy` (e.g.
+> `maxReceiveCount` 3–5 → `<queue>.dlq`), and/or pass a backoff:
+>
+> ```ts
+> new SqsConsumer(sqs, url, handlers, {
+>   releaseDelay: (attempts) => Math.min(2 ** attempts * 5, 900),
+> });
+> ```
+An unmapped URN follows `unknownUrn`: `fail` (report, leave), `delete`, `release`
+(`ChangeMessageVisibility` after `unknownUrnReleaseDelay`, default `0`) or
+`dead_letter` (annotated envelope to the opt-in `deadLetterQueueUrl`, then delete; a
+`.fifo` DLQ gets `MessageGroupId` + `MessageDeduplicationId`). Without `unknownUrn`,
+`onUnknownUrn` is called and the message deleted, or — with no hook — reported and left.
 ## Test

package/dist/index.cjs CHANGED Viewed

@@ -20,7 +20,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  MAX_VISIBILITY_TIMEOUT: () => MAX_VISIBILITY_TIMEOUT,
   SqsConsumer: () => SqsConsumer,
+  SqsDeleteError: () => SqsDeleteError,
   SqsPublisher: () => SqsPublisher,
   headersOf: () => headersOf,
   mergeAttributes: () => mergeAttributes,
@@ -43,6 +45,7 @@ function sanitizeHeaders(headers) {
 // src/index.ts
 var MAX_ATTRIBUTES = 10;
+var MAX_VISIBILITY_TIMEOUT = 43200;
 var str = (value) => ({
   DataType: "String",
   StringValue: String(value)
@@ -84,6 +87,12 @@ function headersOf(message) {
   }
   return out;
 }
+var BLANK_ASCII = /^[ \t\n\v\f\r]*$/;
+function unsupportedSchemaVersion(message) {
+  const raw = message.MessageAttributes?.["bq-schema-version"]?.StringValue;
+  if (typeof raw !== "string" || BLANK_ASCII.test(raw)) return void 0;
+  return raw === String(import_core.SCHEMA_VERSION) ? void 0 : raw;
+}
 function queueNameFromUrl(queueUrl) {
   const segments = queueUrl.split("/").filter(Boolean);
   return segments[segments.length - 1] ?? "default";
@@ -121,12 +130,29 @@ var SqsPublisher = class {
     return envelope.meta.id;
   }
 };
+var SqsDeleteError = class extends import_core.BabelQueueError {
+  constructor(cause) {
+    super("Failed to delete a processed SQS message; it will be redelivered after its visibility timeout.");
+    this.name = "SqsDeleteError";
+    this.cause = cause;
+  }
+};
 var SqsConsumer = class {
   constructor(client, queueUrl, handlers, options = {}) {
     this.client = client;
     this.queueUrl = queueUrl;
     this.handlers = handlers;
     this.options = options;
+    const strategy = options.unknownUrn;
+    if (strategy !== void 0 && !Object.values(import_core.UnknownUrnStrategy).includes(strategy)) {
+      throw new import_core.BabelQueueError(`Unknown unknownUrn strategy "${strategy}".`);
+    }
+    const needsRelease = options.releaseDelay != null || strategy === import_core.UnknownUrnStrategy.RELEASE;
+    if (needsRelease && typeof client.changeMessageVisibility !== "function") {
+      throw new import_core.BabelQueueError(
+        "SqsConsumer release requires a client with changeMessageVisibility (contract \xA73.5)."
+      );
+    }
   }
   client;
   queueUrl;
@@ -158,6 +184,17 @@ var SqsConsumer = class {
     }
   }
   async handle(message) {
+    const rejectedVersion = unsupportedSchemaVersion(message);
+    if (rejectedVersion !== void 0) {
+      this.options.onError?.(
+        new import_core.BabelQueueError(
+          `Rejected a message from SQS with unsupported bq-schema-version "${rejectedVersion}" (supported: ${import_core.SCHEMA_VERSION}).`
+        ),
+        {},
+        message
+      );
+      return;
+    }
     const envelope = import_core.EnvelopeCodec.decode(message.Body ?? "");
     const receiveCount = message.Attributes?.["ApproximateReceiveCount"];
     if (receiveCount !== void 0) {
@@ -178,6 +215,38 @@ var SqsConsumer = class {
     const urn = import_core.EnvelopeCodec.urn(envelope);
     const handler = this.handlers[urn];
     if (!handler) {
+      await this.unknown(urn, envelope, message);
+      return;
+    }
+    try {
+      await handler(envelope, message, headersOf(message));
+    } catch (error) {
+      this.options.onError?.(error, envelope, message);
+      await this.guard(envelope, message, async () => {
+        const delay = this.options.releaseDelay ?? 0;
+        const attempts = typeof envelope.attempts === "number" ? envelope.attempts : 0;
+        await this.release(message, typeof delay === "function" ? delay(attempts) : delay);
+      });
+      return;
+    }
+    await this.guard(envelope, message, () => this.deleteHandled(message));
+  }
+  /**
+   * Run a release / dead-letter step; a failure (e.g. `MessageNotInflight`, a missing IAM grant, a
+   * throwing `releaseDelay`) is reported to `onError` and the message is left undeleted, so
+   * visibility expiry still redelivers it. Never lets the error stop the consume loop.
+   */
+  async guard(envelope, message, step) {
+    try {
+      await step();
+    } catch (error) {
+      this.options.onError?.(error, envelope, message);
+    }
+  }
+  /** Apply the unknown-URN strategy (contract §3.5). */
+  async unknown(urn, envelope, message) {
+    const strategy = this.options.unknownUrn;
+    if (strategy === void 0) {
       if (this.options.onUnknownUrn) {
         await this.options.onUnknownUrn(envelope, message);
         await this.delete(message);
@@ -186,11 +255,61 @@ var SqsConsumer = class {
       }
       return;
     }
+    await this.guard(envelope, message, async () => {
+      await this.options.onUnknownUrn?.(envelope, message);
+    });
+    switch (strategy) {
+      case import_core.UnknownUrnStrategy.DELETE:
+        await this.guard(envelope, message, () => this.deleteHandled(message));
+        return;
+      case import_core.UnknownUrnStrategy.RELEASE:
+        await this.guard(envelope, message, () => this.release(message, this.options.unknownUrnReleaseDelay ?? 0));
+        return;
+      case import_core.UnknownUrnStrategy.DEAD_LETTER:
+        await this.guard(envelope, message, async () => {
+          await this.deadLetter(envelope, "unknown_urn");
+          await this.deleteHandled(message);
+        });
+        return;
+      default:
+        this.options.onError?.(new import_core.UnknownUrnError(urn), envelope, message);
+    }
+  }
+  /** Make the message visible again after `seconds` via `ChangeMessageVisibility`; never deletes. */
+  async release(message, seconds) {
+    if (!message.ReceiptHandle || !this.client.changeMessageVisibility) return;
+    const timeout = Number.isFinite(seconds) ? Math.min(MAX_VISIBILITY_TIMEOUT, Math.max(0, Math.floor(seconds))) : 0;
+    await this.client.changeMessageVisibility({
+      QueueUrl: this.queueUrl,
+      ReceiptHandle: message.ReceiptHandle,
+      VisibilityTimeout: timeout
+    });
+  }
+  /** Send the annotated envelope to the opt-in DLQ; a no-op (→ plain delete) when none is set. */
+  async deadLetter(envelope, reason) {
+    const dlq = this.options.deadLetterQueueUrl;
+    if (!dlq) return;
+    const source = envelope.meta?.queue ?? queueNameFromUrl(this.queueUrl);
+    const annotated = (0, import_core.annotate)(envelope, reason, source, {
+      attempts: envelope.attempts ?? 0
+    });
+    const input = {
+      QueueUrl: dlq,
+      MessageBody: import_core.EnvelopeCodec.encode(annotated),
+      MessageAttributes: toMessageAttributes(annotated)
+    };
+    if (dlq.endsWith(".fifo")) {
+      input.MessageGroupId = source;
+      if (annotated.meta?.id) input.MessageDeduplicationId = annotated.meta.id;
+    }
+    await this.client.sendMessage(input);
+  }
+  /** Delete a message whose processing already succeeded; a broker failure becomes an SqsDeleteError. */
+  async deleteHandled(message) {
     try {
-      await handler(envelope, message, headersOf(message));
       await this.delete(message);
     } catch (error) {
-      this.options.onError?.(error, envelope, message);
+      throw new SqsDeleteError(error);
     }
   }
   async delete(message) {
@@ -203,7 +322,9 @@ var SqsConsumer = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  MAX_VISIBILITY_TIMEOUT,
   SqsConsumer,
+  SqsDeleteError,
   SqsPublisher,
   headersOf,
   mergeAttributes,

package/dist/index.cjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/index.ts","../src/headers.ts"],"sourcesContent":["/*\n Amazon SQS adapter for BabelQueue.\n \n A canonical-envelope publisher and a URN-routed consumer over Amazon SQS,\n * so an SQS-based Node service speaks the same contract (envelope shape, URN\n * identity, trace propagation) as the PHP/Laravel, Python, Go, Java and .NET SDKs.\n \n import { SQS } from \"@aws-sdk/client-sqs\";\n * import { SqsPublisher, SqsConsumer } from \"@babelqueue/sqs\";\n \n const sqs = new SQS({ region: \"eu-central-1\" });\n * const url = \"https://sqs.eu-central-1.amazonaws.com/123456789012/orders\";\n \n await new SqsPublisher(sqs, url).publish(\"urn:babel:orders:created\", { order_id: 1042 });\n \n const consumer = new SqsConsumer(sqs, url, {\n * \"urn:babel:orders:created\": async (env) => { ... },\n * });\n * await consumer.run();\n \n This implements §3 of the broker-bindings contract: the canonical envelope is the\n * message body, projected onto native SQS `MessageAttributes`. The envelope is\n * unchanged (`schema_version` stays 1); SQS is purely additive. Retry is SQS-native\n * (a failed handler leaves the message for visibility-timeout redelivery); the\n * authoritative attempt count is `ApproximateReceiveCount`, surfaced to handlers as\n * `attempts = count − 1`.\n \n Out-of-band headers (ADR-0028). A `headers` carrier (e.g. a W3C `traceparent` for cross-hop\n * span linkage) rides as additional String `MessageAttributes` beside the contract `bq-`\n attributes where `bq-trace-id` already lives — the contract attributes win a key collision, and\n * the merged set is bounded by SQS's 10-attribute limit (contract attributes are seeded first,\n * so a rider only lands while headroom remains). On consume the inbound `MessageAttributes` are\n * surfaced as a `Record<string,string>` so the core's `otel` extract sees the `traceparent` and\n * links the consumer span as a child. A header-less publish is byte-identical. This mirrors the Go\n * `/sqs` and PHP `SqsTransport` wiring. GR-1: the wire envelope body is never touched.\n /\n\nimport { BabelQueueError, EnvelopeCodec, UnknownUrnError } from \"@babelqueue/core\";\nimport type { Envelope, HeaderCarrier, IncomingEnvelope } from \"@babelqueue/core\";\n\nimport { sanitizeHeaders } from \"./headers.js\";\n\n/* SQS allows at most 10 user message attributes per message. /\nconst MAX_ATTRIBUTES = 10;\n\n// --- Minimal SQS shapes (a structural subset of @aws-sdk/client-sqs) -----------\n\nexport interface SqsMessageAttributeValue {\n DataType: string;\n StringValue?: string;\n}\n\nexport interface SqsMessage {\n Body?: string;\n ReceiptHandle?: string;\n MessageAttributes?: Record<string, SqsMessageAttributeValue>;\n Attributes?: Record<string, string>;\n}\n\nexport interface SendMessageInput {\n QueueUrl: string;\n MessageBody: string;\n MessageAttributes?: Record<string, SqsMessageAttributeValue>;\n MessageGroupId?: string;\n MessageDeduplicationId?: string;\n}\n\nexport interface ReceiveMessageInput {\n QueueUrl: string;\n MaxNumberOfMessages?: number;\n WaitTimeSeconds?: number;\n VisibilityTimeout?: number;\n MessageAttributeNames?: string[];\n AttributeNames?: string[];\n}\n\n/\n The subset of the AWS SQS client this adapter calls. The aggregated `SQS` class\n * from `@aws-sdk/client-sqs` satisfies it structurally; a fake satisfies it in tests.\n /\nexport interface SqsApi {\n sendMessage(input: SendMessageInput): Promise<{ MessageId?: string } \| unknown>;\n receiveMessage(input: ReceiveMessageInput): Promise<{ Messages?: SqsMessage[] }>;\n deleteMessage(input: { QueueUrl: string; ReceiptHandle: string }): Promise<unknown>;\n}\n\n// --- Attribute projection (contract §3.2) --------------------------------------\n\nconst str = (value: unknown): SqsMessageAttributeValue => ({\n DataType: \"String\",\n StringValue: String(value),\n});\nconst num = (value: unknown): SqsMessageAttributeValue => ({\n DataType: \"Number\",\n StringValue: String(value),\n});\n\n/\n Project the envelope's contract fields onto native SQS `MessageAttributes` — a\n * redundant, routable view of the body (the body stays authoritative).\n /\nexport function toMessageAttributes(envelope: Envelope): Record<string, SqsMessageAttributeValue> {\n const attrs: Record<string, SqsMessageAttributeValue> = {};\n if (envelope.job) attrs[\"bq-job\"] = str(envelope.job);\n if (envelope.trace_id) attrs[\"bq-trace-id\"] = str(envelope.trace_id);\n if (envelope.meta.id) attrs[\"bq-message-id\"] = str(envelope.meta.id);\n if (envelope.meta.schema_version != null) {\n attrs[\"bq-schema-version\"] = num(envelope.meta.schema_version);\n }\n if (envelope.meta.lang) attrs[\"bq-source-lang\"] = str(envelope.meta.lang);\n if (envelope.meta.created_at != null) {\n attrs[\"bq-created-at\"] = num(envelope.meta.created_at);\n }\n return attrs;\n}\n\n/\n Overlay the out-of-band `headers` onto the contract attribute projection as String\n * `MessageAttributes`, without overwriting an existing `bq-` attribute (the contract wins a key\n collision) and skipping blanks. Keys are merged in sorted order and the merge stops at the\n * 10-attribute SQS ceiling, so unbounded riders can never push the message past the limit (SQS\n * rejects the whole send otherwise) — the contract attributes are always preserved first. Mirrors\n * Go's `mergeAttributes` / PHP's `SqsTransport::attributes`.\n /\nexport function mergeAttributes(\n base: Record<string, SqsMessageAttributeValue>,\n headers: HeaderCarrier \| null \| undefined,\n): Record<string, SqsMessageAttributeValue> {\n const clean = sanitizeHeaders(headers);\n for (const key of Object.keys(clean).sort()) {\n if (key in base) continue; // never clobber a contract bq- attribute\n if (Object.keys(base).length >= MAX_ATTRIBUTES) break; // respect the SQS 10-attribute cap\n base[key] = str(clean[key]);\n }\n return base;\n}\n\n/*\n Map inbound SQS `MessageAttributes` onto a flat {@link HeaderCarrier} (the consume-side\n * counterpart of {@link mergeAttributes}), reading each attribute's `StringValue`. Returns an empty\n * object when there are none. Both the contract `bq-` attributes and any out-of-band rider (e.g.\n `traceparent`) surface — the core's `otel` extract reads only the keys it knows.\n /\nexport function headersOf(message: SqsMessage): HeaderCarrier {\n const attrs = message.MessageAttributes;\n const out: HeaderCarrier = {};\n if (!attrs) return out;\n for (const key of Object.keys(attrs)) {\n const value = attrs[key]?.StringValue;\n if (value != null && value !== \"\") out[key] = value;\n }\n return out;\n}\n\nfunction queueNameFromUrl(queueUrl: string): string {\n const segments = queueUrl.split(\"/\").filter(Boolean);\n return segments[segments.length - 1] ?? \"default\";\n}\n\n// --- Publisher -----------------------------------------------------------------\n\n/* Options for {@link SqsPublisher}. /\nexport interface SqsPublisherOptions {\n /* Treat the queue as FIFO: set `MessageGroupId` and (unless content dedup) `MessageDeduplicationId`. /\n fifo?: boolean;\n /* FIFO ordering group (default: the queue name from the URL). /\n messageGroupId?: string;\n /* Use the queue's content-based dedup instead of `meta.id` as the dedup id. /\n contentDedup?: boolean;\n}\n\n/* Options for {@link SqsPublisher.publish}. /\nexport interface PublishOptions {\n /* Reuse an existing trace id (trace continuation). /\n traceId?: string;\n /\n Out-of-band transport headers carried as String `MessageAttributes` beside the contract `bq-`\n attributes (ADR-0028) — e.g. a W3C `traceparent` written by `@babelqueue/core/otel`'s `publish`.\n * The contract attributes win a key collision and the merged set is capped at SQS's 10-attribute\n * limit; an empty/omitted carrier leaves the publish unchanged.\n /\n headers?: HeaderCarrier;\n}\n\n/* Sends canonical-envelope messages to one SQS queue with the §3 attribute projection. /\nexport class SqsPublisher {\n constructor(\n private readonly client: SqsApi,\n private readonly queueUrl: string,\n private readonly options: SqsPublisherOptions = {},\n ) {}\n\n /\n Build the canonical envelope for `(urn, data)`, send it as the message body with\n * the projected `MessageAttributes`, and return the message id (`meta.id`).\n /\n async publish(\n urn: string,\n data: Record<string, unknown>,\n options: PublishOptions = {},\n ): Promise<string> {\n const envelope = EnvelopeCodec.make(urn, data, {\n queue: queueNameFromUrl(this.queueUrl),\n traceId: options.traceId,\n });\n const input: SendMessageInput = {\n QueueUrl: this.queueUrl,\n MessageBody: EnvelopeCodec.encode(envelope),\n MessageAttributes: mergeAttributes(toMessageAttributes(envelope), options.headers),\n };\n if (this.options.fifo) {\n input.MessageGroupId = this.options.messageGroupId ?? queueNameFromUrl(this.queueUrl);\n if (!this.options.contentDedup) {\n input.MessageDeduplicationId = envelope.meta.id;\n }\n }\n await this.client.sendMessage(input);\n return envelope.meta.id;\n }\n}\n\n// --- Consumer ------------------------------------------------------------------\n\n/\n A URN handler. Receives the validated envelope, the raw SQS message, and the out-of-band\n * {@link HeaderCarrier} read from the message's `MessageAttributes` (empty when there are none).\n * Pass `headers` to `@babelqueue/core/otel`'s `wrapHandler` to link the consumer span as a child of\n * the producer span (ADR-0028).\n /\nexport type BabelHandler = (envelope: Envelope, message: SqsMessage, headers: HeaderCarrier) => unknown \| Promise<unknown>;\n\n/* A map of URN → handler. /\nexport type BabelHandlers = Record<string, BabelHandler>;\n\n/* Options for {@link SqsConsumer}. /\nexport interface SqsConsumerOptions {\n /* Called instead of erroring when a message's URN has no handler (then the message is deleted). /\n onUnknownUrn?: (envelope: IncomingEnvelope, message: SqsMessage) => unknown \| Promise<unknown>;\n /* Called for a non-conformant envelope, an unmapped URN (no `onUnknownUrn`), or a throwing handler. The loop never stops. /\n onError?: (error: unknown, envelope: IncomingEnvelope, message: SqsMessage) => void;\n /* Long-poll wait seconds (default 20). /\n waitTimeSeconds?: number;\n /* Reservation window applied on receive (seconds). /\n visibilityTimeout?: number;\n /* Max messages per receive (default 10). /\n maxMessages?: number;\n}\n\n/\n Polls an SQS queue, decodes + validates each message, routes it to the handler\n * registered for its URN, and deletes it on success. A throwing handler leaves the\n * message undeleted — SQS redelivers it after the visibility timeout (at-least-once);\n * `attempts` is reconciled to `ApproximateReceiveCount − 1` for the handler.\n /\nexport class SqsConsumer {\n constructor(\n private readonly client: SqsApi,\n private readonly queueUrl: string,\n private readonly handlers: BabelHandlers,\n private readonly options: SqsConsumerOptions = {},\n ) {}\n\n /* Receive one batch, route each message, delete the ones handled. Returns the batch size. /\n async poll(): Promise<number> {\n const input: ReceiveMessageInput = {\n QueueUrl: this.queueUrl,\n MaxNumberOfMessages: this.options.maxMessages ?? 10,\n WaitTimeSeconds: this.options.waitTimeSeconds ?? 20,\n MessageAttributeNames: [\"All\"],\n AttributeNames: [\"ApproximateReceiveCount\"],\n };\n if (this.options.visibilityTimeout != null) {\n input.VisibilityTimeout = this.options.visibilityTimeout;\n }\n const result = await this.client.receiveMessage(input);\n const messages = result.Messages ?? [];\n for (const message of messages) {\n await this.handle(message);\n }\n return messages.length;\n }\n\n /* Poll until `signal` aborts (each poll long-polls, so this does not busy-loop). /\n async run(signal?: AbortSignal): Promise<void> {\n while (signal?.aborted !== true) {\n await this.poll();\n }\n }\n\n private async handle(message: SqsMessage): Promise<void> {\n const envelope = EnvelopeCodec.decode(message.Body ?? \"\");\n\n const receiveCount = message.Attributes?.[\"ApproximateReceiveCount\"];\n if (receiveCount !== undefined) {\n const native = Number.parseInt(receiveCount, 10) - 1;\n const current = typeof envelope.attempts === \"number\" ? envelope.attempts : 0;\n if (Number.isFinite(native) && native > current) {\n envelope.attempts = native;\n }\n }\n\n if (!EnvelopeCodec.accepts(envelope)) {\n this.options.onError?.(\n new BabelQueueError(\"Rejected a non-conformant BabelQueue envelope from SQS.\"),\n envelope,\n message,\n );\n return;\n }\n\n const urn = EnvelopeCodec.urn(envelope);\n const handler = this.handlers[urn];\n if (!handler) {\n if (this.options.onUnknownUrn) {\n await this.options.onUnknownUrn(envelope, message);\n await this.delete(message);\n } else {\n this.options.onError?.(new UnknownUrnError(urn), envelope, message);\n }\n return;\n }\n\n try {\n await handler(envelope, message, headersOf(message));\n await this.delete(message);\n } catch (error) {\n // Leave the message undeleted — SQS redelivers after the visibility timeout.\n this.options.onError?.(error, envelope, message);\n }\n }\n\n private async delete(message: SqsMessage): Promise<void> {\n if (!message.ReceiptHandle) return;\n await this.client.deleteMessage({\n QueueUrl: this.queueUrl,\n ReceiptHandle: message.ReceiptHandle,\n });\n }\n}\n","/\n Pure, dependency-free helpers for the out-of-band transport-header seam (ADR-0028) — the Node\n * adapter mirror of Go's `sanitizeHeaders` and PHP's `Support\\Headers`. They fold an injected\n * {@link HeaderCarrier} (e.g. a W3C `traceparent`) onto a transport's metadata channel *without\n clobbering** the contract headers it already carries.\n \n Headers ride beside the frozen wire envelope (GR-1), never inside it.\n /\n\nimport type { HeaderCarrier } from \"@babelqueue/core\";\n\n/\n Copy `headers`, dropping blank keys and blank values. Returns an empty object when nothing\n * survives, so a caller can treat the result as \"no headers\". A nullish input yields an empty\n * object.\n */\nexport function sanitizeHeaders(headers: HeaderCarrier \| null \| undefined): HeaderCarrier {\n const out: HeaderCarrier = {};\n if (!headers) return out;\n for (const key of Object.keys(headers)) {\n const value = headers[key];\n if (key === \"\" \|\| value == null \|\| value === \"\") continue;\n out[key] = value;\n }\n return out;\n}\n"],"mappings":"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","names":[]}
1	+ {"version":3,"sources":["../src/index.ts","../src/headers.ts"],"sourcesContent":["/*\n Amazon SQS adapter for BabelQueue.\n \n A canonical-envelope publisher and a URN-routed consumer over Amazon SQS,\n * so an SQS-based Node service speaks the same contract (envelope shape, URN\n * identity, trace propagation) as the PHP/Laravel, Python, Go, Java and .NET SDKs.\n \n import { SQS } from \"@aws-sdk/client-sqs\";\n * import { SqsPublisher, SqsConsumer } from \"@babelqueue/sqs\";\n \n const sqs = new SQS({ region: \"eu-central-1\" });\n * const url = \"https://sqs.eu-central-1.amazonaws.com/123456789012/orders\";\n \n await new SqsPublisher(sqs, url).publish(\"urn:babel:orders:created\", { order_id: 1042 });\n \n const consumer = new SqsConsumer(sqs, url, {\n * \"urn:babel:orders:created\": async (env) => { ... },\n * });\n * await consumer.run();\n \n This implements §3 of the broker-bindings contract: the canonical envelope is the\n * message body, projected onto native SQS `MessageAttributes`. The envelope is\n * unchanged (`schema_version` stays 1); SQS is purely additive. Retry is SQS-native\n * (a failed handler's message is released via `ChangeMessageVisibility` after\n * `releaseDelay`, default 0 s — pair the queue with a `RedrivePolicy`); the\n * authoritative attempt count is `ApproximateReceiveCount`, surfaced to handlers as\n * `attempts = count − 1`.\n \n Version gate (§3.7). Before the body is decoded the consumer reads the `bq-schema-version`\n * message attribute. A missing or blank value (empty or only ASCII whitespace) changes nothing; any\n * value other than the core's supported `SCHEMA_VERSION` (`\"2\"`, `\"x\"`, `\"01\"`, ...) rejects the\n * message undecoded through the same path as a non-conformant envelope — `onError` (with an error\n * naming the version, and an empty envelope since nothing was decoded) and the message is left\n * undeleted, so it is redelivered and the queue's `RedrivePolicy` moves it to the DLQ.\n \n Out-of-band headers (ADR-0028). A `headers` carrier (e.g. a W3C `traceparent` for cross-hop\n * span linkage) rides as additional String `MessageAttributes` beside the contract `bq-`\n attributes where `bq-trace-id` already lives — the contract attributes win a key collision, and\n * the merged set is bounded by SQS's 10-attribute limit (contract attributes are seeded first,\n * so a rider only lands while headroom remains). On consume the inbound `MessageAttributes` are\n * surfaced as a `Record<string,string>` so the core's `otel` extract sees the `traceparent` and\n * links the consumer span as a child. A header-less publish is byte-identical. This mirrors the Go\n * `/sqs` and PHP `SqsTransport` wiring. GR-1: the wire envelope body is never touched.\n /\n\nimport {\n BabelQueueError,\n EnvelopeCodec,\n SCHEMA_VERSION,\n UnknownUrnError,\n UnknownUrnStrategy,\n annotate,\n} from \"@babelqueue/core\";\nimport type { Envelope, HeaderCarrier, IncomingEnvelope } from \"@babelqueue/core\";\n\nimport { sanitizeHeaders } from \"./headers.js\";\n\n/* SQS allows at most 10 user message attributes per message. /\nconst MAX_ATTRIBUTES = 10;\n\n/* The SQS ceiling for a `VisibilityTimeout` (12 hours, in seconds). /\nexport const MAX_VISIBILITY_TIMEOUT = 43_200;\n\n// --- Minimal SQS shapes (a structural subset of @aws-sdk/client-sqs) -----------\n\nexport interface SqsMessageAttributeValue {\n DataType: string;\n StringValue?: string;\n}\n\nexport interface SqsMessage {\n Body?: string;\n ReceiptHandle?: string;\n MessageAttributes?: Record<string, SqsMessageAttributeValue>;\n Attributes?: Record<string, string>;\n}\n\nexport interface SendMessageInput {\n QueueUrl: string;\n MessageBody: string;\n MessageAttributes?: Record<string, SqsMessageAttributeValue>;\n MessageGroupId?: string;\n MessageDeduplicationId?: string;\n}\n\nexport interface ReceiveMessageInput {\n QueueUrl: string;\n MaxNumberOfMessages?: number;\n WaitTimeSeconds?: number;\n VisibilityTimeout?: number;\n MessageAttributeNames?: string[];\n AttributeNames?: string[];\n}\n\n/\n The subset of the AWS SQS client this adapter calls. The aggregated `SQS` class\n * from `@aws-sdk/client-sqs` satisfies it structurally; a fake satisfies it in tests.\n /\nexport interface SqsApi {\n sendMessage(input: SendMessageInput): Promise<{ MessageId?: string } \| unknown>;\n receiveMessage(input: ReceiveMessageInput): Promise<{ Messages?: SqsMessage[] }>;\n deleteMessage(input: { QueueUrl: string; ReceiptHandle: string }): Promise<unknown>;\n /\n The §3.5 release primitive. Optional so existing structural clients keep compiling; it is\n * required (checked at construction) when a consumer sets `releaseDelay` or the `release`\n * unknown-URN strategy explicitly. Without it the default handler-failure release degrades to\n * leaving the message for visibility-timeout redelivery. The aggregated `SQS` class from\n * `@aws-sdk/client-sqs` provides it.\n /\n changeMessageVisibility?(input: ChangeMessageVisibilityInput): Promise<unknown>;\n}\n\nexport interface ChangeMessageVisibilityInput {\n QueueUrl: string;\n ReceiptHandle: string;\n VisibilityTimeout: number;\n}\n\n// --- Attribute projection (contract §3.2) --------------------------------------\n\nconst str = (value: unknown): SqsMessageAttributeValue => ({\n DataType: \"String\",\n StringValue: String(value),\n});\nconst num = (value: unknown): SqsMessageAttributeValue => ({\n DataType: \"Number\",\n StringValue: String(value),\n});\n\n/\n Project the envelope's contract fields onto native SQS `MessageAttributes` — a\n * redundant, routable view of the body (the body stays authoritative).\n /\nexport function toMessageAttributes(envelope: Envelope): Record<string, SqsMessageAttributeValue> {\n const attrs: Record<string, SqsMessageAttributeValue> = {};\n if (envelope.job) attrs[\"bq-job\"] = str(envelope.job);\n if (envelope.trace_id) attrs[\"bq-trace-id\"] = str(envelope.trace_id);\n if (envelope.meta.id) attrs[\"bq-message-id\"] = str(envelope.meta.id);\n if (envelope.meta.schema_version != null) {\n attrs[\"bq-schema-version\"] = num(envelope.meta.schema_version);\n }\n if (envelope.meta.lang) attrs[\"bq-source-lang\"] = str(envelope.meta.lang);\n if (envelope.meta.created_at != null) {\n attrs[\"bq-created-at\"] = num(envelope.meta.created_at);\n }\n return attrs;\n}\n\n/\n Overlay the out-of-band `headers` onto the contract attribute projection as String\n * `MessageAttributes`, without overwriting an existing `bq-` attribute (the contract wins a key\n collision) and skipping blanks. Keys are merged in sorted order and the merge stops at the\n * 10-attribute SQS ceiling, so unbounded riders can never push the message past the limit (SQS\n * rejects the whole send otherwise) — the contract attributes are always preserved first. Mirrors\n * Go's `mergeAttributes` / PHP's `SqsTransport::attributes`.\n /\nexport function mergeAttributes(\n base: Record<string, SqsMessageAttributeValue>,\n headers: HeaderCarrier \| null \| undefined,\n): Record<string, SqsMessageAttributeValue> {\n const clean = sanitizeHeaders(headers);\n for (const key of Object.keys(clean).sort()) {\n if (key in base) continue; // never clobber a contract bq- attribute\n if (Object.keys(base).length >= MAX_ATTRIBUTES) break; // respect the SQS 10-attribute cap\n base[key] = str(clean[key]);\n }\n return base;\n}\n\n/*\n Map inbound SQS `MessageAttributes` onto a flat {@link HeaderCarrier} (the consume-side\n * counterpart of {@link mergeAttributes}), reading each attribute's `StringValue`. Returns an empty\n * object when there are none. Both the contract `bq-` attributes and any out-of-band rider (e.g.\n `traceparent`) surface — the core's `otel` extract reads only the keys it knows.\n /\nexport function headersOf(message: SqsMessage): HeaderCarrier {\n const attrs = message.MessageAttributes;\n const out: HeaderCarrier = {};\n if (!attrs) return out;\n for (const key of Object.keys(attrs)) {\n const value = attrs[key]?.StringValue;\n if (value != null && value !== \"\") out[key] = value;\n }\n return out;\n}\n\n/* Blank = empty or only ASCII whitespace (space, \\t, \\n, \\v, \\f, \\r) — not `String.prototype.trim()`'s wider set. /\nconst BLANK_ASCII = /^[ \\t\\n\\v\\f\\r]$/;\n\n/*\n The `bq-schema-version` message attribute when it is present, non-blank and not the supported\n * version (compared against the core's `SCHEMA_VERSION`, exact string match: `\"01\"`, `\" 1\"`, `\"1.0\"`\n * are rejected). Blank means the empty string or only ASCII whitespace (the same set in every SDK,\n * GR-5); NBSP, U+0085, U+FEFF, U+3000 and the like are not blank. `undefined` when the message may\n * be decoded.\n /\nfunction unsupportedSchemaVersion(message: SqsMessage): string \| undefined {\n const raw: unknown = message.MessageAttributes?.[\"bq-schema-version\"]?.StringValue;\n if (typeof raw !== \"string\" \|\| BLANK_ASCII.test(raw)) return undefined;\n return raw === String(SCHEMA_VERSION) ? undefined : raw;\n}\n\nfunction queueNameFromUrl(queueUrl: string): string {\n const segments = queueUrl.split(\"/\").filter(Boolean);\n return segments[segments.length - 1] ?? \"default\";\n}\n\n// --- Publisher -----------------------------------------------------------------\n\n/* Options for {@link SqsPublisher}. /\nexport interface SqsPublisherOptions {\n /* Treat the queue as FIFO: set `MessageGroupId` and (unless content dedup) `MessageDeduplicationId`. /\n fifo?: boolean;\n /* FIFO ordering group (default: the queue name from the URL). /\n messageGroupId?: string;\n /* Use the queue's content-based dedup instead of `meta.id` as the dedup id. /\n contentDedup?: boolean;\n}\n\n/* Options for {@link SqsPublisher.publish}. /\nexport interface PublishOptions {\n /* Reuse an existing trace id (trace continuation). /\n traceId?: string;\n /\n Out-of-band transport headers carried as String `MessageAttributes` beside the contract `bq-`\n attributes (ADR-0028) — e.g. a W3C `traceparent` written by `@babelqueue/core/otel`'s `publish`.\n * The contract attributes win a key collision and the merged set is capped at SQS's 10-attribute\n * limit; an empty/omitted carrier leaves the publish unchanged.\n /\n headers?: HeaderCarrier;\n}\n\n/* Sends canonical-envelope messages to one SQS queue with the §3 attribute projection. /\nexport class SqsPublisher {\n constructor(\n private readonly client: SqsApi,\n private readonly queueUrl: string,\n private readonly options: SqsPublisherOptions = {},\n ) {}\n\n /\n Build the canonical envelope for `(urn, data)`, send it as the message body with\n * the projected `MessageAttributes`, and return the message id (`meta.id`).\n /\n async publish(\n urn: string,\n data: Record<string, unknown>,\n options: PublishOptions = {},\n ): Promise<string> {\n const envelope = EnvelopeCodec.make(urn, data, {\n queue: queueNameFromUrl(this.queueUrl),\n traceId: options.traceId,\n });\n const input: SendMessageInput = {\n QueueUrl: this.queueUrl,\n MessageBody: EnvelopeCodec.encode(envelope),\n MessageAttributes: mergeAttributes(toMessageAttributes(envelope), options.headers),\n };\n if (this.options.fifo) {\n input.MessageGroupId = this.options.messageGroupId ?? queueNameFromUrl(this.queueUrl);\n if (!this.options.contentDedup) {\n input.MessageDeduplicationId = envelope.meta.id;\n }\n }\n await this.client.sendMessage(input);\n return envelope.meta.id;\n }\n}\n\n// --- Consumer ------------------------------------------------------------------\n\n/\n A URN handler. Receives the validated envelope, the raw SQS message, and the out-of-band\n * {@link HeaderCarrier} read from the message's `MessageAttributes` (empty when there are none).\n * Pass `headers` to `@babelqueue/core/otel`'s `wrapHandler` to link the consumer span as a child of\n * the producer span (ADR-0028).\n /\nexport type BabelHandler = (envelope: Envelope, message: SqsMessage, headers: HeaderCarrier) => unknown \| Promise<unknown>;\n\n/* A map of URN → handler. /\nexport type BabelHandlers = Record<string, BabelHandler>;\n\n/* Options for {@link SqsConsumer}. /\nexport interface SqsConsumerOptions {\n /\n Called when a message's URN has no handler. Without `unknownUrn` the message is then deleted\n * (the original behaviour); with `unknownUrn` set it is a notification hook and the strategy\n * decides the message's fate.\n /\n onUnknownUrn?: (envelope: IncomingEnvelope, message: SqsMessage) => unknown \| Promise<unknown>;\n /\n Unknown-URN strategy per contract §3.5 — `fail` \| `delete` \| `release` \| `dead_letter`\n * ({@link UnknownUrnStrategy}). Omitted keeps the original behaviour (`onUnknownUrn` → delete,\n * otherwise report and leave for visibility-timeout redelivery, i.e. `fail`). `release` uses\n * `ChangeMessageVisibility` with {@link unknownUrnReleaseDelay}; `dead_letter` sends the annotated\n * envelope to {@link deadLetterQueueUrl} then deletes, degrading to `delete` when no DLQ is set.\n /\n unknownUrn?: string;\n /* Backoff (seconds) for the `release` unknown-URN strategy (default 0 = redeliver now). /\n unknownUrnReleaseDelay?: number;\n /\n Backoff before a failed message is redelivered. A failed handler always releases the message\n * via `ChangeMessageVisibility(ReceiptHandle, VisibilityTimeout)` (contract §3.5); this sets the\n * `VisibilityTimeout` — a number of seconds, or a function of the (reconciled) `attempts`\n * returning seconds (e.g. an exponential backoff). Clamped to `0…43200`. Default `0`: the message\n * is visible again immediately. A permanently failing handler therefore retries without pause\n * until the queue's `RedrivePolicy` (`maxReceiveCount`) moves it to the DLQ — configure one.\n /\n releaseDelay?: number \| ((attempts: number) => number);\n /\n The cross-language `<queue>.dlq` URL for the `dead_letter` strategy (opt-in; default none). A\n * `.fifo` DLQ is sent with `MessageGroupId` (the source queue name) and `MessageDeduplicationId`\n * (`meta.id`).\n /\n deadLetterQueueUrl?: string \| null;\n /\n Called for a non-conformant envelope, an unmapped URN (no `onUnknownUrn`), a throwing handler,\n * a throwing `onUnknownUrn` under an `unknownUrn` strategy, a failed release / dead-letter send, or\n * a failed delete after successful processing (an {@link SqsDeleteError} wrapping the broker\n * error; never released). The message is then left for visibility-timeout redelivery. The loop\n * never stops on these.\n /\n onError?: (error: unknown, envelope: IncomingEnvelope, message: SqsMessage) => void;\n /* Long-poll wait seconds (default 20). /\n waitTimeSeconds?: number;\n /* Reservation window applied on receive (seconds). /\n visibilityTimeout?: number;\n /* Max messages per receive (default 10). /\n maxMessages?: number;\n}\n\n/\n Reported via `onError` when `DeleteMessage` fails for a message whose processing already succeeded\n * (a handler returned normally, or the unknown-URN strategy chose `delete` / `dead_letter`). The\n * broker error is `cause`. Distinct from a handler failure: the message is NOT released, so it is\n * redelivered only after its visibility timeout expires (at-least-once; dedupe on `meta.id` with the\n * idempotency helper if the side effect must not repeat).\n /\nexport class SqsDeleteError extends BabelQueueError {\n constructor(cause: unknown) {\n super(\"Failed to delete a processed SQS message; it will be redelivered after its visibility timeout.\");\n this.name = \"SqsDeleteError\";\n this.cause = cause;\n }\n}\n\n/\n Polls an SQS queue, decodes + validates each message, routes it to the handler\n * registered for its URN, and deletes it on success. A throwing handler's message is released via\n * `ChangeMessageVisibility` after `releaseDelay` (default 0 s, contract §3.5); if the release itself\n * fails the message is left for visibility-timeout redelivery (at-least-once);\n * `attempts` is reconciled to `ApproximateReceiveCount − 1` for the handler. An unmapped URN\n * follows the `unknownUrn` strategy (`fail` \| `delete` \| `release` \| `dead_letter`).\n /\nexport class SqsConsumer {\n constructor(\n private readonly client: SqsApi,\n private readonly queueUrl: string,\n private readonly handlers: BabelHandlers,\n private readonly options: SqsConsumerOptions = {},\n ) {\n const strategy = options.unknownUrn;\n if (strategy !== undefined && !(Object.values(UnknownUrnStrategy) as string[]).includes(strategy)) {\n throw new BabelQueueError(`Unknown unknownUrn strategy \"${strategy}\".`);\n }\n const needsRelease = options.releaseDelay != null \|\| strategy === UnknownUrnStrategy.RELEASE;\n if (needsRelease && typeof client.changeMessageVisibility !== \"function\") {\n throw new BabelQueueError(\n \"SqsConsumer release requires a client with changeMessageVisibility (contract §3.5).\",\n );\n }\n }\n\n /* Receive one batch, route each message, delete the ones handled. Returns the batch size. /\n async poll(): Promise<number> {\n const input: ReceiveMessageInput = {\n QueueUrl: this.queueUrl,\n MaxNumberOfMessages: this.options.maxMessages ?? 10,\n WaitTimeSeconds: this.options.waitTimeSeconds ?? 20,\n MessageAttributeNames: [\"All\"],\n AttributeNames: [\"ApproximateReceiveCount\"],\n };\n if (this.options.visibilityTimeout != null) {\n input.VisibilityTimeout = this.options.visibilityTimeout;\n }\n const result = await this.client.receiveMessage(input);\n const messages = result.Messages ?? [];\n for (const message of messages) {\n await this.handle(message);\n }\n return messages.length;\n }\n\n /* Poll until `signal` aborts (each poll long-polls, so this does not busy-loop). /\n async run(signal?: AbortSignal): Promise<void> {\n while (signal?.aborted !== true) {\n await this.poll();\n }\n }\n\n private async handle(message: SqsMessage): Promise<void> {\n // §3.7: gate on the bq-schema-version attribute before the body is decoded. The message is\n // not deleted, so SQS redelivers it and the queue's RedrivePolicy moves it to the DLQ.\n const rejectedVersion = unsupportedSchemaVersion(message);\n if (rejectedVersion !== undefined) {\n this.options.onError?.(\n new BabelQueueError(\n `Rejected a message from SQS with unsupported bq-schema-version \"${rejectedVersion}\" (supported: ${SCHEMA_VERSION}).`,\n ),\n {},\n message,\n );\n return;\n }\n\n const envelope = EnvelopeCodec.decode(message.Body ?? \"\");\n\n const receiveCount = message.Attributes?.[\"ApproximateReceiveCount\"];\n if (receiveCount !== undefined) {\n const native = Number.parseInt(receiveCount, 10) - 1;\n const current = typeof envelope.attempts === \"number\" ? envelope.attempts : 0;\n if (Number.isFinite(native) && native > current) {\n envelope.attempts = native;\n }\n }\n\n if (!EnvelopeCodec.accepts(envelope)) {\n this.options.onError?.(\n new BabelQueueError(\"Rejected a non-conformant BabelQueue envelope from SQS.\"),\n envelope,\n message,\n );\n return;\n }\n\n const urn = EnvelopeCodec.urn(envelope);\n const handler = this.handlers[urn];\n if (!handler) {\n await this.unknown(urn, envelope as Envelope, message);\n return;\n }\n\n try {\n await handler(envelope, message, headersOf(message));\n } catch (error) {\n this.options.onError?.(error, envelope, message);\n await this.guard(envelope, message, async () => {\n const delay = this.options.releaseDelay ?? 0;\n const attempts = typeof envelope.attempts === \"number\" ? envelope.attempts : 0;\n await this.release(message, typeof delay === \"function\" ? delay(attempts) : delay);\n });\n return;\n }\n // Outside the handler's try: a failed delete is not a handler failure. It is reported as an\n // SqsDeleteError and the message is NOT released — releasing at the (default 0 s) backoff would\n // redeliver an already-processed message immediately; it returns on visibility expiry instead.\n await this.guard(envelope, message, () => this.deleteHandled(message));\n }\n\n /\n Run a release / dead-letter step; a failure (e.g. `MessageNotInflight`, a missing IAM grant, a\n * throwing `releaseDelay`) is reported to `onError` and the message is left undeleted, so\n * visibility expiry still redelivers it. Never lets the error stop the consume loop.\n /\n private async guard(envelope: IncomingEnvelope, message: SqsMessage, step: () => Promise<void>): Promise<void> {\n try {\n await step();\n } catch (error) {\n this.options.onError?.(error, envelope, message);\n }\n }\n\n /* Apply the unknown-URN strategy (contract §3.5). /\n private async unknown(urn: string, envelope: Envelope, message: SqsMessage): Promise<void> {\n const strategy = this.options.unknownUrn;\n if (strategy === undefined) {\n if (this.options.onUnknownUrn) {\n await this.options.onUnknownUrn(envelope, message);\n await this.delete(message);\n } else {\n this.options.onError?.(new UnknownUrnError(urn), envelope, message);\n }\n return;\n }\n\n await this.guard(envelope, message, async () => {\n await this.options.onUnknownUrn?.(envelope, message);\n });\n switch (strategy) {\n case UnknownUrnStrategy.DELETE:\n await this.guard(envelope, message, () => this.deleteHandled(message));\n return;\n case UnknownUrnStrategy.RELEASE:\n await this.guard(envelope, message, () => this.release(message, this.options.unknownUrnReleaseDelay ?? 0));\n return;\n case UnknownUrnStrategy.DEAD_LETTER:\n await this.guard(envelope, message, async () => {\n await this.deadLetter(envelope, \"unknown_urn\");\n await this.deleteHandled(message);\n });\n return;\n default:\n // FAIL: surface and do NOT delete — visibility expiry redelivers, native redrive quarantines.\n this.options.onError?.(new UnknownUrnError(urn), envelope, message);\n }\n }\n\n /* Make the message visible again after `seconds` via `ChangeMessageVisibility`; never deletes. /\n private async release(message: SqsMessage, seconds: number): Promise<void> {\n if (!message.ReceiptHandle \|\| !this.client.changeMessageVisibility) return;\n const timeout = Number.isFinite(seconds)\n ? Math.min(MAX_VISIBILITY_TIMEOUT, Math.max(0, Math.floor(seconds)))\n : 0;\n await this.client.changeMessageVisibility({\n QueueUrl: this.queueUrl,\n ReceiptHandle: message.ReceiptHandle,\n VisibilityTimeout: timeout,\n });\n }\n\n /* Send the annotated envelope to the opt-in DLQ; a no-op (→ plain delete) when none is set. /\n private async deadLetter(envelope: Envelope, reason: string): Promise<void> {\n const dlq = this.options.deadLetterQueueUrl;\n if (!dlq) return;\n const source = envelope.meta?.queue ?? queueNameFromUrl(this.queueUrl);\n const annotated = annotate(envelope, reason, source, {\n attempts: envelope.attempts ?? 0,\n });\n const input: SendMessageInput = {\n QueueUrl: dlq,\n MessageBody: EnvelopeCodec.encode(annotated),\n MessageAttributes: toMessageAttributes(annotated),\n };\n if (dlq.endsWith(\".fifo\")) {\n // A FIFO DLQ (`<queue>.dlq.fifo`) rejects a send without a group; dedup on meta.id (§3.2).\n input.MessageGroupId = source;\n if (annotated.meta?.id) input.MessageDeduplicationId = annotated.meta.id;\n }\n await this.client.sendMessage(input);\n }\n\n /* Delete a message whose processing already succeeded; a broker failure becomes an SqsDeleteError. /\n private async deleteHandled(message: SqsMessage): Promise<void> {\n try {\n await this.delete(message);\n } catch (error) {\n throw new SqsDeleteError(error);\n }\n }\n\n private async delete(message: SqsMessage): Promise<void> {\n if (!message.ReceiptHandle) return;\n await this.client.deleteMessage({\n QueueUrl: this.queueUrl,\n ReceiptHandle: message.ReceiptHandle,\n });\n }\n}\n","/\n Pure, dependency-free helpers for the out-of-band transport-header seam (ADR-0028) — the Node\n * adapter mirror of Go's `sanitizeHeaders` and PHP's `Support\\Headers`. They fold an injected\n * {@link HeaderCarrier} (e.g. a W3C `traceparent`) onto a transport's metadata channel *without\n clobbering** the contract headers it already carries.\n \n Headers ride beside the frozen wire envelope (GR-1), never inside it.\n /\n\nimport type { HeaderCarrier } from \"@babelqueue/core\";\n\n/\n Copy `headers`, dropping blank keys and blank values. Returns an empty object when nothing\n * survives, so a caller can treat the result as \"no headers\". A nullish input yields an empty\n * object.\n */\nexport function sanitizeHeaders(headers: HeaderCarrier \| null \| undefined): HeaderCarrier {\n const out: HeaderCarrier = {};\n if (!headers) return out;\n for (const key of Object.keys(headers)) {\n const value = headers[key];\n if (key === \"\" \|\| value == null \|\| value === \"\") continue;\n out[key] = value;\n }\n return out;\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts CHANGED Viewed

@@ -1,4 +1,4 @@
-import { Envelope, HeaderCarrier, IncomingEnvelope } from '@babelqueue/core';
+import { Envelope, HeaderCarrier, IncomingEnvelope, BabelQueueError } from '@babelqueue/core';
 /**
  * Amazon SQS adapter for BabelQueue.
@@ -23,10 +23,18 @@ import { Envelope, HeaderCarrier, IncomingEnvelope } from '@babelqueue/core';
  * This implements §3 of the broker-bindings contract: the canonical envelope is the
  * message body, projected onto native SQS `MessageAttributes`. The envelope is
  * unchanged (`schema_version` stays 1); SQS is purely additive. Retry is SQS-native
- * (a failed handler leaves the message for visibility-timeout redelivery); the
+ * (a failed handler's message is released via `ChangeMessageVisibility` after
+ * `releaseDelay`, default 0 s — pair the queue with a `RedrivePolicy`); the
  * authoritative attempt count is `ApproximateReceiveCount`, surfaced to handlers as
  * `attempts = count − 1`.
  *
+ * **Version gate (§3.7).** Before the body is decoded the consumer reads the `bq-schema-version`
+ * message attribute. 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 the message is left
+ * undeleted, so it is redelivered and the queue's `RedrivePolicy` moves it to the DLQ.
+ *
  * **Out-of-band headers (ADR-0028).** A `headers` carrier (e.g. a W3C `traceparent` for cross-hop
  * span linkage) rides as additional String `MessageAttributes` **beside** the contract `bq-*`
  * attributes where `bq-trace-id` already lives — the contract attributes win a key collision, and
@@ -37,6 +45,8 @@ import { Envelope, HeaderCarrier, IncomingEnvelope } from '@babelqueue/core';
  * `/sqs` and PHP `SqsTransport` wiring. GR-1: the wire envelope body is never touched.
  */
+/** The SQS ceiling for a `VisibilityTimeout` (12 hours, in seconds). */
+declare const MAX_VISIBILITY_TIMEOUT = 43200;
 interface SqsMessageAttributeValue {
     DataType: string;
     StringValue?: string;
@@ -77,6 +87,19 @@ interface SqsApi {
         QueueUrl: string;
         ReceiptHandle: string;
     }): Promise<unknown>;
+    /**
+     * The §3.5 release primitive. Optional so existing structural clients keep compiling; it is
+     * required (checked at construction) when a consumer sets `releaseDelay` or the `release`
+     * unknown-URN strategy explicitly. Without it the default handler-failure release degrades to
+     * leaving the message for visibility-timeout redelivery. The aggregated `SQS` class from
+     * `@aws-sdk/client-sqs` provides it.
+     */
+    changeMessageVisibility?(input: ChangeMessageVisibilityInput): Promise<unknown>;
+}
+interface ChangeMessageVisibilityInput {
+    QueueUrl: string;
+    ReceiptHandle: string;
+    VisibilityTimeout: number;
 }
 /**
  * Project the envelope's contract fields onto native SQS `MessageAttributes` — a
@@ -143,9 +166,44 @@ type BabelHandler = (envelope: Envelope, message: SqsMessage, headers: HeaderCar
 type BabelHandlers = Record<string, BabelHandler>;
 /** Options for {@link SqsConsumer}. */
 interface SqsConsumerOptions {
-    /** Called instead of erroring when a message's URN has no handler (then the message is deleted). */
+    /**
+     * Called when a message's URN has no handler. Without `unknownUrn` the message is then deleted
+     * (the original behaviour); with `unknownUrn` set it is a notification hook and the strategy
+     * decides the message's fate.
+     */
     onUnknownUrn?: (envelope: IncomingEnvelope, message: SqsMessage) => unknown | Promise<unknown>;
-    /** Called for a non-conformant envelope, an unmapped URN (no `onUnknownUrn`), or a throwing handler. The loop never stops. */
+    /**
+     * Unknown-URN strategy per contract §3.5 — `fail` | `delete` | `release` | `dead_letter`
+     * ({@link UnknownUrnStrategy}). Omitted keeps the original behaviour (`onUnknownUrn` → delete,
+     * otherwise report and leave for visibility-timeout redelivery, i.e. `fail`). `release` uses
+     * `ChangeMessageVisibility` with {@link unknownUrnReleaseDelay}; `dead_letter` sends the annotated
+     * envelope to {@link deadLetterQueueUrl} then deletes, degrading to `delete` when no DLQ is set.
+     */
+    unknownUrn?: string;
+    /** Backoff (seconds) for the `release` unknown-URN strategy (default 0 = redeliver now). */
+    unknownUrnReleaseDelay?: number;
+    /**
+     * Backoff before a failed message is redelivered. A failed handler always releases the message
+     * via `ChangeMessageVisibility(ReceiptHandle, VisibilityTimeout)` (contract §3.5); this sets the
+     * `VisibilityTimeout` — a number of seconds, or a function of the (reconciled) `attempts`
+     * returning seconds (e.g. an exponential backoff). Clamped to `0…43200`. Default `0`: the message
+     * is visible again immediately. A permanently failing handler therefore retries without pause
+     * until the queue's `RedrivePolicy` (`maxReceiveCount`) moves it to the DLQ — configure one.
+     */
+    releaseDelay?: number | ((attempts: number) => number);
+    /**
+     * The cross-language `<queue>.dlq` URL for the `dead_letter` strategy (opt-in; default none). A
+     * `.fifo` DLQ is sent with `MessageGroupId` (the source queue name) and `MessageDeduplicationId`
+     * (`meta.id`).
+     */
+    deadLetterQueueUrl?: string | null;
+    /**
+     * Called for a non-conformant envelope, an unmapped URN (no `onUnknownUrn`), a throwing handler,
+     * a throwing `onUnknownUrn` under an `unknownUrn` strategy, a failed release / dead-letter send, or
+     * a failed delete after successful processing (an {@link SqsDeleteError} wrapping the broker
+     * error; never released). The message is then left for visibility-timeout redelivery. The loop
+     * never stops on these.
+     */
     onError?: (error: unknown, envelope: IncomingEnvelope, message: SqsMessage) => void;
     /** Long-poll wait seconds (default 20). */
     waitTimeSeconds?: number;
@@ -154,11 +212,23 @@ interface SqsConsumerOptions {
     /** Max messages per receive (default 10). */
     maxMessages?: number;
 }
+/**
+ * Reported via `onError` when `DeleteMessage` fails for a message whose processing already succeeded
+ * (a handler returned normally, or the unknown-URN strategy chose `delete` / `dead_letter`). The
+ * broker error is `cause`. Distinct from a handler failure: the message is NOT released, so it is
+ * redelivered only after its visibility timeout expires (at-least-once; dedupe on `meta.id` with the
+ * idempotency helper if the side effect must not repeat).
+ */
+declare class SqsDeleteError extends BabelQueueError {
+    constructor(cause: unknown);
+}
 /**
  * Polls an SQS queue, decodes + validates each message, routes it to the handler
- * registered for its URN, and deletes it on success. A throwing handler leaves the
- * message undeleted — SQS redelivers it after the visibility timeout (at-least-once);
- * `attempts` is reconciled to `ApproximateReceiveCount − 1` for the handler.
+ * registered for its URN, and deletes it on success. A throwing handler's message is released via
+ * `ChangeMessageVisibility` after `releaseDelay` (default 0 s, contract §3.5); if the release itself
+ * fails the message is left for visibility-timeout redelivery (at-least-once);
+ * `attempts` is reconciled to `ApproximateReceiveCount − 1` for the handler. An unmapped URN
+ * follows the `unknownUrn` strategy (`fail` | `delete` | `release` | `dead_letter`).
  */
 declare class SqsConsumer {
     private readonly client;
@@ -171,7 +241,21 @@ declare class SqsConsumer {
     /** Poll until `signal` aborts (each poll long-polls, so this does not busy-loop). */
     run(signal?: AbortSignal): Promise<void>;
     private handle;
+    /**
+     * Run a release / dead-letter step; a failure (e.g. `MessageNotInflight`, a missing IAM grant, a
+     * throwing `releaseDelay`) is reported to `onError` and the message is left undeleted, so
+     * visibility expiry still redelivers it. Never lets the error stop the consume loop.
+     */
+    private guard;
+    /** Apply the unknown-URN strategy (contract §3.5). */
+    private unknown;
+    /** Make the message visible again after `seconds` via `ChangeMessageVisibility`; never deletes. */
+    private release;
+    /** Send the annotated envelope to the opt-in DLQ; a no-op (→ plain delete) when none is set. */
+    private deadLetter;
+    /** Delete a message whose processing already succeeded; a broker failure becomes an SqsDeleteError. */
+    private deleteHandled;
     private delete;
 }
-export { type BabelHandler, type BabelHandlers, type PublishOptions, type ReceiveMessageInput, type SendMessageInput, type SqsApi, SqsConsumer, type SqsConsumerOptions, type SqsMessage, type SqsMessageAttributeValue, SqsPublisher, type SqsPublisherOptions, headersOf, mergeAttributes, toMessageAttributes };
+export { type BabelHandler, type BabelHandlers, type ChangeMessageVisibilityInput, MAX_VISIBILITY_TIMEOUT, type PublishOptions, type ReceiveMessageInput, type SendMessageInput, type SqsApi, SqsConsumer, type SqsConsumerOptions, SqsDeleteError, type SqsMessage, type SqsMessageAttributeValue, SqsPublisher, type SqsPublisherOptions, headersOf, mergeAttributes, toMessageAttributes };

package/dist/index.d.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-import { Envelope, HeaderCarrier, IncomingEnvelope } from '@babelqueue/core';
+import { Envelope, HeaderCarrier, IncomingEnvelope, BabelQueueError } from '@babelqueue/core';
 /**
  * Amazon SQS adapter for BabelQueue.
@@ -23,10 +23,18 @@ import { Envelope, HeaderCarrier, IncomingEnvelope } from '@babelqueue/core';
  * This implements §3 of the broker-bindings contract: the canonical envelope is the
  * message body, projected onto native SQS `MessageAttributes`. The envelope is
  * unchanged (`schema_version` stays 1); SQS is purely additive. Retry is SQS-native
- * (a failed handler leaves the message for visibility-timeout redelivery); the
+ * (a failed handler's message is released via `ChangeMessageVisibility` after
+ * `releaseDelay`, default 0 s — pair the queue with a `RedrivePolicy`); the
  * authoritative attempt count is `ApproximateReceiveCount`, surfaced to handlers as
  * `attempts = count − 1`.
  *
+ * **Version gate (§3.7).** Before the body is decoded the consumer reads the `bq-schema-version`
+ * message attribute. 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 the message is left
+ * undeleted, so it is redelivered and the queue's `RedrivePolicy` moves it to the DLQ.
+ *
  * **Out-of-band headers (ADR-0028).** A `headers` carrier (e.g. a W3C `traceparent` for cross-hop
  * span linkage) rides as additional String `MessageAttributes` **beside** the contract `bq-*`
  * attributes where `bq-trace-id` already lives — the contract attributes win a key collision, and
@@ -37,6 +45,8 @@ import { Envelope, HeaderCarrier, IncomingEnvelope } from '@babelqueue/core';
  * `/sqs` and PHP `SqsTransport` wiring. GR-1: the wire envelope body is never touched.
  */
+/** The SQS ceiling for a `VisibilityTimeout` (12 hours, in seconds). */
+declare const MAX_VISIBILITY_TIMEOUT = 43200;
 interface SqsMessageAttributeValue {
     DataType: string;
     StringValue?: string;
@@ -77,6 +87,19 @@ interface SqsApi {
         QueueUrl: string;
         ReceiptHandle: string;
     }): Promise<unknown>;
+    /**
+     * The §3.5 release primitive. Optional so existing structural clients keep compiling; it is
+     * required (checked at construction) when a consumer sets `releaseDelay` or the `release`
+     * unknown-URN strategy explicitly. Without it the default handler-failure release degrades to
+     * leaving the message for visibility-timeout redelivery. The aggregated `SQS` class from
+     * `@aws-sdk/client-sqs` provides it.
+     */
+    changeMessageVisibility?(input: ChangeMessageVisibilityInput): Promise<unknown>;
+}
+interface ChangeMessageVisibilityInput {
+    QueueUrl: string;
+    ReceiptHandle: string;
+    VisibilityTimeout: number;
 }
 /**
  * Project the envelope's contract fields onto native SQS `MessageAttributes` — a
@@ -143,9 +166,44 @@ type BabelHandler = (envelope: Envelope, message: SqsMessage, headers: HeaderCar
 type BabelHandlers = Record<string, BabelHandler>;
 /** Options for {@link SqsConsumer}. */
 interface SqsConsumerOptions {
-    /** Called instead of erroring when a message's URN has no handler (then the message is deleted). */
+    /**
+     * Called when a message's URN has no handler. Without `unknownUrn` the message is then deleted
+     * (the original behaviour); with `unknownUrn` set it is a notification hook and the strategy
+     * decides the message's fate.
+     */
     onUnknownUrn?: (envelope: IncomingEnvelope, message: SqsMessage) => unknown | Promise<unknown>;
-    /** Called for a non-conformant envelope, an unmapped URN (no `onUnknownUrn`), or a throwing handler. The loop never stops. */
+    /**
+     * Unknown-URN strategy per contract §3.5 — `fail` | `delete` | `release` | `dead_letter`
+     * ({@link UnknownUrnStrategy}). Omitted keeps the original behaviour (`onUnknownUrn` → delete,
+     * otherwise report and leave for visibility-timeout redelivery, i.e. `fail`). `release` uses
+     * `ChangeMessageVisibility` with {@link unknownUrnReleaseDelay}; `dead_letter` sends the annotated
+     * envelope to {@link deadLetterQueueUrl} then deletes, degrading to `delete` when no DLQ is set.
+     */
+    unknownUrn?: string;
+    /** Backoff (seconds) for the `release` unknown-URN strategy (default 0 = redeliver now). */
+    unknownUrnReleaseDelay?: number;
+    /**
+     * Backoff before a failed message is redelivered. A failed handler always releases the message
+     * via `ChangeMessageVisibility(ReceiptHandle, VisibilityTimeout)` (contract §3.5); this sets the
+     * `VisibilityTimeout` — a number of seconds, or a function of the (reconciled) `attempts`
+     * returning seconds (e.g. an exponential backoff). Clamped to `0…43200`. Default `0`: the message
+     * is visible again immediately. A permanently failing handler therefore retries without pause
+     * until the queue's `RedrivePolicy` (`maxReceiveCount`) moves it to the DLQ — configure one.
+     */
+    releaseDelay?: number | ((attempts: number) => number);
+    /**
+     * The cross-language `<queue>.dlq` URL for the `dead_letter` strategy (opt-in; default none). A
+     * `.fifo` DLQ is sent with `MessageGroupId` (the source queue name) and `MessageDeduplicationId`
+     * (`meta.id`).
+     */
+    deadLetterQueueUrl?: string | null;
+    /**
+     * Called for a non-conformant envelope, an unmapped URN (no `onUnknownUrn`), a throwing handler,
+     * a throwing `onUnknownUrn` under an `unknownUrn` strategy, a failed release / dead-letter send, or
+     * a failed delete after successful processing (an {@link SqsDeleteError} wrapping the broker
+     * error; never released). The message is then left for visibility-timeout redelivery. The loop
+     * never stops on these.
+     */
     onError?: (error: unknown, envelope: IncomingEnvelope, message: SqsMessage) => void;
     /** Long-poll wait seconds (default 20). */
     waitTimeSeconds?: number;
@@ -154,11 +212,23 @@ interface SqsConsumerOptions {
     /** Max messages per receive (default 10). */
     maxMessages?: number;
 }
+/**
+ * Reported via `onError` when `DeleteMessage` fails for a message whose processing already succeeded
+ * (a handler returned normally, or the unknown-URN strategy chose `delete` / `dead_letter`). The
+ * broker error is `cause`. Distinct from a handler failure: the message is NOT released, so it is
+ * redelivered only after its visibility timeout expires (at-least-once; dedupe on `meta.id` with the
+ * idempotency helper if the side effect must not repeat).
+ */
+declare class SqsDeleteError extends BabelQueueError {
+    constructor(cause: unknown);
+}
 /**
  * Polls an SQS queue, decodes + validates each message, routes it to the handler
- * registered for its URN, and deletes it on success. A throwing handler leaves the
- * message undeleted — SQS redelivers it after the visibility timeout (at-least-once);
- * `attempts` is reconciled to `ApproximateReceiveCount − 1` for the handler.
+ * registered for its URN, and deletes it on success. A throwing handler's message is released via
+ * `ChangeMessageVisibility` after `releaseDelay` (default 0 s, contract §3.5); if the release itself
+ * fails the message is left for visibility-timeout redelivery (at-least-once);
+ * `attempts` is reconciled to `ApproximateReceiveCount − 1` for the handler. An unmapped URN
+ * follows the `unknownUrn` strategy (`fail` | `delete` | `release` | `dead_letter`).
  */
 declare class SqsConsumer {
     private readonly client;
@@ -171,7 +241,21 @@ declare class SqsConsumer {
     /** Poll until `signal` aborts (each poll long-polls, so this does not busy-loop). */
     run(signal?: AbortSignal): Promise<void>;
     private handle;
+    /**
+     * Run a release / dead-letter step; a failure (e.g. `MessageNotInflight`, a missing IAM grant, a
+     * throwing `releaseDelay`) is reported to `onError` and the message is left undeleted, so
+     * visibility expiry still redelivers it. Never lets the error stop the consume loop.
+     */
+    private guard;
+    /** Apply the unknown-URN strategy (contract §3.5). */
+    private unknown;
+    /** Make the message visible again after `seconds` via `ChangeMessageVisibility`; never deletes. */
+    private release;
+    /** Send the annotated envelope to the opt-in DLQ; a no-op (→ plain delete) when none is set. */
+    private deadLetter;
+    /** Delete a message whose processing already succeeded; a broker failure becomes an SqsDeleteError. */
+    private deleteHandled;
     private delete;
 }
-export { type BabelHandler, type BabelHandlers, type PublishOptions, type ReceiveMessageInput, type SendMessageInput, type SqsApi, SqsConsumer, type SqsConsumerOptions, type SqsMessage, type SqsMessageAttributeValue, SqsPublisher, type SqsPublisherOptions, headersOf, mergeAttributes, toMessageAttributes };
+export { type BabelHandler, type BabelHandlers, type ChangeMessageVisibilityInput, MAX_VISIBILITY_TIMEOUT, type PublishOptions, type ReceiveMessageInput, type SendMessageInput, type SqsApi, SqsConsumer, type SqsConsumerOptions, SqsDeleteError, type SqsMessage, type SqsMessageAttributeValue, SqsPublisher, type SqsPublisherOptions, headersOf, mergeAttributes, toMessageAttributes };

package/dist/index.js CHANGED Viewed

@@ -1,5 +1,12 @@
 // src/index.ts
-import { BabelQueueError, EnvelopeCodec, UnknownUrnError } from "@babelqueue/core";
+import {
+  BabelQueueError,
+  EnvelopeCodec,
+  SCHEMA_VERSION,
+  UnknownUrnError,
+  UnknownUrnStrategy,
+  annotate
+} from "@babelqueue/core";
 // src/headers.ts
 function sanitizeHeaders(headers) {
@@ -15,6 +22,7 @@ function sanitizeHeaders(headers) {
 // src/index.ts
 var MAX_ATTRIBUTES = 10;
+var MAX_VISIBILITY_TIMEOUT = 43200;
 var str = (value) => ({
   DataType: "String",
   StringValue: String(value)
@@ -56,6 +64,12 @@ function headersOf(message) {
   }
   return out;
 }
+var BLANK_ASCII = /^[ \t\n\v\f\r]*$/;
+function unsupportedSchemaVersion(message) {
+  const raw = message.MessageAttributes?.["bq-schema-version"]?.StringValue;
+  if (typeof raw !== "string" || BLANK_ASCII.test(raw)) return void 0;
+  return raw === String(SCHEMA_VERSION) ? void 0 : raw;
+}
 function queueNameFromUrl(queueUrl) {
   const segments = queueUrl.split("/").filter(Boolean);
   return segments[segments.length - 1] ?? "default";
@@ -93,12 +107,29 @@ var SqsPublisher = class {
     return envelope.meta.id;
   }
 };
+var SqsDeleteError = class extends BabelQueueError {
+  constructor(cause) {
+    super("Failed to delete a processed SQS message; it will be redelivered after its visibility timeout.");
+    this.name = "SqsDeleteError";
+    this.cause = cause;
+  }
+};
 var SqsConsumer = class {
   constructor(client, queueUrl, handlers, options = {}) {
     this.client = client;
     this.queueUrl = queueUrl;
     this.handlers = handlers;
     this.options = options;
+    const strategy = options.unknownUrn;
+    if (strategy !== void 0 && !Object.values(UnknownUrnStrategy).includes(strategy)) {
+      throw new BabelQueueError(`Unknown unknownUrn strategy "${strategy}".`);
+    }
+    const needsRelease = options.releaseDelay != null || strategy === UnknownUrnStrategy.RELEASE;
+    if (needsRelease && typeof client.changeMessageVisibility !== "function") {
+      throw new BabelQueueError(
+        "SqsConsumer release requires a client with changeMessageVisibility (contract \xA73.5)."
+      );
+    }
   }
   client;
   queueUrl;
@@ -130,6 +161,17 @@ var SqsConsumer = class {
     }
   }
   async handle(message) {
+    const rejectedVersion = unsupportedSchemaVersion(message);
+    if (rejectedVersion !== void 0) {
+      this.options.onError?.(
+        new BabelQueueError(
+          `Rejected a message from SQS with unsupported bq-schema-version "${rejectedVersion}" (supported: ${SCHEMA_VERSION}).`
+        ),
+        {},
+        message
+      );
+      return;
+    }
     const envelope = EnvelopeCodec.decode(message.Body ?? "");
     const receiveCount = message.Attributes?.["ApproximateReceiveCount"];
     if (receiveCount !== void 0) {
@@ -150,6 +192,38 @@ var SqsConsumer = class {
     const urn = EnvelopeCodec.urn(envelope);
     const handler = this.handlers[urn];
     if (!handler) {
+      await this.unknown(urn, envelope, message);
+      return;
+    }
+    try {
+      await handler(envelope, message, headersOf(message));
+    } catch (error) {
+      this.options.onError?.(error, envelope, message);
+      await this.guard(envelope, message, async () => {
+        const delay = this.options.releaseDelay ?? 0;
+        const attempts = typeof envelope.attempts === "number" ? envelope.attempts : 0;
+        await this.release(message, typeof delay === "function" ? delay(attempts) : delay);
+      });
+      return;
+    }
+    await this.guard(envelope, message, () => this.deleteHandled(message));
+  }
+  /**
+   * Run a release / dead-letter step; a failure (e.g. `MessageNotInflight`, a missing IAM grant, a
+   * throwing `releaseDelay`) is reported to `onError` and the message is left undeleted, so
+   * visibility expiry still redelivers it. Never lets the error stop the consume loop.
+   */
+  async guard(envelope, message, step) {
+    try {
+      await step();
+    } catch (error) {
+      this.options.onError?.(error, envelope, message);
+    }
+  }
+  /** Apply the unknown-URN strategy (contract §3.5). */
+  async unknown(urn, envelope, message) {
+    const strategy = this.options.unknownUrn;
+    if (strategy === void 0) {
       if (this.options.onUnknownUrn) {
         await this.options.onUnknownUrn(envelope, message);
         await this.delete(message);
@@ -158,11 +232,61 @@ var SqsConsumer = class {
       }
       return;
     }
+    await this.guard(envelope, message, async () => {
+      await this.options.onUnknownUrn?.(envelope, message);
+    });
+    switch (strategy) {
+      case UnknownUrnStrategy.DELETE:
+        await this.guard(envelope, message, () => this.deleteHandled(message));
+        return;
+      case UnknownUrnStrategy.RELEASE:
+        await this.guard(envelope, message, () => this.release(message, this.options.unknownUrnReleaseDelay ?? 0));
+        return;
+      case UnknownUrnStrategy.DEAD_LETTER:
+        await this.guard(envelope, message, async () => {
+          await this.deadLetter(envelope, "unknown_urn");
+          await this.deleteHandled(message);
+        });
+        return;
+      default:
+        this.options.onError?.(new UnknownUrnError(urn), envelope, message);
+    }
+  }
+  /** Make the message visible again after `seconds` via `ChangeMessageVisibility`; never deletes. */
+  async release(message, seconds) {
+    if (!message.ReceiptHandle || !this.client.changeMessageVisibility) return;
+    const timeout = Number.isFinite(seconds) ? Math.min(MAX_VISIBILITY_TIMEOUT, Math.max(0, Math.floor(seconds))) : 0;
+    await this.client.changeMessageVisibility({
+      QueueUrl: this.queueUrl,
+      ReceiptHandle: message.ReceiptHandle,
+      VisibilityTimeout: timeout
+    });
+  }
+  /** Send the annotated envelope to the opt-in DLQ; a no-op (→ plain delete) when none is set. */
+  async deadLetter(envelope, reason) {
+    const dlq = this.options.deadLetterQueueUrl;
+    if (!dlq) return;
+    const source = envelope.meta?.queue ?? queueNameFromUrl(this.queueUrl);
+    const annotated = annotate(envelope, reason, source, {
+      attempts: envelope.attempts ?? 0
+    });
+    const input = {
+      QueueUrl: dlq,
+      MessageBody: EnvelopeCodec.encode(annotated),
+      MessageAttributes: toMessageAttributes(annotated)
+    };
+    if (dlq.endsWith(".fifo")) {
+      input.MessageGroupId = source;
+      if (annotated.meta?.id) input.MessageDeduplicationId = annotated.meta.id;
+    }
+    await this.client.sendMessage(input);
+  }
+  /** Delete a message whose processing already succeeded; a broker failure becomes an SqsDeleteError. */
+  async deleteHandled(message) {
     try {
-      await handler(envelope, message, headersOf(message));
       await this.delete(message);
     } catch (error) {
-      this.options.onError?.(error, envelope, message);
+      throw new SqsDeleteError(error);
     }
   }
   async delete(message) {
@@ -174,7 +298,9 @@ var SqsConsumer = class {
   }
 };
 export {
+  MAX_VISIBILITY_TIMEOUT,
   SqsConsumer,
+  SqsDeleteError,
   SqsPublisher,
   headersOf,
   mergeAttributes,

package/dist/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/index.ts","../src/headers.ts"],"sourcesContent":["/*\n Amazon SQS adapter for BabelQueue.\n \n A canonical-envelope publisher and a URN-routed consumer over Amazon SQS,\n * so an SQS-based Node service speaks the same contract (envelope shape, URN\n * identity, trace propagation) as the PHP/Laravel, Python, Go, Java and .NET SDKs.\n \n import { SQS } from \"@aws-sdk/client-sqs\";\n * import { SqsPublisher, SqsConsumer } from \"@babelqueue/sqs\";\n \n const sqs = new SQS({ region: \"eu-central-1\" });\n * const url = \"https://sqs.eu-central-1.amazonaws.com/123456789012/orders\";\n \n await new SqsPublisher(sqs, url).publish(\"urn:babel:orders:created\", { order_id: 1042 });\n \n const consumer = new SqsConsumer(sqs, url, {\n * \"urn:babel:orders:created\": async (env) => { ... },\n * });\n * await consumer.run();\n \n This implements §3 of the broker-bindings contract: the canonical envelope is the\n * message body, projected onto native SQS `MessageAttributes`. The envelope is\n * unchanged (`schema_version` stays 1); SQS is purely additive. Retry is SQS-native\n * (a failed handler leaves the message for visibility-timeout redelivery); the\n * authoritative attempt count is `ApproximateReceiveCount`, surfaced to handlers as\n * `attempts = count − 1`.\n \n Out-of-band headers (ADR-0028). A `headers` carrier (e.g. a W3C `traceparent` for cross-hop\n * span linkage) rides as additional String `MessageAttributes` beside the contract `bq-`\n attributes where `bq-trace-id` already lives — the contract attributes win a key collision, and\n * the merged set is bounded by SQS's 10-attribute limit (contract attributes are seeded first,\n * so a rider only lands while headroom remains). On consume the inbound `MessageAttributes` are\n * surfaced as a `Record<string,string>` so the core's `otel` extract sees the `traceparent` and\n * links the consumer span as a child. A header-less publish is byte-identical. This mirrors the Go\n * `/sqs` and PHP `SqsTransport` wiring. GR-1: the wire envelope body is never touched.\n /\n\nimport { BabelQueueError, EnvelopeCodec, UnknownUrnError } from \"@babelqueue/core\";\nimport type { Envelope, HeaderCarrier, IncomingEnvelope } from \"@babelqueue/core\";\n\nimport { sanitizeHeaders } from \"./headers.js\";\n\n/* SQS allows at most 10 user message attributes per message. /\nconst MAX_ATTRIBUTES = 10;\n\n// --- Minimal SQS shapes (a structural subset of @aws-sdk/client-sqs) -----------\n\nexport interface SqsMessageAttributeValue {\n DataType: string;\n StringValue?: string;\n}\n\nexport interface SqsMessage {\n Body?: string;\n ReceiptHandle?: string;\n MessageAttributes?: Record<string, SqsMessageAttributeValue>;\n Attributes?: Record<string, string>;\n}\n\nexport interface SendMessageInput {\n QueueUrl: string;\n MessageBody: string;\n MessageAttributes?: Record<string, SqsMessageAttributeValue>;\n MessageGroupId?: string;\n MessageDeduplicationId?: string;\n}\n\nexport interface ReceiveMessageInput {\n QueueUrl: string;\n MaxNumberOfMessages?: number;\n WaitTimeSeconds?: number;\n VisibilityTimeout?: number;\n MessageAttributeNames?: string[];\n AttributeNames?: string[];\n}\n\n/\n The subset of the AWS SQS client this adapter calls. The aggregated `SQS` class\n * from `@aws-sdk/client-sqs` satisfies it structurally; a fake satisfies it in tests.\n /\nexport interface SqsApi {\n sendMessage(input: SendMessageInput): Promise<{ MessageId?: string } \| unknown>;\n receiveMessage(input: ReceiveMessageInput): Promise<{ Messages?: SqsMessage[] }>;\n deleteMessage(input: { QueueUrl: string; ReceiptHandle: string }): Promise<unknown>;\n}\n\n// --- Attribute projection (contract §3.2) --------------------------------------\n\nconst str = (value: unknown): SqsMessageAttributeValue => ({\n DataType: \"String\",\n StringValue: String(value),\n});\nconst num = (value: unknown): SqsMessageAttributeValue => ({\n DataType: \"Number\",\n StringValue: String(value),\n});\n\n/\n Project the envelope's contract fields onto native SQS `MessageAttributes` — a\n * redundant, routable view of the body (the body stays authoritative).\n /\nexport function toMessageAttributes(envelope: Envelope): Record<string, SqsMessageAttributeValue> {\n const attrs: Record<string, SqsMessageAttributeValue> = {};\n if (envelope.job) attrs[\"bq-job\"] = str(envelope.job);\n if (envelope.trace_id) attrs[\"bq-trace-id\"] = str(envelope.trace_id);\n if (envelope.meta.id) attrs[\"bq-message-id\"] = str(envelope.meta.id);\n if (envelope.meta.schema_version != null) {\n attrs[\"bq-schema-version\"] = num(envelope.meta.schema_version);\n }\n if (envelope.meta.lang) attrs[\"bq-source-lang\"] = str(envelope.meta.lang);\n if (envelope.meta.created_at != null) {\n attrs[\"bq-created-at\"] = num(envelope.meta.created_at);\n }\n return attrs;\n}\n\n/\n Overlay the out-of-band `headers` onto the contract attribute projection as String\n * `MessageAttributes`, without overwriting an existing `bq-` attribute (the contract wins a key\n collision) and skipping blanks. Keys are merged in sorted order and the merge stops at the\n * 10-attribute SQS ceiling, so unbounded riders can never push the message past the limit (SQS\n * rejects the whole send otherwise) — the contract attributes are always preserved first. Mirrors\n * Go's `mergeAttributes` / PHP's `SqsTransport::attributes`.\n /\nexport function mergeAttributes(\n base: Record<string, SqsMessageAttributeValue>,\n headers: HeaderCarrier \| null \| undefined,\n): Record<string, SqsMessageAttributeValue> {\n const clean = sanitizeHeaders(headers);\n for (const key of Object.keys(clean).sort()) {\n if (key in base) continue; // never clobber a contract bq- attribute\n if (Object.keys(base).length >= MAX_ATTRIBUTES) break; // respect the SQS 10-attribute cap\n base[key] = str(clean[key]);\n }\n return base;\n}\n\n/*\n Map inbound SQS `MessageAttributes` onto a flat {@link HeaderCarrier} (the consume-side\n * counterpart of {@link mergeAttributes}), reading each attribute's `StringValue`. Returns an empty\n * object when there are none. Both the contract `bq-` attributes and any out-of-band rider (e.g.\n `traceparent`) surface — the core's `otel` extract reads only the keys it knows.\n /\nexport function headersOf(message: SqsMessage): HeaderCarrier {\n const attrs = message.MessageAttributes;\n const out: HeaderCarrier = {};\n if (!attrs) return out;\n for (const key of Object.keys(attrs)) {\n const value = attrs[key]?.StringValue;\n if (value != null && value !== \"\") out[key] = value;\n }\n return out;\n}\n\nfunction queueNameFromUrl(queueUrl: string): string {\n const segments = queueUrl.split(\"/\").filter(Boolean);\n return segments[segments.length - 1] ?? \"default\";\n}\n\n// --- Publisher -----------------------------------------------------------------\n\n/* Options for {@link SqsPublisher}. /\nexport interface SqsPublisherOptions {\n /* Treat the queue as FIFO: set `MessageGroupId` and (unless content dedup) `MessageDeduplicationId`. /\n fifo?: boolean;\n /* FIFO ordering group (default: the queue name from the URL). /\n messageGroupId?: string;\n /* Use the queue's content-based dedup instead of `meta.id` as the dedup id. /\n contentDedup?: boolean;\n}\n\n/* Options for {@link SqsPublisher.publish}. /\nexport interface PublishOptions {\n /* Reuse an existing trace id (trace continuation). /\n traceId?: string;\n /\n Out-of-band transport headers carried as String `MessageAttributes` beside the contract `bq-`\n attributes (ADR-0028) — e.g. a W3C `traceparent` written by `@babelqueue/core/otel`'s `publish`.\n * The contract attributes win a key collision and the merged set is capped at SQS's 10-attribute\n * limit; an empty/omitted carrier leaves the publish unchanged.\n /\n headers?: HeaderCarrier;\n}\n\n/* Sends canonical-envelope messages to one SQS queue with the §3 attribute projection. /\nexport class SqsPublisher {\n constructor(\n private readonly client: SqsApi,\n private readonly queueUrl: string,\n private readonly options: SqsPublisherOptions = {},\n ) {}\n\n /\n Build the canonical envelope for `(urn, data)`, send it as the message body with\n * the projected `MessageAttributes`, and return the message id (`meta.id`).\n /\n async publish(\n urn: string,\n data: Record<string, unknown>,\n options: PublishOptions = {},\n ): Promise<string> {\n const envelope = EnvelopeCodec.make(urn, data, {\n queue: queueNameFromUrl(this.queueUrl),\n traceId: options.traceId,\n });\n const input: SendMessageInput = {\n QueueUrl: this.queueUrl,\n MessageBody: EnvelopeCodec.encode(envelope),\n MessageAttributes: mergeAttributes(toMessageAttributes(envelope), options.headers),\n };\n if (this.options.fifo) {\n input.MessageGroupId = this.options.messageGroupId ?? queueNameFromUrl(this.queueUrl);\n if (!this.options.contentDedup) {\n input.MessageDeduplicationId = envelope.meta.id;\n }\n }\n await this.client.sendMessage(input);\n return envelope.meta.id;\n }\n}\n\n// --- Consumer ------------------------------------------------------------------\n\n/\n A URN handler. Receives the validated envelope, the raw SQS message, and the out-of-band\n * {@link HeaderCarrier} read from the message's `MessageAttributes` (empty when there are none).\n * Pass `headers` to `@babelqueue/core/otel`'s `wrapHandler` to link the consumer span as a child of\n * the producer span (ADR-0028).\n /\nexport type BabelHandler = (envelope: Envelope, message: SqsMessage, headers: HeaderCarrier) => unknown \| Promise<unknown>;\n\n/* A map of URN → handler. /\nexport type BabelHandlers = Record<string, BabelHandler>;\n\n/* Options for {@link SqsConsumer}. /\nexport interface SqsConsumerOptions {\n /* Called instead of erroring when a message's URN has no handler (then the message is deleted). /\n onUnknownUrn?: (envelope: IncomingEnvelope, message: SqsMessage) => unknown \| Promise<unknown>;\n /* Called for a non-conformant envelope, an unmapped URN (no `onUnknownUrn`), or a throwing handler. The loop never stops. /\n onError?: (error: unknown, envelope: IncomingEnvelope, message: SqsMessage) => void;\n /* Long-poll wait seconds (default 20). /\n waitTimeSeconds?: number;\n /* Reservation window applied on receive (seconds). /\n visibilityTimeout?: number;\n /* Max messages per receive (default 10). /\n maxMessages?: number;\n}\n\n/\n Polls an SQS queue, decodes + validates each message, routes it to the handler\n * registered for its URN, and deletes it on success. A throwing handler leaves the\n * message undeleted — SQS redelivers it after the visibility timeout (at-least-once);\n * `attempts` is reconciled to `ApproximateReceiveCount − 1` for the handler.\n /\nexport class SqsConsumer {\n constructor(\n private readonly client: SqsApi,\n private readonly queueUrl: string,\n private readonly handlers: BabelHandlers,\n private readonly options: SqsConsumerOptions = {},\n ) {}\n\n /* Receive one batch, route each message, delete the ones handled. Returns the batch size. /\n async poll(): Promise<number> {\n const input: ReceiveMessageInput = {\n QueueUrl: this.queueUrl,\n MaxNumberOfMessages: this.options.maxMessages ?? 10,\n WaitTimeSeconds: this.options.waitTimeSeconds ?? 20,\n MessageAttributeNames: [\"All\"],\n AttributeNames: [\"ApproximateReceiveCount\"],\n };\n if (this.options.visibilityTimeout != null) {\n input.VisibilityTimeout = this.options.visibilityTimeout;\n }\n const result = await this.client.receiveMessage(input);\n const messages = result.Messages ?? [];\n for (const message of messages) {\n await this.handle(message);\n }\n return messages.length;\n }\n\n /* Poll until `signal` aborts (each poll long-polls, so this does not busy-loop). /\n async run(signal?: AbortSignal): Promise<void> {\n while (signal?.aborted !== true) {\n await this.poll();\n }\n }\n\n private async handle(message: SqsMessage): Promise<void> {\n const envelope = EnvelopeCodec.decode(message.Body ?? \"\");\n\n const receiveCount = message.Attributes?.[\"ApproximateReceiveCount\"];\n if (receiveCount !== undefined) {\n const native = Number.parseInt(receiveCount, 10) - 1;\n const current = typeof envelope.attempts === \"number\" ? envelope.attempts : 0;\n if (Number.isFinite(native) && native > current) {\n envelope.attempts = native;\n }\n }\n\n if (!EnvelopeCodec.accepts(envelope)) {\n this.options.onError?.(\n new BabelQueueError(\"Rejected a non-conformant BabelQueue envelope from SQS.\"),\n envelope,\n message,\n );\n return;\n }\n\n const urn = EnvelopeCodec.urn(envelope);\n const handler = this.handlers[urn];\n if (!handler) {\n if (this.options.onUnknownUrn) {\n await this.options.onUnknownUrn(envelope, message);\n await this.delete(message);\n } else {\n this.options.onError?.(new UnknownUrnError(urn), envelope, message);\n }\n return;\n }\n\n try {\n await handler(envelope, message, headersOf(message));\n await this.delete(message);\n } catch (error) {\n // Leave the message undeleted — SQS redelivers after the visibility timeout.\n this.options.onError?.(error, envelope, message);\n }\n }\n\n private async delete(message: SqsMessage): Promise<void> {\n if (!message.ReceiptHandle) return;\n await this.client.deleteMessage({\n QueueUrl: this.queueUrl,\n ReceiptHandle: message.ReceiptHandle,\n });\n }\n}\n","/\n Pure, dependency-free helpers for the out-of-band transport-header seam (ADR-0028) — the Node\n * adapter mirror of Go's `sanitizeHeaders` and PHP's `Support\\Headers`. They fold an injected\n * {@link HeaderCarrier} (e.g. a W3C `traceparent`) onto a transport's metadata channel *without\n clobbering** the contract headers it already carries.\n \n Headers ride beside the frozen wire envelope (GR-1), never inside it.\n /\n\nimport type { HeaderCarrier } from \"@babelqueue/core\";\n\n/\n Copy `headers`, dropping blank keys and blank values. Returns an empty object when nothing\n * survives, so a caller can treat the result as \"no headers\". A nullish input yields an empty\n * object.\n */\nexport function sanitizeHeaders(headers: HeaderCarrier \| null \| undefined): HeaderCarrier {\n const out: HeaderCarrier = {};\n if (!headers) return out;\n for (const key of Object.keys(headers)) {\n const value = headers[key];\n if (key === \"\" \|\| value == null \|\| value === \"\") continue;\n out[key] = value;\n }\n return out;\n}\n"],"mappings":"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","names":[]}
1	+ {"version":3,"sources":["../src/index.ts","../src/headers.ts"],"sourcesContent":["/*\n Amazon SQS adapter for BabelQueue.\n \n A canonical-envelope publisher and a URN-routed consumer over Amazon SQS,\n * so an SQS-based Node service speaks the same contract (envelope shape, URN\n * identity, trace propagation) as the PHP/Laravel, Python, Go, Java and .NET SDKs.\n \n import { SQS } from \"@aws-sdk/client-sqs\";\n * import { SqsPublisher, SqsConsumer } from \"@babelqueue/sqs\";\n \n const sqs = new SQS({ region: \"eu-central-1\" });\n * const url = \"https://sqs.eu-central-1.amazonaws.com/123456789012/orders\";\n \n await new SqsPublisher(sqs, url).publish(\"urn:babel:orders:created\", { order_id: 1042 });\n \n const consumer = new SqsConsumer(sqs, url, {\n * \"urn:babel:orders:created\": async (env) => { ... },\n * });\n * await consumer.run();\n \n This implements §3 of the broker-bindings contract: the canonical envelope is the\n * message body, projected onto native SQS `MessageAttributes`. The envelope is\n * unchanged (`schema_version` stays 1); SQS is purely additive. Retry is SQS-native\n * (a failed handler's message is released via `ChangeMessageVisibility` after\n * `releaseDelay`, default 0 s — pair the queue with a `RedrivePolicy`); the\n * authoritative attempt count is `ApproximateReceiveCount`, surfaced to handlers as\n * `attempts = count − 1`.\n \n Version gate (§3.7). Before the body is decoded the consumer reads the `bq-schema-version`\n * message attribute. A missing or blank value (empty or only ASCII whitespace) changes nothing; any\n * value other than the core's supported `SCHEMA_VERSION` (`\"2\"`, `\"x\"`, `\"01\"`, ...) rejects the\n * message undecoded through the same path as a non-conformant envelope — `onError` (with an error\n * naming the version, and an empty envelope since nothing was decoded) and the message is left\n * undeleted, so it is redelivered and the queue's `RedrivePolicy` moves it to the DLQ.\n \n Out-of-band headers (ADR-0028). A `headers` carrier (e.g. a W3C `traceparent` for cross-hop\n * span linkage) rides as additional String `MessageAttributes` beside the contract `bq-`\n attributes where `bq-trace-id` already lives — the contract attributes win a key collision, and\n * the merged set is bounded by SQS's 10-attribute limit (contract attributes are seeded first,\n * so a rider only lands while headroom remains). On consume the inbound `MessageAttributes` are\n * surfaced as a `Record<string,string>` so the core's `otel` extract sees the `traceparent` and\n * links the consumer span as a child. A header-less publish is byte-identical. This mirrors the Go\n * `/sqs` and PHP `SqsTransport` wiring. GR-1: the wire envelope body is never touched.\n /\n\nimport {\n BabelQueueError,\n EnvelopeCodec,\n SCHEMA_VERSION,\n UnknownUrnError,\n UnknownUrnStrategy,\n annotate,\n} from \"@babelqueue/core\";\nimport type { Envelope, HeaderCarrier, IncomingEnvelope } from \"@babelqueue/core\";\n\nimport { sanitizeHeaders } from \"./headers.js\";\n\n/* SQS allows at most 10 user message attributes per message. /\nconst MAX_ATTRIBUTES = 10;\n\n/* The SQS ceiling for a `VisibilityTimeout` (12 hours, in seconds). /\nexport const MAX_VISIBILITY_TIMEOUT = 43_200;\n\n// --- Minimal SQS shapes (a structural subset of @aws-sdk/client-sqs) -----------\n\nexport interface SqsMessageAttributeValue {\n DataType: string;\n StringValue?: string;\n}\n\nexport interface SqsMessage {\n Body?: string;\n ReceiptHandle?: string;\n MessageAttributes?: Record<string, SqsMessageAttributeValue>;\n Attributes?: Record<string, string>;\n}\n\nexport interface SendMessageInput {\n QueueUrl: string;\n MessageBody: string;\n MessageAttributes?: Record<string, SqsMessageAttributeValue>;\n MessageGroupId?: string;\n MessageDeduplicationId?: string;\n}\n\nexport interface ReceiveMessageInput {\n QueueUrl: string;\n MaxNumberOfMessages?: number;\n WaitTimeSeconds?: number;\n VisibilityTimeout?: number;\n MessageAttributeNames?: string[];\n AttributeNames?: string[];\n}\n\n/\n The subset of the AWS SQS client this adapter calls. The aggregated `SQS` class\n * from `@aws-sdk/client-sqs` satisfies it structurally; a fake satisfies it in tests.\n /\nexport interface SqsApi {\n sendMessage(input: SendMessageInput): Promise<{ MessageId?: string } \| unknown>;\n receiveMessage(input: ReceiveMessageInput): Promise<{ Messages?: SqsMessage[] }>;\n deleteMessage(input: { QueueUrl: string; ReceiptHandle: string }): Promise<unknown>;\n /\n The §3.5 release primitive. Optional so existing structural clients keep compiling; it is\n * required (checked at construction) when a consumer sets `releaseDelay` or the `release`\n * unknown-URN strategy explicitly. Without it the default handler-failure release degrades to\n * leaving the message for visibility-timeout redelivery. The aggregated `SQS` class from\n * `@aws-sdk/client-sqs` provides it.\n /\n changeMessageVisibility?(input: ChangeMessageVisibilityInput): Promise<unknown>;\n}\n\nexport interface ChangeMessageVisibilityInput {\n QueueUrl: string;\n ReceiptHandle: string;\n VisibilityTimeout: number;\n}\n\n// --- Attribute projection (contract §3.2) --------------------------------------\n\nconst str = (value: unknown): SqsMessageAttributeValue => ({\n DataType: \"String\",\n StringValue: String(value),\n});\nconst num = (value: unknown): SqsMessageAttributeValue => ({\n DataType: \"Number\",\n StringValue: String(value),\n});\n\n/\n Project the envelope's contract fields onto native SQS `MessageAttributes` — a\n * redundant, routable view of the body (the body stays authoritative).\n /\nexport function toMessageAttributes(envelope: Envelope): Record<string, SqsMessageAttributeValue> {\n const attrs: Record<string, SqsMessageAttributeValue> = {};\n if (envelope.job) attrs[\"bq-job\"] = str(envelope.job);\n if (envelope.trace_id) attrs[\"bq-trace-id\"] = str(envelope.trace_id);\n if (envelope.meta.id) attrs[\"bq-message-id\"] = str(envelope.meta.id);\n if (envelope.meta.schema_version != null) {\n attrs[\"bq-schema-version\"] = num(envelope.meta.schema_version);\n }\n if (envelope.meta.lang) attrs[\"bq-source-lang\"] = str(envelope.meta.lang);\n if (envelope.meta.created_at != null) {\n attrs[\"bq-created-at\"] = num(envelope.meta.created_at);\n }\n return attrs;\n}\n\n/\n Overlay the out-of-band `headers` onto the contract attribute projection as String\n * `MessageAttributes`, without overwriting an existing `bq-` attribute (the contract wins a key\n collision) and skipping blanks. Keys are merged in sorted order and the merge stops at the\n * 10-attribute SQS ceiling, so unbounded riders can never push the message past the limit (SQS\n * rejects the whole send otherwise) — the contract attributes are always preserved first. Mirrors\n * Go's `mergeAttributes` / PHP's `SqsTransport::attributes`.\n /\nexport function mergeAttributes(\n base: Record<string, SqsMessageAttributeValue>,\n headers: HeaderCarrier \| null \| undefined,\n): Record<string, SqsMessageAttributeValue> {\n const clean = sanitizeHeaders(headers);\n for (const key of Object.keys(clean).sort()) {\n if (key in base) continue; // never clobber a contract bq- attribute\n if (Object.keys(base).length >= MAX_ATTRIBUTES) break; // respect the SQS 10-attribute cap\n base[key] = str(clean[key]);\n }\n return base;\n}\n\n/*\n Map inbound SQS `MessageAttributes` onto a flat {@link HeaderCarrier} (the consume-side\n * counterpart of {@link mergeAttributes}), reading each attribute's `StringValue`. Returns an empty\n * object when there are none. Both the contract `bq-` attributes and any out-of-band rider (e.g.\n `traceparent`) surface — the core's `otel` extract reads only the keys it knows.\n /\nexport function headersOf(message: SqsMessage): HeaderCarrier {\n const attrs = message.MessageAttributes;\n const out: HeaderCarrier = {};\n if (!attrs) return out;\n for (const key of Object.keys(attrs)) {\n const value = attrs[key]?.StringValue;\n if (value != null && value !== \"\") out[key] = value;\n }\n return out;\n}\n\n/* Blank = empty or only ASCII whitespace (space, \\t, \\n, \\v, \\f, \\r) — not `String.prototype.trim()`'s wider set. /\nconst BLANK_ASCII = /^[ \\t\\n\\v\\f\\r]$/;\n\n/*\n The `bq-schema-version` message attribute when it is present, non-blank and not the supported\n * version (compared against the core's `SCHEMA_VERSION`, exact string match: `\"01\"`, `\" 1\"`, `\"1.0\"`\n * are rejected). Blank means the empty string or only ASCII whitespace (the same set in every SDK,\n * GR-5); NBSP, U+0085, U+FEFF, U+3000 and the like are not blank. `undefined` when the message may\n * be decoded.\n /\nfunction unsupportedSchemaVersion(message: SqsMessage): string \| undefined {\n const raw: unknown = message.MessageAttributes?.[\"bq-schema-version\"]?.StringValue;\n if (typeof raw !== \"string\" \|\| BLANK_ASCII.test(raw)) return undefined;\n return raw === String(SCHEMA_VERSION) ? undefined : raw;\n}\n\nfunction queueNameFromUrl(queueUrl: string): string {\n const segments = queueUrl.split(\"/\").filter(Boolean);\n return segments[segments.length - 1] ?? \"default\";\n}\n\n// --- Publisher -----------------------------------------------------------------\n\n/* Options for {@link SqsPublisher}. /\nexport interface SqsPublisherOptions {\n /* Treat the queue as FIFO: set `MessageGroupId` and (unless content dedup) `MessageDeduplicationId`. /\n fifo?: boolean;\n /* FIFO ordering group (default: the queue name from the URL). /\n messageGroupId?: string;\n /* Use the queue's content-based dedup instead of `meta.id` as the dedup id. /\n contentDedup?: boolean;\n}\n\n/* Options for {@link SqsPublisher.publish}. /\nexport interface PublishOptions {\n /* Reuse an existing trace id (trace continuation). /\n traceId?: string;\n /\n Out-of-band transport headers carried as String `MessageAttributes` beside the contract `bq-`\n attributes (ADR-0028) — e.g. a W3C `traceparent` written by `@babelqueue/core/otel`'s `publish`.\n * The contract attributes win a key collision and the merged set is capped at SQS's 10-attribute\n * limit; an empty/omitted carrier leaves the publish unchanged.\n /\n headers?: HeaderCarrier;\n}\n\n/* Sends canonical-envelope messages to one SQS queue with the §3 attribute projection. /\nexport class SqsPublisher {\n constructor(\n private readonly client: SqsApi,\n private readonly queueUrl: string,\n private readonly options: SqsPublisherOptions = {},\n ) {}\n\n /\n Build the canonical envelope for `(urn, data)`, send it as the message body with\n * the projected `MessageAttributes`, and return the message id (`meta.id`).\n /\n async publish(\n urn: string,\n data: Record<string, unknown>,\n options: PublishOptions = {},\n ): Promise<string> {\n const envelope = EnvelopeCodec.make(urn, data, {\n queue: queueNameFromUrl(this.queueUrl),\n traceId: options.traceId,\n });\n const input: SendMessageInput = {\n QueueUrl: this.queueUrl,\n MessageBody: EnvelopeCodec.encode(envelope),\n MessageAttributes: mergeAttributes(toMessageAttributes(envelope), options.headers),\n };\n if (this.options.fifo) {\n input.MessageGroupId = this.options.messageGroupId ?? queueNameFromUrl(this.queueUrl);\n if (!this.options.contentDedup) {\n input.MessageDeduplicationId = envelope.meta.id;\n }\n }\n await this.client.sendMessage(input);\n return envelope.meta.id;\n }\n}\n\n// --- Consumer ------------------------------------------------------------------\n\n/\n A URN handler. Receives the validated envelope, the raw SQS message, and the out-of-band\n * {@link HeaderCarrier} read from the message's `MessageAttributes` (empty when there are none).\n * Pass `headers` to `@babelqueue/core/otel`'s `wrapHandler` to link the consumer span as a child of\n * the producer span (ADR-0028).\n /\nexport type BabelHandler = (envelope: Envelope, message: SqsMessage, headers: HeaderCarrier) => unknown \| Promise<unknown>;\n\n/* A map of URN → handler. /\nexport type BabelHandlers = Record<string, BabelHandler>;\n\n/* Options for {@link SqsConsumer}. /\nexport interface SqsConsumerOptions {\n /\n Called when a message's URN has no handler. Without `unknownUrn` the message is then deleted\n * (the original behaviour); with `unknownUrn` set it is a notification hook and the strategy\n * decides the message's fate.\n /\n onUnknownUrn?: (envelope: IncomingEnvelope, message: SqsMessage) => unknown \| Promise<unknown>;\n /\n Unknown-URN strategy per contract §3.5 — `fail` \| `delete` \| `release` \| `dead_letter`\n * ({@link UnknownUrnStrategy}). Omitted keeps the original behaviour (`onUnknownUrn` → delete,\n * otherwise report and leave for visibility-timeout redelivery, i.e. `fail`). `release` uses\n * `ChangeMessageVisibility` with {@link unknownUrnReleaseDelay}; `dead_letter` sends the annotated\n * envelope to {@link deadLetterQueueUrl} then deletes, degrading to `delete` when no DLQ is set.\n /\n unknownUrn?: string;\n /* Backoff (seconds) for the `release` unknown-URN strategy (default 0 = redeliver now). /\n unknownUrnReleaseDelay?: number;\n /\n Backoff before a failed message is redelivered. A failed handler always releases the message\n * via `ChangeMessageVisibility(ReceiptHandle, VisibilityTimeout)` (contract §3.5); this sets the\n * `VisibilityTimeout` — a number of seconds, or a function of the (reconciled) `attempts`\n * returning seconds (e.g. an exponential backoff). Clamped to `0…43200`. Default `0`: the message\n * is visible again immediately. A permanently failing handler therefore retries without pause\n * until the queue's `RedrivePolicy` (`maxReceiveCount`) moves it to the DLQ — configure one.\n /\n releaseDelay?: number \| ((attempts: number) => number);\n /\n The cross-language `<queue>.dlq` URL for the `dead_letter` strategy (opt-in; default none). A\n * `.fifo` DLQ is sent with `MessageGroupId` (the source queue name) and `MessageDeduplicationId`\n * (`meta.id`).\n /\n deadLetterQueueUrl?: string \| null;\n /\n Called for a non-conformant envelope, an unmapped URN (no `onUnknownUrn`), a throwing handler,\n * a throwing `onUnknownUrn` under an `unknownUrn` strategy, a failed release / dead-letter send, or\n * a failed delete after successful processing (an {@link SqsDeleteError} wrapping the broker\n * error; never released). The message is then left for visibility-timeout redelivery. The loop\n * never stops on these.\n /\n onError?: (error: unknown, envelope: IncomingEnvelope, message: SqsMessage) => void;\n /* Long-poll wait seconds (default 20). /\n waitTimeSeconds?: number;\n /* Reservation window applied on receive (seconds). /\n visibilityTimeout?: number;\n /* Max messages per receive (default 10). /\n maxMessages?: number;\n}\n\n/\n Reported via `onError` when `DeleteMessage` fails for a message whose processing already succeeded\n * (a handler returned normally, or the unknown-URN strategy chose `delete` / `dead_letter`). The\n * broker error is `cause`. Distinct from a handler failure: the message is NOT released, so it is\n * redelivered only after its visibility timeout expires (at-least-once; dedupe on `meta.id` with the\n * idempotency helper if the side effect must not repeat).\n /\nexport class SqsDeleteError extends BabelQueueError {\n constructor(cause: unknown) {\n super(\"Failed to delete a processed SQS message; it will be redelivered after its visibility timeout.\");\n this.name = \"SqsDeleteError\";\n this.cause = cause;\n }\n}\n\n/\n Polls an SQS queue, decodes + validates each message, routes it to the handler\n * registered for its URN, and deletes it on success. A throwing handler's message is released via\n * `ChangeMessageVisibility` after `releaseDelay` (default 0 s, contract §3.5); if the release itself\n * fails the message is left for visibility-timeout redelivery (at-least-once);\n * `attempts` is reconciled to `ApproximateReceiveCount − 1` for the handler. An unmapped URN\n * follows the `unknownUrn` strategy (`fail` \| `delete` \| `release` \| `dead_letter`).\n /\nexport class SqsConsumer {\n constructor(\n private readonly client: SqsApi,\n private readonly queueUrl: string,\n private readonly handlers: BabelHandlers,\n private readonly options: SqsConsumerOptions = {},\n ) {\n const strategy = options.unknownUrn;\n if (strategy !== undefined && !(Object.values(UnknownUrnStrategy) as string[]).includes(strategy)) {\n throw new BabelQueueError(`Unknown unknownUrn strategy \"${strategy}\".`);\n }\n const needsRelease = options.releaseDelay != null \|\| strategy === UnknownUrnStrategy.RELEASE;\n if (needsRelease && typeof client.changeMessageVisibility !== \"function\") {\n throw new BabelQueueError(\n \"SqsConsumer release requires a client with changeMessageVisibility (contract §3.5).\",\n );\n }\n }\n\n /* Receive one batch, route each message, delete the ones handled. Returns the batch size. /\n async poll(): Promise<number> {\n const input: ReceiveMessageInput = {\n QueueUrl: this.queueUrl,\n MaxNumberOfMessages: this.options.maxMessages ?? 10,\n WaitTimeSeconds: this.options.waitTimeSeconds ?? 20,\n MessageAttributeNames: [\"All\"],\n AttributeNames: [\"ApproximateReceiveCount\"],\n };\n if (this.options.visibilityTimeout != null) {\n input.VisibilityTimeout = this.options.visibilityTimeout;\n }\n const result = await this.client.receiveMessage(input);\n const messages = result.Messages ?? [];\n for (const message of messages) {\n await this.handle(message);\n }\n return messages.length;\n }\n\n /* Poll until `signal` aborts (each poll long-polls, so this does not busy-loop). /\n async run(signal?: AbortSignal): Promise<void> {\n while (signal?.aborted !== true) {\n await this.poll();\n }\n }\n\n private async handle(message: SqsMessage): Promise<void> {\n // §3.7: gate on the bq-schema-version attribute before the body is decoded. The message is\n // not deleted, so SQS redelivers it and the queue's RedrivePolicy moves it to the DLQ.\n const rejectedVersion = unsupportedSchemaVersion(message);\n if (rejectedVersion !== undefined) {\n this.options.onError?.(\n new BabelQueueError(\n `Rejected a message from SQS with unsupported bq-schema-version \"${rejectedVersion}\" (supported: ${SCHEMA_VERSION}).`,\n ),\n {},\n message,\n );\n return;\n }\n\n const envelope = EnvelopeCodec.decode(message.Body ?? \"\");\n\n const receiveCount = message.Attributes?.[\"ApproximateReceiveCount\"];\n if (receiveCount !== undefined) {\n const native = Number.parseInt(receiveCount, 10) - 1;\n const current = typeof envelope.attempts === \"number\" ? envelope.attempts : 0;\n if (Number.isFinite(native) && native > current) {\n envelope.attempts = native;\n }\n }\n\n if (!EnvelopeCodec.accepts(envelope)) {\n this.options.onError?.(\n new BabelQueueError(\"Rejected a non-conformant BabelQueue envelope from SQS.\"),\n envelope,\n message,\n );\n return;\n }\n\n const urn = EnvelopeCodec.urn(envelope);\n const handler = this.handlers[urn];\n if (!handler) {\n await this.unknown(urn, envelope as Envelope, message);\n return;\n }\n\n try {\n await handler(envelope, message, headersOf(message));\n } catch (error) {\n this.options.onError?.(error, envelope, message);\n await this.guard(envelope, message, async () => {\n const delay = this.options.releaseDelay ?? 0;\n const attempts = typeof envelope.attempts === \"number\" ? envelope.attempts : 0;\n await this.release(message, typeof delay === \"function\" ? delay(attempts) : delay);\n });\n return;\n }\n // Outside the handler's try: a failed delete is not a handler failure. It is reported as an\n // SqsDeleteError and the message is NOT released — releasing at the (default 0 s) backoff would\n // redeliver an already-processed message immediately; it returns on visibility expiry instead.\n await this.guard(envelope, message, () => this.deleteHandled(message));\n }\n\n /\n Run a release / dead-letter step; a failure (e.g. `MessageNotInflight`, a missing IAM grant, a\n * throwing `releaseDelay`) is reported to `onError` and the message is left undeleted, so\n * visibility expiry still redelivers it. Never lets the error stop the consume loop.\n /\n private async guard(envelope: IncomingEnvelope, message: SqsMessage, step: () => Promise<void>): Promise<void> {\n try {\n await step();\n } catch (error) {\n this.options.onError?.(error, envelope, message);\n }\n }\n\n /* Apply the unknown-URN strategy (contract §3.5). /\n private async unknown(urn: string, envelope: Envelope, message: SqsMessage): Promise<void> {\n const strategy = this.options.unknownUrn;\n if (strategy === undefined) {\n if (this.options.onUnknownUrn) {\n await this.options.onUnknownUrn(envelope, message);\n await this.delete(message);\n } else {\n this.options.onError?.(new UnknownUrnError(urn), envelope, message);\n }\n return;\n }\n\n await this.guard(envelope, message, async () => {\n await this.options.onUnknownUrn?.(envelope, message);\n });\n switch (strategy) {\n case UnknownUrnStrategy.DELETE:\n await this.guard(envelope, message, () => this.deleteHandled(message));\n return;\n case UnknownUrnStrategy.RELEASE:\n await this.guard(envelope, message, () => this.release(message, this.options.unknownUrnReleaseDelay ?? 0));\n return;\n case UnknownUrnStrategy.DEAD_LETTER:\n await this.guard(envelope, message, async () => {\n await this.deadLetter(envelope, \"unknown_urn\");\n await this.deleteHandled(message);\n });\n return;\n default:\n // FAIL: surface and do NOT delete — visibility expiry redelivers, native redrive quarantines.\n this.options.onError?.(new UnknownUrnError(urn), envelope, message);\n }\n }\n\n /* Make the message visible again after `seconds` via `ChangeMessageVisibility`; never deletes. /\n private async release(message: SqsMessage, seconds: number): Promise<void> {\n if (!message.ReceiptHandle \|\| !this.client.changeMessageVisibility) return;\n const timeout = Number.isFinite(seconds)\n ? Math.min(MAX_VISIBILITY_TIMEOUT, Math.max(0, Math.floor(seconds)))\n : 0;\n await this.client.changeMessageVisibility({\n QueueUrl: this.queueUrl,\n ReceiptHandle: message.ReceiptHandle,\n VisibilityTimeout: timeout,\n });\n }\n\n /* Send the annotated envelope to the opt-in DLQ; a no-op (→ plain delete) when none is set. /\n private async deadLetter(envelope: Envelope, reason: string): Promise<void> {\n const dlq = this.options.deadLetterQueueUrl;\n if (!dlq) return;\n const source = envelope.meta?.queue ?? queueNameFromUrl(this.queueUrl);\n const annotated = annotate(envelope, reason, source, {\n attempts: envelope.attempts ?? 0,\n });\n const input: SendMessageInput = {\n QueueUrl: dlq,\n MessageBody: EnvelopeCodec.encode(annotated),\n MessageAttributes: toMessageAttributes(annotated),\n };\n if (dlq.endsWith(\".fifo\")) {\n // A FIFO DLQ (`<queue>.dlq.fifo`) rejects a send without a group; dedup on meta.id (§3.2).\n input.MessageGroupId = source;\n if (annotated.meta?.id) input.MessageDeduplicationId = annotated.meta.id;\n }\n await this.client.sendMessage(input);\n }\n\n /* Delete a message whose processing already succeeded; a broker failure becomes an SqsDeleteError. /\n private async deleteHandled(message: SqsMessage): Promise<void> {\n try {\n await this.delete(message);\n } catch (error) {\n throw new SqsDeleteError(error);\n }\n }\n\n private async delete(message: SqsMessage): Promise<void> {\n if (!message.ReceiptHandle) return;\n await this.client.deleteMessage({\n QueueUrl: this.queueUrl,\n ReceiptHandle: message.ReceiptHandle,\n });\n }\n}\n","/\n Pure, dependency-free helpers for the out-of-band transport-header seam (ADR-0028) — the Node\n * adapter mirror of Go's `sanitizeHeaders` and PHP's `Support\\Headers`. They fold an injected\n * {@link HeaderCarrier} (e.g. a W3C `traceparent`) onto a transport's metadata channel *without\n clobbering** the contract headers it already carries.\n \n Headers ride beside the frozen wire envelope (GR-1), never inside it.\n /\n\nimport type { HeaderCarrier } from \"@babelqueue/core\";\n\n/\n Copy `headers`, dropping blank keys and blank values. Returns an empty object when nothing\n * survives, so a caller can treat the result as \"no headers\". A nullish input yields an empty\n * object.\n */\nexport function sanitizeHeaders(headers: HeaderCarrier \| null \| undefined): HeaderCarrier {\n const out: HeaderCarrier = {};\n if (!headers) return out;\n for (const key of Object.keys(headers)) {\n const value = headers[key];\n if (key === \"\" \|\| value == null \|\| value === \"\") continue;\n out[key] = value;\n }\n return out;\n}\n"],"mappings":"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","names":[]}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@babelqueue/sqs",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Amazon SQS adapter for BabelQueue — canonical-envelope publisher and a URN-routed consumer.",
   "keywords": [
     "babelqueue",
@@ -20,7 +20,7 @@
     "directory": "packages/sqs"
   },
   "license": "MIT",
-  "author": "Muhammet Şafak <info@muhammetsafak.com.tr>",
+  "author": "Muhammet Şafak <info@muhammetsafak.com>",
   "type": "module",
   "exports": {
     ".": {
@@ -50,7 +50,7 @@
     "test": "node --import tsx --test test/*.test.ts"
   },
   "dependencies": {
-    "@babelqueue/core": "^1.4.0"
+    "@babelqueue/core": "^1.8.0"
   },
   "peerDependencies": {
     "@aws-sdk/client-sqs": "^3.0.0"