@fastify/reply-from 12.3.1 → 12.5.0

package/.github/workflows/ci.yml

@@ -14,6 +14,11 @@ on:
       - 'docs/**'
       - '*.md'
 
+# This allows a subsequently queued workflow run to interrupt previous runs
+concurrency:
+    group: "${{ github.workflow }}-${{ github.event.pull_request.head.label || github.head_ref || github.ref }}"
+    cancel-in-progress: true
+
 permissions:
   contents: read
 

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/README.md

@@ -13,9 +13,6 @@ HTTP2 to HTTP is supported too.
 npm i @fastify/reply-from
 ```
 
-## Compatibility with @fastify/multipart
-`@fastify/reply-from` and [`@fastify/multipart`](https://github.com/fastify/fastify-multipart) should not be registered as sibling plugins nor should they be registered in plugins that have a parent-child relationship.`<br>` The two plugins are incompatible, in the sense that the behavior of `@fastify/reply-from` might not be the expected one when the above-mentioned conditions are not respected.`<br>` This is due to the fact that `@fastify/multipart` consumes the multipart content by parsing it, hence this content is not forwarded to the target service by `@fastify/reply-from`.`<br>`
-However, the two plugins may be used within the same fastify instance, at the condition that they belong to disjoint branches of the fastify plugins hierarchy tree.
 
 ## Usage
 
@@ -518,14 +515,43 @@ This library has:
 When a timeout happens, [`504 Gateway Timeout`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504)
 will be returned to the client.
 
-## TODO
+## Compatibility with @fastify/multipart
+
+`@fastify/reply-from` and [`@fastify/multipart`](https://github.com/fastify/fastify-multipart) should not be registered as sibling plugins nor should they be registered in plugins that have a parent-child relationship.
+
+The two plugins are incompatible, in the sense that the behavior of `@fastify/reply-from` might not be the expected one when the above-mentioned conditions are not respected.
+This is due to the fact that `@fastify/multipart` consumes the multipart content by parsing it, hence this content is not forwarded to the target service by `@fastify/reply-from`.
+
+However, the two plugins may be used within the same fastify instance, at the condition that they belong to disjoint branches of the fastify plugins hierarchy tree.
+
+### Proxying specific content types without parsing
+
+If you need to proxy certain content types (like `multipart/form-data` or `text/event-stream`) without parsing them, you can use custom content type parsers:
+
+```js
+// Register custom content type parsers that pass raw body through
+fastify.addContentTypeParser('multipart/form-data', function (req, body, done) {
+  done(null, body)
+})
+
+fastify.addContentTypeParser('text/event-stream', function (req, body, done) {
+  done(null, body)
+})
+
+fastify.register(require('@fastify/reply-from'))
+
+fastify.post('/upload', (request, reply) => {
+  // The multipart data will be proxied as-is to the upstream server
+  reply.from('http://upstream-server.com/upload')
+})
+
+fastify.post('/events', (request, reply) => {
+  // The SSE data will be proxied as-is to the upstream server
+  reply.from('http://upstream-server.com/events')
+})
+```
 
-* [ ] support overriding the body with a stream
-* [ ] forward the request id to the other peer might require some
-  refactoring because we have to make the `req.id` unique
-  (see [hyperid](https://npm.im/hyperid)).
-* [ ] Support origin HTTP2 push
-* [X] benchmarks
+This approach allows these content types to be proxied correctly while avoiding parsing that would consume the request body.
 
 ## License
 

package/index.js

@@ -71,7 +71,9 @@ const fastifyReplyFrom = fp(function from (fastify, opts, next) {
     const retryDelay = opts.retryDelay || undefined
 
     if (!source) {
-      source = req.url
+      const requestUrl = req.url
+      const queryIndex = requestUrl.indexOf('?')
+      source = queryIndex >= 0 ? requestUrl.substring(0, queryIndex) : requestUrl
     }
 
     // we leverage caching to avoid parsing the destination URL
@@ -285,7 +287,7 @@ function onErrorDefault (reply, { error }) {
 }
 
 function isFastifyMultipartRegistered (fastify) {
-  return fastify.hasContentTypeParser('multipart/form-data')
+  return fastify.hasPlugin('@fastify/multipart')
 }
 
 function createRequestRetry (requestImpl, reply, retryHandler) {

package/lib/utils.js

@@ -42,12 +42,17 @@ function stripHttp1ConnectionHeaders (headers) {
       case 'connection':
       case 'upgrade':
       case 'http2-settings':
-      case 'te':
       case 'transfer-encoding':
       case 'proxy-connection':
       case 'keep-alive':
       case 'host':
         break
+      case 'te':
+        // see illegal connection specific header handling in Node.js
+        if (headers['te'] === 'trailers') {
+          dest[header] = headers[header]
+        }
+        break
       default:
         dest[header] = headers[header]
         break
@@ -58,6 +63,12 @@ function stripHttp1ConnectionHeaders (headers) {
 
 // issue ref: https://github.com/fastify/fast-proxy/issues/42
 function buildURL (source, reqBase) {
+  if (decodeURIComponent(source).includes('..')) {
+    const err = new Error('source/request contain invalid characters')
+    err.statusCode = 400
+    throw err
+  }
+
   if (Array.isArray(reqBase)) reqBase = reqBase[0]
   let baseOrigin = reqBase ? new URL(reqBase).href : undefined
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastify/reply-from",
-  "version": "12.3.1",
+  "version": "12.5.0",
   "description": "forward your HTTP request to another server, for fastify",
   "main": "index.js",
   "type": "commonjs",
@@ -60,7 +60,6 @@
   "devDependencies": {
     "@fastify/formbody": "^8.0.0",
     "@fastify/multipart": "^9.0.0",
-    "@fastify/pre-commit": "^2.1.0",
     "@sinonjs/fake-timers": "^14.0.0",
     "@types/node": "^24.0.8",
     "@types/tap": "^18.0.0",
@@ -74,7 +73,7 @@
     "proxy": "^2.1.1",
     "proxyquire": "^2.1.3",
     "split2": "^4.2.0",
-    "tsd": "^0.32.0"
+    "tsd": "^0.33.0"
   },
   "dependencies": {
     "@fastify/error": "^4.0.0",
@@ -85,10 +84,6 @@
     "toad-cache": "^3.7.0",
     "undici": "^7.0.0"
   },
-  "pre-commit": [
-    "lint",
-    "test"
-  ],
   "publishConfig": {
     "access": "public"
   }

package/test/build-url.test.js

@@ -76,3 +76,35 @@ test('should throw when trying to override base', async (t) => {
 
   await Promise.all(promises)
 })
+
+test('should throw on path traversal attempts', (t) => {
+  t.assert.throws(
+    () => buildURL('/foo/bar/../', 'http://localhost'),
+    new Error('source/request contain invalid characters')
+  )
+
+  t.assert.throws(
+    () => buildURL('/foo/bar/..', 'http://localhost'),
+    new Error('source/request contain invalid characters')
+  )
+
+  t.assert.throws(
+    () => buildURL('/foo/bar/%2e%2e/', 'http://localhost'),
+    new Error('source/request contain invalid characters')
+  )
+
+  t.assert.throws(
+    () => buildURL('/foo/bar/%2E%2E/', 'http://localhost'),
+    new Error('source/request contain invalid characters')
+  )
+
+  t.assert.throws(
+    () => buildURL('/foo/bar/..%2f', 'http://localhost'),
+    new Error('source/request contain invalid characters')
+  )
+
+  t.assert.throws(
+    () => buildURL('/foo/bar/%2e%2e%2f', 'http://localhost'),
+    new Error('source/request contain invalid characters')
+  )
+})

package/test/fix-GHSA-2q7r-29rg-6m5h.test.js

@@ -0,0 +1,32 @@
+'use strict'
+
+const t = require('node:test')
+const Fastify = require('fastify')
+const { request } = require('undici')
+const From = require('..')
+const http = require('node:http')
+
+const instance = Fastify()
+
+t.test('fix for GHSA-2q7r-29rg-6m5h vulnerability', async (t) => {
+  t.plan(2)
+
+  const target = http.createServer((_, res) => {
+    res.statusCode = 205
+    res.end('hi')
+  })
+  await target.listen({ port: 0 })
+  t.after(() => target.close())
+
+  instance.get('/', (_request, reply) => { reply.from('/ho/%2E%2E/hi') })
+  instance.register(From, {
+    base: `http://localhost:${target.address().port}/hi/`,
+    undici: true
+  })
+  await instance.listen({ port: 0 })
+  t.after(() => instance.close())
+
+  const { statusCode, body } = await request(`http://localhost:${instance.server.address().port}`)
+  t.assert.strictEqual(statusCode, 400)
+  t.assert.strictEqual(await body.text(), '{"statusCode":400,"error":"Bad Request","message":"source/request contain invalid characters"}')
+})

