Add RetryAgent (nodejs#2798)

Signed-off-by: Matteo Collina <hello@matteocollina.com>

docs/api/RetryAgent.md

@@ -0,0 +1,45 @@
+# Class: RetryAgent
+
+Extends: `undici.Dispatcher`
+
+A `undici.Dispatcher` that allows to automatically retry a request.
+Wraps a `undici.RetryHandler`.
+
+## `new RetryAgent(dispatcher, [options])`
+
+Arguments:
+
+* **dispatcher** `undici.Dispatcher` (required) - the  dispactgher to wrap
+* **options** `RetryHandlerOptions` (optional) - the options
+
+Returns: `ProxyAgent`
+
+### Parameter: `RetryHandlerOptions`
+
+- **retry** `(err: Error, context: RetryContext, callback: (err?: Error | null) => void) => void` (optional) - Function to be called after every retry. It should pass error if no more retries should be performed.
+- **maxRetries** `number` (optional) - Maximum number of retries. Default: `5`
+- **maxTimeout** `number` (optional) - Maximum number of milliseconds to wait before retrying. Default: `30000` (30 seconds)
+- **minTimeout** `number` (optional) - Minimum number of milliseconds to wait before retrying. Default: `500` (half a second)
+- **timeoutFactor** `number` (optional) - Factor to multiply the timeout by for each retry attempt. Default: `2`
+- **retryAfter** `boolean` (optional) - It enables automatic retry after the `Retry-After` header is received. Default: `true`
+-
+- **methods** `string[]` (optional) - Array of HTTP methods to retry. Default: `['GET', 'PUT', 'HEAD', 'OPTIONS', 'DELETE']`
+- **statusCodes** `number[]` (optional) - Array of HTTP status codes to retry. Default: `[429, 500, 502, 503, 504]`
+- **errorCodes** `string[]` (optional) - Array of Error codes to retry. Default: `['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'ENETDOWN','ENETUNREACH', 'EHOSTDOWN', 'UND_ERR_SOCKET']`
+
+**`RetryContext`**
+
+- `state`: `RetryState` - Current retry state. It can be mutated.
+- `opts`: `Dispatch.DispatchOptions & RetryOptions` - Options passed to the retry handler.
+
+Example:
+
+```js
+import { Agent, RetryAgent } from 'undici'
+
+const agent = new RetryAgent(new Agent())
+
+const res = await agent.request('http://example.com')
+console.log(res.statuCode)
+console.log(await res.body.text())
+```

docs/api/RetryHandler.md

@@ -28,7 +28,7 @@ Extends: [`Dispatch.DispatchOptions`](Dispatcher.md#parameter-dispatchoptions).
 -
 - **methods** `string[]` (optional) - Array of HTTP methods to retry. Default: `['GET', 'PUT', 'HEAD', 'OPTIONS', 'DELETE']`
 - **statusCodes** `number[]` (optional) - Array of HTTP status codes to retry. Default: `[429, 500, 502, 503, 504]`
-- **errorCodes** `string[]` (optional) - Array of Error codes to retry. Default: `['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'ENETDOWN','ENETUNREACH', 'EHOSTDOWN',
+- **errorCodes** `string[]` (optional) - Array of Error codes to retry. Default: `['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'ENETDOWN','ENETUNREACH', 'EHOSTDOWN', 'UND_ERR_SOCKET']`
 
 **`RetryContext`**
 

docsify/sidebar.md

@@ -8,6 +8,7 @@
   * [BalancedPool](/docs/api/BalancedPool.md "Undici API - BalancedPool")
   * [Agent](/docs/api/Agent.md "Undici API - Agent")
   * [ProxyAgent](/docs/api/ProxyAgent.md "Undici API - ProxyAgent")
+  * [RetryAgent](/docs/api/RetryAgent.md "Undici API - RetryAgent")
   * [Connector](/docs/api/Connector.md "Custom connector")
   * [Errors](/docs/api/Errors.md "Undici API - Errors")
   * [EventSource](/docs/api/EventSource.md "Undici API - EventSource")

index.js

@@ -15,6 +15,7 @@ const MockAgent = require('./lib/mock/mock-agent')
 const MockPool = require('./lib/mock/mock-pool')
 const mockErrors = require('./lib/mock/mock-errors')
 const ProxyAgent = require('./lib/proxy-agent')
+const RetryAgent = require('./lib/retry-agent')
 const RetryHandler = require('./lib/handler/RetryHandler')
 const { getGlobalDispatcher, setGlobalDispatcher } = require('./lib/global')
 const DecoratorHandler = require('./lib/handler/DecoratorHandler')
@@ -29,6 +30,7 @@ module.exports.Pool = Pool
 module.exports.BalancedPool = BalancedPool
 module.exports.Agent = Agent
 module.exports.ProxyAgent = ProxyAgent
+module.exports.RetryAgent = RetryAgent
 module.exports.RetryHandler = RetryHandler
 
 module.exports.DecoratorHandler = DecoratorHandler

lib/handler/RetryHandler.js

@@ -53,7 +53,8 @@ class RetryHandler {
         'ENETUNREACH',
         'EHOSTDOWN',
         'EHOSTUNREACH',
-        'EPIPE'
+        'EPIPE',
+        'UND_ERR_SOCKET'
       ]
     }
 
@@ -119,7 +120,6 @@ class RetryHandler {
     if (
       code &&
       code !== 'UND_ERR_REQ_RETRY' &&
-      code !== 'UND_ERR_SOCKET' &&
       !errorCodes.includes(code)
     ) {
       cb(err)

lib/retry-agent.js

@@ -0,0 +1,35 @@
+'use strict'
+
+const Dispatcher = require('./dispatcher')
+const RetryHandler = require('./handler/RetryHandler')
+
+class RetryAgent extends Dispatcher {
+  #agent = null
+  #options = null
+  constructor (agent, options = {}) {
+    super(options)
+    this.#agent = agent
+    this.#options = options
+  }
+
+  dispatch (opts, handler) {
+    const retry = new RetryHandler({
+      ...opts,
+      retryOptions: this.#options
+    }, {
+      dispatch: this.#agent.dispatch.bind(this.#agent),
+      handler
+    })
+    return this.#agent.dispatch(opts, retry)
+  }
+
+  close () {
+    return this.#agent.close()
+  }
+
+  destroy () {
+    return this.#agent.destroy()
+  }
+}
+
+module.exports = RetryAgent

test/retry-agent.js

@@ -0,0 +1,67 @@
+'use strict'
+
+const { tspl } = require('@matteo.collina/tspl')
+const { test, after } = require('node:test')
+const { createServer } = require('node:http')
+const { once } = require('node:events')
+
+const { RetryAgent, Client } = require('..')
+test('Should retry status code', async t => {
+  t = tspl(t, { plan: 2 })
+
+  let counter = 0
+  const server = createServer()
+  const opts = {
+    maxRetries: 5,
+    timeout: 1,
+    timeoutFactor: 1
+  }
+
+  server.on('request', (req, res) => {
+    switch (counter++) {
+      case 0:
+        req.destroy()
+        return
+      case 1:
+        res.writeHead(500)
+        res.end('failed')
+        return
+      case 2:
+        res.writeHead(200)
+        res.end('hello world!')
+        return
+      default:
+        t.fail()
+    }
+  })
+
+  server.listen(0, () => {
+    const client = new Client(`http://localhost:${server.address().port}`)
+    const agent = new RetryAgent(client, opts)
+
+    after(async () => {
+      await agent.close()
+      server.close()
+
+      await once(server, 'close')
+    })
+
+    agent.request({
+      method: 'GET',
+      path: '/',
+      headers: {
+        'content-type': 'application/json'
+      }
+    }).then((res) => {
+      t.equal(res.statusCode, 200)
+      res.body.setEncoding('utf8')
+      let chunks = ''
+      res.body.on('data', chunk => { chunks += chunk })
+      res.body.on('end', () => {
+        t.equal(chunks, 'hello world!')
+      })
+    })
+  })
+
+  await t.completed
+})

test/types/retry-agent.test-d.ts

@@ -0,0 +1,17 @@
+import { expectAssignable } from 'tsd'
+import { RetryAgent, Agent } from '../..'
+
+const dispatcher = new Agent()
+
+expectAssignable<RetryAgent>(new RetryAgent(dispatcher))
+expectAssignable<RetryAgent>(new RetryAgent(dispatcher, { maxRetries: 5 }))
+
+{
+  const retryAgent = new RetryAgent(dispatcher)
+
+  // close
+  expectAssignable<Promise<void>>(retryAgent.close())
+
+  // dispatch
+  expectAssignable<boolean>(retryAgent.dispatch({ origin: '', path: '', method: 'GET' }, {}))
+}

types/index.d.ts

@@ -15,6 +15,7 @@ import MockAgent from'./mock-agent'
 import mockErrors from'./mock-errors'
 import ProxyAgent from'./proxy-agent'
 import RetryHandler from'./retry-handler'
+import RetryAgent from'./retry-agent'
 import { request, pipeline, stream, connect, upgrade } from './api'
 
 export * from './util'
@@ -30,7 +31,7 @@ export * from './content-type'
 export * from './cache'
 export { Interceptable } from './mock-interceptor'
 
-export { Dispatcher, BalancedPool, Pool, Client, buildConnector, errors, Agent, request, stream, pipeline, connect, upgrade, setGlobalDispatcher, getGlobalDispatcher, setGlobalOrigin, getGlobalOrigin, MockClient, MockPool, MockAgent, mockErrors, ProxyAgent, RedirectHandler, DecoratorHandler, RetryHandler }
+export { Dispatcher, BalancedPool, Pool, Client, buildConnector, errors, Agent, request, stream, pipeline, connect, upgrade, setGlobalDispatcher, getGlobalDispatcher, setGlobalOrigin, getGlobalOrigin, MockClient, MockPool, MockAgent, mockErrors, ProxyAgent, RedirectHandler, DecoratorHandler, RetryHandler, RetryAgent }
 export default Undici
 
 declare namespace Undici {

types/retry-agent.d.ts

@@ -0,0 +1,11 @@
+import Agent from './agent'
+import buildConnector from './connector';
+import Dispatcher from './dispatcher'
+import { IncomingHttpHeaders } from './header'
+import RetryHandler from './retry-handler'
+
+export default RetryAgent
+
+declare class RetryAgent extends Dispatcher {
+  constructor(dispatcher: Dispatcher, options?: RetryHandler.RetryOptions)
+}