@fastify/reply-from 12.1.0 → 12.2.0

package/.github/workflows/ci.yml

@@ -14,6 +14,9 @@ on:
       - 'docs/**'
       - '*.md'
 
+permissions:
+  contents: read
+
 jobs:
   test:
     permissions:

package/CLAUDE.md

@@ -0,0 +1,66 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Testing
+- `npm test` - Run all tests (unit + TypeScript)
+- `npm run test:unit` - Run unit tests with coverage using c8 and Node.js test runner
+- `npm run test:typescript` - Run TypeScript definition tests using tsd
+
+### Linting
+- `npm run lint` - Run ESLint to check code style
+- `npm run lint:fix` - Run ESLint with automatic fixes
+- ESLint configuration uses neostandard with TypeScript support
+
+### Building
+- No build step required - this is a CommonJS library
+
+## Architecture Overview
+
+This is a Fastify plugin for proxying HTTP requests to upstream servers. The plugin decorates the Fastify reply with a `from()` method.
+
+### Key Components
+
+**Main Plugin (`index.js`)**
+- Entry point that registers the plugin using fastify-plugin
+- Decorates `reply.from(source, opts)` method
+- Handles request proxying, retries, caching, and error handling
+- Supports HTTP/1.1, HTTP/2, and Undici client strategies
+
+**Request Builder (`lib/request.js`)**
+- Factory for creating request handlers based on transport (HTTP/1.1, HTTP/2, Undici)
+- Handles different agent configurations (HTTP, HTTPS, Unix sockets)
+- Manages timeouts, connection pooling, and retry logic
+- Returns unified interface: `{ request, close, retryOnError }`
+
+**Utilities (`lib/utils.js`)**
+- `filterPseudoHeaders()` - Removes HTTP/2 pseudo-headers (starting with :)
+- `copyHeaders()` - Copies headers to Fastify reply
+- `stripHttp1ConnectionHeaders()` - Removes HTTP/1 connection-specific headers for HTTP/2
+- `buildURL()` - Constructs destination URLs with base path validation
+
+**Error Definitions (`lib/errors.js`)**
+- Standardized error types using @fastify/error
+- Maps different error conditions to appropriate HTTP status codes
+- Includes timeout, connection reset, and gateway errors
+
+### Transport Strategies
+
+1. **Undici (default)** - High-performance HTTP/1.1 client with connection pooling
+2. **HTTP/2** - Native Node.js HTTP/2 client for modern protocols  
+3. **HTTP/1.1** - Node.js built-in http/https modules with custom agents
+
+### Key Features
+
+- **Caching**: URL parsing cache using toad-cache LruMap (default 100 entries)
+- **Retries**: Configurable retry logic for socket hangups and 503 errors
+- **Headers**: Smart header rewriting for HTTP/1.1 ↔ HTTP/2 compatibility
+- **Body handling**: Supports streams, JSON encoding, and custom content types
+- **Unix sockets**: Special handling for unix+http: and unix+https: protocols
+- **Timeouts**: Per-request and session-level timeout configuration
+
+### Configuration
+
+The plugin accepts extensive configuration for different transport methods, retry behavior, caching, and request/response transformation hooks. See README.md for full option documentation.

package/LICENSE

@@ -1,6 +1,9 @@
 MIT License
 
-Copyright (c) 2017 Matteo Collina
+Copyright (c) 2017-present Matteo Collina
+Copyright (c) 2017-present The Fastify team
+
+The Fastify team members are listed at https://github.com/fastify/fastify#team.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -69,6 +69,15 @@ target.listen({ port: 3001 }, (err) => {
 Set the base URL for all the forwarded requests. Will be required if `http2` is set to `true`
 Note that _every path will be discarded_.
 