package/test/full-querystring-url.test.js

@@ -0,0 +1,55 @@
+'use strict'
+
+const t = require('node:test')
+const Fastify = require('fastify')
+const { request } = require('undici')
+const From = require('..')
+const http = require('node:http')
+
+const instance = Fastify()
+
+t.test('full querystring url', async (t) => {
+  const target = http.createServer((req, res) => {
+    t.assert.ok('request proxied')
+    t.assert.strictEqual(req.method, 'GET')
+    t.assert.strictEqual(req.url, '/hi?a=/ho/%2E%2E/hi')
+    res.statusCode = 205
+    res.setHeader('Content-Type', 'text/plain')
+    res.setHeader('x-my-header', 'hi!')
+    res.end('hi')
+  })
+
+  await target.listen({ port: 0 })
+  t.after(() => target.close())
+
+  await instance.register(From, {
+    base: `http://localhost:${target.address().port}`
+  })
+
+  instance.get('/hi', (_request, reply) => {
+    reply.from()
+  })
+
+  instance.get('/foo', (_request, reply) => {
+    reply.from('/hi')
+  })
+
+  await instance.listen({ port: 0 })
+  t.after(() => instance.close())
+
+  {
+    const result = await request(`http://localhost:${instance.server.address().port}/hi?a=/ho/%2E%2E/hi`)
+    t.assert.strictEqual(result.headers['content-type'], 'text/plain')
+    t.assert.strictEqual(result.headers['x-my-header'], 'hi!')
+    t.assert.strictEqual(result.statusCode, 205)
+    t.assert.strictEqual(await result.body.text(), 'hi')
+  }
+
+  {
+    const result = await request(`http://localhost:${instance.server.address().port}/foo?a=/ho/%2E%2E/hi`)
+    t.assert.strictEqual(result.headers['content-type'], 'text/plain')
+    t.assert.strictEqual(result.headers['x-my-header'], 'hi!')
+    t.assert.strictEqual(result.statusCode, 205)
+    t.assert.strictEqual(await result.body.text(), 'hi')
+  }
+})

