extended the README.md [ci skip]

Author: Spencer Alger

README.md

@@ -2,26 +2,26 @@
 
 Official *low-level* client for Elasticsearch.
 
-This project's goal it to give the JavaScript community a solif foundation for all Elasticsearch-related code. It features a complete API, provides a module for use in Node.js as well as several different builds for use in the browser. We have tried to be opinion-free and very plugable.
-
 ## Features
 
  - One-to-one mapping with REST API and other language clients
- - Generalized, pluggable architecture. See [replacing core components](docs/replacing-core-components.md)
+ - Generalized, pluggable architecture. See [replacing core components](TODO: details the peices that are replaceable)
  - Configurable, automatic discovery of cluster nodes
  - Persistent, Keep-Alive connections
- - Load balancing (with pluggable selection strategy) across all availible nodes. Defaults to round-robin
- - Pluggable connection pools to offer different connection strategies
+ - Load balancing (with pluggable selection strategy) across all availible nodes.
 
+## Node and the browser
 
+elasticsearch.js works great in node, as well as modern browsers (many thanks to [browserify](https://github.com/substack/browserify)!!).
 
-## Node and the browser
+ - Node:
+
+  [![Build Status](https://magnum.travis-ci.com/spenceralger/elasticsearch-js.png?token=tsFxSKHtVKG8EZavSjXY)](https://magnum.travis-ci.com/spenceralger/elasticsearch-js)
+
+ - Browsers (see [browser builds](#browser-builds)):
 
-elasticsearch.js works great in node, as well as the browser (many thanks to [browserify](https://github.com/substack/browserify)).
+  ![testling results for browser clients](https://ci.testling.com/spenceralger/xhr-method-test.png)
 
- - Node: [![Build Status](https://magnum.travis-ci.com/spenceralger/elasticsearch-js.png?token=tsFxSKHtVKG8EZavSjXY)](https://magnum.travis-ci.com/spenceralger/elasticsearch-js)
- - Browsers:
-  + ![testling results for browser clients](https://ci.testling.com/spenceralger/xhr-method-test.png)
 
 ## Install in Node
 
@@ -30,21 +30,178 @@ npm install --save elasticsearch
 ```
 
 ## Browser Builds
-Download one of these builds:
 
- - [elasticsearch.js](dist/elasticsearch.js) - [minified](dist/elasticsearch.min.js)
-   - uses the browser's native XHR object
-   - Node style callbacks with a bare-bones `.then()` method
- - [elasticsearch.angular.js](dist/elasticsearch.angular.js) - [minified](dist/elasticsearch.angular.min.js)
+Download one of these browser-ready builds, or install them with `bower`
+
+ - [elasticsearch.js](dist/elasticsearch.min.js) - [dev](dist/elasticsearch.js)
+   - uses the browser's native XMLHttpRequest object
+   - Fully Compatible with IE 10+, Chrome, Firefox, Safari, Opera
+   - Only GET and POST requests available in IE 8 & 9
+   - Node style callbacks or promises provided by [when.js](https://github.com/cujojs/when)
+
+```
+bower install elasticsearch
+```
+
+ - [elasticsearch.angular.js](dist/elasticsearch.angular.min.js) - [dev](dist/elasticsearch.angular.js)
    - Uses angular's $http servive
-   - returns promisses using angular's $q servive
+   - Returns promisses using angular's $q servive (Adds an `abort()` method)
+
+```
+bower install elasticsearch-angular
+```
+
+## Configuration
+
+The `Client` constructor accepts a single object as it's argument, and the following keys can be used to configure that client instance:
+
+```js
+var elasticsearch = require('elasticsearch');
+var es = new elasticsearch.Client({
+  ...
+});
+
+### hosts
+Type: `String`, `String[]` or `Object[]`
+
+Default:
+```js
+hosts: [
+  {
+    host: 'localhost', port: '9200', protocol: 'http'
+  }
+]
+```
+
+Specify the list of hosts that this client will connect to. If sniffing is enabled, or you call sniff, this list will be used as seeds for discovery of the rest of the cluster.
+
+### log
+Type: `String`, `String[]`, `Object`, `Object[]`, or `Constructor`
+
+Default:
+```js
+log: {
+  type: 'stdio',
+  levels: ['error', 'warning']
+}
+```
+
+Unless a constructor is specified, this sets the output settings for the bundled logger. See [setting up logging](TODO: detail logging why) for more information.
+
+### connectionClass
+Type: `String`, `Constructor`
+
+Default:
+ - Node: `'http'`
+ - Browser: `'xhr'`
+ - Angular Build: `'angular'`
+
+Options:
+ - Node: `'http'`
+ - Browser: based on bundle, `'xhr'`, `'angular'`, and `'jquery'` are currently available
+
+Defines the class that will be created once for each node/host that the client communicates with. If you are looking to implement a special protocol you will probably start by writing a Connection class and specifying it here.
+
+### selector
+Type: `String`, `Function`
+
+Default: `'roundRobin'`
+
+Options:
+  - `'roundRobin'`
+  - `'random'`
+
+Defined a function that will be used to select a connection from the ConnectionPool. It should received a single argument, the list of "active" connections, and return the connection to use. Use this selector to implement special logic for your client such as prefering connections in a certain rack, or datacenter.
+
+To make this function asynchronous, accept a second argument which will be the callback which should be called as a Node style callback with a possible error: `cb(err, selectedConnection)`.
+
+### sniffOnStart
+Type: `Boolean`
+
+Default: `false`
+
+Should the client attempt to detect the rest of the cluster when it is first instanciated?
+
+### sniffAfterRequests
+Type: `Number` or `false`
+
+Default: `false`
+
+After `n` requests, perform a sniff operation and ensure out list of nodes is up to date
+
+
+### sniffOnConnectionFail
+Type: `Boolean`
+
+Default: `false`
+
+Should the client immediately sniff for a more current list of nodes when a connection dies? (see [node death](#node-death))
+
+### maxRetries
+Type: `Number`
+
+Defailt: `3`
+
+How many times should the client try to connect to other nodes before returning a [ConnectionFault](TODO: error types) error. (see [node death](#node-death))
+
+### timeout
+Type: `Number`
+
+Default: 10000
+
+How many milliseconds can the connection take before the request is aboorted and retried. (TODO: timeout errors shouldn't cause a retry).
+
+### deadTimeout
+Type: `Number`
+
+Default: 30000
+
+How many milliseconds should a dead a connection/node sit and wait before it is ping-ed? (see [node death](#node-death))
+
+### maxSockets
+Type: `Number`
+
+Default: 10
+
+How many sockets should a connection/node keep to the server? These sockets are currently kept alive ***forever*** (not like nodes current "keep alive" sockets).
+
+### nodesToHostCallback
+Type: `Function`
+
+Default: simple, not much going on [here](src/lib/client_config.js#L65).
+
+This function will receive a list of nodes received durring a sniff. The list of nodes should be transformed into an array of objects which will be fed to the [Host](src/lib/host.js) class. (TODO: allow this function to be async).
 
 ## API
 
-To maintain consistency across all the low-level clients (Ruby, Python, etc), clients accept all of their parameters via a single object, along with a single callback.
+To maintain consistency across all the low-level clients ([PHP](https://github.com/elasticsearch/elasticsearch-php), [Python](https://github.com/elasticsearch/elasticsearch-ph), [Ruby](https://github.com/elasticsearch/elasticsearch-ruby), [Perl](https://github.com/elasticsearch/elasticsearch-perl)), all API methods accept an object with parameters and a callback. If you don't pass the callback, the functions will return a promise.
+
+### Generic Params
+
+Several parameters work on all API methods, and control the way that those requests are carried out:
+
+### ignore
+Type: `Number` or `Number[]`
+
+Default: `null`
+
+Don't treat these HTTP status codes as "errors". Example use cases could be `ignore: 404` or `ignore: [404]`
+
+### timeout
+Type: `Number`
+
+Default: `client.config.timeout`
+
+The number of milliseconds this request has to complete. It defaults to the timeout specified at the client level, which defaults to 10 seconds.
+
+### Methods
+
+All the methods can be seen [here](TODO: api docs), or take a look at [api.js](src/lib/api.js).
+
+### Examples
 
 #### create the client
-```
+```js
 var es = new elasticsearch.Client({
   hosts: [
     'localhost:9200'
@@ -55,7 +212,7 @@ var es = new elasticsearch.Client({
 ```
 
 #### call an endpoint
-```
+```js
 es.cluster.nodeInfo({
   clear: true,
   jvm: true,
@@ -66,7 +223,7 @@ es.cluster.nodeInfo({
 ```
 
 #### skip the callback to get a promise back
-```
+```js
 es.search({
   q: 'pants'
 }).then(function (resp) {
@@ -77,7 +234,7 @@ es.search({
 ```
 
 #### abort a request
-```
+```js
 var req = es.search({
   q: 'robots'
 }, function (err, body, status) {
@@ -91,11 +248,18 @@ var timeout = setTimeout(function () {
 ```
 
 #### or just use the timeout param
-```
+```js
 es.search({
   q: '*',
   timeout: 200
 }).then(function (resp) {
   // Iterate all the hits
 })
 ```
+
+## FAQ
+
+### dead nodes
+Q: When is a connection/node considered dead?
+
+A; A connection is considered dead when a request to it does not complete properly. If the server responds with any status, even 500, it is not considered dead.

docs/replacing-core-components.md

@@ -68,7 +68,8 @@ Client.prototype.ping = function (params, cb) {
 
   this.config.transport.request({
     method: 'HEAD',
-    path: '/'
+    path: '/',
+    timeout: 100,
   }, cb);
 };
 

scripts/grunt-run-wait-stop.js

@@ -45,7 +45,7 @@ ConnectionAbstract.prototype.ping = function (params, cb) {
   return this.request({
     path: '/',
     method: 'HEAD',
-    timeout: '100'
+    timeout: 100
   }, cb);
 };
 

src/lib/client.js

@@ -22,6 +22,15 @@ errors.ConnectionFault = function ConnectionFault(msg) {
 };
 _.inherits(errors.ConnectionFault, ErrorAbstract);
 
+/**
+ * No Living Connections
+ * @param {String} [msg] - An error message that will probably end up in a log.
+ */
+errors.NoConnections = function NoConnections(msg) {
+  ErrorAbstract.call(this, msg || 'No Living connections', errors.NoConnections);
+};
+_.inherits(errors.NoConnections, ErrorAbstract);
+
 /**
  * Generic Error
  * @param {String} [msg] - An error message that will probably end up in a log.

src/lib/connection.js

@@ -64,7 +64,7 @@ TransportRequest.prototype._sendReqWithCon = _.handler(function (err, con) {
     this._request = con.request(this._params.req, this.bound._checkRespForFail);
   } else {
     this._log.warning('No living connections');
-    this._respond(new errors.ConnectionFault('No living connections.'));
+    this._respond(new errors.NoConnections());
   }
 });