getRequest

getRequest allows plugins to add data to Request, or produce an entirely new Request. After this method has run, the subsequent lifecycle methods will use the new or changed Request. getRequest should return a Request or a Promise for one.

Filters

Filters are used to decide whether to apply a set of plugins. They combine with plugins as part of a FetchGroup, deciding whether the plugins will run. If the filter says no, the request is passed to the next plugin for processing.

In the example below, the RateLimitPlugin will only be applied to requests that match the testRequest method of the PathPrefixFilter.

Filters can intercept requests and responses, to decide which portion of the plugin methods run. Filters can implement testRequest and testResponse. They should return true, false or a promise for true or false.

Rationale

The idea for this project comes from TweetDeck, a very 'chatty' native web app. The client-side is an oft-forgetten but important component of a distributed system, capable of bringing down servers with large amounts of traffic.

To mitigate the risk that TweetDeck contributes to a system failure we have developed a fairly complex networking layer. In various places, often ad-hoc, we do some of the following:

use a OAuth1-signing server to authenticate to our requests

de-duplicate in-flight requests

poll rate-limited API endpoints as fast as the limits allow

retry requests if they fail due to lack of network connection

retry, with exponential back-off, requests that return an error from the server

add authentication data in different ways based on app-configuration

track network request performance

timeout requests

fall-back from a stream connection to polling

However, these behaviours can require some manual work. Not all are used for all network requests, even if they should be. In particular, retry + exponential backoff with timeouts are a general good practice that we don't always apply. They can prevent cascading failures, or compounding of issues as they arise.

In many places on the server-side, this is assumed behaviour and done automatically. For example, Twitter's Finagle comes with timeouts, retries and other features out-of-the-box.

This project aims to make it easy to build JavaScript clients that are good citizens of distributed systems.