@rdlabo/workers-hono-kit 0.9.7 → 0.10.0

package/README.md

@@ -104,10 +104,20 @@ npm install ai ai-gateway-provider    # createAiGatewayProvider
 | `verifyAppleReceipt(receipt, opts)` / `classifyAppleRenewal(verify, now)` / `AppleRenewalClassification` / `AppleRenewalState` / `AppleVerifyReceiptResponse` / `ApplePendingRenewalInfo` / `AppleLatestReceiptInfo` | Verify an App Store receipt (production → sandbox fallback; inject `password` / `fetchImpl`) and classify it into `billing_retry` / `lapsed` / `active` / `unknown` plus the raw fields used (`statusCode` / `billingRetryStatus` / `autoRenewStatus`, latest `original_transaction_id` / `expires_date_ms`). |
 | `googleAccessToken(creds, fetch?)` / `getGoogleSubscription(opts)` / `classifyGoogleSubscription(purchase, now)` / `GoogleSubscriptionClassification` / `GoogleSubscriptionState` / `GoogleSubscriptionPurchase` / `GoogleOAuthCredentials` | Exchange a refresh token for an Android Publisher access token (throws on `invalid_grant`), fetch a subscription purchase, and classify it into `canceled` / `gone` / `active` / `unknown` plus raw `statusCode` / `cancelReason`. |
 | `sendInChunks(queue, messages, options?)` / `QueueLike` / `QueueSendMessage` | Send queue messages in bounded chunks to stay under the Workers subrequest cap per invocation. `options.chunkSize` sets the per-batch size (defaults to and is capped at 100). |
-| `processBatch(batch, handler, options?)` / `MessageBatchLike` / `QueueMessageLike` / `ProcessBatchOptions` / `ProcessBatchResult` | Process a queue batch with bounded concurrency (consumer-side counterpart to `sendInChunks`). |
-| `createQueueErrorHandler(options)` / `CreateQueueErrorHandlerOptions` | Factory for `processBatch`'s `onError`: logs every failure; optional Sentry capture with queue/message context; optional `maxRetries` gate (report only on final attempt). |
+| `processBatch(batch, handler, options?)` / `isNonRetryableQueueError(error)` / `NonRetryableQueueErrorLike` / `MessageBatchLike` / `QueueMessageLike` / `ProcessBatchOptions` / `ProcessBatchResult` | Process a queue batch with bounded concurrency. Errors explicitly tagged with `queueDisposition: 'discard'` are reported and acked as permanent failures; all other errors are retried. |
+| `createQueueErrorHandler(options)` / `CreateQueueErrorHandlerOptions` | Factory for `processBatch`'s `onError`: logs every failure; optional Sentry capture with queue/message context; optional `maxRetries` gate (report only on final attempt, except permanent failures which are reported immediately). |
 | `ExecutionContextLike` | Minimal `waitUntil`-only Workers execution context shape used by lifecycle-compatible APIs and deferred work helpers. |
 
+Permanent Queue failures must opt in with the Queue-specific marker; unrelated `retryable` fields are ignored:
+
+```ts
+import type { NonRetryableQueueErrorLike } from '@rdlabo/workers-hono-kit';
+
+class CustomerLinkMissingError extends Error implements NonRetryableQueueErrorLike {
+  readonly queueDisposition = 'discard' as const;
+}
+```
+
 ### Data layer — `@rdlabo/workers-hono-kit/db`
 
 Requires the `drizzle-orm` and `mysql2` peers. Reads run against a replica via raw SQL; writes/transactions run against the primary through the Drizzle ORM with deadlock retry. The kit deliberately does not depend on the ORM's type identity — you pass the Drizzle instance in.

package/dist/index.d.ts