+Set the base URL for all the forwarded requests.  
+*String or String[]*:  
+
+* **Single string** → a normal `undici.Pool` / `http.request` client is used.  
+* **Array with ≥ 2 elements** → **[`undici.BalancedPool`](https://undici.nodejs.org/#/docs/api/BalancedPool)** is automatically selected and requests are load-balanced round-robin across the given origins.
+
+When you provide an array, only the *origin* (`protocol://host:port`) part of each URL is considered; any path component is ignored.
+
+
 Custom URL protocols `unix+http:` and `unix+https:` can be used to forward requests to a unix
 socket server by using `querystring.escape(socketPath)` as the hostname.  This is not supported
 for http2 nor undici.  To illustrate:
@@ -125,6 +134,17 @@ proxy.register(require('@fastify/reply-from'), {
 })
 ```
 
+You can also use with BalancedPool:
+ ```js
+proxy.register(require('@fastify/reply-from'), {
+  base: [
+    'http://api-1.internal:8080',
+    'http://api-2.internal:8080',
+    'http://api-3.internal:8080'
+  ]
+})
+```
+
 #### `http`
 
 Set the `http` option to an Object to use

package/index.js

@@ -1,5 +1,6 @@
 'use strict'
 
+const http2 = require('node:http2')
 const fp = require('fastify-plugin')
 const { LruMap } = require('toad-cache')
 const querystring = require('fast-querystring')
@@ -24,6 +25,8 @@ const {
   BadGatewayError
 } = require('./lib/errors')
 
+const { NGHTTP2_CANCEL } = http2.constants
+
 const fastifyReplyFrom = fp(function from (fastify, opts, next) {
   const contentTypesToEncode = new Set([
     'application/json',
@@ -206,6 +209,13 @@ const fastifyReplyFrom = fp(function from (fastify, opts, next) {
         onError(this, { error: new BadGatewayError() })
         this.request.log.warn(err, 'response has invalid status code')
       }
+      if (this.request.raw.aborted && res.stream) {
+        // the request could have been canceled before we got a response from the target
+        // forward this to the upstream server and close the stream to prevent leaks
+        res.stream.close(NGHTTP2_CANCEL)
+        // no need to send a reply for aborted requests or call the onResponse callback
+        return
+      }
       if (onResponse) {
         onResponse(this.request, this, res)
       } else {

package/lib/request.js

@@ -37,6 +37,9 @@ function isUndiciInstance (obj) {
 
 function buildRequest (opts) {
   const isHttp2 = !!opts.http2
+  if (Array.isArray(opts.base) && opts.base.length === 1) {
+    opts.base = opts.base[0]
+  }
   const hasUndiciOptions = shouldUseUndici(opts)
   const requests = {
     'http:': http,
@@ -46,7 +49,8 @@ function buildRequest (opts) {
   }
   const http2Opts = getHttp2Opts(opts)
   const httpOpts = getHttpOpts(opts)
-  const baseUrl = opts.base && new URL(opts.base).origin
+  const baseUrl = Array.isArray(opts.base) ? null : (opts.base && new URL(opts.base).origin)
+  const isBalanced = Array.isArray(opts.base) && opts.base.length > 1
   const undiciOpts = opts.undici || {}
   const globalAgent = opts.globalAgent
   const destroyAgent = opts.destroyAgent
@@ -75,7 +79,10 @@ function buildRequest (opts) {
   if (isHttp2) {
     return { request: handleHttp2Req, close, retryOnError: 'ECONNRESET' }
   } else if (hasUndiciOptions) {
-    if (opts.base?.startsWith('unix+')) {
+    if (isBalanced) {
+      const origins = opts.base.map(u => new URL(u).origin)
+      undiciInstance = new undici.BalancedPool(origins, getUndiciOptions(opts.undici))
+    } else if (opts.base?.startsWith('unix+')) {
       const undiciOpts = getUndiciOptions(opts.undici)
       undiciOpts.socketPath = decodeURIComponent(new URL(opts.base).host)
       const protocol = opts.base.startsWith('unix+https') ? 'https' : 'http'
@@ -155,6 +162,8 @@ function buildRequest (opts) {
 
     if (undiciInstance) {
       pool = undiciInstance
+    } else if (pool instanceof undici.BalancedPool) {
+      delete req.origin
     } else if (!baseUrl && opts.url.protocol.startsWith('unix')) {
       done(new Error('unix socket not supported with undici yet'))
       return

package/lib/utils.js

@@ -58,6 +58,7 @@ function stripHttp1ConnectionHeaders (headers) {
 
 // issue ref: https://github.com/fastify/fast-proxy/issues/42
 function buildURL (source, reqBase) {
+  if (Array.isArray(reqBase)) reqBase = reqBase[0]
   let baseOrigin = reqBase ? new URL(reqBase).href : undefined
 
   // To make sure we don't accidentally override the base path

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastify/reply-from",
-  "version": "12.1.0",
+  "version": "12.2.0",
   "description": "forward your HTTP request to another server, for fastify",
   "main": "index.js",
   "type": "commonjs",
@@ -9,7 +9,7 @@
     "lint": "eslint",
     "lint:fix": "eslint --fix",
     "test": "npm run test:unit && npm run test:typescript",
-    "test:unit": "tap",
+    "test:unit": "c8 node --test",
     "test:typescript": "tsd"
   },
   "repository": {
@@ -62,26 +62,24 @@
     "@fastify/multipart": "^9.0.0",
     "@fastify/pre-commit": "^2.1.0",
     "@sinonjs/fake-timers": "^14.0.0",
-    "@types/node": "^22.0.0",
+    "@types/node": "^24.0.8",
     "@types/tap": "^18.0.0",
+    "c8": "^10.1.3",
     "eslint": "^9.17.0",
     "fastify": "^5.0.0",
     "form-data": "^4.0.0",
-    "got": "^11.8.6",
     "h2url": "^0.2.0",
     "neostandard": "^0.12.0",
     "nock": "^14.0.0",
     "proxy": "^2.1.1",
     "proxyquire": "^2.1.3",
-    "simple-get": "^4.0.1",
     "split2": "^4.2.0",
-    "tap": "^18.7.2",
-    "tsd": "^0.31.0"
+    "tsd": "^0.32.0"
   },
   "dependencies": {
     "@fastify/error": "^4.0.0",
     "end-of-stream": "^1.4.4",
-    "fast-content-type-parse": "^2.0.0",
+    "fast-content-type-parse": "^3.0.0",
     "fast-querystring": "^1.1.2",
     "fastify-plugin": "^5.0.1",
     "toad-cache": "^3.7.0",

package/test/async-route-handler.test.js

@@ -1,50 +1,47 @@
 'use strict'
 
-const t = require('tap')
+const t = require('node:test')
 const Fastify = require('fastify')
 const From = require('..')
 const http = require('node:http')
-const get = require('simple-get').concat
+const { request } = require('undici')
 
 const instance = Fastify()
 
-t.plan(11)
-t.teardown(instance.close.bind(instance))
-
-const target = http.createServer((req, res) => {
-  t.pass('request proxied')
-  t.equal(req.method, 'GET')
-  t.equal(req.url, '/')
-  res.statusCode = 205
-  res.setHeader('Content-Type', 'text/plain')
-  res.setHeader('x-my-header', 'hello!')
-  res.end('hello world')
-})
+t.test('async route handler', async (t) => {
+  t.plan(8)
+  t.after(() => instance.close())
+
+  const target = http.createServer((req, res) => {
+    t.assert.ok('request proxied')
+    t.assert.strictEqual(req.method, 'GET')
+    t.assert.strictEqual(req.url, '/')
+    res.statusCode = 205
+    res.setHeader('Content-Type', 'text/plain')
+    res.setHeader('x-my-header', 'hello!')
+    res.end('hello world')
+  })
 
-instance.get('/', async (_request, reply) => {
-  const p = reply.from()
-  t.equal(p, reply)
-  return p
-})
+  instance.get('/', async (_request, reply) => {
+    const p = reply.from()
+    t.assert.strictEqual(p, reply)
+    return p
+  })
 
-t.teardown(target.close.bind(target))
+  t.after(() => target.close())
 
-target.listen({ port: 0 }, (err) => {
-  t.error(err)
+  await new Promise(resolve => target.listen({ port: 0 }, resolve))
 
   instance.register(From, {
     base: `http://localhost:${target.address().port}`
   })
 
