Skip to content

Commit 05d683a

Browse files
easonLiangWorldedtecheasonliang28easonLiangWorldedtech
authored
feat(api): shared abort-signal cancellation-scope helpers (Zoo-Code-Org#1651)
* feat(api): add abort-signal cancellation-scope helpers to the shared utils Extend src/api/providers/utils/abort-signal.ts with the abort-signal series helpers used by the gateway providers: - isRequestAborted(error, signal): wider abort detection - an aborted signal, a DOM AbortError, the OpenAI/Anthropic SDK APIUserAbortError (name check), or the exact SDK abort message "Request was aborted." - trusting name/message only on real Error instances so a plain object that merely looks like an abort propagates unchanged - createAbortError(providerName): fresh error satisfying the Task.ts abort contract (name "AbortError", message ending in "aborted") - rejectOnAbort(pending, signal, providerName): settle a signal-less async phase (model discovery) on the provider AbortError when the signal fires first; the abort listener detaches when pending settles - resolveModelWithAbort(fetchModel, signal, providerName): run model resolution inside a cancellation scope - entry fast-fail for a pre-aborted signal, the rejectOnAbort race while the lookup is pending, and normalization of abort-flavored lookup failures; any other resolution failure propagates unchanged Includes direct unit tests for the resolveModelWithAbort cancellation scope (pre-aborted fast-fail, no-signal pass-through, mid-resolution race, abort normalization, non-abort propagation), the isRequestAborted instanceof tightening tests, and the settle-guard test utility. Unit 1/3 of the Zoo-Code-Org#1295 split (content source: 62f596c). Part of the abort-signal series (round 1). Builds on Zoo-Code-Org#674, Zoo-Code-Org#901, Zoo-Code-Org#1008. Addresses Zoo-Code-Org#404. * fix: restore throwIfAborted export dropped by the util rewrite (+ tests) * fix(abort-r1): handle a rejecting pending promise in rejectOnAbort's pre-aborted branch * test(abort-r1): remove the process listener on every exit path * chore: trigger CodeRabbit re-review (findings already addressed) --------- Co-authored-by: Eason Liang <[email protected]> Co-authored-by: easonLiangWorldedtech <[email protected]>
1 parent 2157677 commit 05d683a

3 files changed

Lines changed: 337 additions & 11 deletions

File tree

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

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,227 @@ import {
33
isRequestAborted,
44
mergeAbortSignalAndTimeout,
55
mergeAbortSignals,
6+
rejectOnAbort,
7+
resolveModelWithAbort,
68
throwIfAborted,
79
} from "../abort-signal"
10+
import { withSettleGuard } from "../../../../test-utils/settle-guard"
11+
12+
describe("rejectOnAbort", () => {
13+
it("resolves with the pending value when it settles before the signal aborts", async () => {
14+
const controller = new AbortController()
15+
16+
await expect(
17+
withSettleGuard(rejectOnAbort(Promise.resolve("done"), controller.signal, "TestProvider")),
18+
).resolves.toBe("done")
19+
expect(controller.signal.aborted).toBe(false)
20+
})
21+
22+
it("rejects with the provider abort error when the signal aborts first", async () => {
23+
const controller = new AbortController()
24+
// Never settles: the race must end purely via the abort.
25+
const pending = new Promise<never>(() => {})
26+
const race = rejectOnAbort(pending, controller.signal, "TestProvider")
27+
controller.abort()
28+
29+
await expect(withSettleGuard(race)).rejects.toMatchObject({
30+
name: "AbortError",
31+
message: "The TestProvider request was aborted",
32+
})
33+
})
34+
35+
it("rejects immediately when the signal is already aborted", async () => {
36+
const controller = new AbortController()
37+
controller.abort()
38+
const pending = new Promise<never>(() => {})
39+
40+
await expect(withSettleGuard(rejectOnAbort(pending, controller.signal, "TestProvider"))).rejects.toMatchObject({
41+
name: "AbortError",
42+
message: "The TestProvider request was aborted",
43+
})
44+
})
45+
46+
it("does not leave a rejecting pending unhandled when the signal is already aborted", async () => {
47+
// The pre-aborted branch returns before consuming `pending`, so it must still
48+
// attach a rejection handler; otherwise a rejecting lookup is reported as an
49+
// unhandled rejection even though the caller already cancelled.
50+
const controller = new AbortController()
51+
controller.abort()
52+
const lookupError = new Error("lookup failed")
53+
const pending = Promise.reject(lookupError)
54+
55+
const unhandled: unknown[] = []
56+
const onUnhandledRejection = (reason: unknown) => unhandled.push(reason)
57+
process.on("unhandledRejection", onUnhandledRejection)
58+
try {
59+
await expect(
60+
withSettleGuard(rejectOnAbort(pending, controller.signal, "TestProvider")),
61+
).rejects.toMatchObject({
62+
name: "AbortError",
63+
message: "The TestProvider request was aborted",
64+
})
65+
66+
// Node reports an unhandled rejection only after the microtask queue drains.
67+
await new Promise((resolve) => setTimeout(resolve, 0))
68+
expect(unhandled).toHaveLength(0)
69+
} finally {
70+
// Remove the process-level listener on every exit path: a failed assertion
71+
// must not leak it into the remaining tests in this file.
72+
process.off("unhandledRejection", onUnhandledRejection)
73+
}
74+
})
75+
76+
it("propagates the pending rejection when the signal stays active", async () => {
77+
const controller = new AbortController()
78+
const boom = new Error("lookup failed")
79+
80+
await expect(
81+
withSettleGuard(rejectOnAbort(Promise.reject(boom), controller.signal, "TestProvider")),
82+
).rejects.toBe(boom)
83+
})
84+
85+
it("detaches the abort listener once the pending settles", async () => {
86+
const controller = new AbortController()
87+
const addSpy = vi.spyOn(controller.signal, "addEventListener")
88+
const removeSpy = vi.spyOn(controller.signal, "removeEventListener")
89+
90+
await expect(
91+
withSettleGuard(rejectOnAbort(Promise.resolve("done"), controller.signal, "TestProvider")),
92+
).resolves.toBe("done")
93+
94+
// The settle path must remove the exact listener that was registered, not just any
95+
// function: removing a different reference would leave the original abort listener
96+
// attached to the signal. First require the registration to have happened at all,
97+
// so a missing registration cannot silently degrade to an undefined comparison.
98+
expect(addSpy).toHaveBeenCalledTimes(1)
99+
const registeredListener = addSpy.mock.calls[0]?.[1] as EventListener | undefined
100+
expect(typeof registeredListener).toBe("function")
101+
expect(removeSpy).toHaveBeenCalledWith("abort", registeredListener)
102+
addSpy.mockRestore()
103+
removeSpy.mockRestore()
104+
})
105+
106+
it("detaches the abort listener when the pending rejects", async () => {
107+
const controller = new AbortController()
108+
const addSpy = vi.spyOn(controller.signal, "addEventListener")
109+
const removeSpy = vi.spyOn(controller.signal, "removeEventListener")
110+
const lookupError = new Error("lookup failed")
111+
112+
await expect(
113+
withSettleGuard(rejectOnAbort(Promise.reject(lookupError), controller.signal, "TestProvider")),
114+
).rejects.toBe(lookupError)
115+
116+
// The settle path must remove the exact listener that was registered, not just any
117+
// function: removing a different reference would leave the original abort listener
118+
// attached to the signal. First require the registration to have happened at all,
119+
// so a missing registration cannot silently degrade to an undefined comparison.
120+
expect(addSpy).toHaveBeenCalledTimes(1)
121+
const registeredListener = addSpy.mock.calls[0]?.[1] as EventListener | undefined
122+
expect(typeof registeredListener).toBe("function")
123+
expect(removeSpy).toHaveBeenCalledWith("abort", registeredListener)
124+
addSpy.mockRestore()
125+
removeSpy.mockRestore()
126+
})
127+
})
128+
129+
describe("resolveModelWithAbort", () => {
130+
it("fast-fails with the provider abort error when the signal is already aborted", async () => {
131+
const controller = new AbortController()
132+
controller.abort()
133+
let lookupRan = false
134+
135+
await expect(
136+
withSettleGuard(
137+
resolveModelWithAbort(
138+
async () => {
139+
lookupRan = true
140+
return "model"
141+
},
142+
controller.signal,
143+
"TestProvider",
144+
),
145+
),
146+
).rejects.toMatchObject({
147+
name: "AbortError",
148+
message: "The TestProvider request was aborted",
149+
})
150+
// The entry guard must run before the lookup starts at all.
151+
expect(lookupRan).toBe(false)
152+
})
153+
154+
it("resolves the model when no abort signal is present", async () => {
155+
await expect(resolveModelWithAbort(async () => "model", undefined, "TestProvider")).resolves.toBe("model")
156+
})
157+
158+
it("propagates a raw resolution failure unchanged when no abort signal is present", async () => {
159+
const boom = new Error("lookup failed")
160+
161+
await expect(
162+
resolveModelWithAbort(
163+
async () => {
164+
throw boom
165+
},
166+
undefined,
167+
"TestProvider",
168+
),
169+
).rejects.toBe(boom)
170+
})
171+
172+
it("rejects with the provider abort error when the signal aborts while resolution is pending", async () => {
173+
const controller = new AbortController()
174+
let release: (value: string) => void = () => {}
175+
const pending = new Promise<string>((resolve) => {
176+
release = resolve
177+
})
178+
const race = withSettleGuard(resolveModelWithAbort(async () => pending, controller.signal, "TestProvider"))
179+
180+
setTimeout(() => controller.abort(), 10)
181+
182+
await expect(race).rejects.toMatchObject({
183+
name: "AbortError",
184+
message: "The TestProvider request was aborted",
185+
})
186+
// A late resolution after the abort won the race must not surface.
187+
release("late model")
188+
})
189+
190+
it("normalizes an abort-flavored resolution failure to the provider abort error", async () => {
191+
const controller = new AbortController()
192+
const abortFlavored = new Error("The operation was aborted.")
193+
abortFlavored.name = "AbortError"
194+
195+
const error = await resolveModelWithAbort(
196+
async () => {
197+
throw abortFlavored
198+
},
199+
controller.signal,
200+
"TestProvider",
201+
).catch((caught: unknown) => caught)
202+
203+
expect(error).not.toBe(abortFlavored)
204+
expect(error).toMatchObject({
205+
name: "AbortError",
206+
message: "The TestProvider request was aborted",
207+
})
208+
})
209+
210+
it("propagates non-abort resolution failures unchanged when a signal is present", async () => {
211+
const controller = new AbortController()
212+
const boom = new Error("lookup failed")
213+
214+
await expect(
215+
withSettleGuard(
216+
resolveModelWithAbort(
217+
async () => {
218+
throw boom
219+
},
220+
controller.signal,
221+
"TestProvider",
222+
),
223+
),
224+
).rejects.toBe(boom)
225+
})
226+
})
8227

9228
describe("abort-signal utilities", () => {
10229
describe("mergeAbortSignalAndTimeout", () => {
@@ -167,6 +386,16 @@ describe("abort-signal utilities", () => {
167386
const controller = new AbortController()
168387
expect(isRequestAborted(new Error("boom"), controller.signal)).toBe(false)
169388
})
389+
390+
it("requires an Error instance for the name and message checks", () => {
391+
// A plain object that merely looks like an abort must not be
392+
// classified as one: the instanceof guard keeps such failures
393+
// propagating unchanged so callers can inspect the real shape.
394+
const fakeAbort = { name: "AbortError", message: "Request was aborted." }
395+
expect(isRequestAborted(fakeAbort)).toBe(false)
396+
expect(isRequestAborted(Object.assign(Object.create(null), { name: "APIUserAbortError" }))).toBe(false)
397+
expect(isRequestAborted("Request was aborted.")).toBe(false)
398+
})
170399
})
171400

172401
describe("createAbortError", () => {

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

Lines changed: 82 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -66,19 +66,20 @@ export type OpenAiRequestOptions = {
6666

6767
/**
6868
* Whether a failure indicates an aborted request: the caller's signal fired,
69-
* the SDK raised a native abort error, or the error carries the OpenAI SDK
70-
* abort error message (exactly "Request was aborted."). The message check
71-
* is an exact match on purpose: a substring match would misclassify
72-
* unrelated errors that merely mention aborting.
69+
* an `Error` carries a native abort error name (`AbortError`,
70+
* `APIUserAbortError`), or an `Error` carries the OpenAI SDK abort error
71+
* message (exactly "Request was aborted.").
72+
*
73+
* The name and message checks require an `Error` instance on purpose: a
74+
* plain object that merely looks like an abort must propagate unchanged so
75+
* callers can inspect the real failure shape. The message check is an exact
76+
* match on purpose: a substring match would misclassify unrelated errors
77+
* that merely mention aborting.
7378
*/
7479
export function isRequestAborted(error: unknown, signal?: AbortSignal): boolean {
75-
const candidate = error as { name?: string; message?: string }
76-
return (
77-
Boolean(signal?.aborted) ||
78-
candidate?.name === "AbortError" ||
79-
candidate?.name === "APIUserAbortError" ||
80-
candidate?.message === "Request was aborted."
81-
)
80+
const hasAbortName = error instanceof Error && (error.name === "AbortError" || error.name === "APIUserAbortError")
81+
const hasSdkAbortMessage = error instanceof Error && error.message === "Request was aborted."
82+
return Boolean(signal?.aborted) || hasAbortName || hasSdkAbortMessage
8283
}
8384

8485
/**
@@ -93,3 +94,73 @@ export function createAbortError(providerName: string): Error {
9394
abortError.name = "AbortError"
9495
return abortError
9596
}
97+
98+
/**
99+
* Await `pending` but reject with the provider's abort error when `signal`
100+
* aborts first. For async phases that have no native signal support (model
101+
* discovery) yet must still settle promptly on cancellation. The underlying
102+
* promise keeps running (its settlement is ignored) — cancellation is
103+
* cooperative at this boundary.
104+
*
105+
* The abort listener is detached once `pending` settles (success or
106+
* failure), so repeated calls on one signal do not accumulate listeners.
107+
*/
108+
export function rejectOnAbort<T>(pending: Promise<T>, signal: AbortSignal, providerName: string): Promise<T> {
109+
if (signal.aborted) {
110+
// The caller has already cancelled, so this branch never consumes `pending`;
111+
// attach a handler anyway so a rejecting `pending` cannot surface as an
112+
// unhandled rejection.
113+
void pending.catch(() => {})
114+
return Promise.reject(createAbortError(providerName))
115+
}
116+
return new Promise<T>((resolve, reject) => {
117+
const onAbort = () => reject(createAbortError(providerName))
118+
// Stryker disable next-line ObjectLiteral,BooleanLiteral: a signal fires its abort event exactly once and the settle handler removes this listener, so the once flag is unobservable
119+
signal.addEventListener("abort", onAbort, { once: true })
120+
void pending.then(
121+
(value) => {
122+
signal.removeEventListener("abort", onAbort)
123+
resolve(value)
124+
},
125+
(error) => {
126+
signal.removeEventListener("abort", onAbort)
127+
reject(error)
128+
},
129+
)
130+
})
131+
}
132+
133+
/**
134+
* Resolve a provider's model metadata inside a cancellation scope.
135+
*
136+
* A pre-aborted signal rejects immediately with the standardized AbortError
137+
* before any lookup starts; a signal that fires while the lookup is pending
138+
* settles via {@link rejectOnAbort} instead of waiting for the catalog to
139+
* resolve. Abort failures from the lookup itself are normalized to the
140+
* provider AbortError; any other resolution failure propagates unchanged.
141+
*
142+
* Providers pass their own resolution step, so the entry guard, the race, and
143+
* the normalization logic exist once and are exercised through every
144+
* provider's spec.
145+
*/
146+
export async function resolveModelWithAbort<T>(
147+
fetchModel: () => Promise<T>,
148+
abortSignal: AbortSignal | undefined,
149+
providerName: string,
150+
): Promise<T> {
151+
if (abortSignal?.aborted) {
152+
throw createAbortError(providerName)
153+
}
154+
155+
try {
156+
if (abortSignal) {
157+
return await rejectOnAbort(fetchModel(), abortSignal, providerName)
158+
}
159+
return await fetchModel()
160+
} catch (error) {
161+
if (isRequestAborted(error, abortSignal)) {
162+
throw createAbortError(providerName)
163+
}
164+
throw error
165+
}
166+
}

‎src/test-utils/settle-guard.ts‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
/**
2+
* Stryker guard: fails fast if `promise` does not settle within `ms`.
3+
*
4+
* Stryker's per-mutant cutoff (timeoutMS 5s x timeoutFactor 1.5 ~= 7.5s) is shorter
5+
* than vitest's testTimeout (20s). A mutant that removes a settle call (or an abort
6+
* listener) leaves an awaited promise pending forever; without this guard the test
7+
* would outlive the cutoff and the mutant would be reported as Timeout (inconclusive).
8+
* Settling the guard at 500ms turns those mutants into fast failures (KILLED).
9+
*/
10+
export function withSettleGuard<T>(promise: Promise<T>, ms = 500): Promise<T> {
11+
return new Promise<T>((resolve, reject) => {
12+
const timer = setTimeout(() => {
13+
reject(new Error(`settle guard timed out after ${ms}ms`))
14+
}, ms)
15+
void promise.then(
16+
(value) => {
17+
clearTimeout(timer)
18+
resolve(value)
19+
},
20+
(error) => {
21+
clearTimeout(timer)
22+
reject(error)
23+
},
24+
)
25+
})
26+
}

0 commit comments

Comments
 (0)