@providerkit/core 0.1.0 → 0.2.0

package/src/transport.ts

@@ -4,7 +4,7 @@
 //
 // Adapters keep only their per-event mapping; everything about being an HTTP
 // client lives here once.
-import { classify, isTransportFailure, ProviderError } from "./errors.ts";
+import { classifyHttp, isTransportFailure, ProviderError } from "./errors.ts";
 
 export interface RequestInit_ {
   url: string;
@@ -62,7 +62,7 @@ export function retryAfterFromHeaders(headers: Headers, now = Date.now()): numbe
 /** Turn a non-2xx response into the classified error every caller branches on. */
 async function errorFor(provider: string, res: Response): Promise<ProviderError> {
   const text = await res.text().catch(() => "");
-  const kind = classify({ status: res.status, error: text }, res.status, text);
+  const kind = classifyHttp(res.status, text);
   const message = text
     ? `${provider} ${res.status}: ${text.slice(0, 500)}`
     : `${provider} ${res.status} ${res.statusText}`;
@@ -100,48 +100,57 @@ export async function postJson<T = unknown>(opts: RequestInit_): Promise<T> {
   return (await res.json()) as T;
 }
 
+/** Pull the `data:` payload out of one SSE frame, joining continuation lines
+ *  the way the spec says to. Returns null for a comment or a frame carrying
+ *  only an `event:` name. */
+function payloadOf(frame: string): string | null {
+  const parts: string[] = [];
+  for (const line of frame.split("\n")) {
+    if (!line.startsWith("data:")) continue;
+    parts.push(line.slice(5).replace(/^ /, ""));
+  }
+  // Gemini abandons the framing to report a mid-stream failure: the
+  // google.rpc.Status is appended as a bare JSON object with no `data:` on
+  // it. Dropped here it never reaches an adapter, and a 429 or a 503 that
+  // lands after the headers reads as an empty, successful turn. Requiring an
+  // object keeps comments and `event:`-only frames returning null.
+  if (parts.length === 0) {
+    const bare = frame.trim();
+    return bare.startsWith("{") ? bare : null;
+  }
+  const payload = parts.join("\n").trim();
+  return payload.length > 0 ? payload : null;
+}
+
 /**
- * POST an SSE request and yield each `data:` payload, trimmed.
+ * Yield each `data:` payload of an SSE body, trimmed — plus the bare JSON
+ * object a vendor appends outside the framing, which is only ever an error
+ * (see `payloadOf`).
+ *
+ * Frames are split on the blank line the spec requires, so a payload containing
+ * a bare newline survives; `[DONE]` is swallowed here rather than in every
+ * adapter. CRLF is normalized — some gateways send it, and a `\r` left on the
+ * end of a JSON payload is a parse error nobody enjoys debugging.
  *
- * Frames are split on the blank line the spec requires, so a payload
- * containing a bare newline survives; `[DONE]` is swallowed here rather than in
- * every adapter. CRLF is normalized — some gateways send it, and a `\r` left on
- * the end of a JSON payload is a parse error nobody enjoys debugging.
+ * Exported apart from `streamSse` because the envelope above it is the half an
+ * adopting app most often cannot take: an app with its own translated error
+ * copy, its own log levels, or its own auth refresh has to keep building the
+ * request and reading the failure itself. Framing is the half nobody should
+ * write twice — hand it a `res.body` and keep your own envelope.
  */
-export async function* streamSse(opts: RequestInit_): AsyncGenerator<string> {
-  const res = await send(opts);
-  if (!res.ok) throw await errorFor(opts.provider, res);
-  // A 2xx with no body at all is an upstream anomaly, not a request we got
-  // wrong — worth the same retry a 5xx gets.
-  if (!res.body) {
-    throw new ProviderError(opts.provider, "overload", `${opts.provider}: empty response body`, {
-      status: res.status,
-    });
-  }
-
-  const reader = res.body.getReader();
+export async function* parseSseStream(body: ReadableStream<Uint8Array>): AsyncGenerator<string> {
+  const reader = body.getReader();
   const decoder = new TextDecoder();
   let buffer = "";
-
-  /** Pull the `data:` payload out of one SSE frame, joining continuation
-   *  lines the way the spec says to. Returns null for a comment or a frame
-   *  carrying only an `event:` name. */
-  function payloadOf(frame: string): string | null {
-    const parts: string[] = [];
-    for (const line of frame.split("\n")) {
-      if (!line.startsWith("data:")) continue;
-      parts.push(line.slice(5).replace(/^ /, ""));
-    }
-    if (parts.length === 0) return null;
-    const payload = parts.join("\n").trim();
-    return payload.length > 0 ? payload : null;
-  }
-
   try {
     for (;;) {
       const { done, value } = await reader.read();
       if (done) break;
-      buffer += decoder.decode(value, { stream: true }).replace(/\r\n/g, "\n");
+      // Normalized on the BUFFER, not on the decoded read: a network read can
+      // end between the CR and the LF, and normalizing each read separately
+      // leaves that CR stranded on the end of a payload — a JSON parse error
+      // that only ever reproduces under a particular packet split.
+      buffer = (buffer + decoder.decode(value, { stream: true })).replace(/\r\n/g, "\n");
 
       let boundary = buffer.indexOf("\n\n");
       while (boundary !== -1) {
@@ -160,3 +169,20 @@ export async function* streamSse(opts: RequestInit_): AsyncGenerator<string> {
     reader.releaseLock();
   }
 }
+
+/**
+ * POST an SSE request and stream its payloads: the envelope (auth, the
+ * classified error, the retry hints) plus `parseSseStream`.
+ */
+export async function* streamSse(opts: RequestInit_): AsyncGenerator<string> {
+  const res = await send(opts);
+  if (!res.ok) throw await errorFor(opts.provider, res);
+  // A 2xx with no body at all is an upstream anomaly, not a request we got
+  // wrong — worth the same retry a 5xx gets.
+  if (!res.body) {
+    throw new ProviderError(opts.provider, "overload", `${opts.provider}: empty response body`, {
+      status: res.status,
+    });
+  }
+  yield* parseSseStream(res.body);
+}