doc enhancements for Host related config
This commit is contained in:
Spencer Alger
@ -18,6 +18,8 @@ WARNING: Due to the complex nature of the configuration, the config object you p
|
||||
[horizontal]
|
||||
`host or hosts`[[config-hosts]]::
|
||||
`String, String[], Object[]` -- Specify the hosts that this client will connect to. If sniffing is enabled, or you call `client.sniff()`, this list will be used as seeds to discover the rest of your cluster.
|
||||
+
|
||||
The value(s) are passed to the <<host-reference,`Host`>> constructor. `Host` objects can help enforce path-prefixes, default headers and query strings, and can be helpfull in making more intellegent selection algorithms; Head over to <<host-reference,the `Host` docs>> for more information.
|
||||
|
||||
Default:::
|
||||
+
|
||||
@ -29,7 +31,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:::
|
||||
@ -60,7 +61,7 @@ Options :::
|
||||
|
||||
|
||||
|
||||
`sniffOnStart`:: `Boolean` -- Should the client attempt to detect the rest of the cluster when it is first instantiated?
|
||||
`sniffOnStart`[[config-sniff-on-start]]:: `Boolean` -- Should the client attempt to detect the rest of the cluster when it is first instantiated?
|
||||
|
||||
Default::: `false`
|
||||
|
||||
@ -68,7 +69,7 @@ Default::: `false`
|
||||
|
||||
|
||||
|
||||
`sniffInterval`:: `Number, false` -- Every `n` milliseconds, perform a sniff operation and make sure our list of nodes is complete.
|
||||
`sniffInterval`[[config-sniff-interval]]:: `Number, false` -- Every `n` milliseconds, perform a sniff operation and make sure our list of nodes is complete.
|
||||
|
||||
Default::: `false`
|
||||
|
||||
@ -76,7 +77,7 @@ Default::: `false`
|
||||
|
||||
|
||||
|
||||
`sniffOnConnectionFault`:: `Boolean` -- Should the client immediately sniff for a more current list of nodes when a connection dies?
|
||||
`sniffOnConnectionFault`[[config-sniff-on-connection-fault]]:: `Boolean` -- Should the client immediately sniff for a more current list of nodes when a connection dies?
|
||||
|
||||
Default::: `false`
|
||||
|
||||
@ -99,32 +100,32 @@ Default::: `30000`
|
||||
|
||||
|
||||
|
||||
`deadTimeout`:: `Number` -- Milliseconds that a dead connection will wait before attempting to revive itself.
|
||||
`deadTimeout`[[config-dead-timeout]]:: `Number` -- Milliseconds that a dead connection will wait before attempting to revive itself.
|
||||
|
||||
Default::: `30000`
|
||||
|
||||
|
||||
|
||||
`keepAlive`:: `Boolean` -- Should the connections to the node be kept open forever? This behavior is recommended when you are connecting directly to Elasticsearch.
|
||||
`keepAlive`[[config-keep-alive]]:: `Boolean` -- Should the connections to the node be kept open forever? This behavior is recommended when you are connecting directly to Elasticsearch.
|
||||
|
||||
Default::: `true`
|
||||
|
||||
|
||||
|
||||
`maxSockets`:: `Number` -- Maximum number of concurrent requests that can be made to any node.
|
||||
`maxSockets`[[config-max-sockets]]:: `Number` -- Maximum number of concurrent requests that can be made to any node.
|
||||
|
||||
Default::: `10`
|
||||
|
||||
|
||||
|
||||
`minSockets`:: `Number` -- Minimum number of sockets to keep connected to a node, only applies when `keepAlive` is true
|
||||
`minSockets`[[config-min-sockets]]:: `Number` -- Minimum number of sockets to keep connected to a node, only applies when `keepAlive` is true
|
||||
|
||||
Default::: `10`
|
||||
|
||||
|
||||
|
||||
|
||||
`connectionClass`[[config-connectionClass]]:: `String, Constructor` -- Defines the class that will be used to create connections to store in the connection pool. If you are looking to implement additional protocols you should probably start by writing a Connection class that extends the ConnectionAbstract.
|
||||
`connectionClass`[[config-connection-class]]:: `String, Constructor` -- Defines the class that will be used to create connections to store in the connection pool. If you are looking to implement additional protocols you should probably start by writing a Connection class that extends the ConnectionAbstract.
|
||||
|
||||
Defaults:::
|
||||
* Node: `"http"`
|
||||
@ -135,7 +136,7 @@ Defaults:::
|
||||
|
||||
|
||||
|
||||
`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.
|
||||
`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.
|
||||
+
|
||||
To make this function asynchronous, accept a second argument which will be the callback to use. The callback should be called Node-style with a possible error like: `cb(err, selectedConnection)`.
|
||||
|
||||
@ -149,7 +150,7 @@ Options:::
|
||||
|
||||
|
||||
|
||||
`defer`:: `Function` -- Override the way that the client creates promises. If you would rather use any other promise library this is how you'd do that. Elasticsearch.js expects that the defer object has a `promise` property (which will be returned to promise consumers), as well as `resolve` and `reject` methods.
|
||||
`defer`[[config-defer]]:: `Function` -- Override the way that the client creates promises. If you would rather use any other promise library this is how you'd do that. Elasticsearch.js expects that the defer object has a `promise` property (which will be returned to promise consumers), as well as `resolve` and `reject` methods.
|
||||
|
||||
Default:::
|
||||
+
|
||||
@ -162,7 +163,7 @@ function () {
|
||||
|
||||
|
||||
|
||||
`nodesToHostCallback`:: `Function` - This function will receive the list of nodes returned from the `_cluster/nodes` API during a sniff operation. The function should return an array of objects which match the <<config-hosts,specification for the `hosts` config>>.
|
||||
`nodesToHostCallback`[[config-nodes-to-host-callback]]:: `Function` - This function will receive the list of nodes returned from the `_cluster/nodes` API during a sniff operation. The function should return an array of objects which match the <<config-hosts,specification for the `hosts` config>>.
|
||||
|
||||
Default:::
|
||||
see https://github.com/elasticsearch/elasticsearch-js/blob/master/src/lib/nodes_to_host.js[nodes_to_host.js]
|
||||
|
||||
103
docs/host.asciidoc
Normal file
103
docs/host.asciidoc
Normal file
@ -0,0 +1,103 @@
|
||||
[[host-reference]]
|
||||
== Host
|
||||
|
||||
The host class is used to represent a single node/host/endpoint. These objects are created automatically by the Client constructor, as well as durring sniff operations.
|
||||
|
||||
=== Constructor(params)
|
||||
|
||||
==== Params
|
||||
Params can either be URL string, or an object with the following properties
|
||||
|
||||
[horizontal]
|
||||
`host`::
|
||||
`String` -- The name of the host
|
||||
|
||||
Default ::: `"localhost"`
|
||||
|
||||
`port`::
|
||||
`Number` -- The port number to use for this host
|
||||
|
||||
Default ::: `9200`
|
||||
|
||||
`protocol`::
|
||||
`String` -- The name of the protocol this host is reachable on
|
||||
|
||||
Default ::: `"http"`
|
||||
|
||||
Options :::
|
||||
* `"http"`
|
||||
* `"https"`
|
||||
|
||||
|
||||
`path`::
|
||||
`String` -- A path prefix that should be prepended to every path requested.
|
||||
|
||||
`auth`::
|
||||
`String` -- Basic authentication i.e. 'user:password' to compute an Authorization header.
|
||||
|
||||
`query`::
|
||||
`String,Object` -- A default set of query string parameters to use on every request.
|
||||
|
||||
`headers`::
|
||||
`Object` -- An object describing the headers to send for every request to this node.
|
||||
|
||||
`...`::
|
||||
`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.
|
||||
|
||||
|
||||
=== Examples
|
||||
|
||||
.Using your application to proxy/filter elasticsearch requests can sometimes be a good idea. Use this configuration to always send requests to `https://my-site.com/elasticsearch/{{request url}}` rather than directly to elasticsearch.
|
||||
[source,js]
|
||||
-----
|
||||
var client = new elasticsearch.Client({
|
||||
host: {
|
||||
protocol: 'https',
|
||||
host: 'my-site.com',
|
||||
port: 80,
|
||||
path: '/elasticsearch/'
|
||||
}
|
||||
})
|
||||
-----
|
||||
|
||||
|
||||
.Use custom keys/vals to add special properties to the hosts, that are used by the selector.
|
||||
[source,js]
|
||||
-----
|
||||
var client = new elasticsearch.Client({
|
||||
hosts: [
|
||||
{
|
||||
protocol: 'https',
|
||||
host: 'box1.server.org',
|
||||
port: 56394,
|
||||
// these custom values are used below by the selector
|
||||
country: 'EU',
|
||||
weight: 10
|
||||
},
|
||||
{
|
||||
protocol: 'https',
|
||||
host: 'box2.server.org',
|
||||
port: 56394,
|
||||
// these custom values are used below by the selector
|
||||
country: 'US',
|
||||
weight: 50
|
||||
}
|
||||
],
|
||||
selector: function (hosts) {
|
||||
var myCountry = process.env.COUNTRY;
|
||||
// first try to find a node that is in the same country
|
||||
var selection = _.find(nodes, function (node) {
|
||||
return node.host.country === myCountry;
|
||||
});
|
||||
|
||||
if (!selection) {
|
||||
// choose the node with the lightest weight.
|
||||
selection = _(nodes).sortBy(function (node) {
|
||||
return node.host.weight;
|
||||
}).first();
|
||||
}
|
||||
|
||||
return selection;
|
||||
}
|
||||
});
|
||||
-----
|
||||
@ -20,6 +20,8 @@ include::api_methods_1_0.asciidoc[]
|
||||
|
||||
include::api_methods_0_90.asciidoc[]
|
||||
|
||||
include::errors.asciidoc[]
|
||||
include::host.asciidoc[]
|
||||
|
||||
include::transport.asciidoc[]
|
||||
include::transport.asciidoc[]
|
||||
|
||||
include::errors.asciidoc[]
|
||||
Reference in New Issue
Block a user