feat(api): add abort signal builder utilities

Author: easonliang28

src/api/providers/__tests__/request-config-builder.spec.ts

@@ -103,6 +103,15 @@ describe("RequestConfigBuilder", () => {
 			expect(config?.headers).toEqual({ "X-Custom": "value1" })
 		})
 
+		test("should do nothing when headers are undefined", () => {
+			const builder = new RequestConfigBuilder({ initial: "value" })
+			const result = builder.addHeaders()
+
+			expect(result).toBe(builder) // chainable
+			const config = builder.build() as Record<string, any>
+			expect(config.headers).toBeUndefined()
+		})
+
 		test("should do nothing when headers object is empty", () => {
 			const builder = new RequestConfigBuilder({ initial: "value" })
 			const result = builder.addHeaders({})
@@ -297,12 +306,62 @@ describe("RequestConfigBuilder", () => {
 		})
 	})
 
+	describe("addMergedSignal", () => {
+		test("should add internal controller signal when metadata and timeout are absent", () => {
+			const internalController = new AbortController()
+			const builder = new RequestConfigBuilder()
+
+			const result = builder.addMergedSignal(internalController)
+
+			expect(result).toBe(builder)
+			const config = builder.build() as { signal?: AbortSignal; _cleanup?: () => void }
+			expect(config.signal).toBe(internalController.signal)
+			expect(config._cleanup).toBeTypeOf("function")
+		})
+
+		test("should merge internal controller signal with metadata abort signal", () => {
+			const internalController = new AbortController()
+			const externalController = new AbortController()
+			const builder = new RequestConfigBuilder()
+
+			builder.addMergedSignal(internalController, {
+				taskId: "test-task",
+				abortSignal: externalController.signal,
+			})
+
+			const config = builder.build() as { signal?: AbortSignal }
+			expect(config.signal).not.toBe(internalController.signal)
+			expect(config.signal).not.toBe(externalController.signal)
+
+			externalController.abort()
+			expect(config.signal?.aborted).toBe(true)
+		})
+
+		test("should merge internal controller signal with timeout", async () => {
+			vi.useFakeTimers()
+			const internalController = new AbortController()
+			const builder = new RequestConfigBuilder()
+
+			builder.addMergedSignal(internalController, undefined, 100)
+
+			const config = builder.build() as { signal?: AbortSignal; _cleanup?: () => void }
+			expect(config.signal).not.toBe(internalController.signal)
+			expect(config.signal?.aborted).toBe(false)
+
+			await vi.advanceTimersByTimeAsync(100)
+
+			expect(config.signal?.aborted).toBe(true)
+			config._cleanup?.()
+			vi.useRealTimers()
+		})
+	})
+
 	describe("static mergeAbortSignals", () => {
-		test("should return merged signal when secondarySignal is undefined", () => {
+		test("should return primary signal directly when secondarySignal is undefined", () => {
 			const controller = new AbortController()
 			const result = RequestConfigBuilder.mergeAbortSignals(controller.signal)
-			// AbortSignal.any() always returns a new signal
-			expect(result).not.toBe(controller.signal)
+
+			expect(result).toBe(controller.signal)
 			expect(result.aborted).toBe(false)
 		})
 

src/api/providers/config-builder/request-config-builder.ts

@@ -1,4 +1,5 @@
 import type { ApiHandlerCreateMessageMetadata } from "../../index"
+import { mergeAbortSignalAndTimeout, mergeAbortSignals } from "../utils/abort-signal"
 
 /**
  * A generic, SDK-agnostic request configuration builder.
@@ -38,8 +39,8 @@ export class RequestConfigBuilder<TOptions extends Record<string, any> = Record<
 	 * @param headers - Key-value pairs of header names and values
 	 * @returns this for chainable calls
 	 */
-	addHeaders(headers: Record<string, string> = {}): this {
-		if (Object.keys(headers).length === 0) {
+	addHeaders(headers?: Record<string, string>): this {
+		if (!headers || Object.keys(headers).length === 0) {
 			return this
 		}
 
@@ -48,6 +49,29 @@ export class RequestConfigBuilder<TOptions extends Record<string, any> = Record<
 		return this
 	}
 
+	/**
+	 * Merge an internal controller signal with an external metadata signal and optional timeout.
+	 *
+	 * Use this for providers that already maintain their own AbortController but also need
+	 * to honor the request-level abort signal from metadata and/or a timeout.
+	 *
+	 * @param internalController - Provider-owned AbortController for the current request
+	 * @param metadata - Optional metadata containing an external abortSignal
+	 * @param timeoutMs - Optional positive timeout in milliseconds; <= 0 disables timeout
+	 * @returns this for chainable calls
+	 */
+	addMergedSignal(
+		internalController: AbortController,
+		metadata?: ApiHandlerCreateMessageMetadata,
+		timeoutMs?: number,
+	): this {
+		const merged = mergeAbortSignalAndTimeout(metadata?.abortSignal, timeoutMs)
+		const signal = mergeAbortSignals(internalController.signal, merged.signal)
+
+		this.options = { ...this.options, signal, _cleanup: merged.cleanup } as TOptions
+		return this
+	}
+
 	/**
 	 * Set a single option by key (type-safe).
 	 *
@@ -118,10 +142,6 @@ export class RequestConfigBuilder<TOptions extends Record<string, any> = Record<
 	 * @returns A merged AbortSignal that aborts when any input signal aborts
 	 */
 	static mergeAbortSignals(primarySignal: AbortSignal, secondarySignal?: AbortSignal): AbortSignal {
-		if (!secondarySignal) {
-			return AbortSignal.any([primarySignal])
-		}
-
-		return AbortSignal.any([primarySignal, secondarySignal])
+		return mergeAbortSignals(primarySignal, secondarySignal)
 	}
 }

src/api/providers/utils/__tests__/abort-signal.spec.ts

@@ -0,0 +1,93 @@
+import { mergeAbortSignalAndTimeout, mergeAbortSignals } from "../abort-signal"
+
+describe("abort-signal utilities", () => {
+	describe("mergeAbortSignalAndTimeout", () => {
+		afterEach(() => {
+			vi.useRealTimers()
+		})
+
+		it("returns no signal and noop cleanup when no signal or positive timeout is provided", () => {
+			const result = mergeAbortSignalAndTimeout(undefined, 0)
+
+			expect(result.signal).toBeUndefined()
+			expect(() => result.cleanup()).not.toThrow()
+		})
+
+		it("forwards external signal directly when timeout is disabled", () => {
+			const controller = new AbortController()
+
+			const result = mergeAbortSignalAndTimeout(controller.signal, -1)
+
+			expect(result.signal).toBe(controller.signal)
+			expect(() => result.cleanup()).not.toThrow()
+		})
+
+		it("creates a timeout signal when only positive timeout is provided", async () => {
+			vi.useFakeTimers()
+
+			const result = mergeAbortSignalAndTimeout(undefined, 100)
+
+			expect(result.signal).toBeInstanceOf(AbortSignal)
+			expect(result.signal?.aborted).toBe(false)
+
+			await vi.advanceTimersByTimeAsync(100)
+
+			expect(result.signal?.aborted).toBe(true)
+		})
+
+		it("merges external signal and timeout signal", async () => {
+			vi.useFakeTimers()
+			const controller = new AbortController()
+
+			const result = mergeAbortSignalAndTimeout(controller.signal, 100)
+
+			expect(result.signal).toBeInstanceOf(AbortSignal)
+			expect(result.signal).not.toBe(controller.signal)
+			expect(result.signal?.aborted).toBe(false)
+
+			controller.abort()
+
+			expect(result.signal?.aborted).toBe(true)
+
+			await vi.advanceTimersByTimeAsync(100)
+			expect(result.signal?.aborted).toBe(true)
+		})
+
+		it("clears timeout during cleanup", async () => {
+			vi.useFakeTimers()
+
+			const result = mergeAbortSignalAndTimeout(undefined, 100)
+			result.cleanup()
+
+			await vi.advanceTimersByTimeAsync(100)
+
+			expect(result.signal?.aborted).toBe(false)
+			expect(vi.getTimerCount()).toBe(0)
+		})
+	})
+
+	describe("mergeAbortSignals", () => {
+		it("returns primary signal directly when secondary signal is absent", () => {
+			const controller = new AbortController()
+
+			const result = mergeAbortSignals(controller.signal)
+
+			expect(result).toBe(controller.signal)
+		})
+
+		it("returns a merged signal when secondary signal is present", () => {
+			const primaryController = new AbortController()
+			const secondaryController = new AbortController()
+
+			const result = mergeAbortSignals(primaryController.signal, secondaryController.signal)
+
+			expect(result).not.toBe(primaryController.signal)
+			expect(result).not.toBe(secondaryController.signal)
+			expect(result.aborted).toBe(false)
+
+			secondaryController.abort()
+
+			expect(result.aborted).toBe(true)
+		})
+	})
+})

src/api/providers/utils/abort-signal.ts

@@ -0,0 +1,49 @@
+export type MergedAbortSignal = {
+	signal?: AbortSignal
+	cleanup: () => void
+}
+
+const noop = () => {}
+
+/**
+ * Merge an optional external abort signal with an optional timeout.
+ *
+ * Timeout values <= 0 are treated as disabled. Call cleanup() from a finally
+ * block to clear any pending timeout created by this helper.
+ */
+export function mergeAbortSignalAndTimeout(externalSignal?: AbortSignal, timeoutMs?: number): MergedAbortSignal {
+	const hasTimeout = typeof timeoutMs === "number" && timeoutMs > 0
+
+	if (!externalSignal && !hasTimeout) {
+		return { cleanup: noop }
+	}
+
+	if (externalSignal && !hasTimeout) {
+		return { signal: externalSignal, cleanup: noop }
+	}
+
+	const timeoutController = new AbortController()
+	const timeoutId = setTimeout(() => timeoutController.abort(), timeoutMs)
+	const cleanup = () => clearTimeout(timeoutId)
+
+	if (!externalSignal) {
+		return { signal: timeoutController.signal, cleanup }
+	}
+
+	return { signal: mergeAbortSignals(externalSignal, timeoutController.signal), cleanup }
+}
+
+/**
+ * Merge two abort signals using the standard AbortSignal.any() API.
+ *
+ * Returns the primary signal directly when no secondary signal is provided to
+ * avoid creating unnecessary controllers/listeners for the common single-signal
+ * path.
+ */
+export function mergeAbortSignals(primarySignal: AbortSignal, secondarySignal?: AbortSignal): AbortSignal {
+	if (!secondarySignal) {
+		return primarySignal
+	}
+
+	return AbortSignal.any([primarySignal, secondarySignal])
+}