@khanglvm/llm-router 1.0.8 → 1.0.9

package/src/runtime/handler/provider-call.js

@@ -15,6 +15,7 @@ import { applyCachingMapping, mergeCachingHeaders } from "./cache-mapping.js";
 import { applyReasoningEffortMapping } from "./reasoning-effort.js";
 import { resolveUpstreamTimeoutMs } from "./request.js";
 import { parseJsonSafely } from "./utils.js";
+import { buildTimeoutSignal } from "../../shared/timeout-signal.js";
 
 async function toProviderError(response) {
   const raw = await response.text();
@@ -136,15 +137,18 @@ export async function makeProviderCall({
   }
 
   let response;
+  let cleanupTimeout = () => {};
   try {
     const timeoutMs = resolveUpstreamTimeoutMs(env);
+    const timeoutControl = buildTimeoutSignal(timeoutMs);
+    cleanupTimeout = timeoutControl.cleanup;
     const init = {
       method: "POST",
       headers,
       body: JSON.stringify(providerBody)
     };
-    if (typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function") {
-      init.signal = AbortSignal.timeout(timeoutMs);
+    if (timeoutControl.signal) {
+      init.signal = timeoutControl.signal;
     }
 
     response = await fetch(providerUrl, {
@@ -164,6 +168,8 @@ export async function makeProviderCall({
         }
       }, 503)
     };
+  } finally {
+    cleanupTimeout();
   }
 
   if (!response.ok) {

package/src/runtime/handler/route-debug.js

@@ -0,0 +1,104 @@
+import { toBoolean } from "./utils.js";
+
+const ROUTE_DEBUG_MAX_LIST_ITEMS = 8;
+const ROUTE_DEBUG_MAX_HEADER_VALUE_LENGTH = 512;
+
+function candidateRef(candidate) {
+  return candidate?.requestModelId ||
+    (candidate?.providerId && candidate?.modelId
+      ? `${candidate.providerId}/${candidate.modelId}`
+      : candidate?.backend || "unknown/unknown");
+}
+
+function pushBounded(list, value, maxItems = ROUTE_DEBUG_MAX_LIST_ITEMS) {
+  if (!Array.isArray(list) || !value) return;
+  if (list.length >= maxItems) return;
+  list.push(value);
+}
+
+function toSafeHeaderValue(value) {
+  const text = String(value || "").replace(/[\r\n]+/g, " ").trim();
+  if (!text) return "";
+  return text.length > ROUTE_DEBUG_MAX_HEADER_VALUE_LENGTH
+    ? text.slice(0, ROUTE_DEBUG_MAX_HEADER_VALUE_LENGTH)
+    : text;
+}
+
+export function isRoutingDebugEnabled(env = {}) {
+  return toBoolean(
+    env?.LLM_ROUTER_DEBUG_ROUTING,
+    toBoolean(env?.LLM_ROUTER_DEBUG, false)
+  );
+}
+
+export function buildRouteDebugState(enabled, resolved) {
+  return {
+    enabled,
+    requestedModel: resolved?.requestedModel || "smart",
+    routeType: resolved?.routeType || "direct",
+    routeRef: resolved?.routeRef || resolved?.resolvedModel || resolved?.requestedModel || "smart",
+    strategy: resolved?.routeStrategy || "ordered",
+    selectedCandidate: "",
+    skippedCandidates: [],
+    attempts: []
+  };
+}
+
+export function recordRouteSkip(debugState, candidate, reasons) {
+  if (!debugState?.enabled) return;
+  const reasonText = Array.isArray(reasons)
+    ? reasons.filter(Boolean).join("+")
+    : String(reasons || "").trim();
+  pushBounded(
+    debugState.skippedCandidates,
+    `${candidateRef(candidate)}:${reasonText || "skipped"}`
+  );
+}
+
+export function recordRouteAttempt(debugState, candidate, status, classification, attempt) {
+  if (!debugState?.enabled) return;
+  const category = classification?.category || (status && status < 400 ? "ok" : "unknown");
+  pushBounded(
+    debugState.attempts,
+    `${candidateRef(candidate)}:${Number.isFinite(status) ? status : "error"}/${category}#${attempt}`
+  );
+}
+
+export function setRouteSelectedCandidate(debugState, candidate, { overwrite = false } = {}) {
+  if (!debugState?.enabled || !candidate) return;
+  if (debugState.selectedCandidate && !overwrite) return;
+  debugState.selectedCandidate = candidateRef(candidate);
+}
+
+export function withRouteDebugHeaders(response, debugState) {
+  if (!debugState?.enabled || !(response instanceof Response)) {
+    return response;
+  }
+
+  const headers = new Headers(response.headers);
+  headers.set("x-llm-router-requested-model", toSafeHeaderValue(debugState.requestedModel));
+  headers.set("x-llm-router-route-type", toSafeHeaderValue(debugState.routeType));
+  headers.set("x-llm-router-route-ref", toSafeHeaderValue(debugState.routeRef));
+  headers.set("x-llm-router-route-strategy", toSafeHeaderValue(debugState.strategy));
+
+  const selectedCandidate = toSafeHeaderValue(debugState.selectedCandidate);
+  if (selectedCandidate) {
+    headers.set("x-llm-router-selected-candidate", selectedCandidate);
+  }
+
+  const skippedCandidates = toSafeHeaderValue(debugState.skippedCandidates.join(","));
+  if (skippedCandidates) {
+    headers.set("x-llm-router-skipped-candidates", skippedCandidates);
+  }
+
+  const attempts = toSafeHeaderValue(debugState.attempts.join(","));
+  if (attempts) {
+    headers.set("x-llm-router-attempts", attempts);
+  }
+
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers
+  });
+}

package/src/runtime/handler/runtime-policy.js

@@ -0,0 +1,161 @@
+import { normalizeStateStoreBackend } from "../state-store.js";
+import { toBoolean, toNonNegativeInteger } from "./utils.js";
+
+function normalizeRuntimeName(value) {
+  const runtime = String(value || "").trim().toLowerCase();
+  if (runtime === "worker" || runtime === "cloudflare-worker" || runtime === "cloudflare") {
+    return "worker";
+  }
+  return "node";
+}
+
+export function resolveRuntimeFlags(options = {}, env = {}) {
+  const runtime = normalizeRuntimeName(options.runtime);
+  const workerRuntime = runtime === "worker";
+  const workerSafeMode = workerRuntime
+    ? toBoolean(env?.LLM_ROUTER_WORKER_SAFE_MODE, toBoolean(options.workerSafeMode, true))
+    : false;
+  const allowBestEffortStatefulRouting = workerRuntime
+    ? toBoolean(
+        env?.LLM_ROUTER_WORKER_ALLOW_BEST_EFFORT_STATEFUL_ROUTING,
+        toBoolean(options.allowWorkerBestEffortStatefulRouting, false)
+      )
+    : false;
+
+  return {
+    runtime,
+    workerRuntime,
+    workerSafeMode,
+    allowBestEffortStatefulRouting,
+    statefulRoutingEnabled: !workerSafeMode || allowBestEffortStatefulRouting
+  };
+}
+
+export function applyRuntimeRetryPolicyGuards(retryPolicy, runtimeFlags) {
+  if (!runtimeFlags?.workerSafeMode || runtimeFlags.statefulRoutingEnabled) {
+    return retryPolicy;
+  }
+
+  return {
+    ...retryPolicy,
+    originRetryAttempts: 1,
+    originRetryBaseDelayMs: 0,
+    originRetryMaxDelayMs: 0
+  };
+}
+
+function normalizeTimestamp(value, fallback = 0) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) return fallback;
+  return Math.floor(parsed);
+}
+
+function normalizeCount(value, fallback = 0) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) return fallback;
+  return Math.floor(parsed);
+}
+
+function isFallbackCircuitTrackingEnabled(policy) {
+  return Number.isFinite(policy?.failureThreshold) &&
+    Number.isFinite(policy?.cooldownMs) &&
+    policy.failureThreshold > 0 &&
+    policy.cooldownMs > 0;
+}
+
+function shouldTrackCandidateFailure(classification) {
+  if (!classification) return false;
+  if (classification.category === "invalid_request" || classification.category === "client_error") {
+    return false;
+  }
+  if (classification.category === "not_supported_error") {
+    return false;
+  }
+  return Boolean(classification.retryable || normalizeTimestamp(classification.originCooldownMs) > 0);
+}
+
+export async function clearCandidateRoutingState(stateStore, candidateKey) {
+  if (!stateStore || !candidateKey) return;
+  await stateStore.setCandidateState(candidateKey, null);
+}
+
+export async function applyCandidateFailureState(
+  stateStore,
+  candidateKey,
+  classification,
+  fallbackCircuitPolicy,
+  status,
+  now = Date.now()
+) {
+  if (!stateStore || !candidateKey || !shouldTrackCandidateFailure(classification)) {
+    return;
+  }
+
+  const prior = await stateStore.getCandidateState(candidateKey) || {};
+  const priorCooldownUntil = normalizeTimestamp(prior.cooldownUntil);
+  const priorOpenUntil = normalizeTimestamp(prior.openUntil);
+  const priorFailures = normalizeCount(
+    prior.consecutiveRetryableFailures ?? prior.consecutiveFailures
+  );
+
+  const consecutiveRetryableFailures = classification.retryable
+    ? priorFailures + 1
+    : 0;
+
+  let openUntil = priorOpenUntil > now ? priorOpenUntil : 0;
+  if (
+    classification.retryable &&
+    isFallbackCircuitTrackingEnabled(fallbackCircuitPolicy) &&
+    consecutiveRetryableFailures >= fallbackCircuitPolicy.failureThreshold
+  ) {
+    openUntil = Math.max(openUntil, now + fallbackCircuitPolicy.cooldownMs);
+  }
+
+  const cooldownMs = normalizeTimestamp(classification.originCooldownMs);
+  const cooldownUntil = cooldownMs > 0
+    ? Math.max(priorCooldownUntil, now + cooldownMs)
+    : (priorCooldownUntil > now ? priorCooldownUntil : 0);
+
+  await stateStore.setCandidateState(candidateKey, {
+    ...prior,
+    cooldownUntil,
+    openUntil,
+    consecutiveRetryableFailures,
+    lastFailureAt: now,
+    lastFailureStatus: Number.isFinite(status) ? Number(status) : 0,
+    lastFailureCategory: classification.category,
+    updatedAt: now
+  });
+}
+
+export function resolveStateStoreOptions(options = {}, env = {}, runtimeFlags = {}) {
+  const baseOptions = options.stateStoreOptions && typeof options.stateStoreOptions === "object"
+    ? { ...options.stateStoreOptions }
+    : {};
+  const defaultBackend = normalizeStateStoreBackend(
+    options.defaultStateStoreBackend || baseOptions.backend,
+    "memory"
+  );
+  const backend = normalizeStateStoreBackend(
+    options.stateStoreBackend || env?.LLM_ROUTER_STATE_BACKEND || baseOptions.backend,
+    defaultBackend
+  );
+  const effectiveBackend = runtimeFlags?.workerRuntime && backend === "file"
+    ? "memory"
+    : backend;
+  const candidateStateTtlMs = toNonNegativeInteger(
+    env?.LLM_ROUTER_CANDIDATE_STATE_TTL_MS,
+    toNonNegativeInteger(options.stateStoreCandidateStateTtlMs, baseOptions.candidateStateTtlMs)
+  );
+  const rawFilePath = options.stateStoreFilePath || env?.LLM_ROUTER_STATE_FILE_PATH || baseOptions.filePath;
+  const filePath = typeof rawFilePath === "string" && rawFilePath.trim()
+    ? rawFilePath.trim()
+    : undefined;
+
+  return {
+    ...baseOptions,
+    backend: effectiveBackend,
+    ...(candidateStateTtlMs !== undefined ? { candidateStateTtlMs } : {}),
+    ...(effectiveBackend === "file" && filePath ? { filePath } : {})
+  };
+}

