@vercel/queue 0.3.0 → 0.3.1

package/dist/index.d.mts

@@ -477,6 +477,14 @@ declare class MessageLockedError extends Error {
     readonly retryAfter?: number;
     constructor(messageId: string, retryAfter?: number);
 }
+/**
+ * Error thrown when the server rate-limits a request (HTTP 429).
+ */
+declare class TooManyRequestsError extends Error {
+    /** Suggested retry delay in seconds, from the Retry-After header, if sent. */
+    readonly retryAfter?: number;
+    constructor(message?: string, retryAfter?: number);
+}
 /**
  * Error thrown when authentication fails.
  * This typically means the token is missing, invalid, or expired.
@@ -895,4 +903,4 @@ declare function parseRawCallback(body: unknown, headers: Record<string, string
  */
 declare function parseCallback(request: Request): Promise<ParsedCallbackRequest>;
 
-export { BadRequestError, type BaseUrlResolver, BufferTransport, CLOUD_EVENT_TYPE_V1BETA, CLOUD_EVENT_TYPE_V2BETA, ConsumerDiscoveryError, ConsumerRegistryNotConfiguredError, DuplicateMessageError, ForbiddenError, InternalServerError, InvalidLimitError, JsonTransport, type Message, MessageAlreadyProcessedError, MessageCorruptedError, type MessageHandler, MessageLockedError, type MessageMetadata, MessageNotAvailableError, MessageNotFoundError, type ParsedCallbackRequest, type ParsedCallbackV1, type ParsedCallbackV2, PollingQueueClient, type PollingQueueClientOptions, QueueClient, type QueueClientOptions, QueueEmptyError, type ReceiveBatchOptions, type ReceiveByIdOptions, type ReceiveOptions, type ReceiveResult, type RegisterDevConsumerOptions, type RetryDirective, type RetryHandler, type SendOptions, type SendResult, StreamTransport, type Transport, UnauthorizedError, type VercelRegion, handleCallback, parseCallback, parseRawCallback, registerDevConsumer, send };
+export { BadRequestError, type BaseUrlResolver, BufferTransport, CLOUD_EVENT_TYPE_V1BETA, CLOUD_EVENT_TYPE_V2BETA, ConsumerDiscoveryError, ConsumerRegistryNotConfiguredError, DuplicateMessageError, ForbiddenError, InternalServerError, InvalidLimitError, JsonTransport, type Message, MessageAlreadyProcessedError, MessageCorruptedError, type MessageHandler, MessageLockedError, type MessageMetadata, MessageNotAvailableError, MessageNotFoundError, type ParsedCallbackRequest, type ParsedCallbackV1, type ParsedCallbackV2, PollingQueueClient, type PollingQueueClientOptions, QueueClient, type QueueClientOptions, QueueEmptyError, type ReceiveBatchOptions, type ReceiveByIdOptions, type ReceiveOptions, type ReceiveResult, type RegisterDevConsumerOptions, type RetryDirective, type RetryHandler, type SendOptions, type SendResult, StreamTransport, TooManyRequestsError, type Transport, UnauthorizedError, type VercelRegion, handleCallback, parseCallback, parseRawCallback, registerDevConsumer, send };

package/dist/index.d.ts

@@ -477,6 +477,14 @@ declare class MessageLockedError extends Error {
     readonly retryAfter?: number;
     constructor(messageId: string, retryAfter?: number);
 }
+/**
+ * Error thrown when the server rate-limits a request (HTTP 429).
+ */
+declare class TooManyRequestsError extends Error {
+    /** Suggested retry delay in seconds, from the Retry-After header, if sent. */
+    readonly retryAfter?: number;
+    constructor(message?: string, retryAfter?: number);
+}
 /**
  * Error thrown when authentication fails.
  * This typically means the token is missing, invalid, or expired.
@@ -895,4 +903,4 @@ declare function parseRawCallback(body: unknown, headers: Record<string, string
  */
 declare function parseCallback(request: Request): Promise<ParsedCallbackRequest>;
 
