fix(probe): add per-request timeout (default 3s) to prevent hanging on unreachable hosts (#87)

* fix(probe): add per-request timeout (default 3s) to prevent hanging on unreachable hosts

* Update src/probe.ts

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* Update src/probe.test.ts

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: sj817

src/probe.test.ts

@@ -6,6 +6,14 @@ beforeEach(() => {
   vi.clearAllMocks()
 })
 
+/** 创建一个永远挂起（直到 signal abort）的请求 mock */
+const hangingRequest = (_url: string, signal: AbortSignal) => {
+  return new Promise<string>((_, reject) => {
+    if (signal.aborted) return reject(signal.reason)
+    signal.addEventListener('abort', () => reject(signal.reason), { once: true })
+  })
+}
+
 describe('probeRace', () => {
   it('首个 URL 最快时应返回其结果', async () => {
     const request = vi.fn().mockResolvedValue('result-1')
@@ -129,4 +137,74 @@ describe('probeRace', () => {
     expect(url).toBe('https://only.com')
     expect(request).toHaveBeenCalledTimes(1)
   })
+
+  describe('超时处理', () => {
+    it('单个请求超时应视为失败', async () => {
+      await expect(probeRace({
+        tag: 'test',
+        urls: ['https://a.com'],
+        timeout: 100,
+        request: hangingRequest,
+      })).rejects.toThrow('所有探针均不可用')
+    })
+
+    it('所有请求超时应抛出错误', async () => {
+      await expect(probeRace({
+        tag: 'test',
+        urls: ['https://a.com', 'https://b.com'],
+        staggerDelay: 50,
+        timeout: 200,
+        request: hangingRequest,
+      })).rejects.toThrow('所有探针均不可用')
+    })
+
+    it('部分超时时应返回成功的那个', async () => {
+      let call = 0
+      const request = vi.fn().mockImplementation((url: string, signal: AbortSignal) => {
+        call++
+        if (call === 1) return hangingRequest(url, signal)
+        return Promise.resolve('result-2')
+      })
+
+      const { result, url } = await probeRace({
+        tag: 'test',
+        urls: ['https://slow.com', 'https://fast.com'],
+        staggerDelay: 50,
+        timeout: 5000,
+        request,
+      })
+      expect(result).toBe('result-2')
+      expect(url).toBe('https://fast.com')
+    })
+
+    it('请求函数应收到带超时的组合 signal', async () => {
+      let capturedSignal: AbortSignal | undefined
+      const request = vi.fn().mockImplementation((_url: string, signal: AbortSignal) => {
+        capturedSignal = signal
+        return Promise.resolve('ok')
+      })
+
+      await probeRace({
+        tag: 'test',
+        urls: ['https://a.com'],
+        timeout: 5000,
+        request,
+      })
+
+      expect(capturedSignal).toBeDefined()
+      // 成功后 signal 应已被 abort（controller.abort）
+      expect(capturedSignal!.aborted).toBe(true)
+    })
+
+    it('默认超时为 3000ms', async () => {
+      const request = vi.fn().mockResolvedValue('ok')
+      await probeRace({
+        tag: 'test',
+        urls: ['https://a.com'],
+        request,
+      })
+      // 不传 timeout 也能正常运行（默认 3s 足够）
+      expect(request).toHaveBeenCalledTimes(1)
+    })
+  })
 })

src/probe.ts

@@ -5,6 +5,8 @@ export interface ProbeOptions<T> {
   urls: string[]
   /** 每个探针之间的延迟（毫秒），默认 300 */
   staggerDelay?: number
+  /** 单个请求的超时时间（毫秒），默认 3000 */
+  timeout?: number
   /** 发起请求的函数 */
   request: (url: string, signal: AbortSignal) => Promise<T>
   /** 日志标签 */
@@ -20,16 +22,38 @@ export interface ProbeResult<T> {
   elapsed: number
 }
 
+/**
+ * 可中断的延迟
+ *
+ * signal 被 abort 时立即 reject，用于取消尚未启动的探针
+ */
+const abortableDelay = (ms: number, signal: AbortSignal): Promise<void> => {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) return reject(signal.reason)
+    const timer = setTimeout(() => {
+      signal.removeEventListener('abort', onAbort)
+      resolve()
+    }, ms)
+    const onAbort = () => {
+      clearTimeout(timer)
+      reject(signal.reason)
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
 /**
  * 通用探针竞速工具
  *
  * 同时向多个 URL 发起请求，首个 URL 立即请求，后续 URL 按 staggerDelay 延迟逐个启动。
+ * 每个请求都有独立的超时控制（默认 3s），超时视为失败。
  * 任一成功后通过 AbortController 取消剩余请求和定时器。
+ * 只有所有 URL 都失败或超时时才抛出错误。
  *
  * @returns 最快成功的结果、对应的 URL 和耗时
  */
 export const probeRace = async <T>(options: ProbeOptions<T>): Promise<ProbeResult<T>> => {
-  const { urls, staggerDelay = 300, request, tag } = options
+  const { urls, staggerDelay = 300, timeout = 3000, request, tag } = options
   const controller = new AbortController()
   const startTime = Date.now()
 
@@ -41,21 +65,12 @@ export const probeRace = async <T>(options: ProbeOptions<T>): Promise<ProbeResul
 
   const probePromises = urls.map(async (url, index) => {
     if (index > 0) {
-      await new Promise<void>((resolve, reject) => {
-        const onAbort = () => {
-          clearTimeout(timer)
-          reject(new Error('Aborted'))
-        }
-        const timer = setTimeout(() => {
-          controller.signal.removeEventListener('abort', onAbort)
-          resolve()
-        }, staggerDelay * index)
-        controller.signal.addEventListener('abort', onAbort, { once: true })
-      })
+      await abortableDelay(staggerDelay * index, controller.signal)
     }
 
     const probeStart = Date.now()
-    const result = await request(url, controller.signal)
+    const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(timeout)])
+    const result = await request(url, signal)
     const probeElapsed = Date.now() - probeStart
     logger.info(`[${tag}] 探针 #${index + 1} 成功: ${url} (${probeElapsed}ms)`)
     return { result, url }