-  instance.listen({ port: 0 }, (err) => {
-    t.error(err)
+  await new Promise(resolve => instance.listen({ port: 0 }, resolve))
 
-    get(`http://localhost:${instance.server.address().port}`, (err, res, data) => {
-      t.error(err)
-      t.equal(res.headers['content-type'], 'text/plain')
-      t.equal(res.headers['x-my-header'], 'hello!')
-      t.equal(res.statusCode, 205)
-      t.equal(data.toString(), 'hello world')
-    })
-  })
+  const result = await request(`http://localhost:${instance.server.address().port}`)
+
+  t.assert.strictEqual(result.headers['content-type'], 'text/plain')
+  t.assert.strictEqual(result.headers['x-my-header'], 'hello!')
+  t.assert.strictEqual(result.statusCode, 205)
+  t.assert.strictEqual(await result.body.text(), 'hello world')
 })

package/test/balanced-pool.test.js

@@ -0,0 +1,48 @@
+'use strict'
+const t = require('node:test')
+const http = require('node:http')
+const Fastify = require('fastify')
+const From = require('..')
+const { request } = require('undici')
+
+t.test('undici balanced pool http', async t => {
+  const hit = [0, 0]
+  const makeTarget = idx => http.createServer((req, res) => {
+    hit[idx]++
+    res.statusCode = 200
+    res.end('hello world')
+  })
+  const target1 = makeTarget(0)
+  const target2 = makeTarget(1)
+
+  await Promise.all([
+    new Promise(resolve => target1.listen(0, resolve)),
+    new Promise(resolve => target2.listen(0, resolve))
+  ])
+  const p1 = target1.address().port
+  const p2 = target2.address().port
+
+  const proxy = Fastify()
+  proxy.register(From, {
+    base: [`http://localhost:${p1}`, `http://localhost:${p2}`]
+  })
+  proxy.get('*', (_req, reply) => {
+    reply.from()
+  })
+
+  t.after(() => {
+    proxy.close()
+    target1.close()
+    target2.close()
+  })
+
+  await proxy.listen({ port: 0 })
+  const proxyPort = proxy.server.address().port
+
+  for (let i = 0; i < 10; i++) {
+    const res = await request(`http://localhost:${proxyPort}/hello`)
+    t.assert.strictEqual(res.statusCode, 200)
+    t.assert.strictEqual(await res.body.text(), 'hello world')
+  }
+  t.assert.ok(hit[0] > 0 && hit[1] > 0, `load distribution OK => [${hit[0]}, ${hit[1]}]`)
+})