-export { BadRequestError, type BaseUrlResolver, BufferTransport, CLOUD_EVENT_TYPE_V1BETA, CLOUD_EVENT_TYPE_V2BETA, ConsumerDiscoveryError, ConsumerRegistryNotConfiguredError, DuplicateMessageError, ForbiddenError, InternalServerError, InvalidLimitError, JsonTransport, type Message, MessageAlreadyProcessedError, MessageCorruptedError, type MessageHandler, MessageLockedError, type MessageMetadata, MessageNotAvailableError, MessageNotFoundError, type ParsedCallbackRequest, type ParsedCallbackV1, type ParsedCallbackV2, PollingQueueClient, type PollingQueueClientOptions, QueueClient, type QueueClientOptions, QueueEmptyError, type ReceiveBatchOptions, type ReceiveByIdOptions, type ReceiveOptions, type ReceiveResult, type RegisterDevConsumerOptions, type RetryDirective, type RetryHandler, type SendOptions, type SendResult, StreamTransport, type Transport, UnauthorizedError, type VercelRegion, handleCallback, parseCallback, parseRawCallback, registerDevConsumer, send };
+export { BadRequestError, type BaseUrlResolver, BufferTransport, CLOUD_EVENT_TYPE_V1BETA, CLOUD_EVENT_TYPE_V2BETA, ConsumerDiscoveryError, ConsumerRegistryNotConfiguredError, DuplicateMessageError, ForbiddenError, InternalServerError, InvalidLimitError, JsonTransport, type Message, MessageAlreadyProcessedError, MessageCorruptedError, type MessageHandler, MessageLockedError, type MessageMetadata, MessageNotAvailableError, MessageNotFoundError, type ParsedCallbackRequest, type ParsedCallbackV1, type ParsedCallbackV2, PollingQueueClient, type PollingQueueClientOptions, QueueClient, type QueueClientOptions, QueueEmptyError, type ReceiveBatchOptions, type ReceiveByIdOptions, type ReceiveOptions, type ReceiveResult, type RegisterDevConsumerOptions, type RetryDirective, type RetryHandler, type SendOptions, type SendResult, StreamTransport, TooManyRequestsError, type Transport, UnauthorizedError, type VercelRegion, handleCallback, parseCallback, parseRawCallback, registerDevConsumer, send };

package/dist/index.js

