@luckystack/api 0.1.9 → 0.2.1

package/dist/index.js

@@ -1,46 +1,312 @@
 // src/handleApiRequest.ts
-import { getSession, logout } from "@luckystack/login";
-import { getProjectConfig } from "@luckystack/core";
-import { getRuntimeApiMaps } from "@luckystack/core";
 import {
+  readSession,
+  performLogout,
+  runWithErrorTrackerIdentityScope,
+  setCurrentErrorTrackerIdentity,
+  getProjectConfig as getProjectConfig4,
+  getRuntimeApiMaps,
   validateRequest,
-  checkRateLimit,
+  checkRateLimit as checkRateLimit2,
   tryCatch,
   parseTransportRouteName,
   buildApiResponseEventName,
-  buildApiStreamEventName,
-  dispatchHook,
-  validateInputByType,
-  getLogger
+  dispatchHook as dispatchHook3,
+  getLogger as getLogger7,
+  resolveClientIp,
+  extractLanguageFromHeader,
+  normalizeErrorResponse as normalizeErrorResponse2,
+  applyErrorFormatter
 } from "@luckystack/core";
+
+// src/_shared/logFlags.ts
+import { getProjectConfig } from "@luckystack/core";
+var shouldLogDev = () => getProjectConfig().logging.devLogs;
+var shouldLogStream = () => getProjectConfig().logging.stream;
+
+// src/_shared/responseEnvelope.ts
+import { defaultHttpStatusForResponse, normalizeErrorResponse, getLogger } from "@luckystack/core";
+var normalizeApiResponse = ({
+  resolvedName,
+  error,
+  result,
+  preferredLocale,
+  user
+}) => {
+  if (error) {
+    if (shouldLogDev()) {
+      getLogger().error(`api: error in ${resolvedName}`, error, { route: resolvedName });
+    }
+    return {
+      ...normalizeErrorResponse({
+        response: { status: "error", errorCode: "api.internalServerError" },
+        preferredLocale,
+        userLanguage: user?.language,
+        fallbackHttpStatus: 500
+      })
+    };
+  }
+  if (result === void 0 || result === null) {
+    if (shouldLogDev()) {
+      getLogger().warn(`api: ${resolvedName} returned nothing`);
+    }
+    return {
+      ...normalizeErrorResponse({
+        response: { status: "error", errorCode: "api.emptyResponse" },
+        preferredLocale,
+        userLanguage: user?.language,
+        fallbackHttpStatus: 500
+      })
+    };
+  }
+  if (shouldLogDev()) {
+    getLogger().debug(`api: ${resolvedName} completed`);
+  }
+  if (result.status !== "success" && result.status !== "error") {
+    return {
+      ...normalizeErrorResponse({
+        response: { status: "error", errorCode: "api.invalidResponseStatus" },
+        preferredLocale,
+        userLanguage: user?.language,
+        fallbackHttpStatus: 500
+      })
+    };
+  }
+  if (result.status === "error") {
+    return {
+      ...normalizeErrorResponse({
+        response: result,
+        preferredLocale,
+        userLanguage: user?.language,
+        fallbackHttpStatus: defaultHttpStatusForResponse({
+          status: "error",
+          explicitHttpStatus: typeof result.httpStatus === "number" ? result.httpStatus : void 0
+        })
+      })
+    };
+  }
+  return {
+    ...result,
+    status: "success",
+    httpStatus: defaultHttpStatusForResponse({
+      status: "success",
+      explicitHttpStatus: typeof result.httpStatus === "number" ? result.httpStatus : void 0
+    })
+  };
+};
+
+// src/_shared/requestLifecycle.ts
 import {
-  defaultHttpStatusForResponse,
-  extractLanguageFromHeader,
-  normalizeErrorResponse,
-  applyErrorFormatter,
+  buildApiStreamEventName,
+  getLogger as getLogger3,
   registerApiAbortController,
   unregisterApiAbortController,
   socketEventNames
 } from "@luckystack/core";