package/test/http2-te-header-not-stripped-if-trailing.test.js

@@ -0,0 +1,60 @@
+'use strict'
+const h2url = require('h2url')
+const t = require('node:test')
+const Fastify = require('fastify')
+const From = require('..')
+const fs = require('node:fs')
+const path = require('node:path')
+const certs = {
+  key: fs.readFileSync(path.join(__dirname, 'fixtures', 'fastify.key')),
+  cert: fs.readFileSync(path.join(__dirname, 'fixtures', 'fastify.cert'))
+}
+
+t.test('do not strip te header if set to trailing', async (t) => {
+  const instance = Fastify({
+    http2: true,
+    https: certs
+  })
+
+  t.after(() => instance.close())
+
+  const target = Fastify({
+    http2: true
+  })
+
+  target.get('/', (request, reply) => {
+    t.assert.strictEqual(request.headers['te'], 'trailers')
+
+    reply.send({
+      hello: 'world'
+    })
+  })
+
+  instance.get('/', (_request, reply) => {
+    reply.from()
+  })
+
+  t.after(() => target.close())
+
+  await target.listen({ port: 0 })
+
+  instance.register(From, {
+    base: `http://localhost:${target.server.address().port}`,
+    http2: true,
+    rejectUnauthorized: false
+  })
+
+  await instance.listen({ port: 0 })
+
+  const { headers } = await h2url.concat({
+    url: `https://localhost:${instance.server.address().port}`,
+    headers: {
+      te: 'trailers'
+    }
+  })
+
+  t.assert.strictEqual(headers[':status'], 200)
+
+  instance.close()
+  target.close()
+})

package/test/multipart-custom-parser.test.js

