(feat, typescript): accept abort signals as request options (#3694)

fern-api · May 24, 2024 · b0bcea3 · b0bcea3
1 parent c222939
commit b0bcea3
Show file tree

Hide file tree

Showing 311 changed files with 4,799 additions and 56,261 deletions.
diff --git a/generators/typescript/sdk/CHANGELOG.md b/generators/typescript/sdk/CHANGELOG.md
@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.20.0-rc0] - 2024-05-20
+
+- Feature: Add `abortSignal` to `RequestOptions`. SDK consumers can now specify an
+  an arbitrary abort signal that can interrupt the API call.
+
+  ```ts
+  const controller = new AbortController();
+  client.endpoint.call(..., {
+    abortSignal: controller.signal,
+  })
+  ```
+
 ## [0.19.0] - 2024-05-20
 
 - Feature: Add `inlineFileProperties` configuration to support generating file upload properties

diff --git a/generators/typescript/sdk/VERSION b/generators/typescript/sdk/VERSION
@@ -1 +1 @@
-0.19.0
+0.20.0-rc0
diff --git a/generators/typescript/sdk/client-class-generator/src/GeneratedSdkClientClassImpl.ts b/generators/typescript/sdk/client-class-generator/src/GeneratedSdkClientClassImpl.ts
@@ -69,6 +69,7 @@ export class GeneratedSdkClientClassImpl implements GeneratedSdkClientClass {
     private static REQUEST_OPTIONS_INTERFACE_NAME = "RequestOptions";
     private static IDEMPOTENT_REQUEST_OPTIONS_INTERFACE_NAME = "IdempotentRequestOptions";
     private static TIMEOUT_IN_SECONDS_REQUEST_OPTION_PROPERTY_NAME = "timeoutInSeconds";
+    private static ABORT_SIGNAL_PROPERTY_NAME = "abortSignal";
     private static MAX_RETRIES_REQUEST_OPTION_PROPERTY_NAME = "maxRetries";
     private static OPTIONS_INTERFACE_NAME = "Options";
     private static OPTIONS_PRIVATE_MEMBER = "_options";
@@ -766,6 +767,11 @@ export class GeneratedSdkClientClassImpl implements GeneratedSdkClientClass {
                     name: GeneratedSdkClientClassImpl.MAX_RETRIES_REQUEST_OPTION_PROPERTY_NAME,
                     type: getTextOfTsNode(ts.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword)),
                     hasQuestionToken: true
+                },
+                {
+                    name: GeneratedSdkClientClassImpl.ABORT_SIGNAL_PROPERTY_NAME,
+                    type: getTextOfTsNode(ts.factory.createIdentifier("AbortSignal")),
+                    hasQuestionToken: true
                 }
             ]
         };
@@ -1125,6 +1131,18 @@ export class GeneratedSdkClientClassImpl implements GeneratedSdkClientClass {
               );
     }
 
+    public getReferenceToAbortSignal({
+        referenceToRequestOptions
+    }: {
+        referenceToRequestOptions: ts.Expression;
+    }): ts.Expression {
+        return ts.factory.createPropertyAccessChain(
+            referenceToRequestOptions,
+            ts.factory.createToken(ts.SyntaxKind.QuestionDotToken),
+            ts.factory.createIdentifier(GeneratedSdkClientClassImpl.ABORT_SIGNAL_PROPERTY_NAME)
+        );
+    }
+
     public getReferenceToOptions(): ts.Expression {
         return ts.factory.createPropertyAccessExpression(
             ts.factory.createThis(),

diff --git a/...t/sdk/client-class-generator/src/endpoints/GeneratedFileDownloadEndpointImplementation.ts b/...t/sdk/client-class-generator/src/endpoints/GeneratedFileDownloadEndpointImplementation.ts
@@ -7,6 +7,7 @@ import { GeneratedSdkClientClassImpl } from "../GeneratedSdkClientClassImpl";
 import { GeneratedEndpointResponse } from "./default/endpoint-response/GeneratedEndpointResponse";
 import { buildUrl } from "./utils/buildUrl";
 import {
+    getAbortSignalExpression,
     getMaxRetriesExpression,
     getRequestOptionsParameter,
     getTimeoutExpression
@@ -160,6 +161,11 @@ export class GeneratedFileDownloadEndpointImplementation implements GeneratedEnd
                     this.generatedSdkClientClass
                 )
             }),
