first commit

grafana/dashboards/requests/node_modules/http-basic/README.md

@@ -0,0 +1,97 @@
+# http-basic
+
+Simple wrapper arround http.request/https.request
+
+[![Build Status](https://img.shields.io/travis/ForbesLindesay/http-basic/master.svg)](https://travis-ci.org/ForbesLindesay/http-basic)
+[![Dependency Status](https://img.shields.io/david/ForbesLindesay/http-basic.svg)](https://david-dm.org/ForbesLindesay/http-basic)
+[![NPM version](https://img.shields.io/npm/v/http-basic.svg)](https://www.npmjs.org/package/http-basic)
+
+## Installation
+
+    npm install http-basic
+
+## Usage
+
+```js
+var request = require('http-basic');
+
+var options = {followRedirects: true, gzip: true, cache: 'memory'};
+
+var req = request('GET', 'http://example.com', options, function (err, res) {
+  if (err) throw err;
+  console.dir(res.statusCode);
+  res.body.resume();
+});
+req.end();
+```
+
+**method:**
+
+The http method (e.g. `GET`, `POST`, `PUT`, `DELETE` etc.)
+
+**url:**
+
+The url as a string (e.g. `http://example.com`).  It must be fully qualified and either http or https.
+
+**options:**
+
+ - `headers` - (default `{}`) http headers
+ - `agent` - (default: `false`) controlls keep-alive (see http://nodejs.org/api/http.html#http_http_request_options_callback)
+ - `duplex` - (default: `true` except for `GET`, `OPTIONS` and `HEAD` requests) allows you to explicitly set a body on a request that uses a method that normally would not have a body
+ - `followRedirects` - (default: `false`) - if true, redirects are followed (note that this only affects the result in the callback)
+ - `maxRedirects` - (default: `Infinity`) - limit the number of redirects allowed.
+ - `allowRedirectHeaders` (default: `null`) - an array of headers allowed for redirects (none if `null`).
+ - `gzip` (default: `false`) - automatically accept gzip and deflate encodings.  This is kept completely transparent to the user.
+ - `cache` - (default: `null`) - `'memory'` or `'file'` to use the default built in caches or you can pass your own cache implementation.
+ - `timeout` (default: `false`) - times out if no response is returned within the given number of milliseconds.
+ - `socketTimeout` (default: `false`) - calls `req.setTimeout` internally which causes the request to timeout if no new data is seen for the given number of milliseconds.
+ - `retry` (default: `false`) - retry GET requests.  Set this to `true` to retry when the request errors or returns a status code greater than or equal to 400 (can also be a function that takes `(err, req, attemptNo) => shouldRetry`)
+ - `retryDelay` (default: `200`) - the delay between retries (can also be set to a function that takes `(err, res, attemptNo) => delay`)
+ - `maxRetries` (default: `5`) - the number of times to retry before giving up.
+ - `ignoreFailedInvalidation` (default: `false`) - whether the cache should swallow errors if there is a problem removing a cached response. Note that enabling this setting may result in incorrect, cached data being returned to the user.
+ - `isMatch` - `(requestHeaders: Headers, cachedResponse: CachedResponse, defaultValue: boolean) => boolean` - override the default behaviour for testing whether a cached response matches a request.
+ - `isExpired` - `(cachedResponse: CachedResponse, defaultValue: boolean) => boolean` - override the default behaviour for testing whether a cached response has expired
+ - `canCache` - `(res: Response<NodeJS.ReadableStream>, defaultValue: boolean) => boolean` - override the default behaviour for testing whether a response can be cached
+
+**callback:**
+
+The callback is called with `err` as the first argument and `res` as the second argument. `res` is an [http-response-object](https://github.com/ForbesLindesay/http-response-object).  It has the following properties:
+
+ - `statusCode` - a number representing the HTTP Status Code
+ - `headers` - an object representing the HTTP headers
+ - `body` - a readable stream respresenting the request body.
+ - `url` - the URL that was requested (in the case of redirects, this is the final url that was requested)
+
+**returns:**
+
+If the method is `GET`, `DELETE` or `HEAD`, it returns `undefined`.
+
+Otherwise, it returns a writable stream for the body of the request.
+
+## Implementing a Cache
+
+A `Cache` is an object with three methods:
+
+ - `getResponse(url, callback)` - retrieve a cached response object
+ - `setResponse(url, response)` - cache a response object
+ - `invalidateResponse(url, callback)` - remove a response which is no longer valid
+
+A cached response object is an object with the following properties:
+
+ - `statusCode` - Number
+ - `headers` - Object (key value pairs of strings)
+ - `body` - Stream (a stream of binary data)
+ - `requestHeaders` - Object (key value pairs of strings)
+ - `requestTimestamp` - Number
+
+`getResponse` should call the callback with an optional error and either `null` or a cached response object, depending on whether the url can be found in the cache.  Only `GET`s are cached.
+
+`setResponse` should just swallow any errors it has (or resport them using `console.warn`).
+
+`invalidateResponse` should call the callback with an optional error if it is unable to invalidate a response.
+
+A cache may also define any of the methods from `lib/cache-utils.js` to override behaviour for what gets cached.  It is currently still only possible to cache "get" requests, although this could be changed.
+
+## License
+
+  MIT