node-http2-proxy

A simple http/2 & http/1.1 to http/1.1 spec compliant proxy helper for Node.

Features

• Proxies HTTP 2, HTTP 1 and WebSocket.
• Simple and high performance.
• Hop by hop header handling.
• Connection header handling.
• Via header handling.
• Forward header handling.

Installation

$ npm install http2-proxy

Notes

http2-proxy requires at least node v10.0.0.

Fully async/await compatible and all callback based usage is optional and discouraged.

Use a final and/or error handler since errored responses won't be cleaned up automatically. This makes it possible to perform retries.

During 503 it is safe to assume that the request never made it to the upstream server. This makes it safe to retry non idempotent methods.

const finalhandler = require('finalhandler')

const defaultWebHandler = (err, req, res) => {
  if (err) {
    console.error('proxy error', err)
    finalhandler(req, res)(err)
  }
}

const defaultWSHandler = (err, req, socket, head) => {
  if (err) {
    console.error('proxy error', err)
    socket.destroy()
  }
}

HTTP/1 API

You must pass allowHTTP1: true to the http2.createServer or http2.createSecureServer factory methods.

import http2 from 'http2'
import proxy from 'http2-proxy'

const server = http2.createServer({ allowHTTP1: true })
server.listen(8000)

You can also use http-proxy2 with the old http && https API's.

import http from 'http'

const server = http.createServer()
server.listen(8000)

API

Proxy HTTP/2, HTTP/1 and WebSocket

server.on('request', (req, res) => {
  proxy.web(req, res, {
    hostname: 'localhost'
    port: 9000
  }, defaultWebHandler)
})
server.on('upgrade', (req, socket, head) => {
  proxy.ws(req, socket, head, {
    hostname: 'localhost'
    port: 9000
  }, defaultWsHandler)
})

Use Connect & Helmet

const app = connect()
app.use(helmet())
app.use((req, res, next) => proxy
  .web(req, res, {
    hostname: 'localhost'
    port: 9000
  }, err => {
    if (err) {
      next(err)
    }
  })
)
server.on('request', app)

Add x-forwarded headers

server.on('request', (req, res) => {
  proxy.web(req, res, {
    hostname: 'localhost'
    port: 9000,
    onReq: (req, { headers }) => {
      headers['x-forwarded-for'] = req.socket.remoteAddress
      headers['x-forwarded-proto'] = req.socket.encrypted ? 'https' : 'http'
      headers['x-forwarded-host'] = req.headers['host']
    }
  }, defaultWebHandler)
})

Follow Redirects

const http = require('follow-redirects').http

server.on('request', (req, res) => {
  proxy.web(req, res, {
    hostname: 'localhost'
    port: 9000,
    onReq: (req, options) => http.request(options)
  }, defaultWebHandler)
})

Add response header

server.on('request', (req, res) => {
  proxy.web(req, res, {
    hostname: 'localhost'
    port: 9000,
    onReq: (req, options) => http.request(options),
    onRes: (req, res, proxyRes) => {
      res.setHeader('test', 'header')
      res.writeHead(proxyRes.statusCode, proxyRes.headers)
      proxyRes.pipe(res)
    }
  }, defaultWebHandler)
})

async web (req, res, options, [callback])

• req: http.IncomingMessage or http2.Http2ServerRequest.
• res: http.ServerResponse or http2.Http2ServerResponse.
• options: See Options
• callback(err, req, res): Called on completion or error. Optional.

See request

async ws (req, socket, head, options, [callback])

• req: http.IncomingMessage.
• socket: net.Socket.
• head: Buffer.
• options: See Options.
• async allback(err, req, socket, head): Called on completion or error. Optional.

See upgrade

options

• hostname: Proxy http.request(options) target hostname.
• port: Proxy http.request(options) target port.
• protocol: Agent protocol ('http' or 'https'). Defaults to 'http'.
• path: Target pathname. Defaults to req.originalUrl || req.url.
• proxyTimeout: Proxy http.request(options) timeout.
• proxyName: Proxy name used for Via header.
• timeout: http.IncomingMessage or http2.Http2ServerRequest timeout.
• async onReq(req, options, callback): Called before proxy request. If returning a truthy value it will be used as the request.
  • req: http.IncomingMessage or http2.Http2ServerRequest
  • options: Options passed to http.request(options).
  • callback(err): Called on completion or error. Optional.
• async onRes(req, resOrSocket, proxyRes, callback): Called on proxy response. Writing of response must be done inside this method if provided.
  • req: http.IncomingMessage or http2.Http2ServerRequest.
  • resOrSocket: For web http.ServerResponse or http2.Http2ServerResponse and for ws net.Socket.
  • proxyRes: http.ServerResponse.
  • callback(err): Called on completion or error. Optional.

License

MIT