package/test/base-get.test.js

@@ -1,48 +1,45 @@
 'use strict'
 
-const t = require('tap')
+const t = require('node:test')
 const Fastify = require('fastify')
+const { request } = require('undici')
 const From = require('..')
 const http = require('node:http')
-const get = require('simple-get').concat
 
 const instance = Fastify()
 
-t.plan(10)
-t.teardown(instance.close.bind(instance))
-
-const target = http.createServer((req, res) => {
-  t.pass('request proxied')
-  t.equal(req.method, 'GET')
-  t.equal(req.url, '/')
-  res.statusCode = 205
-  res.setHeader('Content-Type', 'text/plain')
-  res.setHeader('x-my-header', 'hello!')
-  res.end('hello world')
-})
+t.test('base get', async (t) => {
+  t.plan(7)
+  t.after(() => instance.close())
+
+  const target = http.createServer((req, res) => {
+    t.assert.ok('request proxied')
+    t.assert.strictEqual(req.method, 'GET')
+    t.assert.strictEqual(req.url, '/')
+    res.statusCode = 205
+    res.setHeader('Content-Type', 'text/plain')
+    res.setHeader('x-my-header', 'hello!')
+    res.end('hello world')
+  })
 
-instance.get('/', (_request, reply) => {
-  reply.from()
-})
+  instance.get('/', (_request, reply) => {
+    reply.from()
+  })
 
-t.teardown(target.close.bind(target))
+  t.after(() => target.close())
 
-target.listen({ port: 0 }, (err) => {
-  t.error(err)
+  await new Promise((resolve) => target.listen({ port: 0 }, resolve))
 
   instance.register(From, {
     base: `http://localhost:${target.address().port}`
   })
 
-  instance.listen({ port: 0 }, (err) => {
-    t.error(err)
+  await new Promise((resolve) => instance.listen({ port: 0 }, resolve))
 
-    get(`http://localhost:${instance.server.address().port}`, (err, res, data) => {
-      t.error(err)
-      t.equal(res.headers['content-type'], 'text/plain')
-      t.equal(res.headers['x-my-header'], 'hello!')
-      t.equal(res.statusCode, 205)
-      t.equal(data.toString(), 'hello world')
-    })
-  })
+  const result = await request(`http://localhost:${instance.server.address().port}`)
+
+  t.assert.strictEqual(result.headers['content-type'], 'text/plain')
+  t.assert.strictEqual(result.headers['x-my-header'], 'hello!')
+  t.assert.strictEqual(result.statusCode, 205)
+  t.assert.strictEqual(await result.body.text(), 'hello world')
 })

package/test/base-path.test.js

@@ -1,38 +1,41 @@
 'use strict'
 
-const t = require('tap')
+const t = require('node:test')
 const Fastify = require('fastify')
+const { request, Agent } = require('undici')
 const From = require('..')
-const get = require('simple-get').concat
 const nock = require('nock')
 
-const instance = Fastify()
+t.test('base path', async (t) => {
+  const instance = Fastify()
 
-nock('http://httpbin.org')
-  .get('/ip')
-  .reply(200, function () {
-    t.equal(this.req.headers.host, 'httpbin.org')
-    return { origin: '127.0.0.1' }
-  })
+  nock('http://httpbin.org')
+    .get('/ip')
+    .reply(200, function () {
+      t.assert.strictEqual(this.req.headers.host, 'httpbin.org')
+      return { origin: '127.0.0.1' }
+    })
 
-t.plan(6)
-t.teardown(instance.close.bind(instance))
+  t.plan(4)
+  t.after(() => instance.close())
 
-instance.get('/', (_request, reply) => {
-  reply.from('http://httpbin.org/ip')
-})
+  instance.get('/', (_request, reply) => {
+    reply.from('http://httpbin.org/ip')
+  })
 
-instance.register(From, {
-  undici: false
-})
+  instance.register(From, {
+    undici: false
+  })
 
-instance.listen({ port: 0 }, (err) => {
-  t.error(err)
+  await new Promise(resolve => instance.listen({ port: 0 }, resolve))
 
-  get(`http://localhost:${instance.server.address().port}`, (err, res, data) => {
-    t.error(err)
-    t.equal(res.statusCode, 200)
-    t.equal(res.headers['content-type'], 'application/json')
-    t.equal(typeof JSON.parse(data).origin, 'string')
+  const result = await request(`http://localhost:${instance.server.address().port}`, {
+    dispatcher: new Agent({
+      pipelining: 0
+    })
   })
+
+  t.assert.strictEqual(result.statusCode, 200)
+  t.assert.strictEqual(result.headers['content-type'], 'application/json')
+  t.assert.strictEqual(typeof (await result.body.json()).origin, 'string')
 })

package/test/base-querystring.test.js

@@ -1,48 +1,45 @@
 'use strict'
 
-const t = require('tap')
+const t = require('node:test')
 const Fastify = require('fastify')
+const { request } = require('undici')
 const From = require('..')
 const http = require('node:http')
-const get = require('simple-get').concat
 
 const instance = Fastify()
 
-t.plan(10)
-t.teardown(instance.close.bind(instance))
-
-const target = http.createServer((req, res) => {
-  t.pass('request proxied')
-  t.equal(req.method, 'GET')
-  t.equal(req.url, '/hello?a=b')
-  res.statusCode = 205
-  res.setHeader('Content-Type', 'text/plain')
-  res.setHeader('x-my-header', 'hello!')
-  res.end('hello world')
-})
+t.test('base querystring', async (t) => {
+  t.plan(7)
+  t.after(() => instance.close())
+
+  const target = http.createServer((req, res) => {
+    t.assert.ok('request proxied')
+    t.assert.strictEqual(req.method, 'GET')
+    t.assert.strictEqual(req.url, '/hello?a=b')
+    res.statusCode = 205
+    res.setHeader('Content-Type', 'text/plain')
+    res.setHeader('x-my-header', 'hello!')
+    res.end('hello world')
+  })
 
-instance.get('/hello', (_request, reply) => {
-  reply.from()
-})
+  instance.get('/hello', (_request, reply) => {
+    reply.from()
+  })
 
-t.teardown(target.close.bind(target))
+  t.after(() => target.close())
 
-target.listen({ port: 0 }, (err) => {
-  t.error(err)
+  await new Promise(resolve => target.listen({ port: 0 }, resolve))
 
   instance.register(From, {
     base: `http://localhost:${target.address().port}`
   })
 
-  instance.listen({ port: 0 }, (err) => {
-    t.error(err)
+  await new Promise(resolve => instance.listen({ port: 0 }, resolve))
 
-    get(`http://localhost:${instance.server.address().port}/hello?a=b`, (err, res, data) => {
-      t.error(err)
-      t.equal(res.headers['content-type'], 'text/plain')
-      t.equal(res.headers['x-my-header'], 'hello!')
-      t.equal(res.statusCode, 205)
-      t.equal(data.toString(), 'hello world')
-    })
-  })
+  const result = await request(`http://localhost:${instance.server.address().port}/hello?a=b`)
+
+  t.assert.strictEqual(result.headers['content-type'], 'text/plain')
+  t.assert.strictEqual(result.headers['x-my-header'], 'hello!')
+  t.assert.strictEqual(result.statusCode, 205)
+  t.assert.strictEqual(await result.body.text(), 'hello world')
 })