npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

forwarder-http

v3.2.0

Published

A simple and configurable HTTP forwarder: streams incomming requests to a list of target servers

Downloads

28

Readme

Forwarder HTTP

Build
Status

forwarder-http is a HTTP/HTTPS forwarder. On each request it :

  • Replies to the sender immediately with a 200 (unless you configure it otherwise)
  • Forwards the request to all configured target servers
  • Can be configured to retry requests to specific targets, on error or 5xx response

It is meant to be simple, pluggable via Events, and totally configurable.

It currently supports only node >=6.x.x.

Our use case at @RadioFrance

We built this library because we needed a tiny-footprint tool to dispatch incomming production data to different development environments. As with any distributed system, requests sometimes fail so the forwarder should retry all requests on the production env, at least.

How-to

An example is worth a thousand words:

const Forwarder = require('forwarder-http')

const server = new Forwarder({
  // The servers to forward the request to
  targets: [
    'http://target-nb-1.com', // use default target configs
    {                         // Overwrite some of the default configs
      url: 'http://target-nb-2.com',
      headers: {
        'my-nb1-header': 'my-nb1-val'
      },
      retry: {
        maxRetries: 3
      }
    }
  ],

  // Add a header to the request before forwarding
  targetHeaders: {'token': 'some-complicated-hash'},

  // Define the forwarder response statusCode (default: 200)
  responseStatusCode: 204
})

You'll more detailed examples in the Examples directory

Options

The Forwarder constructor supports a few options, meant to give the user total control on how each request and response is handler:

  • https: bool. Create a HTTPS Forwarder server (Default false)
  • https: object. Options to pass to the https.createServer constructor. Required when using https.
  • timeout: int. Timeout on requests to targets. (Default: null)
  • targets: array. A list of target URLs or target objects to forward requests to. See the examples.
  • targetHeaders: object. Headers to add to the forwarded request (Default: empty).
  • targetOpts: object. Options to pass to the http/https request constructor. See the example and all the options
  • targetRetry object. Retry options for all targets, with one or more of the following properties:
    • maxRetries: int, default 0. Maximum number or retries the forwarder will perform.
    • delay: int, default 300 (ms). Time slot for exponential backoff retry intervals (cf. Wikipedia Exponential Backoff)
    • retryOnInternalError: bool, default false. Should the forwarder also retry if the targets respond with a 5xx status code ?
  • responseStatusCode: int. Status code the forward server will use when responding to requests (Default: 200)
  • responseBody: string. Body the forward server will use when responding to requests (Default: 'OK')
  • responseHeaders: object. Headers the forward server will use when responding to requests (Default: empty)

Target configuration objects

The forwarder options accept the targets array to contain many items in one the following forms :

  • string in the form http://somehost:12345

  • an object like:

{
    url: 'https://somehost:12345',
    opts: {
        key: 'mykey',
        cert: 'my cert',
        rejectUnauthorized: false
    },
    headers: {
        someHeader: 'someVal'
    },
    retry: {
        maxRetries: 2
    }
}

The options passed in the object will overwrite the default forwarder options.

Events

The forwarder-http library allows you to hook into most of the lifecycle to the forwarding process, and change all the requests and responses along the way.

  • request (incommingMessage, response): The request event from the http/https forward server. If you call response.end() in a callback, the request will not be forwarded.

  • requestContents ```(incommingMessage, payload): the body of the request, as a Buffer object.

  • response (incommingMessage, response): Called just before the forwarder responds to the client.

  • requestError (error, incommingMessage): error when handling the request in the forwarder

  • forwardRequest (options, incommingMessage): allows you to change the forwarded request before it is sent. The first argument is the options array passed on to the http.request and https.request constructors, after all the config headers and options avec been applied. If you set options.cancel = true it will cancel the forwarding of the current request to the current target. Check out the examples for ... well ... examples on this.

  • forwardResponse (request, incommingMessage, willRetry): allows you to act on individual target responses. The willRetry option indicates if a retry will be performed by the forwarder (in the case of 5xx responses).

  • forwardRequestError (error, request, willRetry): error when forwarding a request to specific targets.

See the example on how to use the events.

Acknoledgments

  • node-http-proxy: our library started as a forked and simplified version of this library. node-http-proxy also does proxying, which we do not, also supports versions of node older that 6.0.0, which we do not. But only handles a single forward target server, which didn't solve our problem. We ended up re-writing the whole thing. Anyway, many thanks to the folks at nodejitsu for this great pice of code.