Merge branch 'master' of https://github.com/elasticsearch/elasticsearch-js into buildRework

CHANGELOG.md

@@ -1,5 +1,8 @@
 # elasticsearch-js changelog
 
+## 3.1 (Jan 6 2015)
+ - Added HTTPS/SSL configuration options and related errors
+
 ## 3.0 (Nov 7 2014)
  - Added apiVersion `"1.4"`, which is now the default
  - Improved parsing of `host:` strings, [examples in the tests](https://github.com/elasticsearch/elasticsearch-js/blob/165b7d7986b2184b2e4b73d33bf5803e61ce7a54/test/unit/specs/host.js#L71-L92)

README.md

@@ -2,8 +2,8 @@
 
 The official low-level Elasticsearch client for Node.js and the browser.
 
-[![Build Status](http://img.shields.io/travis/elasticsearch/elasticsearch-js/2.4.svg?style=flat-square)](https://travis-ci.org/elasticsearch/elasticsearch-js?branch=3.0)
-[![Coverage Status](http://img.shields.io/coveralls/elasticsearch/elasticsearch-js/2.4.svg?style=flat-square)](https://coveralls.io/r/elasticsearch/elasticsearch-js?branch=3.0)
+[![Build Status](http://img.shields.io/travis/elasticsearch/elasticsearch-js/2.4.svg?style=flat-square)](https://travis-ci.org/elasticsearch/elasticsearch-js?branch=3.1)
+[![Coverage Status](http://img.shields.io/coveralls/elasticsearch/elasticsearch-js/2.4.svg?style=flat-square)](https://coveralls.io/r/elasticsearch/elasticsearch-js?branch=3.1)
 [![Dependencies up to date](http://img.shields.io/david/elasticsearch/elasticsearch-js.svg?style=flat-square)](https://david-dm.org/elasticsearch/elasticsearch-js)
 
 ## Features
@@ -34,10 +34,10 @@ Check out the [Browser Builds](http://www.elasticsearch.org/guide/en/elasticsear
 </tr><tr>
 <td>download:</td>
 <td align="center">
-<a href="https://download.elasticsearch.org/elasticsearch/elasticsearch-js/elasticsearch-js-3.0.2.zip">zip</a>
+<a href="https://download.elasticsearch.org/elasticsearch/elasticsearch-js/elasticsearch-js-3.1.0.zip">zip</a>
 </td>
 <td align="center">
-<a href="https://download.elasticsearch.org/elasticsearch/elasticsearch-js/elasticsearch-js-3.0.2.tar.gz">tar.gz</a>
+<a href="https://download.elasticsearch.org/elasticsearch/elasticsearch-js/elasticsearch-js-3.1.0.tar.gz">tar.gz</a>
 </td>
 </tr>
 </table>

docs/api_conventions.asciidoc

@@ -21,6 +21,7 @@ NOTE: the https://github.com/fullscale/elastic.js[elastic.js] library can be use
   * `requestTimeout` -- <<config-request-timeout, more info>>
   * `maxRetries` -- <<config-max-retries, more info>>
 
+[[api-conventions-cb]]
 === Callbacks or Promises
 When a callback is passed to any of the API methods, it will be called with `(err, response, status)`. If you prefer to use promises, don't pass a callback and a promise will be returned. The promise will either be resolved with the response body, or rejected with the error that occured (including any 300+ response for non "exists" methods).
 

docs/browser_builds.asciidoc

@@ -14,7 +14,7 @@ bower install elasticsearch
 ---------
 
 === Download
- * v3.0.2: https://download.elasticsearch.org/elasticsearch/elasticsearch-js/elasticsearch-js-3.0.2.zip[zip], https://download.elasticsearch.org/elasticsearch/elasticsearch-js/elasticsearch-js-3.0.2.tar.gz[tar.gz]
+ * v3.1.0: https://download.elasticsearch.org/elasticsearch/elasticsearch-js/elasticsearch-js-3.1.0.zip[zip], https://download.elasticsearch.org/elasticsearch/elasticsearch-js/elasticsearch-js-3.1.0.tar.gz[tar.gz]
 
 
 === Angular Build

docs/configuration.asciidoc

@@ -30,7 +30,6 @@ Default:::
 
 
 
-
 `log`[[config-log]]:: `String, String[], Object, Object[], Constructor` -- Unless a constructor is specified, this sets the output settings for the bundled logger. See the section on configuring-logging[logging] for more information.
 
 Default in Node:::
@@ -147,6 +146,35 @@ Defaults:::
 
 
 
+`ssl`[[config-ssl]]:: `Object` -- An object defining HTTPS/SSL configuration to use for all nodes. The properties of this mimic the options accepted by http://nodejs.org/docs/latest/api/tls.html#tls_tls_connect_port_host_options_callback[`tls.connect()`] with the exception of `rejectUnauthorized`, which defaults to `false` allowing self-signed certificates to work out-of-the-box.
++
+Additional information available in <<auth-reference>>.
+
+`ssl.pfx`::: `String,Array[String]` -- Certificate, Private key and CA certificates to use for SSL. Default `null`.
+`ssl.key`::: `String` -- Private key to use for SSL. Default `null`.
+`ssl.passphrase`::: `String` -- A string of passphrase for the private key or pfx. Default `null`.
+`ssl.cert`::: `String` -- Public x509 certificate to use. Default `null`.
+`ssl.ca`::: `String,Array[String]` -- An authority certificate or array of authority certificates to check the remote host against. Default `null`.
+`ssl.ciphers`::: `String` -- A string describing the ciphers to use or exclude. Consult http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT for details on the format.  Default `null`.
+`ssl.rejectUnauthorized`::: `Boolean` -- If true, the server certificate is verified against the list of supplied CAs. An 'error' event is emitted if verification fails. Verification happens at the connection level, before the HTTP request is sent. Default `false`
+`ssl.secureProtocol`::: `String` -- The SSL method to use, e.g. TLSv1_method to force TLS version 1. The possible values depend on your installation of OpenSSL and are defined in the constant SSL_METHODS. Default `null`.
+Example:::
++
+[source,js]
+-----
+var client = new elasticsearch.Client({
+  hosts: [
+    'https://box1.internal.org',
+    'https://box2.internal.org',
+    'https://box3.internal.org'
+  ],
+  ssl: {
+    ca: fs.readFileSync('./cacert.pem'),
+    rejectUnauthorized: true
+  }
+});
+-----
+
 
 `selector`[[config-selector]]:: `String, Function` -- This function 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 preferring nodes in a certain rack or data-center.
 +

docs/host.asciidoc

@@ -44,45 +44,8 @@ Options :::
 `...`::
 `Any` -- When the host receives a configuration object, it assigns all of the object's keys to itself. This allows you to pass in arbitrary keys and values that can be used within selectors, or other custom functionality.
 
-`pfx`::
-`String,Array[String]` -- Certificate, Private key and CA certificates to use for SSL.
-
-Default ::: `null`
-
-`key`::
-`String` -- Private key to use for SSL.
-
-Default ::: `null`
-
-`passphrase`::
-`String` -- A string of passphrase for the private key or pfx.
-
-Default ::: `null`
-
-`cert`::
-`String` -- Public x509 certificate to use.
-
-Default ::: `null`
-
-`ca`::
-`String,Array[String]` -- An authority certificate or array of authority certificates to check the remote host against.
-
-Default ::: `null`
-
-`ciphers`::
-`String` -- A string describing the ciphers to use or exclude. Consult http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT for details on the format.
-
-Default ::: `null`
-
-`rejectUnauthorized`::
-`Boolean` -- If true, the server certificate is verified against the list of supplied CAs. An 'error' event is emitted if verification fails. Verification happens at the connection level, before the HTTP request is sent.
-
-Default ::: `true`
-
-`secureProtocol`::
-`String` -- The SSL method to use, e.g. TLSv1_method to force TLS version 1. The possible values depend on your installation of OpenSSL and are defined in the constant SSL_METHODS.
-
-Default ::: `null`
+`ssl`::
+`Object` -- Host specific version of the <<config-ssl,ssl config>>.
 
 === Examples
 

docs/index.asciidoc

@@ -10,6 +10,8 @@ include::api_conventions.asciidoc[]
 
 include::configuration.asciidoc[]
 
+include::ssl_authentication.asciidoc[]
+
 include::extending_core_components.asciidoc[]
 
 include::logging.asciidoc[]

docs/ssl_authentication.asciidoc

@@ -0,0 +1,49 @@
+[[auth-reference]]
+== SSL and Authentication
+
+You can configure the client to use SSL for connecting to your elasticsearch cluster, including certificate verification and http auth.
+
+=== Basic Auth
+
+Basic authentication credentials can be configured on a per-host basis using URL notiation, or at the `auth:` property of a host config object.
+
+.Credentials directly in the host url:
+[source,js]
+-----
+var client = new elasticsearch.Client({
+  host: 'https://user:password@my-site.com:9200'
+})
+-----
+
+.Credentials as a property of the host config:
+[source,js]
+-----
+var client = new elasticsearch.Client({
+  host: [
+    {
+      host: 'es1.internal.org',
+      auth: 'user:password'
+    }
+  ]
+});
+-----
+
+=== HTTPS/SSL
+
+Without any additional configuration you can specify `https://` host urls, but the certificates used to sign these requests will not verified (`rejectUnauthorized: false`). To turn on certificate verification you must specify an `ssl:` object either in the top level config or in each host config object and set `rejectUnauthorized: true`. The ssl config object can contain many of the same configuration options that http://nodejs.org/docs/latest/api/tls.html#tls_tls_connect_port_host_options_callback[`tls.connect()`] accepts. For convenience these options are also listed in the <<config-ssl,configuration>> reference.
+
+.Specify a certificate authority that should be used to verify server certifcates on all nodes:
+[source,js]
+-----
+var client = new elasticsearch.Client({
+  hosts: [
+    'https://box1.internal.org',
+    'https://box2.internal.org',
+    'https://box3.internal.org'
+  ],
+  ssl: {
+    ca: fs.readFileSync('./cacert.pem'),
+    rejectUnauthorized: true
+  }
+});
+-----

package.json

@@ -7,7 +7,7 @@
   "description": "The official low-level Elasticsearch client for Node.js and the browser.",
   "main": "src/elasticsearch.js",
   "homepage": "http://www.elasticsearch.org/guide/en/elasticsearch/client/javascript-api/current/index.html",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "browser": {
     "./src/lib/connectors/index.js": "./src/lib/connectors/browser_index.js",
     "./src/lib/loggers/index.js": "./src/lib/loggers/browser_index.js",

scripts/generate/js_api.js

@@ -39,11 +39,17 @@ module.exports = function (branch, done) {
   }());
 
   var esDir = fromRoot('src/_elasticsearch_' + _.snakeCase(branch));
-  var aliases = _.transform(require('./aliases'), function (aliases, rule) {
-    if (semver.satisfies(branchAsVersion, rule.version)) {
-      _.assign(aliases, rule.aliases);
-    }
-  }, {});
+
+  var overrides = require('./overrides')
+  .filter(function (rule) {
+    return semver.satisfies(branchAsVersion, rule.version);
+  })
+  .reduce(function (overrides, rule) {
+    return _.merge(overrides, _.omit(rule, 'version'));
+  }, {
+    aliases: {},
+    paramAsBody: {}
+  });
 
   var steps = [
     readSpecFiles,
@@ -217,7 +223,7 @@ module.exports = function (branch, done) {
         spec.requestTimeout = 100;
       }
 
-      var urls = _.difference(def.url.paths, aliases[name]);
+      var urls = _.difference(def.url.paths, overrides.aliases[name]);
       var urlSignatures = [];
       urls = _.map(urls, function (url) {
         var optionalVars = {};
@@ -271,6 +277,10 @@ module.exports = function (branch, done) {
         ]);
       }, {});
 
+      if (overrides.paramAsBody[name]) {
+        spec.paramAsBody = overrides.paramAsBody[name];
+      }
+
       if (_.size(spec.params) === 0) {
         delete spec.params;
       }
@@ -287,7 +297,8 @@ module.exports = function (branch, done) {
           'urls',
           'needBody',
           'requestTimeout',
-          'bulkBody'
+          'bulkBody',
+          'paramAsBody'
         ]),
         location: location,
         docUrl: def.documentation,

scripts/generate/overrides.js

@@ -1,4 +1,10 @@
 module.exports = [
+  {
+    version: '*',
+    paramAsBody: {
+      scroll: 'scrollId'
+    }
+  },
   {
     version: '0.90.x',
     aliases: {

src/lib/apis/0_90.js

@@ -2902,6 +2902,7 @@ api.scroll = ca({
       fmt: '/_search/scroll'
     }
   ],
+  paramAsBody: 'scrollId',
   method: 'POST'
 });
 

src/lib/apis/1_0.js

@@ -4477,6 +4477,7 @@ api.scroll = ca({
       fmt: '/_search/scroll'
     }
   ],
+  paramAsBody: 'scrollId',
   method: 'POST'
 });
 

src/lib/apis/1_1.js

@@ -4574,6 +4574,7 @@ api.scroll = ca({
       fmt: '/_search/scroll'
     }
   ],
+  paramAsBody: 'scrollId',
   method: 'POST'
 });
 

src/lib/apis/1_2.js

@@ -4640,6 +4640,7 @@ api.scroll = ca({
       fmt: '/_search/scroll'
     }
   ],
+  paramAsBody: 'scrollId',
   method: 'POST'
 });
 

src/lib/apis/1_3.js

@@ -4765,6 +4765,7 @@ api.scroll = ca({
       fmt: '/_search/scroll'
     }
   ],
+  paramAsBody: 'scrollId',
   method: 'POST'
 });
 

src/lib/apis/1_4.js

@@ -5020,6 +5020,7 @@ api.scroll = ca({
       fmt: '/_search/scroll'
     }
   ],
+  paramAsBody: 'scrollId',
   method: 'POST'
 });
 

src/lib/apis/1_x.js

@@ -610,6 +610,44 @@ api.cat.prototype.recovery = ca({
   ]
 });
 
+/**
+ * Perform a [cat.segments](http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/cat-segments.html) request
+ *
+ * @param {Object} params - An object with parameters used to carry out this action
+ * @param {String, String[], Boolean} params.h - Comma-separated list of column names to display
+ * @param {Boolean} params.help - Return help information
+ * @param {Boolean} [params.v=true] - Verbose mode. Display column headers
+ * @param {String, String[], Boolean} params.index - A comma-separated list of index names to limit the returned information
+ */
+api.cat.prototype.segments = ca({
+  params: {
+    h: {
+      type: 'list'
+    },
+    help: {
+      type: 'boolean',
+      'default': false
+    },
+    v: {
+      type: 'boolean',
+      'default': true
+    }
+  },
+  urls: [
+    {
+      fmt: '/_cat/segments/<%=index%>',
+      req: {
+        index: {
+          type: 'list'
+        }
+      }
+    },
+    {
+      fmt: '/_cat/segments'
+    }
+  ]
+});
+
 /**
  * Perform a [cat.shards](http://www.elasticsearch.org/guide/en/elasticsearch/reference/1.x/cat-shards.html) request
  *
@@ -5030,6 +5068,7 @@ api.scroll = ca({
       fmt: '/_search/scroll'
     }
   ],
+  paramAsBody: 'scrollId',
   method: 'POST'
 });
 

src/lib/apis/master.js

@@ -669,6 +669,44 @@ api.cat.prototype.recovery = ca({
   ]
 });
 
+/**
+ * Perform a [cat.segments](http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/cat-segments.html) request
+ *
+ * @param {Object} params - An object with parameters used to carry out this action
+ * @param {String, String[], Boolean} params.h - Comma-separated list of column names to display
+ * @param {Boolean} params.help - Return help information
+ * @param {Boolean} [params.v=true] - Verbose mode. Display column headers
+ * @param {String, String[], Boolean} params.index - A comma-separated list of index names to limit the returned information
+ */
+api.cat.prototype.segments = ca({
+  params: {
+    h: {
+      type: 'list'
+    },
+    help: {
+      type: 'boolean',
+      'default': false
+    },
+    v: {
+      type: 'boolean',
+      'default': true
+    }
+  },
+  urls: [
+    {
+      fmt: '/_cat/segments/<%=index%>',
+      req: {
+        index: {
+          type: 'list'
+        }
+      }
+    },
+    {
+      fmt: '/_cat/segments'
+    }
+  ]
+});
+
 /**
  * Perform a [cat.shards](http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/cat-shards.html) request
  *
@@ -5072,6 +5110,7 @@ api.scroll = ca({
       fmt: '/_search/scroll'
     }
   ],
+  paramAsBody: 'scrollId',
   method: 'POST'
 });
 
@@ -5990,7 +6029,6 @@ api.termvectors = ca({
  * @param {String} params.consistency - Explicit write consistency setting for the operation
  * @param {String, String[], Boolean} params.fields - A comma-separated list of fields to return in the response
  * @param {String} params.lang - The script language (default: groovy)
- * @param {String} params.parent - ID of the parent document
  * @param {Boolean} params.refresh - Refresh the index after performing the operation
  * @param {String} [params.replication=sync] - Specific replication type
  * @param {Number} params.retryOnConflict - Specify how many times should the operation be retried when a conflict occurs (default: 0)
@@ -6023,9 +6061,6 @@ api.update = ca({
     lang: {
       type: 'string'
     },
-    parent: {
-      type: 'string'
-    },
     refresh: {
       type: 'boolean'
     },

src/lib/client_action.js

@@ -191,6 +191,11 @@ function exec(transport, spec, params, cb) {
     request.requestTimeout = spec.requestTimeout;
   }
 
+  if (!params.body && spec.paramAsBody) {
+    params.body = params[spec.paramAsBody];
+    delete params[spec.paramAsBody];
+  }
+
   // verify that we have the body if needed
   if (spec.needsBody && !params.body) {
     throw new TypeError('A request body is required.');

src/lib/errors.js

@@ -80,19 +80,19 @@ _.inherits(errors.RequestTypeError, ErrorAbstract);
 var statusCodes = {
 
   /**
-   * Service Unavailable
+   * ServiceUnavailable
    * @param {String} [msg] - An error message that will probably end up in a log.
    */
   503: 'Service Unavailable',
 
   /**
-   * Internal Server Error
+   * InternalServerError
    * @param {String} [msg] - An error message that will probably end up in a log.
    */
   500: 'Internal Server Error',
 
   /**
-   * Precondition Failed
+   * PreconditionFailed
    * @param {String} [msg] - An error message that will probably end up in a log.
    */
   412: 'Precondition Failed',
@@ -104,25 +104,31 @@ var statusCodes = {
   409: 'Conflict',
 
   /**
-   * Forbidden
+   * AuthorizationException
    * @param {String} [msg] - An error message that will probably end up in a log.
    */
-  403: 'Forbidden',
+  403: 'Authorization Exception',
 
   /**
-   * Not Found
+   * NotFound
    * @param {String} [msg] - An error message that will probably end up in a log.
    */
   404: 'Not Found',
 
   /**
-   * Bad Request
+   * AuthenticationException
+   * @param {String} [msg] - An error message that will probably end up in a log.
+   */
+  401: 'Authentication Exception',
+
+  /**
+   * BadRequest
    * @param {String} [msg] - An error message that will probably end up in a log.
    */
   400: 'Bad Request',
 
   /**
-   * Moved Permanently
+   * MovedPermanently
    * @param {String} [msg] - An error message that will probably end up in a log.
    */
   301: 'Moved Permanently'
@@ -132,10 +138,10 @@ _.each(statusCodes, function (name, status) {
   var className = _.studlyCase(name);
 
   function StatusCodeError(msg) {
-    ErrorAbstract.call(this, msg || name, errors[className]);
+    ErrorAbstract.call(this, msg || name, StatusCodeError);
   }
 
   _.inherits(StatusCodeError, ErrorAbstract);
   errors[className] = StatusCodeError;
   errors[status] = StatusCodeError;
-});
+});