@fastify/reply-from 12.3.0 → 12.4.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
 
@@ -320,7 +317,7 @@ Given example
 ```js
    const customRetryLogic = ({err, req, res, attempt, getDefaultRetry}) => {
     //If this block is not included all non 500 errors will not be retried
-    const defaultDelay = getDefaultDelay();
+    const defaultDelay = getDefaultDelay(req, res, err, attempt);
     if (defaultDelay) return defaultDelay();
 
     //Custom retry logic
@@ -518,14 +515,35 @@ 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 multipart/form-data without @fastify/multipart
+
+If you need to proxy `multipart/form-data` requests without parsing them, you can use a custom content type parser instead of `@fastify/multipart`:
+
+```js
+// Register a custom content type parser for multipart/form-data
+// This passes the raw body through without parsing
+fastify.addContentTypeParser('multipart/form-data', 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')
+})
+```
 
-* [ ] 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 `multipart/form-data` to be proxied correctly while avoiding the incompatibility with `@fastify/multipart`.
 
 ## License
 

package/index.js

@@ -47,6 +47,8 @@ const fastifyReplyFrom = fp(function from (fastify, opts, next) {
     globalAgent: opts.globalAgent,
     destroyAgent: opts.destroyAgent
   })
+
+  const isHttp2 = !!opts.http2
   if (requestBuilt instanceof Error) {
     next(requestBuilt)
     return
@@ -209,7 +211,7 @@ 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) {
+      if (this.request.raw.aborted && isHttp2) {
         // 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)
@@ -283,7 +285,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastify/reply-from",
-  "version": "12.3.0",
+  "version": "12.4.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/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/retry-with-a-custom-handler.test.js

@@ -55,8 +55,8 @@ test('a 500 status code with no custom handler should fail', async (t) => {
 })
 
 test("a server 500's with a custom handler and should revive", async (t) => {
-  const customRetryLogic = ({ req, res, getDefaultDelay }) => {
-    const defaultDelay = getDefaultDelay()
+  const customRetryLogic = ({ req, res, err, attempt, getDefaultDelay }) => {
+    const defaultDelay = getDefaultDelay(req, res, err, attempt)
     if (defaultDelay) return defaultDelay
 
     if (res && res.statusCode === 500 && req.method === 'GET') {
@@ -92,9 +92,9 @@ test('custom retry does not invoke the default delay causing a 501', async (t) =
 })
 
 test('custom retry delay functions can invoke the default delay', async (t) => {
-  const customRetryLogic = ({ req, res, getDefaultDelay }) => {
+  const customRetryLogic = ({ req, res, err, attempt, getDefaultDelay }) => {
     // registering the default retry logic for non 500 errors if it occurs
-    const defaultDelay = getDefaultDelay()
+    const defaultDelay = getDefaultDelay(req, res, err, attempt)
     if (defaultDelay) return defaultDelay
 
     if (res && res.statusCode === 500 && req.method === 'GET') {

package/test/utils-filter-pseudo-headers.test.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const test = require('tap').test
+const test = require('node:test')
 const filterPseudoHeaders = require('../lib/utils').filterPseudoHeaders
 
 test('filterPseudoHeaders', t => {
@@ -11,7 +11,7 @@ test('filterPseudoHeaders', t => {
     ':method': 'GET'
   }
 
-  t.strictSame(filterPseudoHeaders(headers), {
+  t.assert.deepStrictEqual(filterPseudoHeaders(headers), {
     accept: '*/*',
     'content-type': 'text/html; charset=UTF-8'
   })

package/types/index.d.ts

@@ -54,7 +54,12 @@ declare namespace fastifyReplyFrom {
     res: FastifyReply<RouteGenericInterface, RawServerBase>;
     attempt: number;
     retriesCount: number;
-    getDefaultDelay: () => number | null;
+    getDefaultDelay: (
+      req: FastifyRequest<RequestGenericInterface, RawServerBase>,
+      res: FastifyReply<RouteGenericInterface, RawServerBase>,
+      err: Error,
+      retries: number,
+    ) => number | null;
   }
 
   export type RawServerResponse<T extends RawServerBase> = RawReplyDefaultExpression<T> & {
@@ -64,7 +69,7 @@ declare namespace fastifyReplyFrom {
   export interface FastifyReplyFromHooks {
     queryString?: { [key: string]: unknown } | QueryStringFunction;
     contentType?: string;
-    retryDelay?: (details: RetryDetails) => {} | null;
+    retryDelay?: (details: RetryDetails) => number | null;
     retriesCount?: number;
     onResponse?: (
       request: FastifyRequest<RequestGenericInterface, RawServerBase>,

package/types/index.test-d.ts

@@ -103,8 +103,8 @@ async function main () {
   instance.get('/http2', (_request, reply) => {
     reply.from('/', {
       method: 'POST',
-      retryDelay: ({ req, res, getDefaultDelay }) => {
-        const defaultDelay = getDefaultDelay()
+      retryDelay: ({ req, res, err, attempt, getDefaultDelay }) => {
+        const defaultDelay = getDefaultDelay(req, res, err, attempt)
         if (defaultDelay) return defaultDelay
 
         if (res && res.statusCode === 500 && req.method === 'GET') {

package/.claude/settings.local.json

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