@@ -78,8 +78,8 @@ export type { GoogleSubscriptionClassification, GoogleSubscriptionState, GoogleS
 export { retryWhenDeadlock } from './db/retry.js';
 export { sendInChunks } from './queue/send.js';
 export type { QueueLike, QueueSendMessage } from './queue/send.js';
-export { processBatch } from './queue/consumer.js';
-export type { QueueMessageLike, MessageBatchLike, ProcessBatchOptions, ProcessBatchResult } from './queue/consumer.js';
+export { isNonRetryableQueueError, processBatch } from './queue/consumer.js';
+export type { QueueMessageLike, MessageBatchLike, NonRetryableQueueErrorLike, ProcessBatchOptions, ProcessBatchResult, } from './queue/consumer.js';
 export { createQueueErrorHandler } from './queue/error-handler.js';
 export type { CreateQueueErrorHandlerOptions } from './queue/error-handler.js';
 export { createAiGatewayProvider } from './ai/gateway.js';

package/dist/index.js

@@ -59,7 +59,7 @@ export { classifyGoogleSubscription, getGoogleSubscription, googleAccessToken }
 export { retryWhenDeadlock } from './db/retry.js';
 // queue
 export { sendInChunks } from './queue/send.js';
-export { processBatch } from './queue/consumer.js';
+export { isNonRetryableQueueError, processBatch } from './queue/consumer.js';
 export { createQueueErrorHandler } from './queue/error-handler.js';
 // ai
 export { createAiGatewayProvider } from './ai/gateway.js';

package/dist/queue/consumer.d.ts

@@ -1,12 +1,14 @@
 /**
  * Consumer-side helper for processing a Cloudflare Queues `MessageBatch` with per-message success and
- * failure handling.
+ * failure handling, including explicit acknowledgement of permanent failures.
  *
  * A queue consumer invocation receives at most `max_batch_size` messages (configured in
  * `wrangler.toml`), which is precisely the mechanism that bounds its subrequest budget: with a small
  * `max_batch_size`, each invocation performs a fixed, small number of external calls no matter how
  * many messages are backed up in the queue. {@link processBatch} applies the standard
  * ack-on-success / retry-on-failure discipline so one poison message does not fail its whole batch.
+ * Errors explicitly tagged with `queueDisposition: 'discard'` are reported and acknowledged because
+ * delivering the same payload again cannot make them converge.
  *
  * Messages are processed sequentially. This keeps the number of *simultaneously open* subrequests at
  * one, staying well clear of the Workers concurrent-connection ceiling, and makes the per-invocation
@@ -66,8 +68,10 @@ export interface MessageBatchLike<Body = unknown> {
  */
 export interface ProcessBatchOptions<Body = unknown> {
     /**
-     * Invoked when `handler` throws for a message, immediately before the message is marked for retry.
-     * Use it to log or report; it must not throw. Defaults to `console.error`.
+     * Invoked when `handler` throws for a message, before the message is retried or acknowledged as a
+     * permanent failure. Use it to log or report; it must not throw. Defaults to `console.error`.
+     * If a custom hook does throw, `processBatch` emits a console fallback and still applies the
+     * original error's disposition so a telemetry outage cannot turn a poison message into retries.
      */
     onError?: (error: unknown, message: QueueMessageLike<Body>) => void;
     /**
@@ -82,14 +86,30 @@ export interface ProcessBatchOptions<Body = unknown> {
 export interface ProcessBatchResult {
     /** Messages whose handler completed successfully and were acked. */
     processed: number;
+    /** Messages whose handler failed permanently and were acked instead of retried. */
+    discarded: number;
     /** Messages whose handler threw and were marked for retry. */
     failed: number;
 }
 /**
- * Process every message in `batch` sequentially, acking on success and retrying on failure.
+ * Error contract for failures that cannot converge by redelivering the same queue message.
  *
- * Each message is passed to `handler`; if it resolves the message is acked, and if it throws the
- * error is routed to {@link ProcessBatchOptions.onError} and the message is marked for retry (honoring
+ * Domain packages should use a named error class with this flag. {@link processBatch} owns the
+ * transport decision: it reports the failure through `onError`, acknowledges the message, and does
+ * not spend retries or dead-letter capacity on it.
+ */
+export interface NonRetryableQueueErrorLike {
+    readonly queueDisposition: 'discard';
+}
+/** Return whether an unknown thrown value explicitly opts out of queue retry. */
+export declare function isNonRetryableQueueError(error: unknown): error is NonRetryableQueueErrorLike;
+/**
+ * Process every message in `batch` sequentially, acking successes and permanent failures while
+ * retrying transient or unclassified failures.
+ *
+ * Each message is passed to `handler`; if it resolves the message is acked. A thrown error is routed
+ * to {@link ProcessBatchOptions.onError}; errors tagged with `queueDisposition: 'discard'` are then
+ * acked and counted as discarded, while all other errors are marked for retry (honoring
  * {@link ProcessBatchOptions.retryDelaySeconds}). One failing message never affects the others, and
  * the returned counts let tests assert that the per-invocation workload — and therefore the
  * subrequest count — stayed bounded by the batch size.
@@ -99,7 +119,7 @@ export interface ProcessBatchResult {
  * @param handler - Async work for a single message; performs the bounded external call(s). Receives
  *   the decoded `body` and the raw message (for `attempts`, `id`, etc.).
  * @param options - Error reporting and retry tuning; see {@link ProcessBatchOptions}.
- * @returns The number of processed and failed messages.
+ * @returns The number of processed, discarded, and retryable-failed messages.
  * @example
  * ```ts
  * const { processed, failed } = await processBatch(

package/dist/queue/consumer.js

@@ -1,12 +1,14 @@
 /**
  * Consumer-side helper for processing a Cloudflare Queues `MessageBatch` with per-message success and
- * failure handling.
+ * failure handling, including explicit acknowledgement of permanent failures.
  *
  * A queue consumer invocation receives at most `max_batch_size` messages (configured in
  * `wrangler.toml`), which is precisely the mechanism that bounds its subrequest budget: with a small
  * `max_batch_size`, each invocation performs a fixed, small number of external calls no matter how
  * many messages are backed up in the queue. {@link processBatch} applies the standard
  * ack-on-success / retry-on-failure discipline so one poison message does not fail its whole batch.
+ * Errors explicitly tagged with `queueDisposition: 'discard'` are reported and acknowledged because
+ * delivering the same payload again cannot make them converge.
  *
  * Messages are processed sequentially. This keeps the number of *simultaneously open* subrequests at
  * one, staying well clear of the Workers concurrent-connection ceiling, and makes the per-invocation
@@ -27,11 +29,17 @@
  *
  * @packageDocumentation
  */
+/** Return whether an unknown thrown value explicitly opts out of queue retry. */
+export function isNonRetryableQueueError(error) {
+    return (typeof error === 'object' && error !== null && 'queueDisposition' in error && error.queueDisposition === 'discard');
+}
 /**
- * Process every message in `batch` sequentially, acking on success and retrying on failure.
+ * Process every message in `batch` sequentially, acking successes and permanent failures while
+ * retrying transient or unclassified failures.
  *
- * Each message is passed to `handler`; if it resolves the message is acked, and if it throws the
- * error is routed to {@link ProcessBatchOptions.onError} and the message is marked for retry (honoring
+ * Each message is passed to `handler`; if it resolves the message is acked. A thrown error is routed
+ * to {@link ProcessBatchOptions.onError}; errors tagged with `queueDisposition: 'discard'` are then
+ * acked and counted as discarded, while all other errors are marked for retry (honoring
  * {@link ProcessBatchOptions.retryDelaySeconds}). One failing message never affects the others, and
  * the returned counts let tests assert that the per-invocation workload — and therefore the
  * subrequest count — stayed bounded by the batch size.
@@ -41,7 +49,7 @@
  * @param handler - Async work for a single message; performs the bounded external call(s). Receives
  *   the decoded `body` and the raw message (for `attempts`, `id`, etc.).
  * @param options - Error reporting and retry tuning; see {@link ProcessBatchOptions}.
- * @returns The number of processed and failed messages.
+ * @returns The number of processed, discarded, and retryable-failed messages.
  * @example
  * ```ts
  * const { processed, failed } = await processBatch(
@@ -58,6 +66,7 @@ export async function processBatch(batch, handler, options) {
         });
     const retryOptions = options?.retryDelaySeconds === undefined ? undefined : { delaySeconds: options.retryDelaySeconds };
     let processed = 0;
+    let discarded = 0;
     let failed = 0;
     for (const message of batch.messages) {
         try {
@@ -69,12 +78,19 @@ export async function processBatch(batch, handler, options) {
             try {
                 onError(error, message);
             }
-            catch {
-                // onError contract says "must not throw"; guard defensively so retry() and remaining messages still run.
+            catch (reportingError) {
+                // Reporting is best-effort. Preserve the domain error's disposition, but never let a broken
+                // custom reporter make a permanent failure disappear without any local trace.
+                console.error(`[queue:${batch.queue}] onError failed for message ${message.id}`, reportingError, 'original error:', error);
+            }
+            if (isNonRetryableQueueError(error)) {
+                message.ack();
+                discarded++;
+                continue;
             }
             message.retry(retryOptions);
             failed++;
         }
     }
-    return { processed, failed };
+    return { processed, discarded, failed };
 }

package/dist/queue/error-handler.d.ts

@@ -8,8 +8,10 @@ export interface CreateQueueErrorHandlerOptions {
     queue: string;
     /**
      * When set, `captureException` is called only after the final delivery attempt
-     * (`message.attempts > maxRetries`). Cloudflare Queues uses 1-based `attempts`; the last delivery
-     * before the dead-letter queue has `attempts === maxRetries + 1`.
+     * (`message.attempts > maxRetries`). Errors tagged with `queueDisposition: 'discard'` are captured
+     * on their first delivery because {@link processBatch} acknowledges them immediately. Cloudflare
+     * Queues uses 1-based `attempts`; the last delivery before the dead-letter queue has
+     * `attempts === maxRetries + 1`.
      */
     maxRetries?: number;
     /** Optional Sentry client. Omit for console-only reporting (e.g. airlec). */

package/dist/queue/error-handler.js

@@ -1,3 +1,4 @@
+import { isNonRetryableQueueError } from './consumer.js';
 /**
  * Factory for {@link processBatch}'s `onError` hook: logs every failure and optionally reports to
  * Sentry (or another sink) with queue / message id / attempts / body context.
@@ -10,11 +11,15 @@ export function createQueueErrorHandler(options) {
         if (!capture) {
             return;
         }
-        if (maxRetries !== undefined && message.attempts <= maxRetries) {
+        if (!isNonRetryableQueueError(error) && maxRetries !== undefined && message.attempts <= maxRetries) {
             return;
         }
         capture(error, {
-            tags: { queue, queue_message_id: message.id },
+            tags: {
+                queue,
+                queue_message_id: message.id,
+                queue_disposition: isNonRetryableQueueError(error) ? 'discard' : 'retry',
+            },
             extra: { attempts: message.attempts, body: message.body },
         });
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rdlabo/workers-hono-kit",
-  "version": "0.9.7",
+  "version": "0.10.0",
   "private": false,
   "publishConfig": {
     "access": "public"