@vercel/queue 0.1.1 → 0.1.3

package/dist/index.mjs

@@ -78,6 +78,8 @@ import { parseMultipartStream } from "mixpart";
 import * as fs from "fs";
 import * as net from "net";
 import * as path from "path";
+import { minimatch } from "minimatch";
+import pc from "picocolors";
 
 // src/types.ts
 var MessageNotFoundError = class extends Error {
@@ -340,11 +342,12 @@ var ConsumerGroup = class {
       message.receiptHandle,
       options
     );
+    const DEFAULT_RETENTION_MS = 864e5;
     const metadata = {
       messageId: message.messageId,
       deliveryCount: message.deliveryCount,
       createdAt: message.createdAt,
-      expiresAt: message.expiresAt,
+      expiresAt: message.expiresAt ?? new Date(message.createdAt.getTime() + DEFAULT_RETENTION_MS),
       topicName: this.topicName,
       consumerGroup: this.consumerGroupName,
       region: this.client.getRegion()
@@ -498,7 +501,9 @@ var Topic = class {
       invokeDevHandlers(
         this.topicName,
         result.messageId,
-        this.client.getRegion()
+        this.client.getRegion(),
+        options?.delaySeconds,
+        options?.retentionSeconds
       );
     }
     return { messageId: result.messageId };
@@ -704,12 +709,30 @@ async function handleCallback(handler, request, options) {
 }
 
 // src/dev.ts
+var PREFIX = pc.cyan("[queue]");
+var OK = pc.green("\u2713");
+var FAIL = pc.red("\u2717");
+var RETRY = pc.yellow("\u21BB");
 function isDevMode() {
   return process.env.NODE_ENV === "development";
 }
 var ROUTE_MAPPINGS_KEY = Symbol.for("@vercel/queue.devRouteMappings");
 function filePathToConsumerGroup(filePath) {
-  return filePath.replace(/_/g, "__").replace(/\//g, "_S").replace(/\./g, "_D");
+  let result = "";
+  for (const char of filePath) {
+    if (char === "_") {
+      result += "__";
+    } else if (char === "/") {
+      result += "_S";
+    } else if (char === ".") {
+      result += "_D";
+    } else if (/[A-Za-z0-9-]/.test(char)) {
+      result += char;
+    } else {
+      result += "_" + char.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0");
+    }
+  }
+  return result;
 }
 function getDevRouteMappings() {
   const g = globalThis;
@@ -734,21 +757,22 @@ function getDevRouteMappings() {
         if (!trigger.type?.startsWith("queue/") || !trigger.topic) continue;
         if (trigger.type !== "queue/v2beta") {
           console.warn(
-            `[Dev Mode] Unsupported trigger type "${trigger.type}" for topic "${trigger.topic}" in ${filePath}. Use "queue/v2beta" instead.`
+            `${PREFIX} Unsupported trigger type "${trigger.type}" for topic "${trigger.topic}" in ${filePath}. Use "queue/v2beta" instead.`
           );
           continue;
         }
         mappings.push({
           filePath,
           topic: trigger.topic,
-          consumer: filePathToConsumerGroup(filePath)
+          consumer: filePathToConsumerGroup(filePath),
+          retryAfterSeconds: trigger.retryAfterSeconds
         });
       }
     }
     g[ROUTE_MAPPINGS_KEY] = mappings.length > 0 ? mappings : null;
     return g[ROUTE_MAPPINGS_KEY];
   } catch (error) {
-    console.warn("[Dev Mode] Failed to read vercel.json:", error);
+    console.warn(`${PREFIX} Failed to read vercel.json:`, error);
     g[ROUTE_MAPPINGS_KEY] = null;
     return null;
   }
@@ -763,6 +787,20 @@ function findMatchingRoutes(topicName) {
     return mapping.topic === topicName;
   });
 }
