ai-gateway-proxy 0.2.0 → 0.3.0

package/README.md

@@ -171,7 +171,7 @@ The path, whether from `extractPath` or the route param, must stay relative: one
 
 ### `afterResponse`
 
-- **Non-streamed responses:** receives the gateway's JSON body as `response`, and the value it returns is sent to the client instead, with the gateway's `usage` when the result has none, as on a stream, since an AI SDK client reads usage from every result. `undefined` or `null` forwards the upstream body. Any other result is checked against `GatewayResponse` (see "Result validation" below), and one that fails is answered with a 500 naming the problem instead of being sent.
+- **Non-streamed responses:** receives the gateway's JSON body as `response`, and the value it returns is sent to the client instead, with the gateway's `usage` when the result has none, as on a stream, since an AI SDK client reads usage from every result. `undefined` or `null` forwards the upstream body. Any other result is checked against `GatewayResponse` (see "Result validation" below), and one that fails is answered with a 424 naming the problem instead of being sent. A hook that throws, or a gateway body that is not a JSON object, is a 424 too. The gateway has already answered, and billed, the call by then, and an AI SDK client retries a 5xx but not a 424, so the call is not paid for again.
 - **Streamed responses:** every event is forwarded to the client as it arrives. When the `finish` event comes, the hook receives the aggregated response, and the `finishReason`, `usage` and `providerMetadata` it returns replace those in the `finish` event; content changes have no effect because the content has already been sent. The aggregated response also carries `response`, the `id`, `modelId` and `timestamp` (the ISO string sent over the wire) of the stream's `response-metadata` parts, the latest value of each winning, so a hook can log the provider's response id or the model that answered; it is absent when no part carried them. If the hook throws, or returns a result that fails the check below, `undefined` or `null`, the error is logged and the original `finish` event is forwarded. If the stream ends, fails or is cancelled before its `finish` event, the hook runs once with the content received so far, `incomplete` set (`{ reason: "ended" }`, `{ reason: "error", error }` or `{ reason: "cancelled", cancelReason }`), `response.usage` `undefined` and `response.finishReason` `error` when the read failed or the stream sent an `error` part, `other` otherwise. A client that leaves counts as `cancelled` whether the framework cancels the response body or aborts `request.signal`, and is not logged. Nothing can be rewritten then, so its return value is ignored and a throw is logged. `response.usage` is typed `LanguageModelV4Usage | undefined`, so a hook that meters usage must handle `undefined`.
 - **Event streams and JSON Lines on other calls:** a successful `text/event-stream` or JSON Lines (`application/x-ndjson`, `application/jsonl`) response to a request without `ai-language-model-streaming: true`, such as the video model's `doGenerate` or the batch API's `doGetBatchResults`, is forwarded as is and the hook does not run, since it is not a language model response.
 - **No content:** a `204` or `205` response is forwarded with no body and no `content-type`, keeping the allowlisted headers, and the hook does not run, since there is no response to pass it.
@@ -187,7 +187,7 @@ A result is rejected when it is not an object or when a field is missing or has
 - `warnings`: absent or an array; `@ai-sdk/gateway` reads a missing one as none
 - `providerMetadata`: absent or an object
 
-`null` is accepted wherever a field may be absent, since a body that went through JSON cannot hold `undefined`. Other fields are not checked and are forwarded as returned. A rejected result is logged with `console.error` as `afterResponse hook returned an invalid response: <problem>`, and on a non-streamed request the client gets the same message as a 500 `proxy_error`.
+`null` is accepted wherever a field may be absent, since a body that went through JSON cannot hold `undefined`. Other fields are not checked and are forwarded as returned. A rejected result is logged with `console.error` as `afterResponse hook returned an invalid response: <problem>`, and on a non-streamed request the client gets the same message as a 424 `proxy_error`.
 
 ### `onError`
 
@@ -254,9 +254,10 @@ Apart from forwarding the gateway's own responses, the handler can answer with a
 | 400 | `invalid_request_error` | `Invalid JSON body` | A request other than `GET` or `HEAD` has a non-empty body that is not JSON. |
 | 400 | `invalid_request_error` | `Invalid request body: a language model call must be a JSON object` | The body is JSON but not an object, such as an array or `null`, on a path that runs `beforeRequest`, `afterResponse` or `onError`, and one of them is set. No hook runs and the gateway is not called. |
 | 499 | none | none | The client aborted the request (`request.signal`) before the handler returned. The signal is passed to the upstream `fetch`, so the abort also cancels the upstream request. |
-| 500 | `proxy_error` | `Error proxying request to AI Gateway` | Anything else that throws: `extractPath`, `beforeRequest`, `beforeRawRequest`, the upstream `fetch`, a successful non-streamed response for `afterResponse` that is not a JSON object, `afterResponse` on a non-streamed request or `afterRawResponse`, or an `afterRawResponse` that read the body and returned no `Response`. |
+| 500 | `proxy_error` | `Error proxying request to AI Gateway` | Anything else that throws: `extractPath`, `beforeRequest`, `beforeRawRequest`, the upstream `fetch` or `afterRawResponse`, or an `afterRawResponse` that read the body and returned no `Response`. |
 | 500 | `proxy_error` | `beforeRequest hook returned an invalid request: the result must be an object` | `beforeRequest` returned a value other than an object, `undefined` or `null`. The gateway is not called. |