@@ -50,6 +50,7 @@ __export(index_exports, {
   QueueClient: () => QueueClient,
   QueueEmptyError: () => QueueEmptyError,
   StreamTransport: () => StreamTransport,
+  TooManyRequestsError: () => TooManyRequestsError,
   UnauthorizedError: () => UnauthorizedError,
   handleCallback: () => handleCallback2,
   parseCallback: () => parseCallback,
@@ -181,6 +182,15 @@ var MessageLockedError = class extends Error {
     this.retryAfter = retryAfter;
   }
 };
+var TooManyRequestsError = class extends Error {
+  /** Suggested retry delay in seconds, from the Retry-After header, if sent. */
+  retryAfter;
+  constructor(message = "Too many requests", retryAfter) {
+    super(message);
+    this.name = "TooManyRequestsError";
+    this.retryAfter = retryAfter;
+  }
+};
 var UnauthorizedError = class extends Error {
   constructor(message = "Missing or invalid authentication token") {
     super(message);
@@ -246,6 +256,8 @@ var MIN_VISIBILITY_TIMEOUT_SECONDS = 30;
 var MAX_RENEWAL_INTERVAL_SECONDS = 60;
 var MIN_RENEWAL_INTERVAL_SECONDS = 10;
 var RETRY_INTERVAL_MS = 3e3;
+var DIRECTIVE_CALL_ATTEMPTS = 3;
+var DIRECTIVE_CALL_RETRY_DELAY_MS = 250;
 function calculateRenewalInterval(visibilityTimeoutSeconds) {
   return Math.min(
     MAX_RENEWAL_INTERVAL_SECONDS,
@@ -289,6 +301,54 @@ var ConsumerGroup = class {
     error instanceof UnauthorizedError || // 401 - auth failed
     error instanceof ForbiddenError;
   }
+  /**
+   * Network-level failures (DNS, connection reset, socket close) surface
+   * from fetch as TypeError with the cause attached; any response that
+   * actually reached the server — whatever its HTTP status — does not.
+   */
+  isNetworkError(error) {
+    return error instanceof TypeError;
+  }
+  /**
+   * Run a directive call (acknowledge / changeVisibility) with bounded
+   * retries. Only failures that are worth re-attempting in process are
+   * retried:
+   * - network-level failures (the request may never have reached the
+   *   server), with jittered linear backoff;
+   * - 429 responses that carry a Retry-After header, waiting the
+   *   indicated delay.
+   * Everything else — other 4xx, 5xx, 429 without Retry-After — is
+   * thrown immediately.
+   */
+  async directiveCallWithRetries(fn) {
+    let lastError;
+    for (let attempt = 1; attempt <= DIRECTIVE_CALL_ATTEMPTS; attempt++) {
+      try {
+        return await fn();
+      } catch (error) {
+        lastError = error;
+        if (attempt === DIRECTIVE_CALL_ATTEMPTS) {
+          throw error;
+        }
+        if (error instanceof TooManyRequestsError) {
+          if (error.retryAfter === void 0) {
+            throw error;
+          }
+          await new Promise(
+            (resolve2) => setTimeout(resolve2, error.retryAfter * 1e3)
+          );
+          continue;
+        }
+        if (!this.isNetworkError(error)) {
+          throw error;
+        }
+        const baseDelayMs = DIRECTIVE_CALL_RETRY_DELAY_MS * attempt;
+        const delayMs = baseDelayMs / 2 + Math.random() * (baseDelayMs / 2);
+        await new Promise((resolve2) => setTimeout(resolve2, delayMs));
+      }
+    }
+    throw lastError;
+  }
   /**
    * Starts a background loop that periodically extends the visibility timeout for a message.
    *
@@ -433,11 +493,13 @@ var ConsumerGroup = class {
         if (directive) {
           if ("acknowledge" in directive && directive.acknowledge) {
             try {
-              await this.client.acknowledgeMessage({
-                queueName: this.topicName,
-                consumerGroup: this.consumerGroupName,
-                receiptHandle: message.receiptHandle
-              });
+              await this.directiveCallWithRetries(
+                () => this.client.acknowledgeMessage({
+                  queueName: this.topicName,
+                  consumerGroup: this.consumerGroupName,
+                  receiptHandle: message.receiptHandle
+                })
+              );
             } catch (ackError) {
               console.warn("Failed to acknowledge message:", ackError);
             }
@@ -446,12 +508,14 @@ var ConsumerGroup = class {
           }
           if ("afterSeconds" in directive && typeof directive.afterSeconds === "number") {
             try {
-              await this.client.changeVisibility({
-                queueName: this.topicName,
-                consumerGroup: this.consumerGroupName,
-                receiptHandle: message.receiptHandle,
-                visibilityTimeoutSeconds: directive.afterSeconds
-              });
+              await this.directiveCallWithRetries(
+                () => this.client.changeVisibility({
+                  queueName: this.topicName,
+                  consumerGroup: this.consumerGroupName,
+                  receiptHandle: message.receiptHandle,
+                  visibilityTimeoutSeconds: directive.afterSeconds
+                })
+              );
             } catch (changeError) {
               console.warn(
                 "Failed to reschedule message for retry:",
@@ -1514,10 +1578,28 @@ async function consumeStream(stream) {
     reader.releaseLock();
   }
 }
-function throwCommonHttpError(status, statusText, errorText, operation, badRequestDefault = "Invalid parameters") {
+function parseRetryAfterSeconds(value) {
+  if (!value) return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return seconds;
+  }
+  const dateMs = Date.parse(value);
+  if (!Number.isNaN(dateMs)) {
+    return Math.max(0, (dateMs - Date.now()) / 1e3);
+  }
+  return void 0;
+}
+function throwCommonHttpError(status, statusText, errorText, operation, badRequestDefault = "Invalid parameters", retryAfterHeader) {
   if (status === 400) {
     throw new BadRequestError(errorText || badRequestDefault);
   }
+  if (status === 429) {
+    throw new TooManyRequestsError(
+      errorText || `Too many requests: ${operation}`,
+      parseRetryAfterSeconds(retryAfterHeader)
+    );
+  }
   if (status === 401) {
     throw new UnauthorizedError(errorText || void 0);
   }
@@ -1694,7 +1776,7 @@ Cause: ${cause}`
       }
       console.debug("[VQS Debug] Request:", JSON.stringify(logData, null, 2));
     }
-    init.headers.set("User-Agent", `@vercel/queue/${"0.3.0"}`);
+    init.headers.set("User-Agent", `@vercel/queue/${"0.3.1"}`);
     init.headers.set("Vqs-Client-Ts", (/* @__PURE__ */ new Date()).toISOString());
     const fetchInit = this.dispatcher ? { ...init, dispatcher: this.dispatcher } : init;
     const response = await fetch(url, fetchInit);
@@ -1973,7 +2055,8 @@ Cause: ${cause}`
         response.statusText,
         errorText,
         "acknowledge message",
-        "Missing or invalid receipt handle"
+        "Missing or invalid receipt handle",
+        response.headers?.get("Retry-After") ?? null
       );
     }
     await response.text();
@@ -2025,7 +2108,8 @@ Cause: ${cause}`
         response.statusText,
         errorText,
         "change visibility",
-        "Missing receipt handle or invalid visibility timeout"
+        "Missing receipt handle or invalid visibility timeout",
+        response.headers?.get("Retry-After") ?? null
       );
     }
     await response.text();
@@ -2384,6 +2468,7 @@ function handleCallback2(handler, options) {
   QueueClient,
   QueueEmptyError,
   StreamTransport,
+  TooManyRequestsError,
   UnauthorizedError,
   handleCallback,
   parseCallback,