package/src/runtime/handler.js

@@ -11,8 +11,7 @@ import {
 import { consumeCandidateRateLimits } from "./rate-limits.js";
 import {
   buildRouteKey,
-  createStateStore,
-  normalizeStateStoreBackend
+  createStateStore
 } from "./state-store.js";
 import { FORMATS } from "../translator/index.js";
 import { shouldEnforceWorkerAuth, validateAuth } from "./handler/auth.js";
@@ -43,52 +42,27 @@ import {
   resolveFallbackCircuitPolicy,
   resolveRetryPolicy
 } from "./handler/fallback.js";
-import { sleep, toBoolean, toNonNegativeInteger } from "./handler/utils.js";
-
-const ROUTE_DEBUG_MAX_LIST_ITEMS = 8;
-const ROUTE_DEBUG_MAX_HEADER_VALUE_LENGTH = 512;
-
-function normalizeTimestamp(value, fallback = 0) {
-  const parsed = Number(value);
-  if (!Number.isFinite(parsed) || parsed < 0) return fallback;
-  return Math.floor(parsed);
-}
-
-function normalizeCount(value, fallback = 0) {
-  const parsed = Number(value);
-  if (!Number.isFinite(parsed) || parsed < 0) return fallback;
-  return Math.floor(parsed);
-}
-
-function isFallbackCircuitTrackingEnabled(policy) {
-  return Number.isFinite(policy?.failureThreshold) &&
-    Number.isFinite(policy?.cooldownMs) &&
-    policy.failureThreshold > 0 &&
-    policy.cooldownMs > 0;
-}
-
-function shouldTrackCandidateFailure(classification) {
-  if (!classification) return false;
-  if (classification.category === "invalid_request" || classification.category === "client_error") {
-    return false;
-  }
-  if (classification.category === "not_supported_error") {
-    return false;
-  }
-  return Boolean(classification.retryable || normalizeTimestamp(classification.originCooldownMs) > 0);
-}
+import { sleep } from "./handler/utils.js";
+import {
+  applyCandidateFailureState,
+  applyRuntimeRetryPolicyGuards,
+  clearCandidateRoutingState,
+  resolveRuntimeFlags,
+  resolveStateStoreOptions
+} from "./handler/runtime-policy.js";
+import {
+  buildRouteDebugState,
+  isRoutingDebugEnabled,
+  recordRouteAttempt,
+  recordRouteSkip,
+  setRouteSelectedCandidate,
+  withRouteDebugHeaders
+} from "./handler/route-debug.js";
 
 function shouldConsumeQuotaFromResult(result) {
   return Boolean(result?.ok || result?.upstreamResponse instanceof Response);
 }
 
-function candidateRef(candidate) {
-  return candidate?.requestModelId ||
-    (candidate?.providerId && candidate?.modelId
-      ? `${candidate.providerId}/${candidate.modelId}`
-      : candidate?.backend || "unknown/unknown");
-}
-
 function filterCandidatesByFormat(candidates) {
   const eligible = [];
   const skipped = [];
@@ -115,182 +89,6 @@ function hasNextEligibleCandidate(entries, startIndex) {
   return false;
 }
 
-function isRoutingDebugEnabled(env = {}) {
-  return toBoolean(
-    env?.LLM_ROUTER_DEBUG_ROUTING,
-    toBoolean(env?.LLM_ROUTER_DEBUG, false)
-  );
-}
-
-function pushBounded(list, value, maxItems = ROUTE_DEBUG_MAX_LIST_ITEMS) {
-  if (!Array.isArray(list) || !value) return;
-  if (list.length >= maxItems) return;
-  list.push(value);
-}
-
-function buildRouteDebugState(enabled, resolved) {
-  return {
-    enabled,
-    requestedModel: resolved?.requestedModel || "smart",
-    routeType: resolved?.routeType || "direct",
-    routeRef: resolved?.routeRef || resolved?.resolvedModel || resolved?.requestedModel || "smart",
-    strategy: resolved?.routeStrategy || "ordered",
-    selectedCandidate: "",
-    skippedCandidates: [],
-    attempts: []
-  };
-}
-
-function recordRouteSkip(debugState, candidate, reasons) {
-  if (!debugState?.enabled) return;
-  const reasonText = Array.isArray(reasons)
-    ? reasons.filter(Boolean).join("+")
-    : String(reasons || "").trim();
-  pushBounded(
-    debugState.skippedCandidates,
-    `${candidateRef(candidate)}:${reasonText || "skipped"}`
-  );
-}
-
-function recordRouteAttempt(debugState, candidate, status, classification, attempt) {
-  if (!debugState?.enabled) return;
-  const category = classification?.category || (status && status < 400 ? "ok" : "unknown");
-  pushBounded(
-    debugState.attempts,
-    `${candidateRef(candidate)}:${Number.isFinite(status) ? status : "error"}/${category}#${attempt}`
-  );
-}
-
-function setRouteSelectedCandidate(debugState, candidate, { overwrite = false } = {}) {
-  if (!debugState?.enabled || !candidate) return;
-  if (debugState.selectedCandidate && !overwrite) return;
-  debugState.selectedCandidate = candidateRef(candidate);
-}
-
-function toSafeHeaderValue(value) {
-  const text = String(value || "").replace(/[\r\n]+/g, " ").trim();
-  if (!text) return "";
-  return text.length > ROUTE_DEBUG_MAX_HEADER_VALUE_LENGTH
-    ? text.slice(0, ROUTE_DEBUG_MAX_HEADER_VALUE_LENGTH)
-    : text;
-}
-
-function withRouteDebugHeaders(response, debugState) {
-  if (!debugState?.enabled || !(response instanceof Response)) {
-    return response;
-  }
-
-  const headers = new Headers(response.headers);
-  headers.set("x-llm-router-requested-model", toSafeHeaderValue(debugState.requestedModel));
-  headers.set("x-llm-router-route-type", toSafeHeaderValue(debugState.routeType));
-  headers.set("x-llm-router-route-ref", toSafeHeaderValue(debugState.routeRef));
-  headers.set("x-llm-router-route-strategy", toSafeHeaderValue(debugState.strategy));
-
-  const selectedCandidate = toSafeHeaderValue(debugState.selectedCandidate);
-  if (selectedCandidate) {
-    headers.set("x-llm-router-selected-candidate", selectedCandidate);
-  }
-
-  const skippedCandidates = toSafeHeaderValue(debugState.skippedCandidates.join(","));
-  if (skippedCandidates) {
-    headers.set("x-llm-router-skipped-candidates", skippedCandidates);
-  }
-
-  const attempts = toSafeHeaderValue(debugState.attempts.join(","));
-  if (attempts) {
-    headers.set("x-llm-router-attempts", attempts);
-  }
-
-  return new Response(response.body, {
-    status: response.status,
-    statusText: response.statusText,
-    headers
-  });
-}
-
-async function clearCandidateRoutingState(stateStore, candidateKey) {
-  if (!stateStore || !candidateKey) return;
-  await stateStore.setCandidateState(candidateKey, null);
-}
-
-async function applyCandidateFailureState(
-  stateStore,
-  candidateKey,
-  classification,
-  fallbackCircuitPolicy,
-  status,
-  now = Date.now()
-) {
-  if (!stateStore || !candidateKey || !shouldTrackCandidateFailure(classification)) {
-    return;
-  }
-
-  const prior = await stateStore.getCandidateState(candidateKey) || {};
-  const priorCooldownUntil = normalizeTimestamp(prior.cooldownUntil);
-  const priorOpenUntil = normalizeTimestamp(prior.openUntil);
-  const priorFailures = normalizeCount(
-    prior.consecutiveRetryableFailures ?? prior.consecutiveFailures
-  );
-
-  const consecutiveRetryableFailures = classification.retryable
-    ? priorFailures + 1
-    : 0;
-
-  let openUntil = priorOpenUntil > now ? priorOpenUntil : 0;
-  if (
-    classification.retryable &&
-    isFallbackCircuitTrackingEnabled(fallbackCircuitPolicy) &&
-    consecutiveRetryableFailures >= fallbackCircuitPolicy.failureThreshold
-  ) {
-    openUntil = Math.max(openUntil, now + fallbackCircuitPolicy.cooldownMs);
-  }
-
-  const cooldownMs = normalizeTimestamp(classification.originCooldownMs);
-  const cooldownUntil = cooldownMs > 0
-    ? Math.max(priorCooldownUntil, now + cooldownMs)
-    : (priorCooldownUntil > now ? priorCooldownUntil : 0);
-
-  await stateStore.setCandidateState(candidateKey, {
-    ...prior,
-    cooldownUntil,
-    openUntil,
-    consecutiveRetryableFailures,
-    lastFailureAt: now,
-    lastFailureStatus: Number.isFinite(status) ? Number(status) : 0,
-    lastFailureCategory: classification.category,
-    updatedAt: now
-  });
-}
-
-function resolveStateStoreOptions(options = {}, env = {}) {
-  const baseOptions = options.stateStoreOptions && typeof options.stateStoreOptions === "object"
-    ? { ...options.stateStoreOptions }
-    : {};
-  const defaultBackend = normalizeStateStoreBackend(
-    options.defaultStateStoreBackend || baseOptions.backend,
-    "memory"
-  );
-  const backend = normalizeStateStoreBackend(
-    options.stateStoreBackend || env?.LLM_ROUTER_STATE_BACKEND || baseOptions.backend,
-    defaultBackend
-  );
-  const candidateStateTtlMs = toNonNegativeInteger(
-    env?.LLM_ROUTER_CANDIDATE_STATE_TTL_MS,
-    toNonNegativeInteger(options.stateStoreCandidateStateTtlMs, baseOptions.candidateStateTtlMs)
-  );
-  const rawFilePath = options.stateStoreFilePath || env?.LLM_ROUTER_STATE_FILE_PATH || baseOptions.filePath;
-  const filePath = typeof rawFilePath === "string" && rawFilePath.trim()
-    ? rawFilePath.trim()
-    : undefined;
-
-  return {
-    ...baseOptions,
-    backend,
-    ...(candidateStateTtlMs !== undefined ? { candidateStateTtlMs } : {}),
-    ...(backend === "file" && filePath ? { filePath } : {})
-  };
-}
-
 async function handleRouteRequest(request, env, getConfig, sourceFormatHint, options = {}) {
   let config;
   try {
@@ -353,9 +151,12 @@ async function handleRouteRequest(request, env, getConfig, sourceFormatHint, opt
     }, 400);
   }
 
+  const runtimeFlags = options.runtimeFlags || resolveRuntimeFlags(options, env);
   const fallbackCircuitPolicy = resolveFallbackCircuitPolicy(env);
-  const retryPolicy = resolveRetryPolicy(env);
-  const stateStore = options.stateStore || null;
+  const retryPolicy = applyRuntimeRetryPolicyGuards(resolveRetryPolicy(env), runtimeFlags);
+  const stateStore = runtimeFlags.statefulRoutingEnabled
+    ? (options.stateStore || null)
+    : null;
   const routeDebug = buildRouteDebugState(isRoutingDebugEnabled(env), resolved);
   const now = Date.now();
 
@@ -392,7 +193,9 @@ async function handleRouteRequest(request, env, getConfig, sourceFormatHint, opt
     ranking = await rankRouteCandidates({
       route: routePlan,
       routeKey: buildRouteKey(routePlan, { sourceFormat }),
-      strategy: resolved.routeType === "alias" ? resolved.routeStrategy : "ordered",
+      strategy: runtimeFlags.statefulRoutingEnabled && resolved.routeType === "alias"
+        ? resolved.routeStrategy
+        : "ordered",
       candidates: formatFiltered.eligible,
       stateStore,
       config,
@@ -531,10 +334,10 @@ export function createFetchHandler(options) {
   let stateStoreRef = options.stateStore || null;
   let stateStorePromise = null;
 
-  async function ensureStateStore(env = {}) {
+  async function ensureStateStore(env = {}, runtimeFlags = {}) {
     if (stateStoreRef) return stateStoreRef;
     if (!stateStorePromise) {
-      stateStorePromise = createStateStore(resolveStateStoreOptions(options, env))
+      stateStorePromise = createStateStore(resolveStateStoreOptions(options, env, runtimeFlags))
         .then((store) => {
           stateStoreRef = store;
           return store;
@@ -557,6 +360,7 @@ export function createFetchHandler(options) {
   const fetchHandler = async function fetchHandler(request, env = {}, ctx) {
     const url = new URL(request.url);
     const respond = (response, corsOptions = {}) => withRequestCors(response, request, env, corsOptions);
+    const runtimeFlags = resolveRuntimeFlags(options, env);
     let preloadedConfig = null;
     let authValidated = false;
 
@@ -641,24 +445,27 @@ export function createFetchHandler(options) {
     }
 
     if (route?.type === "route") {
-      let stateStore;
-      try {
-        stateStore = await ensureStateStore(env);
-      } catch (error) {
-        return respond(jsonResponse({
-          type: "error",
-          error: {
-            type: "configuration_error",
-            message: `Failed initializing routing state: ${error instanceof Error ? error.message : String(error)}`
-          }
-        }, 500));
+      let stateStore = null;
+      if (runtimeFlags.statefulRoutingEnabled) {
+        try {
+          stateStore = await ensureStateStore(env, runtimeFlags);
+        } catch (error) {
+          return respond(jsonResponse({
+            type: "error",
+            error: {
+              type: "configuration_error",
+              message: `Failed initializing routing state: ${error instanceof Error ? error.message : String(error)}`
+            }
+          }, 500));
+        }
       }
 
       const routeResponse = await handleRouteRequest(request, env, options.getConfig, route.sourceFormat, {
         ...options,
         preloadedConfig,
         authValidated,
-        stateStore
+        stateStore,
+        runtimeFlags
       });
       return respond(routeResponse);
     }

package/src/shared/timeout-signal.js

@@ -0,0 +1,23 @@
+export function buildTimeoutSignal(timeoutMs) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    return { signal: undefined, cleanup: () => {} };
+  }
+
+  if (typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function") {
+    return {
+      signal: AbortSignal.timeout(timeoutMs),
+      cleanup: () => {}
+    };
+  }
+
+  if (typeof AbortController === "undefined") {
+    return { signal: undefined, cleanup: () => {} };
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(`timeout:${timeoutMs}`), timeoutMs);
+  return {
+    signal: controller.signal,
+    cleanup: () => clearTimeout(timer)
+  };
+}