-| 500 | `proxy_error` | `afterResponse hook returned an invalid response: <problem>` | `afterResponse` on a non-streamed request returned a result that fails the result validation above. |
+| 424 | `proxy_error` | `Error processing the AI Gateway response` | After the gateway answered a non-streamed call with `afterResponse` set: `afterResponse` threw, or the success body was not a JSON object. The status is one AI SDK clients do not retry, since the gateway has billed the call. |
+| 424 | `proxy_error` | `afterResponse hook returned an invalid response: <problem>` | `afterResponse` on a non-streamed request returned a result that fails the result validation above. |
 | 500 | `proxy_error` | `No response body` | A successful streamed response arrived without a body. |
 | 502 | `proxy_error` | `Upstream redirected, the proxy does not follow redirects` | The gateway answered with a 3xx status. The proxy sets `redirect: "manual"`, runs no `onError` and forwards no `Location`. |
 

package/dist/index.cjs

@@ -511,6 +511,8 @@ const NULL_BODY_STATUS = new Set([
     204,
     205
 ]);
+// AI SDK clients retry 408, 409, 429 and any 5xx, which would pay for the answered call again.
+const ANSWERED_CALL_FAILURE_STATUS = 424;
 // Successful bodies that are a sequence of values rather than one JSON value: event streams and JSON Lines.
 const STREAM_CONTENT_TYPE = /^\s*(?:text\/event-stream|application\/(?:x-ndjson|jsonl|jsonlines|x-jsonlines))\s*(?:;|$)/i;
 /**
@@ -773,7 +775,20 @@ function isGatewayError(value) {
 }
 /**
  * Runs afterResponse on a non-streaming JSON response from the gateway.
- */ async function handleJsonResponse(res, requestBody, afterResponse) {
+ * The gateway has answered, and billed, the call, so a failure here gets a status clients do not retry.
+ */ async function handleJsonResponse(res, requestBody, afterResponse, signal) {
+    try {
+        return await runAfterResponse(res, requestBody, afterResponse);
+    } catch (error) {
+        // The handler answers a client abort with 499.
+        if (signal.aborted) {
+            throw error;
+        }
+        console.error("AI Gateway proxy failed after the gateway answered:", error);
+        return proxyErrorResponse(ANSWERED_CALL_FAILURE_STATUS, "proxy_error", "Error processing the AI Gateway response");
+    }
+}
+async function runAfterResponse(res, requestBody, afterResponse) {
     const parsed = await res.json();
     if (!isRecord(parsed)) {
         throw new TypeError("AI Gateway returned a successful body that is not a JSON object");
@@ -793,7 +808,7 @@ function isGatewayError(value) {
         if (problem) {
             const message = `afterResponse hook returned an invalid response: ${problem}`;
             console.error(message);
-            return proxyErrorResponse(500, "proxy_error", message);
+            return proxyErrorResponse(ANSWERED_CALL_FAILURE_STATUS, "proxy_error", message);
         }
         // As on a stream's finish event: the AI SDK reads usage from every generate result, so it cannot be stripped.
         responseBody = {
@@ -843,7 +858,7 @@ function isGatewayError(value) {
     if (!afterResponse || STREAM_CONTENT_TYPE.test(res.headers.get("content-type") ?? "")) {
         return passThroughResponse(res);
     }
-    return await handleJsonResponse(res, requestBody, afterResponse);
+    return await handleJsonResponse(res, requestBody, afterResponse, signal);
 }
 /**
  * Cancels a body nothing will read, since an unread fetch body holds its upstream connection.

package/dist/index.mjs

@@ -509,6 +509,8 @@ const NULL_BODY_STATUS = new Set([
     204,
     205
 ]);
+// AI SDK clients retry 408, 409, 429 and any 5xx, which would pay for the answered call again.
+const ANSWERED_CALL_FAILURE_STATUS = 424;
 // Successful bodies that are a sequence of values rather than one JSON value: event streams and JSON Lines.
 const STREAM_CONTENT_TYPE = /^\s*(?:text\/event-stream|application\/(?:x-ndjson|jsonl|jsonlines|x-jsonlines))\s*(?:;|$)/i;
 /**
@@ -771,7 +773,20 @@ function isGatewayError(value) {
 }
 /**
  * Runs afterResponse on a non-streaming JSON response from the gateway.
- */ async function handleJsonResponse(res, requestBody, afterResponse) {
+ * The gateway has answered, and billed, the call, so a failure here gets a status clients do not retry.
+ */ async function handleJsonResponse(res, requestBody, afterResponse, signal) {
+    try {
+        return await runAfterResponse(res, requestBody, afterResponse);
+    } catch (error) {
+        // The handler answers a client abort with 499.
+        if (signal.aborted) {
+            throw error;
+        }
+        console.error("AI Gateway proxy failed after the gateway answered:", error);
+        return proxyErrorResponse(ANSWERED_CALL_FAILURE_STATUS, "proxy_error", "Error processing the AI Gateway response");
+    }
+}
+async function runAfterResponse(res, requestBody, afterResponse) {
     const parsed = await res.json();
     if (!isRecord(parsed)) {
         throw new TypeError("AI Gateway returned a successful body that is not a JSON object");
@@ -791,7 +806,7 @@ function isGatewayError(value) {
         if (problem) {
             const message = `afterResponse hook returned an invalid response: ${problem}`;
             console.error(message);
-            return proxyErrorResponse(500, "proxy_error", message);
+            return proxyErrorResponse(ANSWERED_CALL_FAILURE_STATUS, "proxy_error", message);
         }
         // As on a stream's finish event: the AI SDK reads usage from every generate result, so it cannot be stripped.
         responseBody = {
@@ -841,7 +856,7 @@ function isGatewayError(value) {
     if (!afterResponse || STREAM_CONTENT_TYPE.test(res.headers.get("content-type") ?? "")) {
         return passThroughResponse(res);
     }
-    return await handleJsonResponse(res, requestBody, afterResponse);
+    return await handleJsonResponse(res, requestBody, afterResponse, signal);
 }
 /**
  * Cancels a body nothing will read, since an unread fetch body holds its upstream connection.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-gateway-proxy",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",