+function findRetryAfterSeconds(topicName, consumerGroup) {
+  const routes = findMatchingRoutes(topicName);
+  const route = routes.find((r) => r.consumer === consumerGroup);
+  return route?.retryAfterSeconds;
+}
+function stripSrcPrefix(filePath) {
+  if (/^src\/(app|pages|server)\//.test(filePath)) {
+    return filePath.slice(4);
+  }
+  return null;
+}
+function matchesFunctionsPattern(sourceFile, pattern) {
+  return sourceFile === pattern || minimatch(sourceFile, pattern);
+}
 function findMappingsForFile(absolutePath) {
   const mappings = getDevRouteMappings();
   if (!mappings) return [];
@@ -774,7 +812,10 @@ function findMappingsForFile(absolutePath) {
     return [];
   }
   const normalized = relative2.replace(/\\/g, "/");
-  return mappings.filter((m) => m.filePath === normalized);
+  const stripped = stripSrcPrefix(normalized);
+  return mappings.filter(
+    (m) => matchesFunctionsPattern(normalized, m.filePath) || stripped !== null && matchesFunctionsPattern(stripped, m.filePath)
+  );
 }
 function parseFrameFilePath(line) {
   let match = line.match(/\((.+?):\d+:\d+\)/);
@@ -868,7 +909,7 @@ function registerDevHandler(handler, client, options, _testCallerPath) {
   const callerPath = _testCallerPath ?? extractCallerFilePath();
   if (!callerPath) {
     console.warn(
-      "[Dev Mode] Could not determine caller file path for handler registration."
+      `${PREFIX} Could not determine caller file path for handler registration.`
     );
     return;
   }
@@ -880,6 +921,9 @@ function registerDevHandler(handler, client, options, _testCallerPath) {
   );
   if (!registered) {
     const allMappings = getDevRouteMappings();
+    if (allMappings && allMappings.length > 0) {
+      return;
+    }
     const cwd = process.cwd();
     let relative2;
     try {
@@ -887,19 +931,8 @@ function registerDevHandler(handler, client, options, _testCallerPath) {
     } catch {
       relative2 = callerPath;
     }
-    if (allMappings && allMappings.length > 0) {
-      const configuredFiles = Array.from(
-        new Set(allMappings.map((m) => m.filePath))
-      );
-      console.warn(
-        `[Dev Mode] handleCallback() in ${relative2} does not match any queue route in vercel.json. This handler won't receive messages.
-Configured queue routes: [${configuredFiles.join(", ")}]
-If this path is a bundled chunk, keep handleCallback()/handleNodeCallback() at module scope and let dev-mode route priming load the mapped file.`
-      );
-      return;
-    }
     console.warn(
-      `[Dev Mode] handleCallback() in ${relative2} has no matching experimentalTriggers in vercel.json. This handler won't receive messages.
+      `${PREFIX} handleCallback() in ${relative2} has no matching experimentalTriggers in vercel.json. This handler won't receive messages.
 
 Add a trigger to vercel.json:
   "${relative2}": {
@@ -1023,7 +1056,7 @@ async function invokeWithRetry(handler, request, options) {
   }
 }
 function filePathToUrlPath(filePath) {
-  let urlPath = filePath.replace(/^app\//, "/").replace(/^pages\//, "/").replace(/^server\//, "/").replace(/^src\/routes\//, "/").replace(/\/route\.(ts|mts|js|mjs|tsx|jsx)$/, "").replace(/\/\+server\.(ts|mts|js|mjs|tsx|jsx)$/, "").replace(/\.(ts|mts|js|mjs|tsx|jsx)$/, "");
+  let urlPath = filePath.replace(/^src\/app\//, "/").replace(/^src\/pages\//, "/").replace(/^src\/server\//, "/").replace(/^src\/routes\//, "/").replace(/^app\//, "/").replace(/^pages\//, "/").replace(/^server\//, "/").replace(/\/route\.(ts|mts|js|mjs|tsx|jsx)$/, "").replace(/\/\+server\.(ts|mts|js|mjs|tsx|jsx)$/, "").replace(/\.(ts|mts|js|mjs|tsx|jsx)$/, "");
   if (!urlPath.startsWith("/")) {
     urlPath = "/" + urlPath;
   }
@@ -1116,7 +1149,7 @@ function buildNoHandlerWarning(topicName, routes, diagnostics) {
 Import failures: ` + diagnostics.importFailures.slice(0, 2).map((f) => `${f.filePath} (${f.reason})`).join("; ") : "";
   const primeSummary = diagnostics.primeFailures.length > 0 ? `
 Prime failures: ` + diagnostics.primeFailures.slice(0, 3).map((f) => `${f.url} (${f.reason})`).join("; ") : "";
-  return `[Dev Mode] No registered handler for topic "${topicName}". vercel.json maps this topic to [${files.join(", ")}] but auto-loading failed.
+  return `${PREFIX} No registered handler for topic "${topicName}". vercel.json maps this topic to [${files.join(", ")}] but auto-loading failed.
 ${portSummary}${importSummary}${primeSummary}
 Ensure your dev server is running, set PORT if needed, and confirm mapped route files call handleCallback()/handleNodeCallback() at module scope.
 ` + (suggestedUrls.length > 0 ? `Try opening: ${suggestedUrls.join(" or ")}` : "Set PORT (or NEXT_PORT/NUXT_PORT/VITE_PORT) and try sending again.");
@@ -1126,18 +1159,106 @@ function isHandlerRegistered(topicName, consumerGroup) {
     (h) => h.consumerGroup === consumerGroup
   );
 }
-function invokeDevHandlers(topicName, messageId, region, delaySeconds) {
+var DEV_REDELIVERY_MAX_DELAY_S = 10;
+var DEV_REDELIVERY_DEFAULT_DELAY_S = 2;
+var DEV_REDELIVERY_MAX_ATTEMPTS = 10;
+var DEFAULT_RETENTION_S = 86400;
+function scheduleDevRedelivery(ctx, delayS) {
+  const cappedDelay = Math.min(Math.max(delayS, 0), DEV_REDELIVERY_MAX_DELAY_S);
+  console.log(
+    `${PREFIX} ${RETRY} Scheduling re-delivery in ${cappedDelay}s: topic="${ctx.topicName}" consumer="${ctx.consumerGroup}" messageId="${ctx.messageId}"`
+  );
+  setTimeout(async () => {
+    const nextDeliveryCount = ctx.deliveryCount + 1;
+    const expiresAt = new Date(
+      ctx.createdAt.getTime() + ctx.retentionSeconds * 1e3
+    );
+    if (Date.now() >= expiresAt.getTime()) {
+      console.log(
+        `${PREFIX} Message expired, stopping retries: topic="${ctx.topicName}" messageId="${ctx.messageId}"`
+      );
+      return;
+    }
+    if (nextDeliveryCount > DEV_REDELIVERY_MAX_ATTEMPTS) {
+      console.log(
+        `${PREFIX} Max re-deliveries (${DEV_REDELIVERY_MAX_ATTEMPTS}) reached: topic="${ctx.topicName}" messageId="${ctx.messageId}"`
+      );
+      return;
+    }
+    const metadata = {
+      messageId: ctx.messageId,
+      deliveryCount: nextDeliveryCount,
+      createdAt: ctx.createdAt,
+      expiresAt,
+      topicName: ctx.topicName,
+      consumerGroup: ctx.consumerGroup,
+      region: ctx.region
+    };
+    console.log(
+      `${PREFIX} Re-delivering: topic="${ctx.topicName}" consumer="${ctx.consumerGroup}" messageId="${ctx.messageId}" deliveryCount=${nextDeliveryCount}`
+    );
+    let succeeded = true;
+    let nextRetryAfterS = null;
+    let nextAcknowledged = false;
+    try {
+      await ctx.handler(ctx.payload, metadata);
+    } catch (error) {
+      succeeded = false;
+      if (ctx.retry) {
+        let directive;
+        try {
+          directive = ctx.retry(error, metadata);
+        } catch (retryErr) {
+          console.warn(`${PREFIX} retry handler threw:`, retryErr);
+        }
+        if (directive && "afterSeconds" in directive) {
+          nextRetryAfterS = directive.afterSeconds;
+        } else if (directive && "acknowledge" in directive) {
+          nextAcknowledged = true;
+        }
+      }
+      if (!nextAcknowledged) {
+        console.error(
+          `${PREFIX} ${FAIL} Handler error on re-delivery: topic="${ctx.topicName}" messageId="${ctx.messageId}"`,
+          error
+        );
+      }
+    }
+    if (succeeded) {
+      console.log(
+        `${PREFIX} ${OK} Message processed on re-delivery: topic="${ctx.topicName}" consumer="${ctx.consumerGroup}" messageId="${ctx.messageId}"`
+      );
+    } else if (nextAcknowledged) {
+      console.log(
+        `${PREFIX} ${OK} Message acknowledged (will not retry): topic="${ctx.topicName}" consumer="${ctx.consumerGroup}" messageId="${ctx.messageId}"`
+      );
+    } else {
+      const nextDelay = nextRetryAfterS ?? ctx.defaultRetryDelayS;
+      scheduleDevRedelivery(
+        { ...ctx, deliveryCount: nextDeliveryCount },
+        nextDelay
+      );
+    }
+  }, cappedDelay * 1e3);
+}
+function invokeDevHandlers(topicName, messageId, region, delaySeconds, retentionSeconds) {
   if (delaySeconds && delaySeconds > 0) {
     console.log(
-      `[Dev Mode] Message sent with delay: topic="${topicName}" messageId="${messageId}" delay=${delaySeconds}s`
+      `${PREFIX} Message sent with delay: topic="${topicName}" messageId="${messageId}" delay=${delaySeconds}s`
     );
     setTimeout(() => {
-      invokeDevHandlers(topicName, messageId, region);
+      invokeDevHandlers(
+        topicName,
+        messageId,
+        region,
+        void 0,
+        retentionSeconds
+      );
     }, delaySeconds * 1e3);
     return;
   }
   console.log(
-    `[Dev Mode] Message sent: topic="${topicName}" messageId="${messageId}"`
+    `${PREFIX} Message sent: topic="${topicName}" messageId="${messageId}"`
   );
   (async () => {
     let handlers = lookupHandlers(topicName);
@@ -1164,7 +1285,7 @@ function invokeDevHandlers(topicName, messageId, region, delaySeconds) {
         );
       } else {
         console.warn(
-          `[Dev Mode] No registered handler for topic "${topicName}".
+          `${PREFIX} No registered handler for topic "${topicName}".
 Ensure vercel.json has a matching experimentalTriggers entry and the route file calls handleCallback().`
         );
       }
@@ -1172,9 +1293,36 @@ Ensure vercel.json has a matching experimentalTriggers entry and the route file
     }
     const consumerGroups = handlers.map((h) => h.consumerGroup);
     console.log(
-      `[Dev Mode] Invoking handlers for topic="${topicName}" messageId="${messageId}" \u2192 consumers: [${consumerGroups.join(", ")}]`
+      `${PREFIX} Invoking handlers for topic="${topicName}" messageId="${messageId}" \u2192 consumers: [${consumerGroups.join(", ")}]`
     );
+    const effectiveRetention = retentionSeconds ?? DEFAULT_RETENTION_S;
     for (const entry of handlers) {
+      let capturedPayload;
+      let capturedCreatedAt = /* @__PURE__ */ new Date();
+      let capturedDeliveryCount = 1;
+      let handlerSucceeded = true;
+      let retryAfterS = null;
+      let retryAcknowledged = false;
+      const wrappedHandler = async (message, metadata) => {
+        capturedPayload = message;
+        capturedCreatedAt = metadata.createdAt;
+        capturedDeliveryCount = metadata.deliveryCount;
+        try {
+          await entry.handler(message, metadata);
+        } catch (error) {
+          handlerSucceeded = false;
+          throw error;
+        }
+      };
+      const wrappedRetry = entry.options?.retry ? (error, metadata) => {
+        const directive = entry.options.retry(error, metadata);
+        if (directive && "afterSeconds" in directive) {
+          retryAfterS = directive.afterSeconds;
+        } else if (directive && "acknowledge" in directive) {
+          retryAcknowledged = true;
+        }
+        return directive;
+      } : void 0;
       const request = {
         queueName: topicName,
         consumerGroup: entry.consumerGroup,
@@ -1184,18 +1332,47 @@ Ensure vercel.json has a matching experimentalTriggers entry and the route file
       const callbackOptions = {
         client: entry.client,
         visibilityTimeoutSeconds: entry.options?.visibilityTimeoutSeconds,
-        retry: entry.options?.retry
+        retry: wrappedRetry
       };
+      const consumerDefaultDelay = Math.min(
+        findRetryAfterSeconds(topicName, entry.consumerGroup) ?? DEV_REDELIVERY_DEFAULT_DELAY_S,
+        DEV_REDELIVERY_MAX_DELAY_S
+      );
+      const buildRedeliveryCtx = () => ({
+        handler: entry.handler,
+        retry: entry.options?.retry,
+        payload: capturedPayload,
+        topicName,
+        consumerGroup: entry.consumerGroup,
+        messageId,
+        region,
+        createdAt: capturedCreatedAt,
+        retentionSeconds: effectiveRetention,
+        deliveryCount: capturedDeliveryCount,
+        defaultRetryDelayS: consumerDefaultDelay
+      });
       try {
-        await invokeWithRetry(entry.handler, request, callbackOptions);
-        console.log(
-          `[Dev Mode] \u2713 Message processed: topic="${topicName}" consumer="${entry.consumerGroup}" messageId="${messageId}"`
-        );
+        await invokeWithRetry(wrappedHandler, request, callbackOptions);
+        if (handlerSucceeded) {
+          console.log(
+            `${PREFIX} ${OK} Message processed: topic="${topicName}" consumer="${entry.consumerGroup}" messageId="${messageId}"`
+          );
+        } else if (retryAcknowledged) {
+          console.log(
+            `${PREFIX} ${OK} Message acknowledged (will not retry): topic="${topicName}" consumer="${entry.consumerGroup}" messageId="${messageId}"`
+          );
+        } else if (retryAfterS !== null) {
+          const devDelay = Math.min(retryAfterS, DEV_REDELIVERY_MAX_DELAY_S);
+          scheduleDevRedelivery(buildRedeliveryCtx(), devDelay);
+        }
       } catch (error) {
         console.error(
-          `[Dev Mode] \u2717 Handler failed: topic="${topicName}" consumer="${entry.consumerGroup}" messageId="${messageId}"`,
+          `${PREFIX} ${FAIL} Handler failed: topic="${topicName}" consumer="${entry.consumerGroup}" messageId="${messageId}"`,
           error
         );
+        if (!handlerSucceeded) {
+          scheduleDevRedelivery(buildRedeliveryCtx(), consumerDefaultDelay);
+        }
       }
     }
   })();
@@ -1207,6 +1384,10 @@ function clearDevState() {
 }
 if (process.env.NODE_ENV === "test" || process.env.VITEST) {
   globalThis.__clearDevState = clearDevState;
+  globalThis.__filePathToConsumerGroup = filePathToConsumerGroup;
+  globalThis.__filePathToUrlPath = filePathToUrlPath;
+  globalThis.__matchesFunctionsPattern = matchesFunctionsPattern;
+  globalThis.__stripSrcPrefix = stripSrcPrefix;
 }
 
 // src/oidc.ts
@@ -1250,6 +1431,7 @@ function parseQueueHeaders(headers) {
   const timestamp = headers.get("Vqs-Timestamp");
   const contentType = headers.get("Content-Type") || "application/octet-stream";
   const receiptHandle = headers.get("Vqs-Receipt-Handle");
+  const expiresAtStr = headers.get("Vqs-Expires-At");
   if (!messageId || !timestamp || !receiptHandle) {
     return null;
   }
@@ -1261,6 +1443,7 @@ function parseQueueHeaders(headers) {
     messageId,
     deliveryCount,
     createdAt: new Date(timestamp),
+    expiresAt: expiresAtStr ? new Date(expiresAtStr) : void 0,
     contentType,
     receiptHandle
   };
@@ -1344,13 +1527,25 @@ var ApiClient = class _ApiClient {
     if (this.providedToken) {
       return this.providedToken;
     }
-    const token = await getVercelOidcToken();
-    if (!token) {
+    try {
+      return await getVercelOidcToken();
+    } catch (err) {
+      const cause = err instanceof Error ? err.message : String(err);
       throw new Error(
-        "Failed to get OIDC token from Vercel Functions. Make sure you are running in a Vercel Function environment, or provide a token explicitly.\n\nTo set up your environment:\n1. Link your project: 'vercel link'\n2. Pull environment variables: 'vercel env pull'\n3. Run with environment: 'dotenv -e .env.local -- your-command'"
+        isDevMode() ? `Failed to get OIDC token for local development.
+
+To fix this, pull your environment variables with Vercel CLI:
+  \`vercel env pull\`
+
+Cause: ${cause}` : `Failed to get OIDC token. This usually means the function is running outside of a Vercel Function environment.
+
+To fix this, either:
+  - Deploy to Vercel (OIDC tokens are provisioned automatically)
+  - Provide a token explicitly: \`new QueueClient({ token: '...' })\`
+
+Cause: ${cause}`
       );
     }
-    return token;
   }
   buildUrl(queueName, ...pathSegments) {
     const encodedQueue = encodeURIComponent(queueName);
@@ -1381,7 +1576,7 @@ var ApiClient = class _ApiClient {
       }
       console.debug("[VQS Debug] Request:", JSON.stringify(logData, null, 2));
     }
-    init.headers.set("User-Agent", `@vercel/queue/${"0.1.1"}`);
+    init.headers.set("User-Agent", `@vercel/queue/${"0.1.3"}`);
     init.headers.set("Vqs-Client-Ts", (/* @__PURE__ */ new Date()).toISOString());
     const response = await fetch(url, init);
     if (isDebugEnabled()) {
@@ -1756,9 +1951,11 @@ function resolveRegion(region) {
   if (region) return region;
   const fromEnv = process.env.VERCEL_REGION;
   if (fromEnv) return fromEnv;
-  console.warn(
-    `[QueueClient] Region not detected \u2014 defaulting to "${DEFAULT_REGION}". On Vercel this is set automatically via VERCEL_REGION. To silence this warning, pass region explicitly: new QueueClient({ region: "iad1" })`
-  );
+  if (!isDevMode()) {
+    console.warn(
+      `[QueueClient] Region not detected \u2014 defaulting to "${DEFAULT_REGION}". On Vercel this is set automatically via VERCEL_REGION. To silence this warning, pass region explicitly: new QueueClient({ region: "iad1" })`
+    );
+  }
   return DEFAULT_REGION;
 }
 var QueueClient = class {
@@ -1796,7 +1993,8 @@ var QueueClient = class {
         topicName,
         result.messageId,
         api.getRegion(),
-        options?.delaySeconds
+        options?.delaySeconds,
+        options?.retentionSeconds
       );
     }
     return { messageId: result.messageId };