@rdlabo/workers-hono-kit 0.9.6 → 0.10.0

package/README.md

@@ -2,10 +2,10 @@
 
 Infrastructure toolkit for building APIs on [Hono](https://hono.dev) + [Cloudflare Workers](https://workers.cloudflare.com).
 
-It provides the building blocks a NestJS-style API needs but that don't run on `workerd` (no Node.js AWS SDK, no `firebase-admin`), plus middleware for common HTTP response concerns:
+It provides Workers-oriented building blocks for a NestJS-style API, plus middleware for common HTTP response concerns:
 
 - **Firebase ID-token verification** on Workers via [`jose`](https://github.com/panva/jose) (RS256 against Google's securetoken JWKS), with optional Identity Toolkit REST for `getUser` / `deleteUser`.
-- **AWS Secrets Manager / STS AssumeRole / CloudFront signed URLs** via SigV4-signed `fetch` ([`aws4fetch`](https://github.com/mhart/aws4fetch)) or Web Crypto — no AWS SDK.
+- **AWS Secrets Manager / STS AssumeRole / CloudFront signed URLs** via focused SigV4-signed `fetch` ([`aws4fetch`](https://github.com/mhart/aws4fetch)) or Web Crypto, avoiding a broad SDK dependency when only a few AWS APIs are needed.
 - **Middleware**: `finalizeResponse` (weak ETag via `hono/etag`), `validate` (NestJS `ValidationPipe`-shaped 400), and zod number-coercion helpers.
 - **Standard API errors**: `createHttpErrorHandler` / `notFoundHandler` / `HttpStatus`.
 - **Deadlock retry** (`ER_LOCK_DEADLOCK` exponential backoff) and an optional **MySQL data layer** (`@rdlabo/workers-hono-kit/db`) for Hyperdrive + Drizzle.
@@ -104,9 +104,19 @@ 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). |
-| `ExecutionContextLike` | Minimal `waitUntil`-only Workers execution context shape (for `withMysqlConnections` in worker entry modules without importing `./db`). |
+| `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`
 
@@ -114,12 +124,12 @@ Requires the `drizzle-orm` and `mysql2` peers. Reads run against a replica via r
 
 | Export | Description |
 | --- | --- |
-| `createHyperdriveDatabase(options)` | `DisposableDatabase` that lazily opens primary/replica connections from Hyperdrive bindings per request; `dispose()` closes them. |
+| `createHyperdriveDatabase(options)` | `DisposableDatabase` that lazily opens primary/replica connections from Hyperdrive bindings per request. Workers cleans them up at invocation end; the legacy `dispose()` is a no-op. |
 | `createMysqlDatabase(options)` | Assemble a `Database` from an already-connected Drizzle ORM + replica `QueryRunner`. |
 | `databaseFrom(orm, replica)` | Build a `Database` from an existing Drizzle instance + replica handle. |
 | `Database` / `DisposableDatabase` / `QueryRunner` / `TxOf` | The `read` / `write` / `transaction` API and its supporting types. |
-| `hyperdriveConnectionOptions(hyperdrive, overrides?)` / `HyperdriveLike` / `ExecutionContextLike` | Build mysql2 `createConnection` options from a Hyperdrive binding (`disableEval`, `decimalNumbers`, `timezone '+09:00'` by default). `ExecutionContextLike` is the same type as the root export, re-exported here so `withMysqlConnections` callers don't need the root import. |
-| `withMysqlConnections(...)` | Open primary/replica connections, run a function, close them in `finally` (via `ctx.waitUntil`). |
+| `hyperdriveConnectionOptions(hyperdrive, overrides?)` / `HyperdriveLike` / `ExecutionContextLike` | Build mysql2 `createConnection` options from a Hyperdrive binding (`disableEval`, `decimalNumbers`, `timezone '+09:00'` by default). `timezone` controls mysql2's JavaScript `Date` conversion; it does not change the MySQL session timezone. |
+| `withMysqlConnections(...)` | Open primary/replica connections in parallel and run a function. Workers cleans them up at invocation end. |
 | `retryWhenDeadlock(fn, retries?, delay?)` | Same deadlock-retry helper as the root export. |
 | `insertIdOf` / `affectedRowsOf` / `insertedIdsOf` / `DzWriteResult` | Extract `insertId` / `affectedRows` (and derive contiguous bulk-insert ids) from a mysql2 write result. |
 | `toJstDate` / `jstTimestampParams` / `jstDatetimeParams` / `jstDateParams` | JST date/time normalization params (advanced use). |
@@ -588,12 +598,8 @@ const db = createHyperdriveDatabase({
   createOrm: (conn) => drizzle(conn, { ...DRIZZLE_ORM_OPTIONS, schema }),
 });
 
-try {
-  const rows = await db.read('SELECT * FROM users WHERE id = ?', [id]); // replica, raw SQL
-  await db.write((dz) => dz.insert(users).values({ name })); // primary, deadlock-retried
-} finally {
-  await db.dispose();
-}
+const rows = await db.read('SELECT * FROM users WHERE id = ?', [id]); // replica, raw SQL
+await db.write((dz) => dz.insert(users).values({ name })); // primary, deadlock-retried
 ```
 
 ### KV cache

package/dist/aws/secrets-manager.d.ts

@@ -2,7 +2,7 @@
  * AWS credentials used to sign Secrets Manager requests.
  *
  * @remarks
- * Cloudflare Workers have neither the AWS SDK nor IAM role credentials, so static AWS keys are supplied
+ * Cloudflare Workers do not provide the AWS default credential chain, so AWS credentials are supplied
  * as Workers secrets and used to produce a SigV4 signature.
  */
 export interface AwsSecretsOptions {
@@ -19,7 +19,7 @@ export interface AwsSecretsOptions {
  * Fetch and parse a secret from AWS Secrets Manager, caching the result per isolate.
  *
  * Issues a `GetSecretValue` call to Secrets Manager via a SigV4-signed `fetch` (using aws4fetch), with no
- * AWS SDK involved. The parsed `SecretString` is cached per isolate keyed by region, access key ID, and
+ * broad AWS SDK dependency involved. The parsed `SecretString` is cached per isolate keyed by region, access key ID, and
  * secret ID; concurrent first-time callers share one in-flight request, and a rejected fetch clears the
  * cache entry so the next call retries.
  *

package/dist/aws/secrets-manager.js

@@ -15,7 +15,7 @@ let cache = null;
  * Fetch and parse a secret from AWS Secrets Manager, caching the result per isolate.
  *
  * Issues a `GetSecretValue` call to Secrets Manager via a SigV4-signed `fetch` (using aws4fetch), with no
- * AWS SDK involved. The parsed `SecretString` is cached per isolate keyed by region, access key ID, and
+ * broad AWS SDK dependency involved. The parsed `SecretString` is cached per isolate keyed by region, access key ID, and
  * secret ID; concurrent first-time callers share one in-flight request, and a rejected fetch clears the
  * cache entry so the next call retries.
  *

package/dist/db/connection.d.ts

@@ -31,11 +31,9 @@ export interface HyperdriveLike {
  * - `decimalNumbers: true` — return `DECIMAL`/`NEWDECIMAL` columns as JS `number` rather than
  *   strings, so raw-SQL reads and Drizzle's inferred types align on a single numeric domain type.
  *   This assumes no column's precision exceeds the JS safe-integer range.
- * - `timezone: '+09:00'` — set the driver's session timezone to JST. mysql2 defaults to `'local'`,
- *   which is UTC in the Workers runtime; pinning the driver timezone keeps `datetime`/`timestamp`
- *   round-trips independent of the database's session timezone (only the internally stored UTC
- *   value differs, which is invisible to the application). Non-JST deployments can override this
- *   via `extra: { timezone: '...' }`.
+ * - `timezone: '+09:00'` — interpret and serialize JavaScript `Date` values as JST. This is a
+ *   mysql2 client-side conversion option; it does not issue `SET time_zone` or change the MySQL
+ *   session timezone. Non-JST deployments can override it via `extra: { timezone: '...' }`.
  *
  * @param hyperdrive - the Hyperdrive binding to derive connection fields from.
  * @param extra - additional mysql2 options merged last, overriding the defaults above.
@@ -43,14 +41,15 @@ export interface HyperdriveLike {
  */
 export declare function hyperdriveConnectionOptions(hyperdrive: HyperdriveLike, extra?: Record<string, unknown>): Record<string, unknown>;
 /**
- * Open primary and replica connections, run `fn` with them, and close both afterwards.
+ * Open primary and replica connections in parallel and run `fn` with them.
  *
- * The connections are always closed in a `finally` block; closing is scheduled through
- * `ctx.waitUntil` so it can complete after the response has been returned, without blocking it.
+ * Cloudflare Workers automatically cleans up connections created during an invocation. Calling
+ * `Connection.end()` is unnecessary and can race work registered with `waitUntil`. The `ctx`
+ * parameter remains for API compatibility and is intentionally not used for connection teardown.
  *
  * @typeParam T - resolved value produced by `fn`.
  * @param hyperdrives - the primary and replica Hyperdrive bindings to connect to.
- * @param ctx - the execution context whose `waitUntil` defers connection teardown past the response.
+ * @param ctx - the request execution context, retained for API compatibility.
  * @param fn - callback invoked with the open `primary` and `replica` connections.
  * @param connectionOptions - extra mysql2 options forwarded to {@link hyperdriveConnectionOptions}.
  * @returns the value resolved by `fn`.

package/dist/db/connection.js

@@ -11,11 +11,9 @@ import { MYSQL_TIMEZONE } from './jst.js';
  * - `decimalNumbers: true` — return `DECIMAL`/`NEWDECIMAL` columns as JS `number` rather than
  *   strings, so raw-SQL reads and Drizzle's inferred types align on a single numeric domain type.
  *   This assumes no column's precision exceeds the JS safe-integer range.
- * - `timezone: '+09:00'` — set the driver's session timezone to JST. mysql2 defaults to `'local'`,
- *   which is UTC in the Workers runtime; pinning the driver timezone keeps `datetime`/`timestamp`
- *   round-trips independent of the database's session timezone (only the internally stored UTC
- *   value differs, which is invisible to the application). Non-JST deployments can override this
- *   via `extra: { timezone: '...' }`.
+ * - `timezone: '+09:00'` — interpret and serialize JavaScript `Date` values as JST. This is a
+ *   mysql2 client-side conversion option; it does not issue `SET time_zone` or change the MySQL
+ *   session timezone. Non-JST deployments can override it via `extra: { timezone: '...' }`.
  *
  * @param hyperdrive - the Hyperdrive binding to derive connection fields from.
  * @param extra - additional mysql2 options merged last, overriding the defaults above.
@@ -35,14 +33,15 @@ export function hyperdriveConnectionOptions(hyperdrive, extra) {
     };
 }
 /**
- * Open primary and replica connections, run `fn` with them, and close both afterwards.
+ * Open primary and replica connections in parallel and run `fn` with them.
  *
- * The connections are always closed in a `finally` block; closing is scheduled through
- * `ctx.waitUntil` so it can complete after the response has been returned, without blocking it.
+ * Cloudflare Workers automatically cleans up connections created during an invocation. Calling
+ * `Connection.end()` is unnecessary and can race work registered with `waitUntil`. The `ctx`
+ * parameter remains for API compatibility and is intentionally not used for connection teardown.
  *
  * @typeParam T - resolved value produced by `fn`.
  * @param hyperdrives - the primary and replica Hyperdrive bindings to connect to.
- * @param ctx - the execution context whose `waitUntil` defers connection teardown past the response.
+ * @param ctx - the request execution context, retained for API compatibility.
  * @param fn - callback invoked with the open `primary` and `replica` connections.
  * @param connectionOptions - extra mysql2 options forwarded to {@link hyperdriveConnectionOptions}.
  * @returns the value resolved by `fn`.
@@ -59,17 +58,10 @@ export function hyperdriveConnectionOptions(hyperdrive, extra) {
  * ```
  */
 export async function withMysqlConnections(hyperdrives, ctx, fn, connectionOptions) {
-    let primary;
-    let replica;
-    try {
-        primary = await createConnection(hyperdriveConnectionOptions(hyperdrives.primary, connectionOptions));
-        replica = await createConnection(hyperdriveConnectionOptions(hyperdrives.replica, connectionOptions));
-        return await fn({ primary, replica });
-    }
-    finally {
-        const closing = [primary, replica].filter((c) => c !== undefined).map((c) => c.end());
-        if (closing.length > 0) {
-            ctx.waitUntil(Promise.allSettled(closing));
-        }
-    }
+    void ctx;
+    const [primary, replica] = await Promise.all([
+        createConnection(hyperdriveConnectionOptions(hyperdrives.primary, connectionOptions)),
+        createConnection(hyperdriveConnectionOptions(hyperdrives.replica, connectionOptions)),
+    ]);
+    return fn({ primary, replica });
 }

package/dist/db/database.d.ts

@@ -79,19 +79,22 @@ export interface Database<TDrizzle, TTx = TxOf<TDrizzle>> {
     transaction<T>(fn: (tx: TTx) => Promise<T>): Promise<T>;
 }
 /**
- * A {@link Database} that owns its connections and must be disposed.
+ * A {@link Database} that opens its own connections.
  *
  * @remarks
- * Used by the variants that open connections internally (Hyperdrive- or Pool-backed).
+ * Used by variants that open connections internally. Lifecycle behavior depends on the backing
+ * implementation: pool-backed databases close their pool, while Hyperdrive-backed databases leave
+ * invocation-scoped connection cleanup to the Workers runtime.
  *
  * @typeParam TDrizzle - the consumer's Drizzle ORM type.
  * @typeParam TTx - the transaction-handle type, inferred from `TDrizzle` by default.
  */
 export interface DisposableDatabase<TDrizzle, TTx = TxOf<TDrizzle>> extends Database<TDrizzle, TTx> {
     /**
-     * Close the connections opened by this database.
+     * Release resources owned by the implementation. Hyperdrive-backed databases keep this method as
+     * a compatibility no-op; pool-backed databases use it to close their pool.
      *
-     * @returns a promise that settles once both connections are closed.
+     * @returns a promise that resolves after implementation-specific cleanup.
      */
     dispose(): Promise<void>;
 }
@@ -155,13 +158,15 @@ export interface CreateHyperdriveDatabaseOptions<TDrizzle> {
  * Create a {@link DisposableDatabase} that lazily opens its connections from Hyperdrive bindings.
  *
  * @remarks
- * Construct one per request and call `dispose()` after the response to close the connections.
- * Connections and the ORM are created on first use and reused for the lifetime of the instance; the
- * read/write/transaction surface is identical to {@link createMysqlDatabase}.
+ * Construct one per request. Connections and the ORM are created on first use and reused for the
+ * lifetime of the instance; the read/write/transaction surface is identical to
+ * {@link createMysqlDatabase}. Workers automatically cleans up connections at the end of the
+ * invocation, so callers do not need to close them manually.
  *
  * @typeParam TDrizzle - the consumer's Drizzle ORM type.
  * @param options - the primary/replica Hyperdrive bindings, the ORM factory, and connection options.
- * @returns a {@link DisposableDatabase} that must be disposed when done.
+ * @returns a {@link DisposableDatabase} whose compatibility `dispose()` method is a no-op; Workers
+ *   cleans up its invocation-scoped connections automatically.
  * @example
  * ```ts
  * const db = createHyperdriveDatabase({
@@ -169,11 +174,7 @@ export interface CreateHyperdriveDatabaseOptions<TDrizzle> {
  *   replicaHyperdrive: env.REPLICA,
  *   createOrm: (primary) => drizzle(primary, { schema, ...DRIZZLE_ORM_OPTIONS }),
  * });
- * try {
- *   await db.write((dz) => dz.insert(users).values(user));
- * } finally {
- *   await db.dispose();
- * }
+ * await db.write((dz) => dz.insert(users).values(user));
  * ```
  */
 export declare function createHyperdriveDatabase<TDrizzle>(options: CreateHyperdriveDatabaseOptions<TDrizzle>): DisposableDatabase<TDrizzle>;

package/dist/db/database.js

@@ -27,13 +27,15 @@ export function createMysqlDatabase(options) {
  * Create a {@link DisposableDatabase} that lazily opens its connections from Hyperdrive bindings.
  *
  * @remarks
- * Construct one per request and call `dispose()` after the response to close the connections.
- * Connections and the ORM are created on first use and reused for the lifetime of the instance; the
- * read/write/transaction surface is identical to {@link createMysqlDatabase}.
+ * Construct one per request. Connections and the ORM are created on first use and reused for the
+ * lifetime of the instance; the read/write/transaction surface is identical to
+ * {@link createMysqlDatabase}. Workers automatically cleans up connections at the end of the
+ * invocation, so callers do not need to close them manually.
  *
  * @typeParam TDrizzle - the consumer's Drizzle ORM type.
  * @param options - the primary/replica Hyperdrive bindings, the ORM factory, and connection options.
- * @returns a {@link DisposableDatabase} that must be disposed when done.
+ * @returns a {@link DisposableDatabase} whose compatibility `dispose()` method is a no-op; Workers
+ *   cleans up its invocation-scoped connections automatically.
  * @example
  * ```ts
  * const db = createHyperdriveDatabase({
@@ -41,11 +43,7 @@ export function createMysqlDatabase(options) {
  *   replicaHyperdrive: env.REPLICA,
  *   createOrm: (primary) => drizzle(primary, { schema, ...DRIZZLE_ORM_OPTIONS }),
  * });
- * try {
- *   await db.write((dz) => dz.insert(users).values(user));
- * } finally {
- *   await db.dispose();
- * }
+ * await db.write((dz) => dz.insert(users).values(user));
  * ```
  */
 export function createHyperdriveDatabase(options) {
@@ -71,8 +69,9 @@ export function createHyperdriveDatabase(options) {
             const dz = (await ormFor());
             return retryWhenDeadlock(() => dz.transaction(fn));
         },
-        async dispose() {
-            await Promise.all([primaryConn?.then((c) => c.end()), replicaConn?.then((c) => c.end())]);
+        /** @deprecated Workers cleans up invocation-scoped connections automatically. */
+        dispose() {
+            return Promise.resolve();
         },
     };
 }

package/dist/firebase/identity-toolkit.d.ts

@@ -16,8 +16,8 @@ export interface ServiceAccount {
  * Minimal Google Identity Toolkit REST client for the user-management operations that token
  * verification does not cover: `accounts:lookup` (getUser) and `accounts:delete` (deleteUser).
  *
- * This replaces the parts of the `firebase-admin` Node SDK that cannot run on Cloudflare
- * Workers (workerd).
+ * This is a focused REST alternative for projects that only need a small subset of Firebase Auth
+ * administration and do not want to bundle the broader `firebase-admin` SDK.
  *
  * @remarks
  * Authentication follows the JWT-bearer flow: a JWT assertion is signed with the service

package/dist/firebase/identity-toolkit.js

@@ -11,8 +11,8 @@ const LOOKUP_CHUNK_SIZE = 100;
  * Minimal Google Identity Toolkit REST client for the user-management operations that token
  * verification does not cover: `accounts:lookup` (getUser) and `accounts:delete` (deleteUser).
  *
- * This replaces the parts of the `firebase-admin` Node SDK that cannot run on Cloudflare
- * Workers (workerd).
+ * This is a focused REST alternative for projects that only need a small subset of Firebase Auth
+ * administration and do not want to bundle the broader `firebase-admin` SDK.
  *
  * @remarks
  * Authentication follows the JWT-bearer flow: a JWT assertion is signed with the service
@@ -152,6 +152,12 @@ export class IdentityToolkit {
             body: JSON.stringify({ localId: uid }),
         });
         if (!res.ok) {
+            const body = (await res.json().catch(() => undefined));
+            // Account deletion is an idempotent operation for callers. A retry after a lost response may
+            // legitimately find that the preceding request already removed the Firebase user.
+            if (body?.error?.message === 'USER_NOT_FOUND') {
+                return;
+            }
             throw new Error(`Identity Toolkit delete failed: ${res.status}`);
         }
     }

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/dist/queue/send.d.ts

@@ -2,11 +2,13 @@
  * Producer-side helper for fanning a large list of items into a Cloudflare Queue without letting the
  * producer's own subrequest count scale linearly with the list.
  *
- * A Worker may issue at most 50 (free) / 1000 (paid) subrequests per invocation, and each
- * {@link QueueLike.send} counts as one subrequest. Enqueuing `N` items with per-item `send()` calls
- * therefore reintroduces the very unbounded fan-out that queues exist to remove. {@link sendInChunks}
- * instead groups items into batches and issues one {@link QueueLike.sendBatch} per batch, so the
- * producer spends `ceil(N / chunkSize)` subrequests regardless of how large `N` grows.
+ * Queue bindings call a Cloudflare internal service. The internal-service subrequest budget is
+ * 1,000 on Workers Free and matches the configured subrequest limit on Paid (10,000 by default,
+ * configurable up to 10 million). Each {@link QueueLike.send} counts as one subrequest. Enqueuing
+ * `N` items with per-item `send()` calls therefore reintroduces the very unbounded fan-out that
+ * queues exist to remove. {@link sendInChunks} instead groups items into batches and issues one
+ * {@link QueueLike.sendBatch} per batch, so the producer spends `ceil(N / chunkSize)` subrequests
+ * regardless of how large `N` grows.
  *
  * The heavy per-item work (external API calls, etc.) is expected to run in the queue *consumer*,
  * where each invocation processes only `max_batch_size` messages and thus enjoys its own bounded

package/dist/queue/send.js

@@ -2,11 +2,13 @@
  * Producer-side helper for fanning a large list of items into a Cloudflare Queue without letting the
  * producer's own subrequest count scale linearly with the list.
  *
- * A Worker may issue at most 50 (free) / 1000 (paid) subrequests per invocation, and each
- * {@link QueueLike.send} counts as one subrequest. Enqueuing `N` items with per-item `send()` calls
- * therefore reintroduces the very unbounded fan-out that queues exist to remove. {@link sendInChunks}
- * instead groups items into batches and issues one {@link QueueLike.sendBatch} per batch, so the
- * producer spends `ceil(N / chunkSize)` subrequests regardless of how large `N` grows.
+ * Queue bindings call a Cloudflare internal service. The internal-service subrequest budget is
+ * 1,000 on Workers Free and matches the configured subrequest limit on Paid (10,000 by default,
+ * configurable up to 10 million). Each {@link QueueLike.send} counts as one subrequest. Enqueuing
+ * `N` items with per-item `send()` calls therefore reintroduces the very unbounded fan-out that
+ * queues exist to remove. {@link sendInChunks} instead groups items into batches and issues one
+ * {@link QueueLike.sendBatch} per batch, so the producer spends `ceil(N / chunkSize)` subrequests
+ * regardless of how large `N` grows.
  *
  * The heavy per-item work (external API calls, etc.) is expected to run in the queue *consumer*,
  * where each invocation processes only `max_batch_size` messages and thus enjoys its own bounded

package/package.json

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

package/scripts/check-subrequest-fanout.mjs

@@ -2,7 +2,8 @@
 /**
  * check-subrequest-fanout — flag per-item external-call fan-outs that scale with data size.
  *
- * Cloudflare Workers cap subrequests per invocation (50 free / 1000 paid). Looping an external call
+ * Cloudflare Workers cap external subrequests per invocation (50 on Free; 10,000 by default on
+ * Paid, configurable up to 10 million). Looping an external call
  * (fetch / AI / Stripe / push / ES) once per row reintroduces an unbounded fan-out that eventually
  * exceeds the cap as the userbase/data grows. This gate greps for the concurrency-loop markers that
  * usually wrap such fan-outs and fails CI unless the site is explicitly annotated as safe.