Skip to content

Commit 94623eb

Browse files
JoshMockJoshMock
committed
Drop vestigial node role/filter types and docs
See elastic/elastic-transport-js#231
1 parent 461f9b7 commit 94623eb

File tree

2 files changed

+198
-44
lines changed

2 files changed

+198
-44
lines changed

‎docs/reference/basic-config.md‎

Lines changed: 198 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -8,44 +8,205 @@ mapped_pages:
88
This page shows you the possible basic configuration options that the clients offers.
99

1010
```js
11-
const { Client } = require('@elastic/elasticsearch')
11+
const { Client } = require("@elastic/elasticsearch");
1212

1313
const client = new Client({
14-
cloud: { id: '<cloud-id>' },
15-
auth: { apiKey: 'base64EncodedKey' },
14+
cloud: { id: "<cloud-id>" },
15+
auth: { apiKey: "base64EncodedKey" },
1616
maxRetries: 5,
17-
sniffOnStart: true
18-
})
19-
```
20-
21-
| | |
22-
| --- | --- |
23-
| `node` or `nodes` | The Elasticsearch endpoint to use.<br> It can be a single string or an array of strings:<br><br>```js<br>node: 'http://localhost:9200'<br>```<br><br>Or it can be an object (or an array of objects) that represents the node:<br><br>```js<br>node: {<br> url: new URL('http://localhost:9200'),<br> tls: 'tls options',<br> agent: 'http agent options',<br> id: 'custom node id',<br> headers: { 'custom': 'headers' }<br> roles: {<br> master: true,<br> data: true,<br> ingest: true,<br> ml: false<br> }<br>}<br>```<br> |
24-
| `auth` | Your authentication data. You can use both basic authentication and [ApiKey](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key).<br> See [Authentication](/reference/connecting.md#authentication) for more details.<br> *Default:* `null`<br><br>Basic authentication:<br><br>```js<br>auth: {<br> username: 'elastic',<br> password: 'changeme'<br>}<br>```<br><br>[ApiKey](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key) authentication:<br><br>```js<br>auth: {<br> apiKey: 'base64EncodedKey'<br>}<br>```<br><br>Bearer authentication, useful for [service account tokens](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-service-token). Be aware that it does not handle automatic token refresh:<br><br>```js<br>auth: {<br> bearer: 'token'<br>}<br>```<br> |
25-
| `maxRetries` | `number` - Max number of retries for each request.<br>*Default:* `3` |
26-
| `requestTimeout` | `number` - Max request timeout in milliseconds for each request.<br>*Default:* No value |
27-
| `pingTimeout` | `number` - Max ping request timeout in milliseconds for each request.<br>*Default:* `3000` |
28-
| `sniffInterval` | `number, boolean` - Perform a sniff operation every `n` milliseconds. Sniffing might not be the best solution for you, take a look [here](https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how) to know more.<br>*Default:* `false` |
29-
| `sniffOnStart` | `boolean` - Perform a sniff once the client is started. Sniffing might not be the best solution for you, take a look [here](https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how) to know more.<br>*Default:* `false` |
30-
| `sniffEndpoint` | `string` - Endpoint to ping during a sniff.<br>*Default:* `'_nodes/_all/http'` |
31-
| `sniffOnConnectionFault` | `boolean` - Perform a sniff on connection fault. Sniffing might not be the best solution for you, take a look [here](https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how) to know more.<br>*Default:* `false` |
32-
| `resurrectStrategy` | `string` - Configure the node resurrection strategy.<br>*Options:* `'ping'`, `'optimistic'`, `'none'`<br>*Default:* `'ping'` |
33-
| `suggestCompression` | `boolean` - Adds `accept-encoding` header to every request.<br>*Default:* `false` |
34-
| `compression` | `string, boolean` - Enables gzip request body compression.<br>*Options:* `'gzip'`, `false`<br>*Default:* `false` |
35-
| `tls` | `http.SecureContextOptions` - tls [configuraton](https://nodejs.org/api/tls.md).<br>*Default:* `null` |
36-
| `proxy` | `string, URL` - If you are using an http(s) proxy, you can put its url here. The client will automatically handle the connection to it.<br> *Default:* `null`<br><br>```js<br>const client = new Client({<br> node: 'http://localhost:9200',<br> proxy: 'http://localhost:8080'<br>})<br><br>const client = new Client({<br> node: 'http://localhost:9200',<br> proxy: 'http://user:pwd@localhost:8080'<br>})<br>```<br> |
37-
| `agent` | `http.AgentOptions, function` - http agent [options](https://nodejs.org/api/http.md#http_new_agent_options), or a function that returns an actual http agent instance. If you want to disable the http agent use entirely (and disable the `keep-alive` feature), set the agent to `false`.<br> *Default:* `null`<br><br>```js<br>const client = new Client({<br> node: 'http://localhost:9200',<br> agent: { agent: 'options' }<br>})<br><br>const client = new Client({<br> node: 'http://localhost:9200',<br> // the function takes as parameter the option<br> // object passed to the Connection constructor<br> agent: (opts) => new CustomAgent()<br>})<br><br>const client = new Client({<br> node: 'http://localhost:9200',<br> // Disable agent and keep-alive<br> agent: false<br>})<br>```<br> |
38-
| `nodeFilter` | `function` - Filters which node not to use for a request.<br> *Default:*<br><br>```js<br>function defaultNodeFilter (node) {<br> // avoid master only nodes<br> if (node.roles.master === true &&<br> node.roles.data === false &&<br> node.roles.ingest === false) {<br> return false<br> }<br> return true<br>}<br>```<br> |
39-
| `nodeSelector` | `function` - custom selection strategy.<br> *Options:* `'round-robin'`, `'random'`, custom function<br> *Default:* `'round-robin'`<br> *Custom function example:*<br><br>```js<br>function nodeSelector (connections) {<br> const index = calculateIndex()<br> return connections[index]<br>}<br>```<br> |
40-
| `generateRequestId` | `function` - function to generate the request id for every request, it takes two parameters, the request parameters and options.<br> By default it generates an incremental integer for every request.<br> *Custom function example:*<br><br>```js<br>function generateRequestId (params, options) {<br> // your id generation logic<br> // must be syncronous<br> return 'id'<br>}<br>```<br> |
41-
| `name` | `string, symbol` - The name to identify the client instance in the events.<br>*Default:* `elasticsearch-js` |
42-
| `opaqueIdPrefix` | `string` - A string that will be use to prefix any `X-Opaque-Id` header.<br>See [`X-Opaque-Id` support](/reference/observability.md#_x_opaque_id_support) for more details.<br>_Default:* `null` |
43-
| `headers` | `object` - A set of custom headers to send in every request.<br>*Default:* `{}` |
44-
| `context` | `object` - A custom object that you can use for observability in your events.It will be merged with the API level context option.<br>*Default:* `null` |
45-
| `enableMetaHeader` | `boolean` - If true, adds an header named `'x-elastic-client-meta'`, containing some minimal telemetry data,such as the client and platform version.<br>*Default:* `true` |
46-
| `cloud` | `object` - Custom configuration for connecting to [Elastic Cloud](https://cloud.elastic.co). See [Authentication](/reference/connecting.md) for more details.<br> *Default:* `null`<br> *Cloud configuration example:*<br><br>```js<br>const client = new Client({<br> cloud: {<br> id: '<cloud-id>'<br> },<br> auth: {<br> username: 'elastic',<br> password: 'changeme'<br> }<br>})<br>```<br> |
47-
| `disablePrototypePoisoningProtection` | `boolean`, `'proto'`, `'constructor'` - The client can protect you against prototype poisoning attacks. Read [this article](https://web.archive.org/web/20200319091159/https://hueniverse.com/square-brackets-are-the-enemy-ff5b9fd8a3e8?gi=184a27ee2a08) to learn more about this security concern. If needed, you can enable prototype poisoning protection entirely (`false`) or one of the two checks (`'proto'` or `'constructor'`). For performance reasons, it is disabled by default. Read the `secure-json-parse` [documentation](https://github.com/fastify/secure-json-parse) to learn more.<br>*Default:* `true` |
48-
| `caFingerprint` | `string` - If configured, verify that the fingerprint of the CA certificate that has signed the certificate of the server matches the supplied fingerprint. Only accepts SHA256 digest fingerprints.<br>*Default:* `null` |
49-
| `maxResponseSize` | `number` - When configured, it verifies that the uncompressed response size is lower than the configured number, if it’s higher it will abort the request. It cannot be higher than buffer.constants.MAX_STRING_LENGTH<br>*Default:* `null` |
50-
| `maxCompressedResponseSize` | `number` - When configured, it verifies that the compressed response size is lower than the configured number, if it’s higher it will abort the request. It cannot be higher than buffer.constants.MAX_LENGTH<br>*Default:* `null` |
17+
sniffOnStart: true,
18+
});
19+
```
20+
21+
| | |
22+
| ----------------- | ------------------------------------------------------------------------------------ |
23+
| `node` or `nodes` | The Elasticsearch endpoint to use. It can be a single string or an array of strings: |
24+
25+
```js
26+
node: "http://localhost:9200";
27+
```
28+
29+
Or it can be an object (or an array of objects) that represents the node:
30+
31+
```js
32+
node: {
33+
url: new URL('http://localhost:9200'),
34+
tls: 'tls options',
35+
agent: 'http agent options',
36+
id: 'custom node id',
37+
headers: { 'custom': 'headers' }
38+
roles: {
39+
master: true,
40+
data: true,
41+
ingest: true,
42+
ml: false
43+
}
44+
}
45+
```
46+
47+
|
48+
| `auth` | Your authentication data. You can use both basic authentication and [ApiKey](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key).
49+
See [Authentication](/reference/connecting.md#authentication) for more details.
50+
_Default:_ `null`
51+
52+
Basic authentication:
53+
54+
```js
55+
auth: {
56+
username: 'elastic',
57+
password: 'changeme'
58+
}
59+
```
60+
61+
[ApiKey](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key) authentication:
62+
63+
```js
64+
auth: {
65+
apiKey: "base64EncodedKey";
66+
}
67+
```
68+
69+
Bearer authentication, useful for [service account tokens](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-service-token). Be aware that it does not handle automatic token refresh:
70+
71+
```js
72+
auth: {
73+
bearer: "token";
74+
}
75+
```
76+
77+
|
78+
| `maxRetries` | `number` - Max number of retries for each request.
79+
_Default:_ `3` |
80+
| `requestTimeout` | `number` - Max request timeout in milliseconds for each request.
81+
_Default:_ No value |
82+
| `pingTimeout` | `number` - Max ping request timeout in milliseconds for each request.
83+
_Default:_ `3000` |
84+
| `sniffInterval` | `number, boolean` - Perform a sniff operation every `n` milliseconds. Sniffing might not be the best solution for you, take a look [here](https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how) to know more.
85+
_Default:_ `false` |
86+
| `sniffOnStart` | `boolean` - Perform a sniff once the client is started. Sniffing might not be the best solution for you, take a look [here](https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how) to know more.
87+
_Default:_ `false` |
88+
| `sniffEndpoint` | `string` - Endpoint to ping during a sniff.
89+
_Default:_ `'_nodes/_all/http'` |
90+
| `sniffOnConnectionFault` | `boolean` - Perform a sniff on connection fault. Sniffing might not be the best solution for you, take a look [here](https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how) to know more.
91+
_Default:_ `false` |
92+
| `resurrectStrategy` | `string` - Configure the node resurrection strategy.
93+
_Options:_ `'ping'`, `'optimistic'`, `'none'`
94+
_Default:_ `'ping'` |
95+
| `suggestCompression` | `boolean` - Adds `accept-encoding` header to every request.
96+
_Default:_ `false` |
97+
| `compression` | `string, boolean` - Enables gzip request body compression.
98+
_Options:_ `'gzip'`, `false`
99+
_Default:_ `false` |
100+
| `tls` | `http.SecureContextOptions` - tls [configuraton](https://nodejs.org/api/tls.md).
101+
_Default:_ `null` |
102+
| `proxy` | `string, URL` - If you are using an http(s) proxy, you can put its url here. The client will automatically handle the connection to it.
103+
_Default:_ `null`
104+
105+
```js
106+
const client = new Client({
107+
node: "http://localhost:9200",
108+
proxy: "http://localhost:8080",
109+
});
110+
111+
const client = new Client({
112+
node: "http://localhost:9200",
113+
proxy: "http://user:pwd@localhost:8080",
114+
});
115+
```
116+
117+
|
118+
| `agent` | `http.AgentOptions, function` - http agent [options](https://nodejs.org/api/http.md#http_new_agent_options), or a function that returns an actual http agent instance. If you want to disable the http agent use entirely (and disable the `keep-alive` feature), set the agent to `false`.
119+
_Default:_ `null`
120+
121+
```js
122+
const client = new Client({
123+
node: "http://localhost:9200",
124+
agent: { agent: "options" },
125+
});
126+
127+
const client = new Client({
128+
node: "http://localhost:9200",
129+
// the function takes as parameter the option
130+
// object passed to the Connection constructor
131+
agent: (opts) => new CustomAgent(),
132+
});
133+
134+
const client = new Client({
135+
node: "http://localhost:9200",
136+
// Disable agent and keep-alive
137+
agent: false,
138+
});
139+
```
140+
141+
|
142+
143+
| `nodeFilter` | `function` - Filters which node not to use for a request.
144+
_Default:_
145+
146+
```js
147+
() => true;
148+
```
149+
150+
|
151+
| `nodeSelector` | `function` - custom selection strategy.
152+
_Options:_ `'round-robin'`, `'random'`, custom function
153+
_Default:_ `'round-robin'`
154+
_Custom function example:_
155+
156+
```js
157+
function nodeSelector(connections) {
158+
const index = calculateIndex();
159+
return connections[index];
160+
}
161+
```
162+
163+
|
164+
| `generateRequestId` | `function` - function to generate the request id for every request, it takes two parameters, the request parameters and options.
165+
By default it generates an incremental integer for every request.
166+
_Custom function example:_
167+
168+
```js
169+
function generateRequestId(params, options) {
170+
// your id generation logic
171+
// must be syncronous
172+
return "id";
173+
}
174+
```
175+
176+
|
177+
| `name` | `string, symbol` - The name to identify the client instance in the events.
178+
_Default:_ `elasticsearch-js` |
179+
| `opaqueIdPrefix` | `string` - A string that will be use to prefix any `X-Opaque-Id` header.
180+
See [`X-Opaque-Id` support](/reference/observability.md#_x_opaque_id_support) for more details.
181+
\_Default:*`null` |
182+
| `headers` | `object` - A set of custom headers to send in every request.
183+
_Default:_ `{}` |
184+
| `context` | `object` - A custom object that you can use for observability in your events.It will be merged with the API level context option.
185+
_Default:_ `null` |
186+
| `enableMetaHeader` | `boolean` - If true, adds an header named `'x-elastic-client-meta'`, containing some minimal telemetry data,such as the client and platform version.
187+
_Default:_ `true` |
188+
| `cloud` | `object` - Custom configuration for connecting to [Elastic Cloud](https://cloud.elastic.co). See [Authentication](/reference/connecting.md) for more details.
189+
_Default:_ `null`
190+
*Cloud configuration example:\*
191+
192+
```js
193+
const client = new Client({
194+
cloud: {
195+
id: "<cloud-id>",
196+
},
197+
auth: {
198+
username: "elastic",
199+
password: "changeme",
200+
},
201+
});
202+
```
51203

204+
|
205+
| `disablePrototypePoisoningProtection` | `boolean`, `'proto'`, `'constructor'` - The client can protect you against prototype poisoning attacks. Read [this article](https://web.archive.org/web/20200319091159/https://hueniverse.com/square-brackets-are-the-enemy-ff5b9fd8a3e8?gi=184a27ee2a08) to learn more about this security concern. If needed, you can enable prototype poisoning protection entirely (`false`) or one of the two checks (`'proto'` or `'constructor'`). For performance reasons, it is disabled by default. Read the `secure-json-parse` [documentation](https://github.com/fastify/secure-json-parse) to learn more.
206+
_Default:_ `true` |
207+
| `caFingerprint` | `string` - If configured, verify that the fingerprint of the CA certificate that has signed the certificate of the server matches the supplied fingerprint. Only accepts SHA256 digest fingerprints.
208+
_Default:_ `null` |
209+
| `maxResponseSize` | `number` - When configured, it verifies that the uncompressed response size is lower than the configured number, if it’s higher it will abort the request. It cannot be higher than buffer.constants.MAX*STRING_LENGTH
210+
\_Default:* `null` |
211+
| `maxCompressedResponseSize` | `number` - When configured, it verifies that the compressed response size is lower than the configured number, if it’s higher it will abort the request. It cannot be higher than buffer.constants.MAX*LENGTH
212+
\_Default:* `null` |

‎src/client.ts‎

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -64,13 +64,6 @@ export interface NodeOptions {
6464
ssl?: TlsConnectionOptions
6565
/** @property headers Custom HTTP headers that should be sent with each request */
6666
headers?: Record<string, any>
67-
/** @property roles Common Elasticsearch roles that can be assigned to this node. Can be helpful when writing custom nodeFilter or nodeSelector functions. */
68-
roles?: {
69-
master: boolean
70-
data: boolean
71-
ingest: boolean
72-
ml: boolean
73-
}
7467
}
7568

7669
export interface ClientOptions {

0 commit comments

Comments
 (0)