Introduce a new error type to represent AbortError (google-gemini#357)

* add a new error to represent AbortError from SDK

* changesets

* format

* fix imports order

* update docs

* Revert "update docs"

This reverts commit d00e6eb.

* api docs

* catch AbortError from stream reader

* format

* test

* fix import

Author: hkt74

.changeset/tricky-glasses-open.md

@@ -0,0 +1,5 @@
+---
+"@google/generative-ai": minor
+---
+
+Introduce a new error type to represent AbortError from SDK

common/api-review/generative-ai.api.md

@@ -539,6 +539,10 @@ export class GoogleGenerativeAI {
     getGenerativeModelFromCachedContent(cachedContent: CachedContent, modelParams?: Partial<ModelParams>, requestOptions?: RequestOptions): GenerativeModel;
 }
 
+// @public
+export class GoogleGenerativeAIAbortError extends GoogleGenerativeAIError {
+}
+
 // @public
 export class GoogleGenerativeAIError extends Error {
     constructor(message: string);

docs/reference/main/generative-ai.googlegenerativeaiaborterror.md

@@ -0,0 +1,15 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [GoogleGenerativeAIAbortError](./generative-ai.googlegenerativeaiaborterror.md)
+
+## GoogleGenerativeAIAbortError class
+
+Error thrown when a request is aborted, either due to a timeout or intentional cancellation by the user.
+
+**Signature:**
+
+```typescript
+export declare class GoogleGenerativeAIAbortError extends GoogleGenerativeAIError 
+```
+**Extends:** [GoogleGenerativeAIError](./generative-ai.googlegenerativeaierror.md)
+

docs/reference/main/generative-ai.md

@@ -11,6 +11,7 @@
 |  [ChatSession](./generative-ai.chatsession.md) | ChatSession class that enables sending chat messages and stores history of sent and received messages so far. |
 |  [GenerativeModel](./generative-ai.generativemodel.md) | Class for generative model APIs. |
 |  [GoogleGenerativeAI](./generative-ai.googlegenerativeai.md) | Top-level class for this SDK |
+|  [GoogleGenerativeAIAbortError](./generative-ai.googlegenerativeaiaborterror.md) | Error thrown when a request is aborted, either due to a timeout or intentional cancellation by the user. |
 |  [GoogleGenerativeAIError](./generative-ai.googlegenerativeaierror.md) | Basic error type for this SDK. |
 |  [GoogleGenerativeAIFetchError](./generative-ai.googlegenerativeaifetcherror.md) | Error class covering HTTP errors when calling the server. Includes HTTP status, statusText, and optional details, if provided in the server response. |
 |  [GoogleGenerativeAIRequestInputError](./generative-ai.googlegenerativeairequestinputerror.md) | Errors in the contents of a request originating from user input. |

src/errors.ts

@@ -64,3 +64,10 @@ export class GoogleGenerativeAIFetchError extends GoogleGenerativeAIError {
  * @public
  */
 export class GoogleGenerativeAIRequestInputError extends GoogleGenerativeAIError {}
+
+/**
+ * Error thrown when a request is aborted, either due to a timeout or
+ * intentional cancellation by the user.
+ * @public
+ */
+export class GoogleGenerativeAIAbortError extends GoogleGenerativeAIError {}

src/requests/request.test.ts

@@ -28,6 +28,7 @@ import {
   makeModelRequest,
 } from "./request";
 import {
+  GoogleGenerativeAIAbortError,
   GoogleGenerativeAIFetchError,
   GoogleGenerativeAIRequestInputError,
 } from "../errors";
@@ -228,7 +229,30 @@ describe("request methods", () => {
       });
       expect(response.ok).to.be.true;
     });
-    it("error with timeout", async () => {
+    it("error with local timeout", async () => {
+      const abortError = new DOMException("Request timeout.", "AbortError");
+      const fetchStub = stub().rejects(abortError);
+
+      try {
+        await makeModelRequest(
+          "model-name",
+          Task.GENERATE_CONTENT,
+          "key",
+          true,
+          "",
+          {
+            timeout: 100,
+          },
+          fetchStub as typeof fetch,
+        );
+      } catch (e) {
+        expect((e as GoogleGenerativeAIAbortError).message).to.include(
+          "Request aborted",
+        );
+      }
+      expect(fetchStub).to.be.calledOnce;
+    });
+    it("error with server timeout", async () => {
       const fetchStub = stub().resolves({
         ok: false,
         status: 500,

src/requests/request.ts

@@ -17,6 +17,7 @@
 
 import { RequestOptions, SingleRequestOptions } from "../../types";
 import {
+  GoogleGenerativeAIAbortError,
   GoogleGenerativeAIError,
   GoogleGenerativeAIFetchError,
   GoogleGenerativeAIRequestInputError,
@@ -172,7 +173,12 @@ export async function makeRequest(
 
 function handleResponseError(e: Error, url: string): void {
   let err = e;
-  if (
+  if (err.name === "AbortError") {
+    err = new GoogleGenerativeAIAbortError(
+      `Request aborted when fetching ${url.toString()}: ${e.message}`,
+    );
+    err.stack = e.stack;
+  } else if (
     !(
       e instanceof GoogleGenerativeAIFetchError ||
       e instanceof GoogleGenerativeAIRequestInputError

src/requests/stream-reader.test.ts

@@ -25,6 +25,7 @@ import { restore } from "sinon";
 import * as sinonChai from "sinon-chai";
 import {
   getChunkedStream,
+  getErrorStream,
   getMockResponseStreaming,
 } from "../../test-utils/mock-response";
 import {
@@ -34,6 +35,10 @@ import {
   HarmCategory,
   HarmProbability,
 } from "../../types";
+import {
+  GoogleGenerativeAIAbortError,
+  GoogleGenerativeAIError,
+} from "../errors";
 
 use(sinonChai);
 
@@ -61,6 +66,48 @@ describe("getResponseStream", () => {
     }
     expect(responses).to.deep.equal(src);
   });
+  it("throw AbortError", async () => {
+    const inputStream = getErrorStream(
+      new DOMException("Simulated AbortError", "AbortError"),
+    ).pipeThrough(new TextDecoderStream("utf8", { fatal: true }));
+    const responseStream = getResponseStream<{ text: string }>(inputStream);
+    const reader = responseStream.getReader();
+    const responses: Array<{ text: string }> = [];
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+          break;
+        }
+        responses.push(value);
+      }
+    } catch (e) {
+      expect((e as GoogleGenerativeAIAbortError).message).to.include(
+        "Request aborted",
+      );
+    }
+  });
+  it("throw non AbortError", async () => {
+    const inputStream = getErrorStream(
+      new DOMException("Simulated Error", "RandomError"),
+    ).pipeThrough(new TextDecoderStream("utf8", { fatal: true }));
+    const responseStream = getResponseStream<{ text: string }>(inputStream);
+    const reader = responseStream.getReader();
+    const responses: Array<{ text: string }> = [];
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+          break;
+        }
+        responses.push(value);
+      }
+    } catch (e) {
+      expect((e as GoogleGenerativeAIError).message).to.include(
+        "Error reading from the stream",
+      );
+    }
+  });
 });
 
 describe("processStream", () => {

src/requests/stream-reader.ts

@@ -22,7 +22,10 @@ import {
   GenerateContentStreamResult,
   Part,
 } from "../../types";
-import { GoogleGenerativeAIError } from "../errors";
+import {
+  GoogleGenerativeAIAbortError,
+  GoogleGenerativeAIError,
+} from "../errors";
 import { addHelpers } from "./response-helpers";
 
 const responseLineRE = /^data\: (.*)(?:\n\n|\r\r|\r\n\r\n)/;
@@ -89,38 +92,54 @@ export function getResponseStream<T>(
       let currentText = "";
       return pump();
       function pump(): Promise<(() => Promise<void>) | undefined> {
-        return reader.read().then(({ value, done }) => {
-          if (done) {
-            if (currentText.trim()) {
-              controller.error(
-                new GoogleGenerativeAIError("Failed to parse stream"),
-              );
+        return reader
+          .read()
+          .then(({ value, done }) => {
+            if (done) {
+              if (currentText.trim()) {
+                controller.error(
+                  new GoogleGenerativeAIError("Failed to parse stream"),
+                );
+                return;
+              }
+              controller.close();
               return;
             }
-            controller.close();
-            return;
-          }
 
-          currentText += value;
-          let match = currentText.match(responseLineRE);
-          let parsedResponse: T;
-          while (match) {
-            try {
-              parsedResponse = JSON.parse(match[1]);
-            } catch (e) {
-              controller.error(
-                new GoogleGenerativeAIError(
-                  `Error parsing JSON response: "${match[1]}"`,
-                ),
+            currentText += value;
+            let match = currentText.match(responseLineRE);
+            let parsedResponse: T;
+            while (match) {
+              try {
+                parsedResponse = JSON.parse(match[1]);
+              } catch (e) {
+                controller.error(
+                  new GoogleGenerativeAIError(
+                    `Error parsing JSON response: "${match[1]}"`,
+                  ),
+                );
+                return;
+              }
+              controller.enqueue(parsedResponse);
+              currentText = currentText.substring(match[0].length);
+              match = currentText.match(responseLineRE);
+            }
+            return pump();
+          })
+          .catch((e: Error) => {
+            let err = e;
+            err.stack = e.stack;
+            if (err.name === "AbortError") {
+              err = new GoogleGenerativeAIAbortError(
+                "Request aborted when reading from the stream",
+              );
+            } else {
+              err = new GoogleGenerativeAIError(
+                "Error reading from the stream",
               );
-              return;
             }
-            controller.enqueue(parsedResponse);
-            currentText = currentText.substring(match[0].length);
-            match = currentText.match(responseLineRE);
-          }
-          return pump();
-        });
+            throw err;
+          });
       }
     },
   });

test-utils/mock-response.ts

@@ -48,6 +48,19 @@ export function getChunkedStream(
 
   return stream;
 }
+
+/**
+ * Returns a stream which would throw the given error.
+ */
+export function getErrorStream(err: Error): ReadableStream<Uint8Array> {
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.error(err);
+    },
+  });
+  return stream;
+}
+
 export function getMockResponseStreaming(
   filename: string,
   chunkLength: number = 20,