@vercel/queue 0.1.0 → 0.1.2

package/dist/index.mjs

@@ -76,7 +76,9 @@ import { parseMultipartStream } from "mixpart";
 
 // src/dev.ts
 import * as fs from "fs";
+import * as net from "net";
 import * as path from "path";
+import { minimatch } from "minimatch";
 
 // src/types.ts
 var MessageNotFoundError = class extends Error {
@@ -261,8 +263,8 @@ var ConsumerGroup = class {
         firstDelayMs = 0;
       }
     }
-    const lifecyclePromise = new Promise((resolve) => {
-      resolveLifecycle = resolve;
+    const lifecyclePromise = new Promise((resolve2) => {
+      resolveLifecycle = resolve2;
     });
     const safeResolve = () => {
       if (!isResolved) {
@@ -339,11 +341,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()
@@ -494,10 +497,12 @@ var Topic = class {
       headers: options?.headers
     });
     if (result.messageId && isDevMode()) {
-      triggerDevCallbacks(
+      invokeDevHandlers(
         this.topicName,
         result.messageId,
-        this.client.getRegion()
+        this.client.getRegion(),
+        options?.delaySeconds,
+        options?.retentionSeconds
       );
     }
     return { messageId: result.messageId };
@@ -703,16 +708,26 @@ async function handleCallback(handler, request, options) {
 }
 
 // src/dev.ts
-var ROUTE_MAPPINGS_KEY = Symbol.for("@vercel/queue.devRouteMappings");
-function filePathToUrlPath(filePath) {
-  let urlPath = filePath.replace(/^app\//, "/").replace(/^pages\//, "/").replace(/\/route\.(ts|mts|js|mjs|tsx|jsx)$/, "").replace(/\.(ts|mts|js|mjs|tsx|jsx)$/, "");
-  if (!urlPath.startsWith("/")) {
-    urlPath = "/" + urlPath;
-  }
-  return urlPath;
+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,13 +749,19 @@ function getDevRouteMappings() {
     for (const [filePath, config] of Object.entries(vercelJson.functions)) {
       if (!config.experimentalTriggers) continue;
       for (const trigger of config.experimentalTriggers) {
-        if (trigger.type?.startsWith("queue/") && trigger.topic) {
-          mappings.push({
-            urlPath: filePathToUrlPath(filePath),
-            topic: trigger.topic,
-            consumer: filePathToConsumerGroup(filePath)
-          });
+        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.`
+          );
+          continue;
         }
+        mappings.push({
+          filePath,
+          topic: trigger.topic,
+          consumer: filePathToConsumerGroup(filePath),
+          retryAfterSeconds: trigger.retryAfterSeconds
+        });
       }
     }
     g[ROUTE_MAPPINGS_KEY] = mappings.length > 0 ? mappings : null;
@@ -753,9 +774,7 @@ function getDevRouteMappings() {
 }
 function findMatchingRoutes(topicName) {
   const mappings = getDevRouteMappings();
-  if (!mappings) {
-    return [];
-  }
+  if (!mappings) return [];
   return mappings.filter((mapping) => {
     if (mapping.topic.includes("*")) {
       return matchesWildcardPattern(topicName, mapping.topic);
@@ -763,149 +782,607 @@ function findMatchingRoutes(topicName) {
     return mapping.topic === topicName;
   });
 }
-function isDevMode() {
-  return process.env.NODE_ENV === "development";
+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 [];
+  const cwd = process.cwd();
+  let relative2;
+  try {
+    relative2 = path.relative(cwd, absolutePath);
+  } catch {
+    return [];
+  }
+  const normalized = relative2.replace(/\\/g, "/");
+  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+\)/);
+  if (!match) match = line.match(/at\s+(.+?):\d+:\d+/);
+  if (!match) return null;
+  let filePath = match[1].trim();
+  if (filePath === "native" || filePath.startsWith("node:") || filePath.startsWith("internal")) {
+    return null;
+  }
+  if (filePath.startsWith("file://")) {
+    try {
+      filePath = new URL(filePath).pathname;
+    } catch {
+      return null;
+    }
+  }
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(filePath)) {
+    return null;
+  }
+  if (filePath.startsWith("./")) {
+    filePath = filePath.slice(2);
+  }
+  return filePath;
+}
+var _sdkPackageDir;
+function getSdkPackageDir() {
+  if (_sdkPackageDir) return _sdkPackageDir;
+  try {
+    const thisDir = typeof __dirname !== "undefined" ? __dirname : path.dirname(new URL(import.meta.url).pathname);
+    _sdkPackageDir = path.resolve(thisDir, "..");
+  } catch {
+    _sdkPackageDir = "";
+  }
+  return _sdkPackageDir;
+}
+function extractCallerFilePath() {
+  const stack = new Error().stack;
+  if (!stack) return null;
+  const lines = stack.split("\n").slice(1);
+  const pkgDir = getSdkPackageDir();
+  for (const line of lines) {
+    const fp = parseFrameFilePath(line);
+    if (!fp) continue;
+    const absolute = path.isAbsolute(fp) ? fp : path.resolve(process.cwd(), fp);
+    let realFp;
+    try {
+      realFp = fs.realpathSync(absolute);
+    } catch {
+      realFp = absolute;
+    }
+    if (pkgDir && realFp.startsWith(pkgDir)) continue;
+    return realFp;
+  }
+  return null;
+}
+var HANDLER_REGISTRY_KEY = Symbol.for("@vercel/queue.devHandlerRegistry");
+function getHandlerRegistry() {
+  const g = globalThis;
+  if (!g[HANDLER_REGISTRY_KEY]) {
+    g[HANDLER_REGISTRY_KEY] = /* @__PURE__ */ new Map();
+  }
+  return g[HANDLER_REGISTRY_KEY];
+}
+function registerHandlerForFile(filePath, handler, client, options) {
+  const absolutePath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+  const fileMappings = findMappingsForFile(absolutePath);
+  if (fileMappings.length === 0) return false;
+  const registry = getHandlerRegistry();
+  for (const mapping of fileMappings) {
+    const key = mapping.topic;
+    const existing = registry.get(key) ?? [];
+    const nextEntry = {
+      consumerGroup: mapping.consumer,
+      handler,
+      client,
+      options
+    };
+    const existingIndex = existing.findIndex(
+      (e) => e.consumerGroup === mapping.consumer
+    );
+    if (existingIndex >= 0) {
+      existing[existingIndex] = nextEntry;
+    } else {
+      existing.push(nextEntry);
+    }
+    registry.set(key, existing);
+  }
+  return true;
+}
+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."
+    );
+    return;
+  }
+  const registered = registerHandlerForFile(
+    callerPath,
+    handler,
+    client,
+    options
+  );
+  if (!registered) {
+    const allMappings = getDevRouteMappings();
+    if (allMappings && allMappings.length > 0) {
+      return;
+    }
+    const cwd = process.cwd();
+    let relative2;
+    try {
+      relative2 = path.relative(cwd, callerPath).replace(/\\/g, "/");
+    } catch {
+      relative2 = callerPath;
+    }
+    console.warn(
+      `[Dev Mode] handleCallback() in ${relative2} has no matching experimentalTriggers in vercel.json. This handler won't receive messages.
+
+Add a trigger to vercel.json:
+  "${relative2}": {
+    "experimentalTriggers": [{ "type": "queue/v2beta", "topic": "your-topic" }]
+  }`
+    );
+  }
+}
+function lookupHandlers(topicName) {
+  const registry = getHandlerRegistry();
+  const result = [];
+  for (const [pattern, handlers] of registry) {
+    const matches = pattern.includes("*") ? matchesWildcardPattern(topicName, pattern) : pattern === topicName;
+    if (matches) {
+      result.push(...handlers);
+    }
+  }
+  return result;
+}
+var DEV_RETRY_INITIAL_DELAY_MS = 50;
+var DEV_RETRY_MAX_WAIT_MS = 5e3;
+var DEV_RETRY_BACKOFF = 2;
+var PORT_CHECK_TIMEOUT_MS = 250;
+var PRIME_PORT_ENV_KEYS = [
+  "PORT",
+  "NEXT_PORT",
+  "NEXTJS_PORT",
+  "NUXT_PORT",
+  "NITRO_PORT",
+  "SVELTEKIT_PORT",
+  "VITE_PORT",
+  "DEV_PORT",
+  "npm_config_port"
+];
+var PRIME_URL_ENV_KEYS = [
+  "__NEXT_PRIVATE_ORIGIN",
+  "NUXT_PUBLIC_SITE_URL",
+  "URL"
+];
+function formatErrorReason(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+function isMessageNotFoundError(error) {
+  if (error instanceof MessageNotFoundError) {
+    return true;
+  }
+  if (error instanceof Error && error.name === "MessageNotFoundError") {
+    return true;
+  }
+  return false;
+}
+function parsePort(value) {
+  if (!value) return null;
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed < 1 || parsed > 65535) return null;
+  return parsed;
+}
+function parsePortFromUrl(value) {
+  if (!value) return null;
+  try {
+    const parsed = new URL(value).port;
+    return parsePort(parsed);
+  } catch {
+    return null;
+  }
+}
+function collectPrimePorts() {
+  const result = [];
+  const seen = /* @__PURE__ */ new Set();
+  const add = (port) => {
+    if (port && !seen.has(port)) {
+      seen.add(port);
+      result.push(port);
+    }
+  };
+  for (const key of PRIME_PORT_ENV_KEYS) {
+    add(parsePort(process.env[key]));
+  }
+  for (const key of PRIME_URL_ENV_KEYS) {
+    add(parsePortFromUrl(process.env[key]));
+  }
+  return result;
+}
+function isPortListening(port) {
+  return new Promise((resolve2) => {
+    const socket = net.connect({ host: "localhost", port });
+    let settled = false;
+    const finish = (listening) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve2(listening);
+    };
+    socket.once("connect", () => finish(true));
+    socket.once("error", () => finish(false));
+    socket.setTimeout(PORT_CHECK_TIMEOUT_MS, () => finish(false));
+  });
 }
-var DEV_VISIBILITY_POLL_INTERVAL = 50;
-var DEV_VISIBILITY_MAX_WAIT = 5e3;
-var DEV_VISIBILITY_BACKOFF_MULTIPLIER = 2;
-async function waitForMessageVisibility(topicName, consumerGroup, messageId, region) {
-  const client = new ApiClient({ region });
+async function invokeWithRetry(handler, request, options) {
   let elapsed = 0;
-  let interval = DEV_VISIBILITY_POLL_INTERVAL;
-  while (elapsed < DEV_VISIBILITY_MAX_WAIT) {
+  let delay = DEV_RETRY_INITIAL_DELAY_MS;
+  while (true) {
     try {
-      await client.receiveMessageById({
-        queueName: topicName,
-        consumerGroup,
-        messageId,
-        visibilityTimeoutSeconds: 0
-      });
-      return true;
+      await handleCallback(handler, request, options);
+      return;
     } catch (error) {
-      if (error instanceof MessageNotFoundError) {
-        await new Promise((resolve) => setTimeout(resolve, interval));
-        elapsed += interval;
-        interval = Math.min(
-          interval * DEV_VISIBILITY_BACKOFF_MULTIPLIER,
-          DEV_VISIBILITY_MAX_WAIT - elapsed
+      if (isMessageNotFoundError(error) && elapsed < DEV_RETRY_MAX_WAIT_MS) {
+        await new Promise((r) => setTimeout(r, delay));
+        elapsed += delay;
+        delay = Math.min(
+          delay * DEV_RETRY_BACKOFF,
+          DEV_RETRY_MAX_WAIT_MS - elapsed
         );
         continue;
       }
-      if (error instanceof MessageAlreadyProcessedError) {
-        console.log(
-          `[Dev Mode] Message already processed: topic="${topicName}" messageId="${messageId}"`
-        );
-        return false;
+      throw error;
+    }
+  }
+}
+function filePathToUrlPath(filePath) {
+  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;
+  }
+  return urlPath;
+}
+async function ensureHandlersLoaded(topicName, options = {}) {
+  const diagnostics = {
+    triedPorts: collectPrimePorts(),
+    listeningPorts: [],
+    unavailablePorts: [],
+    importFailures: [],
+    primeFailures: []
+  };
+  const matchingRoutes = findMatchingRoutes(topicName);
+  if (matchingRoutes.length === 0) return diagnostics;
+  const shouldRefreshRegistered = options.refreshRegistered === true;
+  for (const port of diagnostics.triedPorts) {
+    if (await isPortListening(port)) {
+      diagnostics.listeningPorts.push(port);
+    } else {
+      diagnostics.unavailablePorts.push(port);
+    }
+  }
+  for (const route of matchingRoutes) {
+    const alreadyRegistered = isHandlerRegistered(topicName, route.consumer);
+    if (alreadyRegistered && !shouldRefreshRegistered) {
+      continue;
+    }
+    if (!alreadyRegistered) {
+      const absolutePath = path.resolve(process.cwd(), route.filePath);
+      try {
+        await import(absolutePath);
+      } catch (error) {
+        diagnostics.importFailures.push({
+          filePath: route.filePath,
+          reason: formatErrorReason(error)
+        });
+      }
+      if (isHandlerRegistered(topicName, route.consumer)) continue;
+    }
+    for (const port of diagnostics.listeningPorts) {
+      const url = `http://localhost:${port}${filePathToUrlPath(route.filePath)}`;
+      try {
+        const response = await fetch(url, {
+          method: "POST",
+          headers: {
+            "x-vercel-queue-prime": "1",
+            "x-vercel-queue-prime-file": route.filePath
+          }
+        });
+        try {
+          await response.text();
+        } catch {
+        }
+        if (isHandlerRegistered(topicName, route.consumer)) {
+          break;
+        }
+        diagnostics.primeFailures.push({
+          filePath: route.filePath,
+          url,
+          reason: `HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ""}`.trim()
+        });
+      } catch (error) {
+        diagnostics.primeFailures.push({
+          filePath: route.filePath,
+          url,
+          reason: formatErrorReason(error)
+        });
       }
-      console.error(
-        `[Dev Mode] Error polling for message visibility: topic="${topicName}" messageId="${messageId}"`,
-        error
-      );
-      return false;
     }
   }
-  console.warn(
-    `[Dev Mode] Message visibility timeout after ${DEV_VISIBILITY_MAX_WAIT}ms: topic="${topicName}" messageId="${messageId}"`
+  return diagnostics;
+}
+function buildNoHandlerWarning(topicName, routes, diagnostics) {
+  const files = routes.map((r) => r.filePath);
+  const suggestedPort = diagnostics.listeningPorts[0] ?? diagnostics.triedPorts[0];
+  const suggestedUrls = suggestedPort ? routes.map(
+    (r) => `http://localhost:${suggestedPort}${filePathToUrlPath(r.filePath)}`
+  ) : [];
+  let portSummary;
+  if (diagnostics.triedPorts.length === 0) {
+    portSummary = "No local dev port detected from env. Set PORT (or NEXT_PORT/NUXT_PORT/VITE_PORT).";
+  } else if (diagnostics.listeningPorts.length === 0) {
+    portSummary = `Detected env ports: [${diagnostics.triedPorts.join(", ")}], but none are listening.`;
+  } else {
+    const unavailable = diagnostics.unavailablePorts.length > 0 ? ` Not listening: [${diagnostics.unavailablePorts.join(", ")}].` : "";
+    portSummary = `Detected env ports: [${diagnostics.triedPorts.join(", ")}]. Listening: [${diagnostics.listeningPorts.join(", ")}].` + unavailable;
+  }
+  const importSummary = diagnostics.importFailures.length > 0 ? `
+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.
+${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.");
+}
+function isHandlerRegistered(topicName, consumerGroup) {
+  return lookupHandlers(topicName).some(
+    (h) => h.consumerGroup === consumerGroup
   );
-  return false;
 }
-function triggerDevCallbacks(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(
+    `[Dev Mode] \u21BB 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(
+        `[Dev Mode] Message expired, stopping retries: topic="${ctx.topicName}" messageId="${ctx.messageId}"`
+      );
+      return;
+    }
+    if (nextDeliveryCount > DEV_REDELIVERY_MAX_ATTEMPTS) {
+      console.log(
+        `[Dev Mode] 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(
+      `[Dev Mode] 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("[Dev Mode] retry handler threw:", retryErr);
+        }
+        if (directive && "afterSeconds" in directive) {
+          nextRetryAfterS = directive.afterSeconds;
+        } else if (directive && "acknowledge" in directive) {
+          nextAcknowledged = true;
+        }
+      }
+      if (!nextAcknowledged) {
+        console.error(
+          `[Dev Mode] \u2717 Handler error on re-delivery: topic="${ctx.topicName}" messageId="${ctx.messageId}"`,
+          error
+        );
+      }
+    }
+    if (succeeded) {
+      console.log(
+        `[Dev Mode] \u2713 Message processed on re-delivery: topic="${ctx.topicName}" consumer="${ctx.consumerGroup}" messageId="${ctx.messageId}"`
+      );
+    } else if (nextAcknowledged) {
+      console.log(
+        `[Dev Mode] \u2713 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`
     );
     setTimeout(() => {
-      triggerDevCallbacks(topicName, messageId, region);
+      invokeDevHandlers(
+        topicName,
+        messageId,
+        region,
+        void 0,
+        retentionSeconds
+      );
     }, delaySeconds * 1e3);
     return;
   }
   console.log(
     `[Dev Mode] Message sent: topic="${topicName}" messageId="${messageId}"`
   );
-  const matchingRoutes = findMatchingRoutes(topicName);
-  if (matchingRoutes.length === 0) {
-    console.log(
-      `[Dev Mode] No matching routes in vercel.json for topic "${topicName}"`
-    );
-    return;
-  }
-  const consumerGroups = matchingRoutes.map((r) => r.consumer);
-  console.log(
-    `[Dev Mode] Scheduling callbacks for topic="${topicName}" messageId="${messageId}" \u2192 consumers: [${consumerGroups.join(", ")}]`
-  );
   (async () => {
-    const firstRoute = matchingRoutes[0];
-    const isVisible = await waitForMessageVisibility(
-      topicName,
-      firstRoute.consumer,
-      messageId,
-      region
-    );
-    if (!isVisible) {
-      console.warn(
-        `[Dev Mode] Skipping callbacks - message not visible: topic="${topicName}" messageId="${messageId}"`
-      );
+    let handlers = lookupHandlers(topicName);
+    let diagnostics = null;
+    if (handlers.length > 0) {
+      await ensureHandlersLoaded(topicName, { refreshRegistered: true });
+      handlers = lookupHandlers(topicName);
+    } else {
+      diagnostics = await ensureHandlersLoaded(topicName);
+      handlers = lookupHandlers(topicName);
+    }
+    if (handlers.length === 0) {
+      const matchingRoutes = findMatchingRoutes(topicName);
+      if (matchingRoutes.length > 0) {
+        const safeDiagnostics = diagnostics ?? {
+          triedPorts: collectPrimePorts(),
+          listeningPorts: [],
+          unavailablePorts: [],
+          importFailures: [],
+          primeFailures: []
+        };
+        console.warn(
+          buildNoHandlerWarning(topicName, matchingRoutes, safeDiagnostics)
+        );
+      } else {
+        console.warn(
+          `[Dev Mode] No registered handler for topic "${topicName}".
+Ensure vercel.json has a matching experimentalTriggers entry and the route file calls handleCallback().`
+        );
+      }
       return;
     }
-    const port = process.env.PORT || 3e3;
-    const baseUrl = `http://localhost:${port}`;
-    for (const route of matchingRoutes) {
-      const url = `${baseUrl}${route.urlPath}`;
-      console.log(
-        `[Dev Mode] Invoking handler: topic="${topicName}" consumer="${route.consumer}" messageId="${messageId}" url="${url}"`
+    const consumerGroups = handlers.map((h) => h.consumerGroup);
+    console.log(
+      `[Dev Mode] 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,
+        messageId,
+        region
+      };
+      const callbackOptions = {
+        client: entry.client,
+        visibilityTimeoutSeconds: entry.options?.visibilityTimeoutSeconds,
+        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 {
-        const response = await fetch(url, {
-          method: "POST",
-          headers: {
-            "ce-type": CLOUD_EVENT_TYPE_V2BETA,
-            "ce-vqsqueuename": topicName,
-            "ce-vqsconsumergroup": route.consumer,
-            "ce-vqsmessageid": messageId,
-            "ce-vqsregion": region
-          }
-        });
-        if (response.ok) {
-          try {
-            const responseData = await response.json();
-            if (responseData.status === "success") {
-              console.log(
-                `[Dev Mode] \u2713 Message processed successfully: topic="${topicName}" consumer="${route.consumer}" messageId="${messageId}"`
-              );
-            }
-          } catch {
-            console.warn(
-              `[Dev Mode] Handler returned OK but response was not JSON: topic="${topicName}" consumer="${route.consumer}"`
-            );
-          }
-        } else {
-          try {
-            const errorData = await response.json();
-            console.error(
-              `[Dev Mode] \u2717 Handler failed: topic="${topicName}" consumer="${route.consumer}" messageId="${messageId}" error="${errorData.error || response.statusText}"`
-            );
-          } catch {
-            console.error(
-              `[Dev Mode] \u2717 Handler failed: topic="${topicName}" consumer="${route.consumer}" messageId="${messageId}" status=${response.status}`
-            );
-          }
+        await invokeWithRetry(wrappedHandler, request, callbackOptions);
+        if (handlerSucceeded) {
+          console.log(
+            `[Dev Mode] \u2713 Message processed: topic="${topicName}" consumer="${entry.consumerGroup}" messageId="${messageId}"`
+          );
+        } else if (retryAcknowledged) {
+          console.log(
+            `[Dev Mode] \u2713 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 HTTP request failed: topic="${topicName}" consumer="${route.consumer}" messageId="${messageId}" url="${url}"`,
+          `[Dev Mode] \u2717 Handler failed: topic="${topicName}" consumer="${entry.consumerGroup}" messageId="${messageId}"`,
           error
         );
+        if (!handlerSucceeded) {
+          scheduleDevRedelivery(buildRedeliveryCtx(), consumerDefaultDelay);
+        }
       }
     }
   })();
 }
-function clearDevRouteMappings() {
+function clearDevState() {
   const g = globalThis;
   delete g[ROUTE_MAPPINGS_KEY];
+  delete g[HANDLER_REGISTRY_KEY];
 }
 if (process.env.NODE_ENV === "test" || process.env.VITEST) {
-  globalThis.__clearDevRouteMappings = clearDevRouteMappings;
+  globalThis.__clearDevState = clearDevState;
+  globalThis.__filePathToConsumerGroup = filePathToConsumerGroup;
+  globalThis.__filePathToUrlPath = filePathToUrlPath;
+  globalThis.__matchesFunctionsPattern = matchesFunctionsPattern;
+  globalThis.__stripSrcPrefix = stripSrcPrefix;
 }
 
 // src/oidc.ts
@@ -949,6 +1426,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;
   }
@@ -960,6 +1438,7 @@ function parseQueueHeaders(headers) {
     messageId,
     deliveryCount,
     createdAt: new Date(timestamp),
+    expiresAt: expiresAtStr ? new Date(expiresAtStr) : void 0,
     contentType,
     receiptHandle
   };
@@ -1080,7 +1559,7 @@ var ApiClient = class _ApiClient {
       }
       console.debug("[VQS Debug] Request:", JSON.stringify(logData, null, 2));
     }
-    init.headers.set("User-Agent", `@vercel/queue/${"0.1.0"}`);
+    init.headers.set("User-Agent", `@vercel/queue/${"0.1.2"}`);
     init.headers.set("Vqs-Client-Ts", (/* @__PURE__ */ new Date()).toISOString());
     const response = await fetch(url, init);
     if (isDebugEnabled()) {
@@ -1416,12 +1895,36 @@ var ApiClient = class _ApiClient {
 
 // src/client.ts
 var apiClients = /* @__PURE__ */ new WeakMap();
+var API_CLIENT_KEY = Symbol.for("@vercel/queue.apiClient");
+function setApi(client, api) {
+  apiClients.set(client, api);
+  Object.defineProperty(client, API_CLIENT_KEY, {
+    value: api,
+    writable: false,
+    enumerable: false,
+    configurable: false
+  });
+}
 function getApi(client) {
   const api = apiClients.get(client);
-  if (!api) {
-    throw new Error("Client not initialized");
+  if (api) {
+    return api;
   }
-  return api;
+  const apiFromSymbol = client[API_CLIENT_KEY];
+  if (typeof apiFromSymbol === "object" && apiFromSymbol !== null) {
+    const resolvedApi = apiFromSymbol;
+    apiClients.set(client, resolvedApi);
+    return resolvedApi;
+  }
+  throw new Error(
+    "QueueClient not initialized. This may happen when multiple bundled copies of @vercel/queue are loaded in local dev."
+  );
+}
+function resolveCallbackRequest(input) {
+  if ("request" in input) {
+    return input.request;
+  }
+  return input;
 }
 function getApiClient(client) {
   return getApi(client);
@@ -1431,15 +1934,17 @@ 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 {
   constructor(options = {}) {
     const region = resolveRegion(options.region);
-    apiClients.set(this, new ApiClient({ ...options, region }));
+    setApi(this, new ApiClient({ ...options, region }));
   }
   /**
    * Send a message to a topic.
@@ -1467,11 +1972,12 @@ var QueueClient = class {
       headers: options?.headers
     });
     if (result.messageId && isDevMode()) {
-      triggerDevCallbacks(
+      invokeDevHandlers(
         topicName,
         result.messageId,
         api.getRegion(),
-        options?.delaySeconds
+        options?.delaySeconds,
+        options?.retentionSeconds
       );
     }
     return { messageId: result.messageId };
@@ -1493,10 +1999,26 @@ var QueueClient = class {
    * @param options.visibilityTimeoutSeconds - Message lock duration (default: 300, max: 3600)
    * @param options.retry - Called when the handler throws. Return `{ afterSeconds: N }` to
    *   reschedule the message for redelivery after N seconds.
-   * @returns A `(request: Request) => Promise<Response>` route handler
+   * @returns A route handler that accepts either `Request` or `{ request: Request }`
    */
   handleCallback = (handler, options) => {
-    return async (request) => {
+    if (isDevMode()) {
+      registerDevHandler(handler, this, options);
+    }
+    return async (requestOrEvent) => {
+      const request = resolveCallbackRequest(requestOrEvent);
+      if (isDevMode() && request.headers.get("x-vercel-queue-prime") === "1") {
+        const primeFile = request.headers.get("x-vercel-queue-prime-file");
+        if (primeFile) {
+          registerDevHandler(
+            handler,
+            this,
+            options,
+            primeFile
+          );
+        }
+        return Response.json({ status: "primed" });
+      }
       try {
         const parsed = await parseCallback(request);
         await handleCallback(handler, parsed, {
@@ -1538,11 +2060,29 @@ var QueueClient = class {
    * @returns A `(req, res) => Promise<void>` route handler
    */
   handleNodeCallback = (handler, options) => {
+    if (isDevMode()) {
+      registerDevHandler(handler, this, options);
+    }
     return async (req, res) => {
       if (req.method !== "POST") {
         res.status(200).end();
         return;
       }
+      const primeHeader = req.headers["x-vercel-queue-prime"];
+      if (isDevMode() && primeHeader === "1") {
+        const primeFileHeader = req.headers["x-vercel-queue-prime-file"];
+        const primeFile = Array.isArray(primeFileHeader) ? primeFileHeader[0] : primeFileHeader;
+        if (primeFile) {
+          registerDevHandler(
+            handler,
+            this,
+            options,
+            primeFile
+          );
+        }
+        res.status(200).json({ status: "primed" });
+        return;
+      }
       try {
         const parsed = parseRawCallback(req.body, req.headers);
         await handleCallback(handler, parsed, {
@@ -1564,7 +2104,7 @@ var QueueClient = class {
 };
 var PollingQueueClient = class {
   constructor(options) {
-    apiClients.set(this, new ApiClient(options));
+    setApi(this, new ApiClient(options));
   }
   /**
    * Send a message to a topic.
@@ -1663,6 +2203,25 @@ var PollingQueueClient = class {
     }
   };
 };
+
+// src/default-client.ts
+var _defaultClient;
+function getDefaultClient() {
+  if (!_defaultClient) {
+    _defaultClient = new QueueClient();
+  }
+  return _defaultClient;
+}
+function resolveClient(region) {
+  if (!region) return getDefaultClient();
+  return new QueueClient({ region });
+}
+async function send(topicName, payload, options) {
+  return resolveClient(options?.region).send(topicName, payload, options);
+}
+function handleCallback2(handler, options) {
+  return getDefaultClient().handleCallback(handler, options);
+}
 export {
   BadRequestError,
   BufferTransport,
@@ -1685,7 +2244,9 @@ export {
   QueueEmptyError,
   StreamTransport,
   UnauthorizedError,
+  handleCallback2 as handleCallback,
   parseCallback,
-  parseRawCallback
+  parseRawCallback,
+  send
 };
 //# sourceMappingURL=index.mjs.map