+            abortSignal: getAbortSignalExpression({
+                abortSignalReference: this.generatedSdkClientClass.getReferenceToAbortSignal.bind(
+                    this.generatedSdkClientClass
+                )
+            }),
             withCredentials: this.includeCredentialsOnCrossOriginRequests,
             responseType: visitJavaScriptRuntime(context.targetRuntime, {
                 browser: () => "blob",

diff --git a/...ript/sdk/client-class-generator/src/endpoints/GeneratedStreamingEndpointImplementation.ts b/...ript/sdk/client-class-generator/src/endpoints/GeneratedStreamingEndpointImplementation.ts
@@ -7,6 +7,7 @@ import { GeneratedSdkClientClassImpl } from "../GeneratedSdkClientClassImpl";
 import { GeneratedEndpointResponse } from "./default/endpoint-response/GeneratedEndpointResponse";
 import { buildUrl } from "./utils/buildUrl";
 import {
+    getAbortSignalExpression,
     getMaxRetriesExpression,
     getRequestOptionsParameter,
     getTimeoutExpression
@@ -131,6 +132,11 @@ export class GeneratedStreamingEndpointImplementation implements GeneratedEndpoi
                     this.generatedSdkClientClass
                 )
             }),
+            abortSignal: getAbortSignalExpression({
+                abortSignalReference: this.generatedSdkClientClass.getReferenceToAbortSignal.bind(
+                    this.generatedSdkClientClass
+                )
+            }),
             responseType: "streaming",
             withCredentials: this.includeCredentialsOnCrossOriginRequests
         };

diff --git a/...dk/client-class-generator/src/endpoints/default/GeneratedDefaultEndpointImplementation.ts b/...dk/client-class-generator/src/endpoints/default/GeneratedDefaultEndpointImplementation.ts
@@ -6,6 +6,7 @@ import { GeneratedEndpointRequest } from "../../endpoint-request/GeneratedEndpoi
 import { GeneratedSdkClientClassImpl } from "../../GeneratedSdkClientClassImpl";
 import { buildUrl } from "../utils/buildUrl";
 import {
+    getAbortSignalExpression,
     getMaxRetriesExpression,
     getRequestOptionsParameter,
     getTimeoutExpression,
@@ -206,6 +207,12 @@ export class GeneratedDefaultEndpointImplementation implements GeneratedEndpoint
                     this.generatedSdkClientClass
                 )
             }),
+            abortSignal: getAbortSignalExpression({
+                abortSignalReference: this.generatedSdkClientClass.getReferenceToAbortSignal.bind(
+                    this.generatedSdkClientClass
+                )
+            }),
+
             withCredentials: this.includeCredentialsOnCrossOriginRequests
         };
 

diff --git a/...tors/typescript/sdk/client-class-generator/src/endpoints/utils/requestOptionsParameter.ts b/...tors/typescript/sdk/client-class-generator/src/endpoints/utils/requestOptionsParameter.ts
@@ -63,3 +63,13 @@ export const getMaxRetriesExpression = ({
         isNullable: true
     });
 };
+
+export const getAbortSignalExpression = ({
+    abortSignalReference
+}: {
+    abortSignalReference: (args: { referenceToRequestOptions: ts.Expression }) => ts.Expression;
+}): ts.Expression => {
+    return abortSignalReference({
+        referenceToRequestOptions: ts.factory.createIdentifier(REQUEST_OPTIONS_PARAMETER_NAME)
+    });
+};
diff --git a/generators/typescript/utils/commons/src/core-utilities/fetcher/Fetcher.ts b/generators/typescript/utils/commons/src/core-utilities/fetcher/Fetcher.ts
@@ -90,6 +90,7 @@ export declare namespace Fetcher {
         contentType?: string | ts.Expression;
         queryParameters: ts.Expression | undefined;
         body: ts.Expression | undefined;
+        abortSignal: ts.Expression | undefined;
         withCredentials: boolean;
         timeoutInSeconds: ts.Expression;
         maxRetries?: ts.Expression;

diff --git a/generators/typescript/utils/commons/src/core-utilities/fetcher/FetcherImpl.ts b/generators/typescript/utils/commons/src/core-utilities/fetcher/FetcherImpl.ts
@@ -38,7 +38,8 @@ export class FetcherImpl extends CoreUtility implements Fetcher {
                 body: "body",
                 timeoutMs: "timeoutMs",
                 withCredentials: "withCredentials",
-                responseType: "responseType"
+                responseType: "responseType",
+                abortSignal: "abortSignal"
             },
             _getReferenceToType: this.getReferenceToTypeInFetcherModule("Args")
         },
@@ -132,6 +133,11 @@ export class FetcherImpl extends CoreUtility implements Fetcher {
                     )
                 );
             }