@@ -0,0 +1,74 @@
+'use strict'
+
+const fs = require('node:fs')
+const path = require('node:path')
+const t = require('node:test')
+const Fastify = require('fastify')
+const { request } = require('undici')
+const From = require('..')
+const http = require('node:http')
+const FormData = require('form-data')
+
+t.test('multipart/form-data proxying with custom content type parser', async (t) => {
+  t.plan(7)
+
+  const filetPath = path.join(__dirname, 'fixtures', 'file.txt')
+
+  // Target server that expects multipart/form-data
+  const target = http.createServer((req, res) => {
+    t.assert.ok('request proxied')
+    t.assert.strictEqual(req.method, 'POST')
+    t.assert.match(req.headers['content-type'], /^multipart\/form-data/)
+
+    let data = ''
+    req.setEncoding('utf8')
+    req.on('data', (chunk) => {
+      data += chunk
+    })
+    req.on('end', () => {
+      // Verify the multipart data contains our form fields
+      t.assert.match(data, /Content-Disposition: form-data; name="key"/)
+      t.assert.match(data, /value/)
+      t.assert.match(data, /Content-Disposition: form-data; name="file"/)
+
+      res.setHeader('content-type', 'application/json')
+      res.statusCode = 200
+      res.end(JSON.stringify({ received: 'multipart data' }))
+    })
+  })
+
+  // Fastify instance with custom multipart parser (not @fastify/multipart)
+  const fastify = Fastify()
+
+  // Register custom content type parser for multipart/form-data
+  // This allows the raw body to be passed through without parsing
+  fastify.addContentTypeParser('multipart/form-data', function (req, body, done) {
+    done(null, body)
+  })
+
+  fastify.register(From)
+
+  fastify.post('/', (request, reply) => {
+    reply.from(`http://localhost:${target.address().port}`)
+  })
+
+  t.after(() => fastify.close())
+  t.after(() => target.close())
+
+  await new Promise(resolve => fastify.listen({ port: 0 }, resolve))
+  await new Promise(resolve => target.listen({ port: 0 }, resolve))
+
+  // Create multipart form data
+  const form = new FormData()
+  form.append('key', 'value')
+  form.append('file', fs.createReadStream(filetPath, { encoding: 'utf-8' }))
+
+  // Send request with multipart data
+  const result = await request(`http://localhost:${fastify.server.address().port}`, {
+    method: 'POST',
+    headers: form.getHeaders(),
+    body: form
+  })
+
+  t.assert.deepStrictEqual(await result.body.json(), { received: 'multipart data' })
+})

package/test/text-event-stream-custom-parser.test.js

@@ -0,0 +1,68 @@
+'use strict'
+
+const t = require('node:test')
+const Fastify = require('fastify')
+const { request } = require('undici')
+const From = require('..')
+const http = require('node:http')
+
+t.test('text/event-stream proxying with custom content type parser', async (t) => {
+  t.plan(6)
+
+  // Target server that sends SSE data
+  const target = http.createServer((req, res) => {
+    t.assert.ok('request proxied')
+    t.assert.strictEqual(req.method, 'POST')
+    t.assert.match(req.headers['content-type'], /^text\/event-stream/)
+
+    let data = ''
+    req.setEncoding('utf8')
+    req.on('data', (chunk) => {
+      data += chunk
+    })
+    req.on('end', () => {
+      // Verify the SSE data is received
+      t.assert.match(data, /data: test message/)
+      t.assert.match(data, /event: custom/)
+
+      res.setHeader('content-type', 'application/json')
+      res.statusCode = 200
+      res.end(JSON.stringify({ received: 'sse data' }))
+    })
+  })
+
+  // Fastify instance with custom text/event-stream parser
+  const fastify = Fastify()
+
+  // Register custom content type parser for text/event-stream
+  // This allows the raw body to be passed through without parsing
+  fastify.addContentTypeParser('text/event-stream', function (req, body, done) {
+    done(null, body)
+  })
+
+  fastify.register(From)
+
+  fastify.post('/', (request, reply) => {
+    reply.from(`http://localhost:${target.address().port}`)
+  })
+
+  t.after(() => fastify.close())
+  t.after(() => target.close())
+
+  await fastify.listen({ port: 0 })
+  await target.listen({ port: 0 })
+
+  // Create SSE-like data
+  const sseData = 'data: test message\nevent: custom\ndata: another line\n\n'
+
+  // Send request with SSE data
+  const result = await request(`http://localhost:${fastify.server.address().port}`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'text/event-stream'
+    },
+    body: sseData
+  })
+
+  t.assert.deepStrictEqual(await result.body.json(), { received: 'sse data' })
+})

package/.claude/settings.local.json

@@ -1,9 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(npm run lint:*)",
-      "Bash(node:*)"
-    ],
-    "deny": []
-  }
-}