-var shouldLogDev = () => getProjectConfig().logging.devLogs;
-var shouldLogStream = () => getProjectConfig().logging.stream;
+
+// src/_shared/backpressure.ts
+import { getLogger as getLogger2 } from "@luckystack/core";
+var createApiFlushPressure = (socket, abortSignal) => {
+  return async ({ thresholdBytes } = {}) => {
+    const effectiveThresholdBytes = typeof thresholdBytes === "number" && thresholdBytes > 0 ? thresholdBytes : 1048576;
+    const packetThreshold = Math.max(1, Math.ceil(effectiveThresholdBytes / 1024));
+    while (!abortSignal.aborted) {
+      const conn = socket.conn;
+      if (shouldLogDev() && !conn) {
+        getLogger2().warn("api: socket.conn absent \u2014 engine.io internal may have been renamed; backpressure is a no-op");
+      }
+      const packets = conn?.writeBuffer?.length ?? 0;
+      const writable = conn?.transport?.writable ?? true;
+      if (!writable) return;
+      if (packets < packetThreshold) return;
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+  };
+};
+var httpApiFlushPressureNoop = async () => {
+};
+
+// src/_shared/requestLifecycle.ts
+var createApiRequestLifecycle = ({ socket, responseIndex, resolvedName }) => {
+  const abortController = new AbortController();
+  const abortKey = registerApiAbortController(socket.id, responseIndex, abortController);
+  const onSocketDisconnect = () => {
+    abortController.abort();
+  };
+  socket.once(socketEventNames.disconnect, onSocketDisconnect);
+  let cleanupDone = false;
+  const cleanupRequest = () => {
+    if (cleanupDone) return;
+    cleanupDone = true;
+    socket.off(socketEventNames.disconnect, onSocketDisconnect);
+    unregisterApiAbortController(abortKey);
+  };
+  const emitStream = (payload = {}) => {
+    if (abortController.signal.aborted) {
+      if (shouldLogStream()) {
+        getLogger3().debug(`api: ${resolvedName} stream skipped \u2014 request aborted`);
+      }
+      return;
+    }
+    if (shouldLogStream()) {
+      getLogger3().debug(`api: ${resolvedName} stream`, { payload });
+    }
+    socket.emit(buildApiStreamEventName(responseIndex), payload);
+  };
+  const flushPressure = createApiFlushPressure(socket, abortController.signal);
+  return { abortController, abortSignal: abortController.signal, emitStream, flushPressure, cleanupRequest };
+};
+
+// src/_shared/socketValidationStage.ts
+import { dispatchHook, validateInputByType, getLogger as getLogger5 } from "@luckystack/core";
+
+// src/_shared/inputTypeWarning.ts
+import { getProjectConfig as getProjectConfig2, getLogger as getLogger4 } from "@luckystack/core";
 var warnedMissingInputType = /* @__PURE__ */ new Set();
 var warnIfInputTypeMissing = (resolvedName, inputType) => {
-  if (!getProjectConfig().dev.warnOnMissingInputType) return;
+  if (!getProjectConfig2().dev.warnOnMissingInputType) return;
   if (inputType && inputType.trim().length > 0 && inputType.trim() !== "any") return;
   if (warnedMissingInputType.has(resolvedName)) return;
   warnedMissingInputType.add(resolvedName);
-  getLogger().warn(`api: route ${resolvedName} has no inputType \u2014 runtime input validation is disabled. Regenerate types or set the inputType on the handler.`);
+  getLogger4().warn(`api: route ${resolvedName} has no inputType \u2014 runtime input validation is disabled. Regenerate types or set the inputType on the handler.`);
+};
+
+// src/_shared/socketValidationStage.ts
+var resolveValidationMode = (validation) => {
+  if (!validation) return "strict";
+  if (typeof validation === "string") {
+    return validation === "relaxed" ? "relaxed" : "strict";
+  }
+  return validation.input === "skip" ? "relaxed" : "strict";
+};
+var runSocketApiValidation = async ({
+  apiEntry,
+  resolvedName,
+  normalizedData,
+  user,
+  cleanupRequest,
+  emitInvalidInputType
+}) => {
+  const validationMode = resolveValidationMode(apiEntry.validation);
+  if (validationMode === "strict") {
+    warnIfInputTypeMissing(resolvedName, apiEntry.inputType);
+  }
+  await dispatchHook("preApiValidate", { routeName: resolvedName, data: normalizedData, user, transport: "socket" });
+  if (validationMode === "strict") {
+    const inputValidation = await validateInputByType({
+      typeText: apiEntry.inputType,
+      value: normalizedData,
+      rootKey: "data",
+      filePath: apiEntry.inputTypeFilePath
+    });
+    await dispatchHook("postApiValidate", {
+      routeName: resolvedName,
+      data: normalizedData,
+      user,
+      validation: inputValidation,
+      transport: "socket"
+    });
+    if (inputValidation.status === "error") {
+      if (shouldLogDev()) {
+        getLogger5().warn(`api: input validation failed for ${resolvedName}`, { route: resolvedName, message: inputValidation.message });
+      }
+      cleanupRequest();
+      emitInvalidInputType();
+      return false;
+    }
+  } else {
+    await dispatchHook("postApiValidate", {
+      routeName: resolvedName,
+      data: normalizedData,
+      user,
+      validation: { status: "success" },
+      transport: "socket"
+    });
+  }
+  return true;
+};
+
+// src/_shared/applyApiRateLimits.ts
+import { checkRateLimit, getProjectConfig as getProjectConfig3, dispatchHook as dispatchHook2, getLogger as getLogger6 } from "@luckystack/core";
+
+// src/_shared/rateLimitIdentity.ts
+import { deriveTokenBucketId } from "@luckystack/core";
+
+// src/_shared/applyApiRateLimits.ts
+var applyApiRateLimits = async ({
+  resolvedIp,
+  token,
+  user,
+  resolvedName,
+  rateLimit,
+  transport,
+  skipGlobalIpBucket = false
+}) => {
+  const config = getProjectConfig3();
+  const effectiveApiLimit = rateLimit ?? config.rateLimiting.defaultApiLimit;
+  if (effectiveApiLimit !== false && effectiveApiLimit > 0) {
+    const identityCb = config.rateLimiting.identity;
+    const customIdentity = identityCb?.({ routeName: resolvedName, userId: user?.id ?? null, ip: resolvedIp, transport }) ?? null;
+    const requesterIdentity = customIdentity?.id ?? (token ? deriveTokenBucketId(token) : resolvedIp);
+    const keyPrefix = customIdentity?.scope ?? (token ? "token" : "ip");
+    const rateLimitKey = `${keyPrefix}:${requesterIdentity}:api:${resolvedName}`;
+    const { allowed, resetIn } = await checkRateLimit({
+      key: rateLimitKey,
+      limit: effectiveApiLimit,
+      windowMs: config.rateLimiting.windowMs
+    });
+    if (!allowed) {
+      void dispatchHook2("rateLimitExceeded", {
+        scope: token ? "user" : "ip",
+        key: rateLimitKey,
+        limit: effectiveApiLimit,
+        windowMs: config.rateLimiting.windowMs,
+        count: effectiveApiLimit + 1,
+        route: resolvedName,
+        userId: user?.id,
+        ip: token ? void 0 : resolvedIp
+      });
+      if (shouldLogDev()) {
+        getLogger6().warn(`api: rate limit exceeded for ${resolvedName}`, { route: resolvedName, key: rateLimitKey, transport });
+      }
+      return { allowed: false, errorCode: "api.rateLimitExceeded", resetIn };
+    }
+  }
+  const defaultIpLimit = config.rateLimiting.defaultIpLimit;
+  if (!skipGlobalIpBucket && defaultIpLimit !== false && defaultIpLimit > 0) {
+    const { allowed, resetIn } = await checkRateLimit({
+      key: `ip:${resolvedIp}:api:all`,
+      limit: defaultIpLimit,
+      windowMs: config.rateLimiting.windowMs
+    });
+    if (!allowed) {
+      void dispatchHook2("rateLimitExceeded", {
+        scope: "ip",
+        key: `ip:${resolvedIp}:api:all`,
+        limit: defaultIpLimit,
+        windowMs: config.rateLimiting.windowMs,
+        count: defaultIpLimit + 1,
+        ip: resolvedIp
+      });
+      if (shouldLogDev()) {
+        getLogger6().warn(`api: global IP rate limit exceeded`, { ip: resolvedIp, transport });
+      }
+      return { allowed: false, errorCode: "api.rateLimitExceeded", resetIn };
+    }
+  }
+  return { allowed: true };
 };
+
+// src/handleApiRequest.ts
 var validateApiMessage = ({ msg, emitApiError }) => {
   const { name, data, responseIndex } = msg;
-  if (!responseIndex && typeof responseIndex !== "number") {
+  if (typeof responseIndex !== "number") {
     if (shouldLogDev()) {
-      getLogger().warn("api: no response index given");
+      getLogger7().warn("api: no response index given");
     }
     return null;
   }
-  if (!name || !data || typeof name != "string" || typeof data != "object") {
+  if (!name || !data || typeof name != "string" || typeof data != "object" || Array.isArray(data)) {
     emitApiError({
       response: { status: "error", errorCode: "api.invalidRequest" },
       fallbackHttpStatus: 400
@@ -52,8 +318,14 @@ var validateApiMessage = ({ msg, emitApiError }) => {
 var checkApiAuth = ({ apiEntry, user, name, emitApiError }) => {
   if (apiEntry.auth.login && !user?.id) {
     if (shouldLogDev()) {
-      getLogger().warn(`api: ${name} requires login`, { route: name });
+      getLogger7().warn(`api: ${name} requires login`, { route: name });
     }
+    void dispatchHook3("apiAuthRejected", {
+      routeName: name,
+      reason: "login-required",
+      userId: null,
+      transport: "socket"
+    });
     emitApiError({
       response: { status: "error", errorCode: "auth.required" },
       fallbackHttpStatus: 401
@@ -63,11 +335,19 @@ var checkApiAuth = ({ apiEntry, user, name, emitApiError }) => {
   const authResult = validateRequest({ auth: apiEntry.auth, user });
   if (authResult.status === "error") {
     if (shouldLogDev()) {
-      getLogger().warn(`api: auth failed for ${name}`, { route: name, errorCode: authResult.errorCode });
+      getLogger7().warn(`api: auth failed for ${name}`, { route: name, errorCode: authResult.errorCode });
     }
+    void dispatchHook3("apiAuthRejected", {
+      routeName: name,
+      reason: authResult.errorCode === "auth.misconfiguredPredicate" ? "invalid-condition" : "additional-failed",
+      userId: user?.id ?? null,
+      transport: "socket",
+      failedKey: authResult.errorCode
+    });
     emitApiError({
       response: {
         status: "error",
+        // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- empty string errorCode must still fall back
         errorCode: authResult.errorCode || "auth.forbidden",
         errorParams: authResult.errorParams,
         httpStatus: authResult.httpStatus
@@ -78,78 +358,47 @@ var checkApiAuth = ({ apiEntry, user, name, emitApiError }) => {
   }
   return true;
 };
-var applyApiRateLimits = async ({ apiEntry, resolvedName, token, socket, user, emitApiError }) => {
-  const apiRateLimit = apiEntry.rateLimit;
-  const effectiveApiLimit = apiRateLimit === void 0 ? getProjectConfig().rateLimiting.defaultApiLimit : apiRateLimit;
-  if (effectiveApiLimit !== false && effectiveApiLimit > 0) {
-    const requesterIdentity = token ?? socket.handshake.address ?? "unknown";
-    const keyPrefix = token ? "token" : "ip";
-    const rateLimitKey = `${keyPrefix}:${requesterIdentity}:api:${resolvedName}`;
-    const { allowed, resetIn } = await checkRateLimit({
-      key: rateLimitKey,
-      limit: effectiveApiLimit,
-      windowMs: getProjectConfig().rateLimiting.windowMs
-    });
-    if (!allowed) {
-      void dispatchHook("rateLimitExceeded", {
-        scope: token ? "user" : "route",
-        key: rateLimitKey,
-        limit: effectiveApiLimit,
-        windowMs: getProjectConfig().rateLimiting.windowMs,
-        count: effectiveApiLimit + 1,
-        route: resolvedName,
-        userId: user?.id
-      });
-      if (shouldLogDev()) {
-        getLogger().warn(`api: rate limit exceeded for ${resolvedName}`, { route: resolvedName, key: rateLimitKey });
-      }
-      emitApiError({
-        response: {
-          status: "error",
-          errorCode: "api.rateLimitExceeded",
-          errorParams: [{ key: "seconds", value: resetIn }]
-        },
-        fallbackHttpStatus: 429
-      });
-      return false;
-    }
-  }
-  const defaultIpLimit = getProjectConfig().rateLimiting.defaultIpLimit;
-  if (defaultIpLimit !== false && defaultIpLimit > 0) {
-    const requesterIp = socket.handshake.address ?? "unknown";
-    const { allowed, resetIn } = await checkRateLimit({
-      key: `ip:${requesterIp}:api:all`,
-      limit: defaultIpLimit,
-      windowMs: getProjectConfig().rateLimiting.windowMs
+var runSocketRateLimits = async ({ apiEntry, resolvedName, token, socket, user, emitApiError }) => {
+  const resolvedIp = resolveClientIp({
+    rawAddress: socket.handshake.address,
+    headers: socket.handshake.headers,
+    trustProxy: getProjectConfig4().http.trustProxy,
+    trustedProxyHopCount: getProjectConfig4().http.trustedProxyHopCount
+  });
+  const result = await applyApiRateLimits({
+    resolvedIp,
+    token,
+    user,
+    resolvedName,
+    rateLimit: apiEntry.rateLimit,
+    transport: "socket"
+  });
+  if (!result.allowed) {
+    emitApiError({
+      response: {
+        status: "error",
+        errorCode: result.errorCode ?? "api.rateLimitExceeded",
+        errorParams: [{ key: "seconds", value: result.resetIn ?? 0 }]
+      },
+      fallbackHttpStatus: 429
     });
-    if (!allowed) {
-      void dispatchHook("rateLimitExceeded", {
-        scope: "ip",
-        key: `ip:${requesterIp}:api:all`,
-        limit: defaultIpLimit,
-        windowMs: getProjectConfig().rateLimiting.windowMs,
-        count: defaultIpLimit + 1,
-        ip: requesterIp
-      });
-      if (shouldLogDev()) {
-        getLogger().warn(`api: global IP rate limit exceeded`, { ip: requesterIp });
-      }
-      emitApiError({
-        response: {
-          status: "error",
-          errorCode: "api.rateLimitExceeded",
-          errorParams: [{ key: "seconds", value: resetIn }]
-        },
-        fallbackHttpStatus: 429
-      });
-      return false;
-    }
+    return false;
   }
   return true;
 };
-var executeApiHandler = async ({ apiEntry, normalizedData, user, functionsObject, resolvedName, emitStream, abortSignal, flushPressure }) => {
+var executeApiHandler = async ({ apiEntry, normalizedData, user, functionsObject, resolvedName, emitStream, abortSignal, abortController, flushPressure }) => {
   const executeStart = Date.now();
-  const [error, result] = await tryCatch(
+  const timeoutMs = getProjectConfig4().api.requestTimeoutMs;
+  let timeoutHandle;
+  let timedOut = false;
+  const timeoutPromise = timeoutMs === false ? null : new Promise((resolve) => {
+    timeoutHandle = setTimeout(() => {
+      timedOut = true;
+      abortController.abort();
+      resolve();
+    }, timeoutMs);
+  });
+  const handlerPromise = tryCatch(
     async () => await apiEntry.main({ data: normalizedData, user, functions: functionsObject, stream: emitStream, abortSignal, flushPressure }),
     void 0,
     {
@@ -159,67 +408,59 @@ var executeApiHandler = async ({ apiEntry, normalizedData, user, functionsObject
       transport: "socket"
     }
   );
+  if (timeoutPromise) {
+    await Promise.race([handlerPromise, timeoutPromise]);
+  }
+  clearTimeout(timeoutHandle);
+  if (timedOut) {
+    return { error: null, result: void 0, durationMs: Date.now() - executeStart, timedOut: true };
+  }
+  const [error, result] = await handlerPromise;
   return { error: error ?? null, result: result ?? void 0, durationMs: Date.now() - executeStart };
 };
-var buildApiResponseEnvelope = ({
+var runSocketApiExecution = async ({
+  apiEntry,
   resolvedName,
-  error,
-  result,
-  preferredLocale,
-  user
+  normalizedData,
+  user,
+  functionsObject,
+  emitStream,
+  abortSignal,
+  abortController,
+  flushPressure
 }) => {
-  if (error) {
-    if (shouldLogDev()) {
-      getLogger().error(`api: error in ${resolvedName}`, error, { route: resolvedName });
-    }
-    return { ...normalizeErrorResponse({
-      response: { status: "error", errorCode: "api.internalServerError" },
-      preferredLocale,
-      userLanguage: user?.language,
-      fallbackHttpStatus: 500
-    }) };
-  }
-  if (result === void 0 || result === null) {
-    if (shouldLogDev()) {
-      getLogger().warn(`api: ${resolvedName} returned nothing`);
-    }
-    return { ...normalizeErrorResponse({
-      response: { status: "error", errorCode: "api.emptyResponse" },
-      preferredLocale,
-      userLanguage: user?.language,
-      fallbackHttpStatus: 500
-    }) };
-  }
-  if (shouldLogDev()) {
-    getLogger().debug(`api: ${resolvedName} completed`);
-  }
-  if (result.status !== "success" && result.status !== "error") {
-    return { ...normalizeErrorResponse({
-      response: { status: "error", errorCode: "api.invalidResponseStatus" },
-      preferredLocale,
-      userLanguage: user?.language,
-      fallbackHttpStatus: 500
-    }) };
+  const executePayload = {
+    routeName: resolvedName,
+    data: normalizedData,
+    user,
+    transport: "socket",
+    result: void 0,
+    error: null,
+    durationMs: 0
+  };
+  const preExecuteResult = await dispatchHook3("preApiExecute", executePayload);
+  if (preExecuteResult.stopped) {
+    return { stopped: true, errorCode: preExecuteResult.signal.errorCode, httpStatus: preExecuteResult.signal.httpStatus };
   }
-  if (result.status === "error") {
-    return { ...normalizeErrorResponse({
-      response: result,
-      preferredLocale,
-      userLanguage: user?.language,
-      fallbackHttpStatus: defaultHttpStatusForResponse({
-        status: "error",
-        explicitHttpStatus: typeof result.httpStatus === "number" ? result.httpStatus : void 0
-      })
-    }) };
+  const { error, result, durationMs, timedOut } = await executeApiHandler({
+    apiEntry,
+    normalizedData,
+    user,
+    functionsObject,
+    resolvedName,
+    emitStream,
+    abortSignal,
+    abortController,
+    flushPressure
+  });
+  if (timedOut) {
+    return { stopped: true, errorCode: "api.timeout", httpStatus: 504 };
   }
-  return {
-    ...result,
-    status: "success",
-    httpStatus: defaultHttpStatusForResponse({
-      status: "success",
-      explicitHttpStatus: typeof result.httpStatus === "number" ? result.httpStatus : void 0
-    })
-  };
+  executePayload.result = result;
+  executePayload.error = error ?? null;
+  executePayload.durationMs = durationMs;
+  await dispatchHook3("postApiExecute", executePayload);
+  return { stopped: false, error, result };
 };
 var emitApiResult = async ({
   socket,
@@ -231,17 +472,17 @@ var emitApiResult = async ({
   user,
   perRouteFormatter
 }) => {
-  const envelope = buildApiResponseEnvelope({ resolvedName, error, result, preferredLocale, user });
+  const envelope = normalizeApiResponse({ resolvedName, error, result, preferredLocale, user });
   const preRespond = { routeName: resolvedName, user, response: envelope };
-  const preRespondResult = await dispatchHook("preApiRespond", preRespond);
-  const finalResponse = preRespondResult.stopped ? { ...normalizeErrorResponse({
+  const preRespondResult = await dispatchHook3("preApiRespond", preRespond);
+  const finalResponse = preRespondResult.stopped ? { ...normalizeErrorResponse2({
     response: { status: "error", errorCode: preRespondResult.signal.errorCode },
     preferredLocale,
     userLanguage: user?.language,
     fallbackHttpStatus: preRespondResult.signal.httpStatus ?? 403
   }) } : preRespond.response;
   const transformPayload = { routeName: resolvedName, user, response: finalResponse };
-  await dispatchHook("transformApiResponse", transformPayload);
+  await dispatchHook3("transformApiResponse", transformPayload);
   const formattedResponse = applyErrorFormatter({
     response: transformPayload.response,
     routeName: resolvedName,
@@ -250,28 +491,48 @@ var emitApiResult = async ({
     perRouteFormatter
   });
   socket.emit(buildApiResponseEventName(responseIndex), formattedResponse);
-  await dispatchHook("postApiRespond", { routeName: resolvedName, user, response: formattedResponse });
+  await dispatchHook3("postApiRespond", { routeName: resolvedName, user, response: formattedResponse });
 };
-async function handleApiRequest({ msg, socket, token }) {
+async function handleApiRequest(args) {
+  await runWithErrorTrackerIdentityScope(() => handleApiRequestInner(args));
+}
+async function handleApiRequestInner({ msg, socket, token }) {
   if (typeof msg != "object") {
     if (shouldLogDev()) {
-      getLogger().warn("api: socket message was not a json object");
+      getLogger7().warn("api: socket message was not a json object");
     }
     return;
   }
   const { responseIndex } = msg;
-  const user = await getSession(token);
-  const preferredLocale = extractLanguageFromHeader(socket.handshake.headers["x-language"]) || extractLanguageFromHeader(socket.handshake.headers["accept-language"]) || void 0;
+  const preMsgResult = await dispatchHook3("preSocketMessage", {
+    channel: "api",
+    socketId: socket.id,
+    ip: socket.handshake.address,
+    authenticated: Boolean(token),
+    routeName: typeof msg.name === "string" ? msg.name : void 0
+  });
+  if (preMsgResult.stopped) {
+    socket.emit(buildApiResponseEventName(responseIndex), {
+      status: "error",
+      errorCode: preMsgResult.signal.errorCode,
+      httpStatus: preMsgResult.signal.httpStatus ?? 403
+    });
+    return;
+  }
+  const user = await readSession(token);
+  setCurrentErrorTrackerIdentity(user?.id ? { id: user.id, email: user.email ?? void 0, username: user.name ?? void 0 } : null);
+  const preferredLocale = extractLanguageFromHeader(socket.handshake.headers["x-language"]) ?? extractLanguageFromHeader(socket.handshake.headers["accept-language"]) ?? void 0;
   let currentRouteName;
   let currentPerRouteFormatter;
   const emitApiError = ({ response, fallbackHttpStatus }) => {
-    const normalized = normalizeErrorResponse({
+    const normalized = normalizeErrorResponse2({
       response,
       preferredLocale,
       userLanguage: user?.language,
       fallbackHttpStatus
     });
     const formatted = applyErrorFormatter({
+      // eslint-disable-next-line no-restricted-syntax -- formatter boundary cast, mirrors handleHttpApiRequest
       response: normalized,
       routeName: currentRouteName ?? "api/unknown",
       transport: "socket",
@@ -285,7 +546,7 @@ async function handleApiRequest({ msg, socket, token }) {
   const { name, data: normalizedData } = validated;
   const parsedRoute = parseTransportRouteName({ value: name, prefix: "api" });
   if (parsedRoute.status === "error") {
-    return emitApiError({
+    emitApiError({
       response: {
         status: "error",
         errorCode: "routing.invalidServiceRouteName",
@@ -293,209 +554,209 @@ async function handleApiRequest({ msg, socket, token }) {
       },
       fallbackHttpStatus: 400
     });
+    return;
   }
   const resolvedName = parsedRoute.normalizedFullName;
   currentRouteName = resolvedName;
   if (parsedRoute.serviceRoute.normalizedRouteName === "system/logout") {
-    await logout({ token, socket, userId: user?.id || null });
-    return socket.emit(buildApiResponseEventName(responseIndex), {
-      status: "success",
-      httpStatus: 200,
-      result: true
+    const logoutIpLimit = getProjectConfig4().rateLimiting.defaultIpLimit;
+    if (logoutIpLimit !== false && logoutIpLimit > 0) {
+      const logoutIp = resolveClientIp({
+        rawAddress: socket.handshake.address,
+        headers: socket.handshake.headers,
+        trustProxy: getProjectConfig4().http.trustProxy,
+        trustedProxyHopCount: getProjectConfig4().http.trustedProxyHopCount
+      });
+      const { allowed, resetIn } = await checkRateLimit2({
+        key: `ip:${logoutIp}:api:all`,
+        limit: logoutIpLimit,
+        windowMs: getProjectConfig4().rateLimiting.windowMs
+      });
+      if (!allowed) {
+        void dispatchHook3("rateLimitExceeded", {
+          scope: "ip",
+          key: `ip:${logoutIp}:api:all`,
+          limit: logoutIpLimit,
+          windowMs: getProjectConfig4().rateLimiting.windowMs,
+          count: logoutIpLimit + 1,
+          ip: logoutIp
+        });
+        emitApiError({
+          response: {
+            status: "error",
+            errorCode: "api.rateLimitExceeded",
+            errorParams: [{ key: "seconds", value: resetIn }]
+          },
+          fallbackHttpStatus: 429
+        });
+        return;
+      }
+    }
+    await performLogout({ token, socket, userId: user?.id ?? null });
+    await emitApiResult({
+      socket,
+      responseIndex,
+      resolvedName,
+      error: null,
+      result: { status: "success", httpStatus: 200, result: true },
+      preferredLocale,
+      user
     });
+    return;
   }
   if (shouldLogDev()) {
-    getLogger().debug(`api: ${resolvedName} called`);
+    getLogger7().debug(`api: ${resolvedName} called`);
   }
   const { apisObject, functionsObject } = await getRuntimeApiMaps();
   if (!apisObject[resolvedName]) {
-    return emitApiError({
+    emitApiError({
       response: {
         status: "error",
         errorCode: "api.notFound",
-        errorParams: [{ key: "name", value: name }]
-      },
-      fallbackHttpStatus: 404
-    });
-  }
-  const apiEntry = apisObject[resolvedName];
-  currentPerRouteFormatter = apiEntry.errorFormatter;
-  const abortController = new AbortController();
-  const abortKey = registerApiAbortController(socket.id, responseIndex, abortController);
-  const onSocketDisconnect = () => {
-    abortController.abort();
-  };
-  socket.once(socketEventNames.disconnect, onSocketDisconnect);
-  let cleanupDone = false;
-  const cleanupRequest = () => {
-    if (cleanupDone) return;
-    cleanupDone = true;
-    socket.off(socketEventNames.disconnect, onSocketDisconnect);
-    unregisterApiAbortController(abortKey);
-  };
-  const emitStream = (payload = {}) => {
-    if (abortController.signal.aborted) {
-      if (shouldLogStream()) {
-        getLogger().debug(`api: ${resolvedName} stream skipped \u2014 request aborted`);
-      }
-      return;
-    }
-    if (shouldLogStream()) {
-      getLogger().debug(`api: ${resolvedName} stream`, { payload });
-    }
-    socket.emit(buildApiStreamEventName(responseIndex), payload);
-  };
-  const apiFlushPressure = async ({ thresholdBytes } = {}) => {
-    if (abortController.signal.aborted) return;
-    const effectiveThresholdBytes = typeof thresholdBytes === "number" && thresholdBytes > 0 ? thresholdBytes : 1048576;
-    const packetThreshold = Math.max(1, Math.ceil(effectiveThresholdBytes / 1024));
-    while (true) {
-      if (abortController.signal.aborted) return;
-      const conn = socket.conn;
-      const packets = conn?.writeBuffer?.length ?? 0;
-      const writable = conn?.transport?.writable ?? true;
-      if (!writable) return;
-      if (packets < packetThreshold) return;
-      await new Promise((resolve) => setTimeout(resolve, 10));
-    }
-  };
-  if (!checkApiAuth({ apiEntry, user, name, emitApiError })) {
-    cleanupRequest();
-    return;
-  }
-  const rateLimitOk = await applyApiRateLimits({ apiEntry, resolvedName, token, socket, user, emitApiError });
-  if (!rateLimitOk) {
-    cleanupRequest();
-    return;
-  }
-  const validationMode = (() => {
-    const v = apiEntry.validation;
-    if (!v) return "strict";
-    if (typeof v === "string") return v;
-    return v.input === "skip" ? "relaxed" : "strict";
-  })();
-  if (validationMode === "strict") {
-    warnIfInputTypeMissing(resolvedName, apiEntry.inputType);
-  }
-  await dispatchHook("preApiValidate", { routeName: resolvedName, data: normalizedData, user, transport: "socket" });
-  if (validationMode === "strict") {
-    const inputValidation = await validateInputByType({
-      typeText: apiEntry.inputType,
-      value: normalizedData,
-      rootKey: "data",
-      filePath: apiEntry.inputTypeFilePath
-    });
-    await dispatchHook("postApiValidate", {
-      routeName: resolvedName,
-      data: normalizedData,
-      user,
-      validation: inputValidation,
-      transport: "socket"
-    });
-    if (inputValidation.status === "error") {
-      cleanupRequest();
-      return emitApiError({
-        response: {
-          status: "error",
-          errorCode: "api.invalidInputType",
-          errorParams: [{ key: "message", value: inputValidation.message }]
-        },
-        fallbackHttpStatus: 400
-      });
-    }
-  } else {
-    await dispatchHook("postApiValidate", {
-      routeName: resolvedName,
-      data: normalizedData,
-      user,
-      validation: { status: "success" },
-      transport: "socket"
+        errorParams: [{ key: "name", value: name }]
+      },
+      fallbackHttpStatus: 404
     });
+    return;
   }
-  const executePayload = {
-    routeName: resolvedName,
-    data: normalizedData,
-    user,
-    transport: "socket",
-    result: void 0,
-    error: null,
-    durationMs: 0
-  };
-  const preExecuteResult = await dispatchHook("preApiExecute", executePayload);
-  if (preExecuteResult.stopped) {
+  const apiEntry = apisObject[resolvedName];
+  currentPerRouteFormatter = apiEntry.errorFormatter;
+  const { abortController, abortSignal, emitStream, flushPressure, cleanupRequest } = createApiRequestLifecycle({
+    socket,
+    responseIndex,
+    resolvedName
+  });
+  if (!checkApiAuth({ apiEntry, user, name, emitApiError })) {
     cleanupRequest();
-    return emitApiError({
-      response: { status: "error", errorCode: preExecuteResult.signal.errorCode },
-      fallbackHttpStatus: preExecuteResult.signal.httpStatus ?? 403
-    });
+    return;
+  }
+  const rateLimitOk = await runSocketRateLimits({ apiEntry, resolvedName, token, socket, user, emitApiError });
+  if (!rateLimitOk) {
+    cleanupRequest();
+    return;
   }
-  const { error, result, durationMs } = await executeApiHandler({
+  const validationOk = await runSocketApiValidation({
     apiEntry,
+    resolvedName,
     normalizedData,
     user,
-    functionsObject,
+    cleanupRequest,
+    emitInvalidInputType: () => {
+      emitApiError({
+        response: { status: "error", errorCode: "api.invalidInputType" },
+        fallbackHttpStatus: 400
+      });
+    }
+  });
+  if (!validationOk) return;
+  const execution = await runSocketApiExecution({
+    apiEntry,
     resolvedName,
+    normalizedData,
+    user,
+    functionsObject,
     emitStream,
-    abortSignal: abortController.signal,
-    flushPressure: apiFlushPressure
+    abortSignal,
+    abortController,
+    flushPressure
   });
-  executePayload.result = result;
-  executePayload.error = error ?? null;
-  executePayload.durationMs = durationMs;
-  await dispatchHook("postApiExecute", executePayload);
-  await emitApiResult({ socket, responseIndex, resolvedName, error, result, preferredLocale, user, perRouteFormatter: apiEntry.errorFormatter });
+  if (execution.stopped) {
+    cleanupRequest();
+    emitApiError({
+      response: { status: "error", errorCode: execution.errorCode },
+      fallbackHttpStatus: execution.httpStatus ?? 403
+    });
+    return;
+  }
+  await emitApiResult({ socket, responseIndex, resolvedName, error: execution.error, result: execution.result, preferredLocale, user, perRouteFormatter: apiEntry.errorFormatter });
   cleanupRequest();
 }
 
 // src/handleHttpApiRequest.ts
-import { getSession as getSession2 } from "@luckystack/login";
 import {
-  getProjectConfig as getProjectConfig2,
+  getProjectConfig as getProjectConfig5,
+  readSession as readSession2,
   getRuntimeApiMaps as getRuntimeApiMapsFromSource,
+  runWithErrorTrackerIdentityScope as runWithErrorTrackerIdentityScope2,
+  setCurrentErrorTrackerIdentity as setCurrentErrorTrackerIdentity2,
   validateRequest as validateRequest2,
-  checkRateLimit as checkRateLimit2,
   inferHttpMethod,
   tryCatch as tryCatch2,
   parseTransportRouteName as parseTransportRouteName2,
-  validateInputByType as validateInputByType2,
-  dispatchHook as dispatchHook2,
-  getLogger as getLogger2,
-  defaultHttpStatusForResponse as defaultHttpStatusForResponse2,
+  dispatchHook as dispatchHook5,
+  getLogger as getLogger9,
   extractLanguageFromHeader as extractLanguageFromHeader2,
-  normalizeErrorResponse as normalizeErrorResponse2,
-  applyErrorFormatter as applyErrorFormatter2
+  normalizeErrorResponse as normalizeErrorResponse3,
+  applyErrorFormatter as applyErrorFormatter2,
+  isLoopbackIp,
+  resolveClientIp as resolveClientIp2
 } from "@luckystack/core";
-var httpApiFlushPressureNoop = async () => {
-};
-var isRuntimeApiResult = (value) => {
-  if (!value || typeof value !== "object") {
-    return false;
+
+// src/_shared/httpValidationStage.ts
+import { dispatchHook as dispatchHook4, validateInputByType as validateInputByType2, getLogger as getLogger8 } from "@luckystack/core";
+var runHttpApiValidation = async ({
+  resolvedName,
+  inputType,
+  inputTypeFilePath,
+  requestData,
+  user,
+  validation
+}) => {
+  const validationMode = resolveValidationMode(validation);
+  if (validationMode === "strict") {
+    warnIfInputTypeMissing(resolvedName, inputType);
   }
-  const status = value.status;
-  return status === "success" || status === "error";
-};
-var shouldLogDev2 = () => getProjectConfig2().logging.devLogs;
-var shouldLogStream2 = () => getProjectConfig2().logging.stream;
-var warnedMissingInputType2 = /* @__PURE__ */ new Set();
-var warnIfInputTypeMissing2 = (resolvedName, inputType) => {
-  if (!getProjectConfig2().dev.warnOnMissingInputType) return;
-  if (inputType && inputType.trim().length > 0 && inputType.trim() !== "any") return;
-  if (warnedMissingInputType2.has(resolvedName)) return;
-  warnedMissingInputType2.add(resolvedName);
-  getLogger2().warn(`http-api: route ${resolvedName} has no inputType \u2014 runtime input validation is disabled.`);
+  await dispatchHook4("preApiValidate", { routeName: resolvedName, data: requestData, user, transport: "http" });
+  if (validationMode === "relaxed") {
+    await dispatchHook4("postApiValidate", {
+      routeName: resolvedName,
+      data: requestData,
+      user,
+      validation: { status: "success" },
+      transport: "http"
+    });
+    return { ok: true };
+  }
+  const inputValidation = await validateInputByType2({
+    typeText: inputType,
+    value: requestData,
+    rootKey: "data",
+    filePath: inputTypeFilePath
+  });
+  await dispatchHook4("postApiValidate", {
+    routeName: resolvedName,
+    data: requestData,
+    user,
+    validation: inputValidation,
+    transport: "http"
+  });
+  if (inputValidation.status === "error") {
+    if (shouldLogDev()) {
+      getLogger8().warn(`http-api: input validation failed for ${resolvedName}`, { route: resolvedName, message: inputValidation.message, transport: "http" });
+    }
+    return { ok: false };
+  }
+  return { ok: true };
 };
+
+// src/handleHttpApiRequest.ts
 async function handleHttpApiRequest(params) {
+  return runWithErrorTrackerIdentityScope2(() => handleHttpApiRequestScoped(params));
+}
+async function handleHttpApiRequestScoped(params) {
   const { response, user, preferredLocale, perRouteFormatter } = await runHandleHttpApiRequest(params);
   const routeNameForHook = params.name.startsWith("api/") ? params.name : `api/${params.name}`;
   const preRespond = { routeName: routeNameForHook, user, response };
-  const preRespondResult = await dispatchHook2("preApiRespond", preRespond);
-  const finalResponse = preRespondResult.stopped ? normalizeErrorResponse2({
+  const preRespondResult = await dispatchHook5("preApiRespond", preRespond);
+  const finalResponse = preRespondResult.stopped ? normalizeErrorResponse3({
     response: { status: "error", errorCode: preRespondResult.signal.errorCode },
     preferredLocale,
     userLanguage: user?.language,
     fallbackHttpStatus: preRespondResult.signal.httpStatus ?? 403
   }) : preRespond.response;
-  const formatterInput = finalResponse;
+  const transformPayload = { routeName: routeNameForHook, user, response: finalResponse };
+  await dispatchHook5("transformApiResponse", transformPayload);
+  const formatterInput = transformPayload.response;
   const formattedResponse = applyErrorFormatter2({
     response: formatterInput,
     routeName: routeNameForHook,
@@ -503,57 +764,34 @@ async function handleHttpApiRequest(params) {
     userId: user?.id,
     perRouteFormatter
   });
-  await dispatchHook2("postApiRespond", { routeName: routeNameForHook, user, response: formattedResponse });
+  await dispatchHook5("postApiRespond", { routeName: routeNameForHook, user, response: formattedResponse });
   return formattedResponse;
 }
 async function runHandleHttpApiRequest(params) {
   const preferredLocale = extractLanguageFromHeader2(params.xLanguageHeader) ?? extractLanguageFromHeader2(params.acceptLanguageHeader);
-  const user = await getSession2(params.token);
+  const user = await readSession2(params.token);
+  setCurrentErrorTrackerIdentity2(user?.id ? { id: user.id, email: user.email ?? void 0, username: user.name ?? void 0 } : null);
   const formatterHolder = {};
   const response = await runHandleHttpApiRequestInner(params, user, preferredLocale, formatterHolder);
   return { response, user, preferredLocale, perRouteFormatter: formatterHolder.current };
 }
-async function runHandleHttpApiRequestInner({
-  name,
-  data,
-  token,
-  requesterIp,
-  xLanguageHeader: _xLanguageHeader,
-  acceptLanguageHeader: _acceptLanguageHeader,
-  method = "POST",
-  stream,
-  abortSignal
-}, user, preferredLocale, formatterHolder) {
-  const effectiveAbortSignal = abortSignal ?? new AbortController().signal;
-  const flushPressure = httpApiFlushPressureNoop;
-  const normalizedName = name.startsWith("api/") ? name : `api/${name}`;
-  const buildNetworkError = ({
-    response,
-    fallbackHttpStatus
-  }) => {
-    return normalizeErrorResponse2({
-      response,
-      preferredLocale,
-      userLanguage: user?.language,
-      fallbackHttpStatus
-    });
-  };
+async function validateHttpApiRequestShape(name, data, ctx) {
   if (!name || typeof name !== "string") {
-    return buildNetworkError({
+    return ctx.buildNetworkError({
       response: { status: "error", errorCode: "api.invalidName" },
       fallbackHttpStatus: 400
     });
   }
-  if (typeof data !== "object" || data === null) {
-    return buildNetworkError({
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    return ctx.buildNetworkError({
       response: { status: "error", errorCode: "api.invalidDataObject" },
       fallbackHttpStatus: 400
     });
   }
-  const requestData = data ?? {};
+  const normalizedName = name.startsWith("api/") ? name : `api/${name}`;
   const parsedRoute = parseTransportRouteName2({ value: normalizedName, prefix: "api" });
   if (parsedRoute.status === "error") {
-    return buildNetworkError({
+    return ctx.buildNetworkError({
       response: {
         status: "error",
         errorCode: "routing.invalidServiceRouteName",
@@ -563,12 +801,12 @@ async function runHandleHttpApiRequestInner({
     });
   }
   const resolvedName = parsedRoute.normalizedFullName;
-  if (shouldLogDev2()) {
-    getLogger2().debug(`http api: ${resolvedName} called`);
+  if (shouldLogDev()) {
+    getLogger9().debug(`http api: ${resolvedName} called`);
   }
   const { apisObject, functionsObject } = await getRuntimeApiMapsFromSource();
   if (!apisObject[resolvedName]) {
-    return buildNetworkError({
+    return ctx.buildNetworkError({
       response: {
         status: "error",
         errorCode: "api.notFound",
@@ -577,26 +815,44 @@ async function runHandleHttpApiRequestInner({
       fallbackHttpStatus: 404
     });
   }
-  const runtimeApiRoute = apisObject[resolvedName];
-  formatterHolder.current = runtimeApiRoute.errorFormatter;
-  const { auth, main, httpMethod: declaredMethod } = runtimeApiRoute;
-  const inputType = runtimeApiRoute.inputType;
-  const inputTypeFilePath = runtimeApiRoute.inputTypeFilePath;
-  if (auth.login && !user?.id) {
-    if (shouldLogDev2()) {
-      getLogger2().warn(`http-api: ${name} requires login`, { route: name, transport: "http" });
+  return { resolvedName, requestData: data, apisObject, functionsObject };
+}
+function runHttpApiAuth({
+  name,
+  resolvedName,
+  requesterIp,
+  auth
+}, ctx) {
+  if (auth.login && !ctx.user?.id) {
+    if (shouldLogDev()) {
+      getLogger9().warn(`http-api: ${name} requires login`, { route: name, transport: "http" });
     }
-    return buildNetworkError({
+    void dispatchHook5("apiAuthRejected", {
+      routeName: resolvedName,
+      reason: "login-required",
+      userId: null,
+      transport: "http",
+      ip: requesterIp
+    });
+    return ctx.buildNetworkError({
       response: { status: "error", errorCode: "auth.required" },
       fallbackHttpStatus: 401
     });
   }
-  const authResult = validateRequest2({ auth, user });
+  const authResult = validateRequest2({ auth, user: ctx.user });
   if (authResult.status === "error") {
-    if (shouldLogDev2()) {
-      getLogger2().warn(`http-api: auth failed for ${name}`, { route: name, errorCode: authResult.errorCode, transport: "http" });
+    if (shouldLogDev()) {
+      getLogger9().warn(`http-api: auth failed for ${name}`, { route: name, errorCode: authResult.errorCode, transport: "http" });
     }
-    return buildNetworkError({
+    void dispatchHook5("apiAuthRejected", {
+      routeName: resolvedName,
+      reason: authResult.errorCode === "auth.misconfiguredPredicate" ? "invalid-condition" : "additional-failed",
+      userId: ctx.user?.id ?? null,
+      transport: "http",
+      ip: requesterIp,
+      failedKey: authResult.errorCode
+    });
+    return ctx.buildNetworkError({
       response: {
         status: "error",
         errorCode: authResult.errorCode ?? "auth.forbidden",
@@ -606,77 +862,48 @@ async function runHandleHttpApiRequestInner({
       fallbackHttpStatus: authResult.httpStatus ?? 403
     });
   }
-  const apiRateLimit = runtimeApiRoute.rateLimit;
-  const effectiveApiLimit = apiRateLimit === void 0 ? getProjectConfig2().rateLimiting.defaultApiLimit : apiRateLimit;
-  if (effectiveApiLimit !== false && effectiveApiLimit > 0) {
-    const requesterIdentity = token ?? requesterIp ?? "anonymous";
-    const keyPrefix = token ? "token" : "ip";
-    const rateLimitKey = `${keyPrefix}:${requesterIdentity}:api:${resolvedName}`;
-    const { allowed, resetIn } = await checkRateLimit2({
-      key: rateLimitKey,
-      limit: effectiveApiLimit,
-      windowMs: getProjectConfig2().rateLimiting.windowMs
-    });
-    if (!allowed) {
-      void dispatchHook2("rateLimitExceeded", {
-        scope: token ? "user" : "route",
-        key: rateLimitKey,
-        limit: effectiveApiLimit,
-        windowMs: getProjectConfig2().rateLimiting.windowMs,
-        count: effectiveApiLimit + 1,
-        route: resolvedName,
-        userId: user?.id
-      });
-      if (shouldLogDev2()) {
-        getLogger2().warn(`http api: rate limit exceeded for ${resolvedName}`);
-      }
-      return buildNetworkError({
-        response: {
-          status: "error",
-          errorCode: "api.rateLimitExceeded",
-          errorParams: [{ key: "seconds", value: resetIn }]
-        },
-        fallbackHttpStatus: 429
-      });
-    }
-  }
-  const defaultIpLimit = getProjectConfig2().rateLimiting.defaultIpLimit;
-  const requesterIsLoopback = process.env.NODE_ENV !== "production" && (requesterIp === "127.0.0.1" || requesterIp === "::1" || requesterIp === "::ffff:127.0.0.1" || typeof requesterIp === "string" && requesterIp.startsWith("127."));
-  if (!requesterIsLoopback && defaultIpLimit !== false && defaultIpLimit > 0) {
-    const ipBucket = requesterIp ?? "unknown";
-    const { allowed, resetIn } = await checkRateLimit2({
-      key: `ip:${ipBucket}:api:all`,
-      limit: defaultIpLimit,
-      windowMs: getProjectConfig2().rateLimiting.windowMs
+  return null;
+}
+async function applyHttpApiRateLimits({
+  requesterIp,
+  token,
+  resolvedName,
+  rateLimit
+}, ctx) {
+  const effectiveIp = requesterIp ?? resolveClientIp2({ rawAddress: void 0, headers: {} });
+  const skipGlobalIpForLoopback = getProjectConfig5().rateLimiting.skipLoopbackInDev && process.env.NODE_ENV !== "production" && isLoopbackIp(requesterIp ?? "");
+  const rateLimitResult = await applyApiRateLimits({
+    resolvedIp: effectiveIp,
+    token,
+    user: ctx.user,
+    resolvedName,
+    rateLimit,
+    transport: "http",
+    skipGlobalIpBucket: skipGlobalIpForLoopback
+  });
+  if (!rateLimitResult.allowed) {
+    return ctx.buildNetworkError({
+      response: {
+        status: "error",
+        errorCode: rateLimitResult.errorCode ?? "api.rateLimitExceeded",
+        errorParams: [{ key: "seconds", value: rateLimitResult.resetIn ?? 0 }]
+      },
+      fallbackHttpStatus: 429
     });
-    if (!allowed) {
-      void dispatchHook2("rateLimitExceeded", {
-        scope: "ip",
-        key: `ip:${ipBucket}:api:all`,
-        limit: defaultIpLimit,
-        windowMs: getProjectConfig2().rateLimiting.windowMs,
-        count: defaultIpLimit + 1,
-        ip: ipBucket
-      });
-      if (shouldLogDev2()) {
-        getLogger2().warn(`http api: global IP rate limit exceeded`, { ip: ipBucket });
-      }
-      return buildNetworkError({
-        response: {
-          status: "error",
-          errorCode: "api.rateLimitExceeded",
-          errorParams: [{ key: "seconds", value: resetIn }]
-        },
-        fallbackHttpStatus: 429
-      });
-    }
   }
+  return null;
+}
+function checkHttpApiMethod({
+  method,
+  resolvedName,
+  declaredMethod
+}, ctx) {
   const expectedMethod = declaredMethod ?? inferHttpMethod(resolvedName);
   if (method !== expectedMethod) {
-    if (shouldLogDev2()) {
-      getLogger2().warn(`http api: method mismatch for ${resolvedName}`, { expected: expectedMethod, got: method });
+    if (shouldLogDev()) {
+      getLogger9().warn(`http api: method mismatch for ${resolvedName}`, { expected: expectedMethod, got: method });
     }
-    return buildNetworkError({
+    return ctx.buildNetworkError({
       response: {
         status: "error",
         errorCode: "api.methodNotAllowed",
@@ -685,129 +912,178 @@ async function runHandleHttpApiRequestInner({
       fallbackHttpStatus: 405
     });
   }
-  warnIfInputTypeMissing2(resolvedName, inputType);
-  await dispatchHook2("preApiValidate", { routeName: resolvedName, data: requestData, user, transport: "http" });
-  const inputValidation = await validateInputByType2({
-    typeText: inputType,
-    value: requestData,
-    rootKey: "data",
-    filePath: inputTypeFilePath
-  });
-  await dispatchHook2("postApiValidate", {
-    routeName: resolvedName,
-    data: requestData,
-    user,
-    validation: inputValidation,
-    transport: "http"
-  });
-  if (inputValidation.status === "error") {
-    return buildNetworkError({
-      response: {
-        status: "error",
-        errorCode: "api.invalidInputType",
-        errorParams: [{ key: "message", value: inputValidation.message }]
-      },
-      fallbackHttpStatus: 400
-    });
-  }
+  return null;
+}
+async function runHttpApiExecution({
+  resolvedName,
+  requestData,
+  functionsObject,
+  runtimeApiRoute,
+  effectiveAbortSignal,
+  stream
+}, ctx) {
+  const flushPressure = httpApiFlushPressureNoop;
   const emitApiStream = (payload = {}) => {
     if (!stream) {
       return;
     }
     if (effectiveAbortSignal.aborted) {
-      if (shouldLogStream2()) {
-        getLogger2().debug(`http api: ${resolvedName} stream skipped \u2014 request aborted`);
+      if (shouldLogStream()) {
+        getLogger9().debug(`http api: ${resolvedName} stream skipped \u2014 request aborted`);
       }
       return;
     }
-    if (shouldLogStream2()) {
-      getLogger2().debug(`http api: ${resolvedName} stream`, { payload });
+    if (shouldLogStream()) {
+      getLogger9().debug(`http api: ${resolvedName} stream`, { payload });
     }
     stream(payload);
   };
   const executePayload = {
     routeName: resolvedName,
     data: requestData,
-    user,
+    user: ctx.user,
     transport: "http",
     result: void 0,
     error: null,
     durationMs: 0
   };
-  const preExecuteResult = await dispatchHook2("preApiExecute", executePayload);
+  const preExecuteResult = await dispatchHook5("preApiExecute", executePayload);
   if (preExecuteResult.stopped) {
-    return buildNetworkError({
+    return ctx.buildNetworkError({
       response: { status: "error", errorCode: preExecuteResult.signal.errorCode },
       fallbackHttpStatus: preExecuteResult.signal.httpStatus ?? 403
     });
   }
+  const timeoutMs = getProjectConfig5().api.requestTimeoutMs;
+  const combinedController = new AbortController();
+  if (effectiveAbortSignal.aborted) {
+    combinedController.abort();
+  } else {
+    effectiveAbortSignal.addEventListener("abort", () => {
+      combinedController.abort();
+    }, { once: true });
+  }
+  let timedOut = false;
+  let timeoutHandle;
+  const timeoutPromise = timeoutMs === false ? null : new Promise((resolve) => {
+    timeoutHandle = setTimeout(() => {
+      timedOut = true;
+      combinedController.abort();
+      resolve();
+    }, timeoutMs);
+  });
   const executeStart = Date.now();
-  const [error, result] = await tryCatch2(
-    async () => await main({
+  const handlerPromise = tryCatch2(
+    async () => await runtimeApiRoute.main({
       data: requestData,
-      user,
+      user: ctx.user,
       functions: functionsObject,
       stream: emitApiStream,
-      abortSignal: effectiveAbortSignal,
+      abortSignal: combinedController.signal,
       flushPressure
     }),
     void 0,
     {
       handler: "handleHttpApiRequest",
       api: resolvedName,
-      userId: user?.id,
+      userId: ctx.user?.id,
       transport: "http"
     }
   );
+  if (timeoutPromise) {
+    await Promise.race([handlerPromise, timeoutPromise]);
+  }
+  clearTimeout(timeoutHandle);
+  if (timedOut) {
+    return ctx.buildNetworkError({
+      response: { status: "error", errorCode: "api.timeout" },
+      fallbackHttpStatus: 504
+    });
+  }
+  const [error, result] = await handlerPromise;
   executePayload.result = result;
   executePayload.error = error ?? null;
   executePayload.durationMs = Date.now() - executeStart;
-  await dispatchHook2("postApiExecute", executePayload);
-  if (error) {
-    if (shouldLogDev2()) {
-      getLogger2().error(`http-api: error in ${resolvedName}`, error, { route: resolvedName, transport: "http" });
-    }
-    return buildNetworkError({
-      response: { status: "error", errorCode: "api.internalServerError" },
-      fallbackHttpStatus: 500
+  await dispatchHook5("postApiExecute", executePayload);
+  const envelope = normalizeApiResponse({
+    resolvedName,
+    error: error ?? null,
+    result: result ?? void 0,
+    preferredLocale: ctx.preferredLocale,
+    user: ctx.user
+  });
+  return envelope;
+}
+async function runHandleHttpApiRequestInner({
+  name,
+  data,
+  token,
+  requesterIp,
+  xLanguageHeader: _xLanguageHeader,
+  acceptLanguageHeader: _acceptLanguageHeader,
+  method = "POST",
+  stream,
+  abortSignal
+}, user, preferredLocale, formatterHolder) {
+  const effectiveAbortSignal = abortSignal ?? new AbortController().signal;
+  const buildNetworkError = ({
+    response,
+    fallbackHttpStatus
+  }) => {
+    return normalizeErrorResponse3({
+      response,
+      preferredLocale,
+      userLanguage: user?.language,
+      fallbackHttpStatus
     });
+  };
+  const ctx = { buildNetworkError, user, preferredLocale };
+  const shapeResult = await validateHttpApiRequestShape(name, data, ctx);
+  if ("status" in shapeResult) {
+    return shapeResult;
   }
-  if (result !== void 0 && result !== null) {
-    if (shouldLogDev2()) {
-      getLogger2().debug(`http api: ${resolvedName} completed`);
-    }
-    if (isRuntimeApiResult(result)) {
-      if (result.status === "error") {
-        return buildNetworkError({
-          response: result,
-          fallbackHttpStatus: defaultHttpStatusForResponse2({
-            status: "error",
-            explicitHttpStatus: typeof result.httpStatus === "number" ? result.httpStatus : void 0
-          })
-        });
-      }
-      const successEnvelope = {
-        ...result,
-        status: "success",
-        httpStatus: defaultHttpStatusForResponse2({
-          status: "success",
-          explicitHttpStatus: typeof result.httpStatus === "number" ? result.httpStatus : void 0
-        })
-      };
-      return successEnvelope;
-    }
-    return buildNetworkError({
-      response: { status: "error", errorCode: "api.invalidResponseStatus" },
-      fallbackHttpStatus: 500
-    });
+  const { resolvedName, requestData, apisObject, functionsObject } = shapeResult;
+  const runtimeApiRoute = apisObject[resolvedName];
+  formatterHolder.current = runtimeApiRoute.errorFormatter;
+  const authError = runHttpApiAuth({ name, resolvedName, requesterIp, auth: runtimeApiRoute.auth }, ctx);
+  if (authError) {
+    return authError;
+  }
+  const rateLimitError = await applyHttpApiRateLimits(
+    { requesterIp, token, resolvedName, rateLimit: runtimeApiRoute.rateLimit },
+    ctx
+  );
+  if (rateLimitError) {
+    return rateLimitError;
   }
-  if (shouldLogDev2()) {
-    getLogger2().warn(`http api: ${resolvedName} returned nothing`);
+  const methodError = checkHttpApiMethod(
+    { method, resolvedName, declaredMethod: runtimeApiRoute.httpMethod },
+    ctx
+  );
+  if (methodError) {
+    return methodError;
   }
-  return buildNetworkError({
-    response: { status: "error", errorCode: "api.emptyResponse" },
-    fallbackHttpStatus: 500
+  const httpValidation = await runHttpApiValidation({
+    resolvedName,
+    inputType: runtimeApiRoute.inputType,
+    inputTypeFilePath: runtimeApiRoute.inputTypeFilePath,
+    requestData,
+    user,
+    validation: runtimeApiRoute.validation
   });
+  if (!httpValidation.ok) {
+    return buildNetworkError({
+      response: {
+        status: "error",
+        errorCode: "api.invalidInputType"
+      },
+      fallbackHttpStatus: 400
+    });
+  }
+  return runHttpApiExecution(
+    { resolvedName, requestData, functionsObject, runtimeApiRoute, effectiveAbortSignal, stream },
+    ctx
+  );
 }
 export {
   handleApiRequest,