cartethyia 2.7.3 → 2.7.5

package/src/transport/guards/body-policy.ts

@@ -4,7 +4,7 @@ import { GatewayError } from "../../protocol/gateway-error";
 import { assertBoundedJsonDepth } from "../../protocol/codecs";
 import type { ProxyRequestStateStore } from "../request/state";
 import { fastPathname } from "../pathname";
-import { NATIVE_SERVICE_PATHS, TOKEN_COUNT_PATH } from "../contracts";
+import { NATIVE_SERVICE_PATHS, RESPONSES_COMPACT_PATH, TOKEN_COUNT_PATH } from "../contracts";
 import { bodyTooLargeError } from "./guard-errors";
 
 /** Whether this request is a gateway (`/v1/*`) request. */
@@ -33,7 +33,7 @@ const PROXY_JSON_ROUTES = [
   "/v1/chat/completions",
   "/v1/responses",
   "/v1/completions",
-  "/v1/responses/compact",
+  RESPONSES_COMPACT_PATH,
   "/v1/messages",
   // Reads a JSON body through the ingress policy but skips the canonical chat
   // stage — see `isOpaqueBodyRoute`. Listed here because this table must mirror
@@ -62,7 +62,7 @@ export function isJsonProxyRoutePath(path: string): boolean {
   return isJsonProxyRoute(path);
 }
 
-export interface IngressPolicyOptions {
+interface IngressPolicyOptions {
   readonly maxBodyBytes?: number;
 }
 
@@ -77,11 +77,11 @@ export async function readIngressBody(
   const isJsonRoute = isJsonProxyRoute(p);
   const contentType = request.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase();
   if (!contentType) {
-    if (isJsonRoute) throw new GatewayError("unsupported_media_type", 415, "This endpoint reads JSON, so the request needs a content-type: application/json header.");
+    if (isJsonRoute) throw new GatewayError("unsupported_media_type", 415, "This endpoint reads JSON, so the request needs a content-type: application/json header (request {requestId}). We speak JSON here — send JSON 💬");
     return undefined;
   }
   if (contentType !== "application/json") {
-    if (isJsonRoute) throw new GatewayError("unsupported_media_type", 415, `This endpoint reads JSON and cannot parse '${contentType}'. Send content-type: application/json.`);
+    if (isJsonRoute) throw new GatewayError("unsupported_media_type", 415, `This endpoint reads JSON and cannot parse '${contentType}' (request {requestId}). Send content-type: application/json. We speak JSON here — send JSON 💬`);
     return undefined;
   }
   const maxBytes = options.maxBodyBytes ?? 1_048_576;
@@ -91,7 +91,7 @@ export async function readIngressBody(
     throw bodyTooLargeError(maxBytes);
 
   const reader = request.body?.getReader();
-  if (!reader) throw new GatewayError("invalid_request", 400, "The request body could not be read. Resend it with a JSON body.");
+  if (!reader) throw new GatewayError("invalid_request", 400, "The request body could not be read (request {requestId}). Resend it with a JSON body. Check the shape of what you sent — then resend 🪞");
   // Collect raw chunks then decode once. String `+=` on each chunk reallocates
   // the accumulating UTF-16 string (O(n²) for large Claude Code prompts);
   // Buffer.concat + one TextDecoder pass is linear and allocation-stable.
@@ -126,7 +126,7 @@ export async function readIngressBody(
     return body;
   } catch (error) {
     if (error instanceof GatewayError) throw error;
-    throw new GatewayError("invalid_request", 400, "The request body is not valid JSON. Check for a trailing comma or an unclosed brace.");
+    throw new GatewayError("invalid_request", 400, "The request body is not valid JSON (request {requestId}). Check for a trailing comma or an unclosed brace. Check the shape of what you sent — then resend 🪞");
   }
 }
 

package/src/transport/guards/error-lifecycle.ts

@@ -49,6 +49,18 @@ function retryAfterSeconds(error: GatewayError | undefined): string | undefined
   return undefined;
 }
 
+/**
+ * Ensures a public message carries the request id. Builders write a
+ * `{requestId}` placeholder in the lead (the canonical convention); anything
+ * that predates the convention gets the id appended so every client-visible
+ * message is correlatable to the server log.
+ */
+function applyRequestId(message: string, requestId: string): string {
+  if (message.includes("{requestId}")) return message.replaceAll("{requestId}", requestId);
+  if (message.includes("(request ")) return message;
+  return `${message} (request ${requestId})`;
+}
+
 /**
  * Normalizes every thrown error (from any lifecycle hook or handler, on
  * `/v1/*` or `/console/api/*`) into the stable public `{ error: { code,
@@ -81,7 +93,8 @@ export function createErrorNormalizationMiddleware(deps: {
         gateway?.status ?? builtinStatus ?? (isBuiltinError || isInputError ? 400 : 500);
       const code =
         gateway?.code ?? builtinCode ?? (isBuiltinError || isInputError ? "invalid_request" : "internal_error");
-      const message =
+      const requestId = state?.requestId ?? crypto.randomUUID();
+      const rawMessage =
         gateway !== undefined
           ? explainGatewayError(gateway)
           : isInputError && error instanceof Error
@@ -90,8 +103,9 @@ export function createErrorNormalizationMiddleware(deps: {
                 code,
                 isBuiltinError
                   ? builtin?.message ?? "Unable to process the request as written."
-                  : "The gateway hit an internal error. Retry; if it persists, the server logs carry the request id.",
+                  : "The gateway hit an internal error. Retry; if it persists, quote the request id to support. Even we have bad days — retry, and quote the id if it persists 🐻",
               );
+      const message = applyRequestId(rawMessage, requestId);
       const origin = gateway?.origin ?? "cartethyia";
       // `afterResponse` telemetry hook can enqueue it even when the request
       // never reached canonical parse / auth / preparation.
@@ -108,7 +122,7 @@ export function createErrorNormalizationMiddleware(deps: {
       if (!state?.canonicalRequest && !state?.authorization)
         metrics.proxy_requests_total.inc(1, { status: "rejected" });
       set.headers["cache-control"] = "no-store";
-      set.headers["x-request-id"] = state?.requestId ?? crypto.randomUUID();
+      set.headers["x-request-id"] = requestId;
       Object.assign(set.headers, GATEWAY_SECURITY_HEADERS);
       if (deps.hsts) set.headers["strict-transport-security"] = "max-age=31536000";
       set.status = status;
@@ -128,6 +142,7 @@ export function createErrorNormalizationMiddleware(deps: {
         error: {
           origin,
           code,
+          requestId,
           message,
           ...(gateway
             ? { details: publicGatewayErrorDetails(gateway) }

package/src/transport/guards/guard-errors.ts

@@ -8,15 +8,19 @@ import { GatewayError } from "../../protocol/gateway-error";
 
 /** Thrown when the request's client peer address cannot be established. */
 export function peerAddressUnavailableError(): GatewayError {
-  return new GatewayError("admission_unavailable", 503, "client peer address unavailable");
+  return new GatewayError(
+    "admission_unavailable",
+    503,
+    "client peer address unavailable (request {requestId}). We couldn't see who's knocking — retry 🚪",
+  );
 }
 
 /** Thrown when the request body exceeds the endpoint's byte budget. */
 export function bodyTooLargeError(maxBytes: number): GatewayError {
   return new GatewayError(
-    "invalid_request",
+    "request_too_large",
     413,
-    `The request body is larger than this endpoint accepts (${maxBytes} bytes). Shorten the prompt or split the request.`,
+    `The request body is larger than this endpoint accepts (${maxBytes} bytes) (request {requestId}). Shorten the prompt or split the request. We love long reads, but not that long 📚`,
   );
 }
 

package/src/transport/guards/headroom-guard.ts

@@ -31,7 +31,7 @@ const SHED_MARKER_TTL_SECONDS = 5;
 const SHED_MARKER_KEY = "gateway:shed:v1";
 const SHED_RETRY_MS = 1_000;
 
-export interface HeadroomGuardDeps {
+interface HeadroomGuardDeps {
   readonly store: ProxyRequestStateStore;
   /**
   * The last sampled memory state, published once per sample by
@@ -90,7 +90,7 @@ export function createHeadroomGuard(deps: HeadroomGuardDeps): Elysia {
       throw new GatewayError(
         "overloaded",
         503,
-        "The gateway is at capacity; retry shortly.",
+        "The gateway is at capacity (request {requestId}); retry shortly. It's not you, it's us — come back in a few minutes ☕️",
         {
           retryAfterMs: SHED_RETRY_MS,
           minFreeBytes: headroom,

package/src/transport/guards/pipeline.ts

@@ -1,4 +1,4 @@
-import { Elysia } from "elysia";
+import { Elysia, type AnyElysia } from "elysia";
 import { createIngressPolicyMiddleware } from "./body-policy";
 import {
   createCanonicalRequestMiddleware,
@@ -35,7 +35,7 @@ import {
 } from "../../observability/payload-capture";
 
 /** Shared state/context carried by every ordered transport stage. */
-export interface TransportPipelineContext {
+interface TransportPipelineContext {
   readonly db: CartethyiaDatabase;
   readonly stateStore: ProxyRequestStateStore;
   readonly surfaceRegistry: SurfaceAdapterRegistry;
@@ -81,9 +81,9 @@ export interface TransportPipelineContext {
  */
 export interface TransportPipeline {
   /** Applies root-scoped request context and error normalization. */
-  mountRoot(app: Elysia<any, any, any, any, any, any, any, any>): void;
+  mountRoot(app: AnyElysia): void;
   /** Builds the complete `/v1/*` gateway plugin around registered routes. */
-  createGateway(registerRoutes: (routes: Elysia<any, any, any, any, any, any, any, any>) => void): Elysia;
+  createGateway(registerRoutes: (routes: AnyElysia) => void): Elysia;
 }
 
 /**
@@ -129,7 +129,7 @@ export function createTransportPipeline(context: TransportPipelineContext): Tran
       preparer: context.preparer,
     }),
   ];
-  const mountRoot = (app: Elysia<any, any, any, any, any, any, any, any>): void => {
+  const mountRoot = (app: AnyElysia): void => {
     app.use(
       createRequestContextMiddleware({
         stateStore: context.stateStore,
@@ -205,8 +205,8 @@ export function createTransportPipeline(context: TransportPipelineContext): Tran
     }
   };
   const createGateway = (
-    registerRoutes: (routes: Elysia<any, any, any, any, any, any, any, any>) => void,
-  ): Elysia<any, any, any, any, any, any, any, any> => {
+    registerRoutes: (routes: AnyElysia) => void,
+  ): AnyElysia => {
     const gateway = new Elysia({ prefix: "/v1" });
     for (const plugin of stages) gateway.use(plugin);
     // No telemetry/cleanup registration here: the lifecycle is owned by

package/src/transport/guards/readiness-guard.ts

@@ -21,8 +21,22 @@ export function createDependencyReadinessMiddleware(deps: ReadinessMiddlewareDep
         throw new GatewayError(notice.code, 503, notice.message);
       }
       const readiness = await deps.readiness();
-      if (readiness.status !== "ready")
-        throw new GatewayError("platform_unavailable", 503, "The gateway's dependencies are not ready, so no request can be served. Retry shortly; if it persists, check the database and coordination backend.");
+      if (readiness.status !== "ready") {
+        // A probe that timed out under load says nothing about the dependencies —
+        // it could not get a backend in time, usually because the process is
+        // saturated. Surface that as overload, not as a broken dependency. A
+        // hard failure (connection refused, migrations missing) keeps the
+        // dependency message, which tells the operator what to actually fix.
+        if (readiness.reason?.endsWith("timed out")) {
+          throw new GatewayError(
+            "overloaded",
+            503,
+            "The gateway is overloaded (request {requestId}); retry shortly. It's not you, it's us — back in a moment ☕️",
+            { retryAfterMs: 1_000 },
+          );
+        }
+        throw new GatewayError("platform_unavailable", 503, "The gateway's dependencies are not ready, so no request can be served (request {requestId}). Retry shortly; if it persists, check the database and coordination backend. Warming up — back in a moment ☕️");
+      }
     })
     .as("plugin");
 }

package/src/transport/guards/request-context.ts

@@ -24,7 +24,7 @@ interface RequestApp {
   ): RequestApp;
 }
 
-export interface RequestContextDeps {
+interface RequestContextDeps {
   readonly stateStore: ProxyRequestStateStore;
   readonly clock?: () => number;
   /** Explicit deadline override; defaults to `CARTETHYIA_UPSTREAM_TIMEOUT_MS` (120s). */
@@ -148,8 +148,7 @@ export function createCanonicalRequestMiddleware(deps: {
       // the JSON routes table, so the body-policy predicate covers it.
       // Native routes (compact, System One) read a body but are never parsed
       // into a canonical request — their bodies are opaque by contract.
-      if (!isJsonProxyRoutePath(path) || path === "/v1/responses/compact" || isOpaqueBodyRoute(path))
-        return;
+      if (!isJsonProxyRoutePath(path) || isOpaqueBodyRoute(path)) return;
       // Model discovery and other GET/multimodal routes must not go through canonical parsing.
       const state = deps.stateStore.require(request);
       // Single-read invariant: the ingress policy middleware already decoded the
@@ -159,7 +158,7 @@ export function createCanonicalRequestMiddleware(deps: {
       // literal `null` body) is a valid single-read value and flows to the
       // surface adapter's parse error rather than triggering a second read.
       if (state.ingressBody === undefined)
-        throw new GatewayError("admission_unavailable", 503, "The request body was never read, so this route cannot be served. Resend the request.");
+        throw new GatewayError("route_unavailable", 503, "The request body was never read, so this route cannot be served (request {requestId}). Resend the request. The bouncer stepped out — resend shortly 🚪");
       const body = state.ingressBody;
       const headers: Record<string, string> = {};
       request.headers.forEach((value, key) => {
@@ -192,7 +191,7 @@ export function createCanonicalRequestMiddleware(deps: {
         throw new GatewayError(
           "capability_unsupported",
           400,
-          `Surface adapter unavailable: ${detection.surface}`,
+          `Surface adapter unavailable: ${detection.surface} (request {requestId}). Know your tools — this one just isn't in the box 🧰`,
           { surface: detection.surface },
         );
       const ingress = deps.stateStore.require(request);
@@ -221,25 +220,21 @@ export function createProxyRoutePreparationMiddleware(deps: {
       if (!path.startsWith("/v1/")) return;
       if (request.method === "GET" || request.method === "HEAD") return;
       const isJsonRoute = isJsonProxyRoutePath(path);
-      if (!isJsonRoute || path === "/v1/responses/compact" || isOpaqueBodyRoute(path)) return;
+      if (!isJsonRoute || isOpaqueBodyRoute(path)) return;
       const state = deps.stateStore.require(request);
       if (!state.authorization || !state.canonicalRequest)
-        throw new GatewayError("admission_unavailable", 503, "The request was not authenticated and parsed, so this route cannot be served. Resend the request.");
+        throw new GatewayError("route_unavailable", 503, "The request was not authenticated and parsed, so this route cannot be served (request {requestId}). Resend the request. The bouncer stepped out — resend shortly 🚪");
       // The key rides along so a strike is charged to the caller that made it.
       // Without it, one recipient of a shared link could escalate a ban onto
-      try {
-        state.preparedRequest = await deps.preparer.prepare({
-          canonicalRequest: state.canonicalRequest,
-          authorization: state.authorization,
-          deadlineMs: state.deadlineMs,
-          signal: state.abortController.signal,
-          ...(state.clientUserAgent === undefined
-            ? {}
-            : { clientUserAgent: state.clientUserAgent }),
-        });
-      } catch (error) {
-        throw error;
-      }
+      state.preparedRequest = await deps.preparer.prepare({
+        canonicalRequest: state.canonicalRequest,
+        authorization: state.authorization,
+        deadlineMs: state.deadlineMs,
+        signal: state.abortController.signal,
+        ...(state.clientUserAgent === undefined
+          ? {}
+          : { clientUserAgent: state.clientUserAgent }),
+      });
     })
     .as("plugin");
 }