+            if (args.abortSignal) {
+                properties.push(
+                    ts.factory.createPropertyAssignment(this.Fetcher.Args.properties.abortSignal, args.abortSignal)
+                );
+            }
 
             return ts.factory.createAwaitExpression(
                 ts.factory.createCallExpression(referenceToFetcher, cast != null ? [cast] : [], [

diff --git a/generators/typescript/utils/core-utilities/fetcher/.depcheckrc.json b/generators/typescript/utils/core-utilities/fetcher/.depcheckrc.json
@@ -1 +1 @@
-{ "ignores": ["@types/jest", "@types/node"], "ignore-patterns": ["lib"] }
+{ "ignores": ["@types/jest", "@types/node", "node-fetch", "qs", "@types/node-fetch", "@types/qs"], "ignore-patterns": ["lib"] }
diff --git a/generators/typescript/utils/core-utilities/fetcher/.mrlint.json b/generators/typescript/utils/core-utilities/fetcher/.mrlint.json
@@ -5,6 +5,9 @@
   "rules": {
     "duplicate-dependencies": {
       "exclude": ["@fern-fern/ir-sdk"]
+    },
+    "depcheck": {
+      "ignores": ["@types/jest", "@types/node", "node-fetch", "qs", "@types/node-fetch", "@types/qs"]
     }
   }
 }
diff --git a/generators/typescript/utils/core-utilities/fetcher/src/fetcher/Fetcher.ts b/generators/typescript/utils/core-utilities/fetcher/src/fetcher/Fetcher.ts
@@ -15,6 +15,7 @@ export declare namespace Fetcher {
         timeoutMs?: number;
         maxRetries?: number;
         withCredentials?: boolean;
+        abortSignal?: AbortSignal;
         responseType?: "json" | "blob" | "streaming" | "text";
     }
 
@@ -103,21 +104,33 @@ async function fetcherImpl<R = unknown>(args: Fetcher.Args): Promise<APIResponse
             : ((await import("node-fetch")).default as any);
 
     const makeRequest = async (): Promise<Response> => {
-        const controller = new AbortController();
-        let abortId = undefined;
+        const signals: AbortSignal[] = [];
+
+        // Add timeout signal
+        let timeoutAbortId: NodeJS.Timeout | undefined = undefined;
         if (args.timeoutMs != null) {
-            abortId = setTimeout(() => controller.abort(), args.timeoutMs);
+            const { signal, abortId } = getTimeoutSignal(args.timeoutMs);
+            timeoutAbortId = abortId;
+            signals.push(signal);
+        }
+
+        // Add arbitrary signal
+        if (args.abortSignal != null) {
+            signals.push(args.abortSignal);
         }
+
         const response = await fetchFn(url, {
             method: args.method,
             headers,
             body,
-            signal: controller.signal,
+            signal: anySignal(signals),
             credentials: args.withCredentials ? "include" : undefined
         });
-        if (abortId != null) {
-            clearTimeout(abortId);
+
+        if (timeoutAbortId != null) {
+            clearTimeout(timeoutAbortId);
         }
+
         return response;
     };
 
@@ -181,7 +194,15 @@ async function fetcherImpl<R = unknown>(args: Fetcher.Args): Promise<APIResponse
             };
         }
     } catch (error) {
-        if (error instanceof Error && error.name === "AbortError") {
+        if (args.abortSignal != null && args.abortSignal.aborted) {
+            return {
+                ok: false,
+                error: {
+                    reason: "unknown",
+                    errorMessage: "The user aborted a request"
+                }
+            };
+        } else if (error instanceof Error && error.name === "AbortError") {
             return {
                 ok: false,
                 error: {
@@ -208,4 +229,43 @@ async function fetcherImpl<R = unknown>(args: Fetcher.Args): Promise<APIResponse
     }
 }
 
+const TIMEOUT = "timeout";
+
+function getTimeoutSignal(timeoutMs: number): { signal: AbortSignal; abortId: NodeJS.Timeout } {
+    const controller = new AbortController();
+    const abortId = setTimeout(() => controller.abort(TIMEOUT), timeoutMs);
+    return { signal: controller.signal, abortId };
+}
+
+/**
+ * Returns an abort signal that is getting aborted when
+ * at least one of the specified abort signals is aborted.
+ *
+ * Requires at least node.js 18.
+ */
+function anySignal(...args: AbortSignal[] | [AbortSignal[]]): AbortSignal {
+    // Allowing signals to be passed either as array
+    // of signals or as multiple arguments.
+    const signals = <AbortSignal[]>(args.length === 1 && Array.isArray(args[0]) ? args[0] : args);
+
+    const controller = new AbortController();
+
+    for (const signal of signals) {
+        if (signal.aborted) {
+            // Exiting early if one of the signals
+            // is already aborted.
+            controller.abort((signal as any)?.reason);
+            break;
+        }
+
+        // Listening for signals and removing the listeners
+        // when at least one symbol is aborted.
+        signal.addEventListener("abort", () => controller.abort((signal as any)?.reason), {
+            signal: controller.signal
+        });
+    }
+
+    return controller.signal;
+}
+
 export const fetcher: FetchFunction = fetcherImpl;
diff --git a/generators/typescript/utils/core-utilities/fetcher/src/stream/Stream.ts b/generators/typescript/utils/core-utilities/fetcher/src/stream/Stream.ts
@@ -11,6 +11,10 @@ export declare namespace Stream {
          * The event shape to use for parsing the stream data.
          */
         eventShape: JsonEvent | SseEvent;
+        /**
+         * An abort signal to stop the stream.
+         */
+        signal?: AbortSignal;
     }
 
     interface JsonEvent {
@@ -36,8 +40,9 @@ export class Stream<T> implements AsyncIterable<T> {
     private prefix: string | undefined;
     private messageTerminator: string;
     private streamTerminator: string | undefined;
+    private controller: AbortController = new AbortController();
 
-    constructor({ stream, parse, eventShape }: Stream.Args & { parse: (val: unknown) => Promise<T> }) {
+    constructor({ stream, parse, eventShape, signal }: Stream.Args & { parse: (val: unknown) => Promise<T> }) {
         this.stream = stream;
         this.parse = parse;
         if (eventShape.type === "sse") {
@@ -47,9 +52,11 @@ export class Stream<T> implements AsyncIterable<T> {
         } else {
             this.messageTerminator = eventShape.messageTerminator;
         }
+        signal?.addEventListener("abort", () => this.controller.abort());
     }
 
     private async *iterMessages(): AsyncGenerator<T, void> {
+        this.controller.signal;
         const stream = readableStreamAsyncIterable<any>(this.stream);
         let buf = "";
         let prefixSeen = false;

diff --git a/packages/cli/ete-tests/src/tests/fetcher/fetcher.test.ts b/packages/cli/ete-tests/src/tests/fetcher/fetcher.test.ts
@@ -115,4 +115,69 @@ describe("Fetcher Tests", () => {
             process.stdout.write(JSON.stringify(message));
         }
     }, 90_000);
+
+    it.skip("abort while making request", async () => {
+        const controller = new AbortController();
+        const call = fetcher<stream.Readable>({
+            url: "https://api.cohere.ai/v1/chat",
+            method: "POST",
+            responseType: "streaming",
+            headers: {
+                Authorization: "Bearer <>",
+                "Content-Type": "application/json"
+            },
+            body: {
+                message: "Write a long essay about devtools",
+                stream: true
+            },
+            // timeoutMs: 10,
+            abortSignal: controller.signal
+        });
+        controller.abort();
+        const response = await call;
+        expect(response.ok).toEqual(false);
+        if (response.ok) {
+            throw new Error("Expected response to fail");
+        }
+        expect(response.error.reason === "unknown" && response.error.errorMessage.includes("aborted")).toBe(true);
+    }, 90_000);
+
+    it.skip("abort while streaming events", async () => {
+        const controller = new AbortController();
+        const response = await fetcher<stream.Readable>({
+            url: "https://api.cohere.ai/v1/chat",
+            method: "POST",
+            responseType: "streaming",
+            headers: {
+                Authorization: "Bearer ",
+                "Content-Type": "application/json"
+            },
+            body: {
+                message: "Write a long essay about devtools",
+                stream: true
+            },
+            // timeoutMs: 10,
+            abortSignal: controller.signal
+        });
+        expect(response.ok).toEqual(true);
+        if (!response.ok) {
+            throw new Error("Response failed");
+        }
+        const stream = new Stream<unknown>({
+            stream: response.body,
+            parse: async (data) => data,
+            eventShape: {
+                type: "json",
+                messageTerminator: "\n"
+            }
+        });
+        let i = 1;
+        for await (const event of stream) {
+            if (i === 10) {
+                controller.abort();
+            }
+            console.log(JSON.stringify(event));
+            i += 1;
+        }
+    }, 90_000);
 });
diff --git a/seed/ts-sdk/api-wide-base-path/src/Client.ts b/seed/ts-sdk/api-wide-base-path/src/Client.ts