From 94623eb1673b9caf482ba47b8f2efb1913df9ae8 Mon Sep 17 00:00:00 2001 From: Josh Mock Date: Fri, 21 Mar 2025 14:07:47 -0500 Subject: [PATCH 1/6] Drop vestigial node role/filter types and docs See https://github.com/elastic/elastic-transport-js/issues/231 --- docs/reference/basic-config.md | 235 +++++++++++++++++++++++++++------ src/client.ts | 7 - 2 files changed, 198 insertions(+), 44 deletions(-) diff --git a/docs/reference/basic-config.md b/docs/reference/basic-config.md index dd3452217..47056003d 100644 --- a/docs/reference/basic-config.md +++ b/docs/reference/basic-config.md @@ -8,44 +8,205 @@ mapped_pages: This page shows you the possible basic configuration options that the clients offers. ```js -const { Client } = require('@elastic/elasticsearch') +const { Client } = require("@elastic/elasticsearch"); const client = new Client({ - cloud: { id: '' }, - auth: { apiKey: 'base64EncodedKey' }, + cloud: { id: "" }, + auth: { apiKey: "base64EncodedKey" }, maxRetries: 5, - sniffOnStart: true -}) -``` - -| | | -| --- | --- | -| `node` or `nodes` | The Elasticsearch endpoint to use.
It can be a single string or an array of strings:

```js
node: 'http://localhost:9200'
```

Or it can be an object (or an array of objects) that represents the node:

```js
node: {
url: new URL('http://localhost:9200'),
tls: 'tls options',
agent: 'http agent options',
id: 'custom node id',
headers: { 'custom': 'headers' }
roles: {
master: true,
data: true,
ingest: true,
ml: false
}
}
```
| -| `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).
See [Authentication](/reference/connecting.md#authentication) for more details.
*Default:* `null`

Basic authentication:

```js
auth: {
username: 'elastic',
password: 'changeme'
}
```

[ApiKey](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key) authentication:

```js
auth: {
apiKey: 'base64EncodedKey'
}
```

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:

```js
auth: {
bearer: 'token'
}
```
| -| `maxRetries` | `number` - Max number of retries for each request.
*Default:* `3` | -| `requestTimeout` | `number` - Max request timeout in milliseconds for each request.
*Default:* No value | -| `pingTimeout` | `number` - Max ping request timeout in milliseconds for each request.
*Default:* `3000` | -| `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.
*Default:* `false` | -| `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.
*Default:* `false` | -| `sniffEndpoint` | `string` - Endpoint to ping during a sniff.
*Default:* `'_nodes/_all/http'` | -| `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.
*Default:* `false` | -| `resurrectStrategy` | `string` - Configure the node resurrection strategy.
*Options:* `'ping'`, `'optimistic'`, `'none'`
*Default:* `'ping'` | -| `suggestCompression` | `boolean` - Adds `accept-encoding` header to every request.
*Default:* `false` | -| `compression` | `string, boolean` - Enables gzip request body compression.
*Options:* `'gzip'`, `false`
*Default:* `false` | -| `tls` | `http.SecureContextOptions` - tls [configuraton](https://nodejs.org/api/tls.md).
*Default:* `null` | -| `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.
*Default:* `null`

```js
const client = new Client({
node: 'http://localhost:9200',
proxy: 'http://localhost:8080'
})

const client = new Client({
node: 'http://localhost:9200',
proxy: 'http://user:pwd@localhost:8080'
})
```
| -| `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`.
*Default:* `null`

```js
const client = new Client({
node: 'http://localhost:9200',
agent: { agent: 'options' }
})

const client = new Client({
node: 'http://localhost:9200',
// the function takes as parameter the option
// object passed to the Connection constructor
agent: (opts) => new CustomAgent()
})

const client = new Client({
node: 'http://localhost:9200',
// Disable agent and keep-alive
agent: false
})
```
| -| `nodeFilter` | `function` - Filters which node not to use for a request.
*Default:*

```js
function defaultNodeFilter (node) {
// avoid master only nodes
if (node.roles.master === true &&
node.roles.data === false &&
node.roles.ingest === false) {
return false
}
return true
}
```
| -| `nodeSelector` | `function` - custom selection strategy.
*Options:* `'round-robin'`, `'random'`, custom function
*Default:* `'round-robin'`
*Custom function example:*

```js
function nodeSelector (connections) {
const index = calculateIndex()
return connections[index]
}
```
| -| `generateRequestId` | `function` - function to generate the request id for every request, it takes two parameters, the request parameters and options.
By default it generates an incremental integer for every request.
*Custom function example:*

```js
function generateRequestId (params, options) {
// your id generation logic
// must be syncronous
return 'id'
}
```
| -| `name` | `string, symbol` - The name to identify the client instance in the events.
*Default:* `elasticsearch-js` | -| `opaqueIdPrefix` | `string` - A string that will be use to prefix any `X-Opaque-Id` header.
See [`X-Opaque-Id` support](/reference/observability.md#_x_opaque_id_support) for more details.
_Default:* `null` | -| `headers` | `object` - A set of custom headers to send in every request.
*Default:* `{}` | -| `context` | `object` - A custom object that you can use for observability in your events.It will be merged with the API level context option.
*Default:* `null` | -| `enableMetaHeader` | `boolean` - If true, adds an header named `'x-elastic-client-meta'`, containing some minimal telemetry data,such as the client and platform version.
*Default:* `true` | -| `cloud` | `object` - Custom configuration for connecting to [Elastic Cloud](https://cloud.elastic.co). See [Authentication](/reference/connecting.md) for more details.
*Default:* `null`
*Cloud configuration example:*

```js
const client = new Client({
cloud: {
id: ''
},
auth: {
username: 'elastic',
password: 'changeme'
}
})
```
| -| `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.
*Default:* `true` | -| `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.
*Default:* `null` | -| `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
*Default:* `null` | -| `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
*Default:* `null` | + sniffOnStart: true, +}); +``` + +| | | +| ----------------- | ------------------------------------------------------------------------------------ | +| `node` or `nodes` | The Elasticsearch endpoint to use. It can be a single string or an array of strings: | + +```js +node: "http://localhost:9200"; +``` + +Or it can be an object (or an array of objects) that represents the node: + +```js +node: { + url: new URL('http://localhost:9200'), + tls: 'tls options', + agent: 'http agent options', + id: 'custom node id', + headers: { 'custom': 'headers' } + roles: { + master: true, + data: true, + ingest: true, + ml: false + } +} +``` + +| +| `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). +See [Authentication](/reference/connecting.md#authentication) for more details. +_Default:_ `null` + +Basic authentication: + +```js +auth: { + username: 'elastic', + password: 'changeme' +} +``` + +[ApiKey](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key) authentication: + +```js +auth: { + apiKey: "base64EncodedKey"; +} +``` + +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: + +```js +auth: { + bearer: "token"; +} +``` + +| +| `maxRetries` | `number` - Max number of retries for each request. +_Default:_ `3` | +| `requestTimeout` | `number` - Max request timeout in milliseconds for each request. +_Default:_ No value | +| `pingTimeout` | `number` - Max ping request timeout in milliseconds for each request. +_Default:_ `3000` | +| `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. +_Default:_ `false` | +| `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. +_Default:_ `false` | +| `sniffEndpoint` | `string` - Endpoint to ping during a sniff. +_Default:_ `'_nodes/_all/http'` | +| `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. +_Default:_ `false` | +| `resurrectStrategy` | `string` - Configure the node resurrection strategy. +_Options:_ `'ping'`, `'optimistic'`, `'none'` +_Default:_ `'ping'` | +| `suggestCompression` | `boolean` - Adds `accept-encoding` header to every request. +_Default:_ `false` | +| `compression` | `string, boolean` - Enables gzip request body compression. +_Options:_ `'gzip'`, `false` +_Default:_ `false` | +| `tls` | `http.SecureContextOptions` - tls [configuraton](https://nodejs.org/api/tls.md). +_Default:_ `null` | +| `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. +_Default:_ `null` + +```js +const client = new Client({ + node: "http://localhost:9200", + proxy: "http://localhost:8080", +}); + +const client = new Client({ + node: "http://localhost:9200", + proxy: "http://user:pwd@localhost:8080", +}); +``` + +| +| `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`. +_Default:_ `null` + +```js +const client = new Client({ + node: "http://localhost:9200", + agent: { agent: "options" }, +}); + +const client = new Client({ + node: "http://localhost:9200", + // the function takes as parameter the option + // object passed to the Connection constructor + agent: (opts) => new CustomAgent(), +}); + +const client = new Client({ + node: "http://localhost:9200", + // Disable agent and keep-alive + agent: false, +}); +``` + +| + +| `nodeFilter` | `function` - Filters which node not to use for a request. +_Default:_ + +```js +() => true; +``` + +| +| `nodeSelector` | `function` - custom selection strategy. +_Options:_ `'round-robin'`, `'random'`, custom function +_Default:_ `'round-robin'` +_Custom function example:_ + +```js +function nodeSelector(connections) { + const index = calculateIndex(); + return connections[index]; +} +``` + +| +| `generateRequestId` | `function` - function to generate the request id for every request, it takes two parameters, the request parameters and options. +By default it generates an incremental integer for every request. +_Custom function example:_ + +```js +function generateRequestId(params, options) { + // your id generation logic + // must be syncronous + return "id"; +} +``` + +| +| `name` | `string, symbol` - The name to identify the client instance in the events. +_Default:_ `elasticsearch-js` | +| `opaqueIdPrefix` | `string` - A string that will be use to prefix any `X-Opaque-Id` header. +See [`X-Opaque-Id` support](/reference/observability.md#_x_opaque_id_support) for more details. +\_Default:*`null` | +| `headers` | `object` - A set of custom headers to send in every request. +_Default:_ `{}` | +| `context` | `object` - A custom object that you can use for observability in your events.It will be merged with the API level context option. +_Default:_ `null` | +| `enableMetaHeader` | `boolean` - If true, adds an header named `'x-elastic-client-meta'`, containing some minimal telemetry data,such as the client and platform version. +_Default:_ `true` | +| `cloud` | `object` - Custom configuration for connecting to [Elastic Cloud](https://cloud.elastic.co). See [Authentication](/reference/connecting.md) for more details. +_Default:_ `null` +*Cloud configuration example:\* + +```js +const client = new Client({ + cloud: { + id: "", + }, + auth: { + username: "elastic", + password: "changeme", + }, +}); +``` +| +| `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. +_Default:_ `true` | +| `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. +_Default:_ `null` | +| `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 +\_Default:* `null` | +| `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 +\_Default:* `null` | diff --git a/src/client.ts b/src/client.ts index 43f78a6e5..88d6618b9 100644 --- a/src/client.ts +++ b/src/client.ts @@ -64,13 +64,6 @@ export interface NodeOptions { ssl?: TlsConnectionOptions /** @property headers Custom HTTP headers that should be sent with each request */ headers?: Record - /** @property roles Common Elasticsearch roles that can be assigned to this node. Can be helpful when writing custom nodeFilter or nodeSelector functions. */ - roles?: { - master: boolean - data: boolean - ingest: boolean - ml: boolean - } } export interface ClientOptions { From de3872875ce803873fa8bb796d2d599131076b87 Mon Sep 17 00:00:00 2001 From: Josh Mock Date: Fri, 21 Mar 2025 14:10:01 -0500 Subject: [PATCH 2/6] Update doc for clarity --- docs/reference/basic-config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/basic-config.md b/docs/reference/basic-config.md index 47056003d..f391f1b27 100644 --- a/docs/reference/basic-config.md +++ b/docs/reference/basic-config.md @@ -140,7 +140,7 @@ const client = new Client({ | -| `nodeFilter` | `function` - Filters which node not to use for a request. +| `nodeFilter` | `function` - Takes a `Connection` and returns `true` if it can be sent a request, otherwise `false`. _Default:_ ```js From 81f38c64bb5e2a4b1b3e601a4bb92f9e074779ee Mon Sep 17 00:00:00 2001 From: Josh Mock Date: Fri, 21 Mar 2025 14:23:22 -0500 Subject: [PATCH 3/6] Update formatting to maintain markdown table structure --- docs/reference/basic-config.md | 236 ++++++--------------------------- 1 file changed, 37 insertions(+), 199 deletions(-) diff --git a/docs/reference/basic-config.md b/docs/reference/basic-config.md index f391f1b27..61301e567 100644 --- a/docs/reference/basic-config.md +++ b/docs/reference/basic-config.md @@ -8,205 +8,43 @@ mapped_pages: This page shows you the possible basic configuration options that the clients offers. ```js -const { Client } = require("@elastic/elasticsearch"); +const { Client } = require('@elastic/elasticsearch') const client = new Client({ - cloud: { id: "" }, - auth: { apiKey: "base64EncodedKey" }, + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' }, maxRetries: 5, - sniffOnStart: true, -}); -``` - -| | | -| ----------------- | ------------------------------------------------------------------------------------ | -| `node` or `nodes` | The Elasticsearch endpoint to use. It can be a single string or an array of strings: | - -```js -node: "http://localhost:9200"; -``` - -Or it can be an object (or an array of objects) that represents the node: - -```js -node: { - url: new URL('http://localhost:9200'), - tls: 'tls options', - agent: 'http agent options', - id: 'custom node id', - headers: { 'custom': 'headers' } - roles: { - master: true, - data: true, - ingest: true, - ml: false - } -} -``` - -| -| `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). -See [Authentication](/reference/connecting.md#authentication) for more details. -_Default:_ `null` - -Basic authentication: - -```js -auth: { - username: 'elastic', - password: 'changeme' -} -``` - -[ApiKey](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key) authentication: - -```js -auth: { - apiKey: "base64EncodedKey"; -} -``` - -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: - -```js -auth: { - bearer: "token"; -} -``` - -| -| `maxRetries` | `number` - Max number of retries for each request. -_Default:_ `3` | -| `requestTimeout` | `number` - Max request timeout in milliseconds for each request. -_Default:_ No value | -| `pingTimeout` | `number` - Max ping request timeout in milliseconds for each request. -_Default:_ `3000` | -| `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. -_Default:_ `false` | -| `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. -_Default:_ `false` | -| `sniffEndpoint` | `string` - Endpoint to ping during a sniff. -_Default:_ `'_nodes/_all/http'` | -| `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. -_Default:_ `false` | -| `resurrectStrategy` | `string` - Configure the node resurrection strategy. -_Options:_ `'ping'`, `'optimistic'`, `'none'` -_Default:_ `'ping'` | -| `suggestCompression` | `boolean` - Adds `accept-encoding` header to every request. -_Default:_ `false` | -| `compression` | `string, boolean` - Enables gzip request body compression. -_Options:_ `'gzip'`, `false` -_Default:_ `false` | -| `tls` | `http.SecureContextOptions` - tls [configuraton](https://nodejs.org/api/tls.md). -_Default:_ `null` | -| `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. -_Default:_ `null` - -```js -const client = new Client({ - node: "http://localhost:9200", - proxy: "http://localhost:8080", -}); - -const client = new Client({ - node: "http://localhost:9200", - proxy: "http://user:pwd@localhost:8080", -}); -``` - -| -| `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`. -_Default:_ `null` - -```js -const client = new Client({ - node: "http://localhost:9200", - agent: { agent: "options" }, -}); - -const client = new Client({ - node: "http://localhost:9200", - // the function takes as parameter the option - // object passed to the Connection constructor - agent: (opts) => new CustomAgent(), -}); - -const client = new Client({ - node: "http://localhost:9200", - // Disable agent and keep-alive - agent: false, -}); -``` - -| - -| `nodeFilter` | `function` - Takes a `Connection` and returns `true` if it can be sent a request, otherwise `false`. -_Default:_ - -```js -() => true; -``` - -| -| `nodeSelector` | `function` - custom selection strategy. -_Options:_ `'round-robin'`, `'random'`, custom function -_Default:_ `'round-robin'` -_Custom function example:_ - -```js -function nodeSelector(connections) { - const index = calculateIndex(); - return connections[index]; -} -``` - -| -| `generateRequestId` | `function` - function to generate the request id for every request, it takes two parameters, the request parameters and options. -By default it generates an incremental integer for every request. -_Custom function example:_ - -```js -function generateRequestId(params, options) { - // your id generation logic - // must be syncronous - return "id"; -} -``` - -| -| `name` | `string, symbol` - The name to identify the client instance in the events. -_Default:_ `elasticsearch-js` | -| `opaqueIdPrefix` | `string` - A string that will be use to prefix any `X-Opaque-Id` header. -See [`X-Opaque-Id` support](/reference/observability.md#_x_opaque_id_support) for more details. -\_Default:*`null` | -| `headers` | `object` - A set of custom headers to send in every request. -_Default:_ `{}` | -| `context` | `object` - A custom object that you can use for observability in your events.It will be merged with the API level context option. -_Default:_ `null` | -| `enableMetaHeader` | `boolean` - If true, adds an header named `'x-elastic-client-meta'`, containing some minimal telemetry data,such as the client and platform version. -_Default:_ `true` | -| `cloud` | `object` - Custom configuration for connecting to [Elastic Cloud](https://cloud.elastic.co). See [Authentication](/reference/connecting.md) for more details. -_Default:_ `null` -*Cloud configuration example:\* - -```js -const client = new Client({ - cloud: { - id: "", - }, - auth: { - username: "elastic", - password: "changeme", - }, -}); -``` - -| -| `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. -_Default:_ `true` | -| `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. -_Default:_ `null` | -| `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 -\_Default:* `null` | -| `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 -\_Default:* `null` | + sniffOnStart: true +}) +``` + +| | | +| --- | --- | +| `node` or `nodes` | The Elasticsearch endpoint to use.
It can be a single string or an array of strings:

```js
node: 'http://localhost:9200'
```

Or it can be an object (or an array of objects) that represents the node:

```js
node: {
url: new URL('http://localhost:9200'),
tls: 'tls options',
agent: 'http agent options',
id: 'custom node id',
headers: { 'custom': 'headers' }
roles: {
master: true,
data: true,
ingest: true,
ml: false
}
}
```
| +| `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).
See [Authentication](/reference/connecting.md#authentication) for more details.
*Default:* `null`

Basic authentication:

```js
auth: {
username: 'elastic',
password: 'changeme'
}
```

[ApiKey](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key) authentication:

```js
auth: {
apiKey: 'base64EncodedKey'
}
```

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:

```js
auth: {
bearer: 'token'
}
```
| +| `maxRetries` | `number` - Max number of retries for each request.
*Default:* `3` | +| `requestTimeout` | `number` - Max request timeout in milliseconds for each request.
*Default:* No value | +| `pingTimeout` | `number` - Max ping request timeout in milliseconds for each request.
*Default:* `3000` | +| `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.
*Default:* `false` | +| `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.
*Default:* `false` | +| `sniffEndpoint` | `string` - Endpoint to ping during a sniff.
*Default:* `'_nodes/_all/http'` | +| `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.
*Default:* `false` | +| `resurrectStrategy` | `string` - Configure the node resurrection strategy.
*Options:* `'ping'`, `'optimistic'`, `'none'`
*Default:* `'ping'` | +| `suggestCompression` | `boolean` - Adds `accept-encoding` header to every request.
*Default:* `false` | +| `compression` | `string, boolean` - Enables gzip request body compression.
*Options:* `'gzip'`, `false`
*Default:* `false` | +| `tls` | `http.SecureContextOptions` - tls [configuraton](https://nodejs.org/api/tls.md).
*Default:* `null` | +| `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.
*Default:* `null`

```js
const client = new Client({
node: 'http://localhost:9200',
proxy: 'http://localhost:8080'
})

const client = new Client({
node: 'http://localhost:9200',
proxy: 'http://user:pwd@localhost:8080'
})
```
| +| `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`.
*Default:* `null`

```js
const client = new Client({
node: 'http://localhost:9200',
agent: { agent: 'options' }
})

const client = new Client({
node: 'http://localhost:9200',
// the function takes as parameter the option
// object passed to the Connection constructor
agent: (opts) => new CustomAgent()
})

const client = new Client({
node: 'http://localhost:9200',
// Disable agent and keep-alive
agent: false
})
```
| +| `nodeFilter` | `function` - Takes a `Connection` and returns `true` if it can be sent a request, otherwise `false`.
*Default:*

```js
() => true
```
| +| `nodeSelector` | `function` - custom selection strategy.
*Options:* `'round-robin'`, `'random'`, custom function
*Default:* `'round-robin'`
*Custom function example:*

```js
function nodeSelector (connections) {
const index = calculateIndex()
return connections[index]
}
```
| +| `generateRequestId` | `function` - function to generate the request id for every request, it takes two parameters, the request parameters and options.
By default it generates an incremental integer for every request.
*Custom function example:*

```js
function generateRequestId (params, options) {
// your id generation logic
// must be syncronous
return 'id'
}
```
| +| `name` | `string, symbol` - The name to identify the client instance in the events.
*Default:* `elasticsearch-js` | +| `opaqueIdPrefix` | `string` - A string that will be use to prefix any `X-Opaque-Id` header.
See [`X-Opaque-Id` support](/reference/observability.md#_x_opaque_id_support) for more details.
_Default:* `null` | +| `headers` | `object` - A set of custom headers to send in every request.
*Default:* `{}` | +| `context` | `object` - A custom object that you can use for observability in your events.It will be merged with the API level context option.
*Default:* `null` | +| `enableMetaHeader` | `boolean` - If true, adds an header named `'x-elastic-client-meta'`, containing some minimal telemetry data,such as the client and platform version.
*Default:* `true` | +| `cloud` | `object` - Custom configuration for connecting to [Elastic Cloud](https://cloud.elastic.co). See [Authentication](/reference/connecting.md) for more details.
*Default:* `null`
*Cloud configuration example:*

```js
const client = new Client({
cloud: {
id: ''
},
auth: {
username: 'elastic',
password: 'changeme'
}
})
```
| +| `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.
*Default:* `true` | +| `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.
*Default:* `null` | +| `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
*Default:* `null` | +| `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
*Default:* `null` | From 87f2bf16fe738db2f78bb9dc77d7223be41978b0 Mon Sep 17 00:00:00 2001 From: Josh Mock Date: Fri, 21 Mar 2025 14:33:26 -0500 Subject: [PATCH 4/6] Update table again --- docs/reference/basic-config.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/reference/basic-config.md b/docs/reference/basic-config.md index 61301e567..03660a92a 100644 --- a/docs/reference/basic-config.md +++ b/docs/reference/basic-config.md @@ -7,7 +7,7 @@ mapped_pages: This page shows you the possible basic configuration options that the clients offers. -```js +

 const { Client } = require('@elastic/elasticsearch')
 
 const client = new Client({
@@ -20,8 +20,8 @@ const client = new Client({
 
 |     |     |
 | --- | --- |
-| `node` or `nodes` | The Elasticsearch endpoint to use.
 It can be a single string or an array of strings:

```js
node: 'http://localhost:9200'
```

Or it can be an object (or an array of objects) that represents the node:

```js
node: {
  url: new URL('http://localhost:9200'),
  tls: 'tls options',
  agent: 'http agent options',
  id: 'custom node id',
  headers: { 'custom': 'headers' }
  roles: {
    master: true,
    data: true,
    ingest: true,
    ml: false
  }
}
```
 |
-| `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).
 See [Authentication](/reference/connecting.md#authentication) for more details.
 *Default:* `null`

Basic authentication:

```js
auth: {
  username: 'elastic',
  password: 'changeme'
}
```

[ApiKey](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key) authentication:

```js
auth: {
  apiKey: 'base64EncodedKey'
}
```

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:

```js
auth: {
  bearer: 'token'
}
```
 |
+| `node` or `nodes` | The Elasticsearch endpoint to use.
 It can be a single string or an array of strings:


node: 'http://localhost:9200'


Or it can be an object (or an array of objects) that represents the node:


node: {
  url: new URL('http://localhost:9200'),
  tls: 'tls options',
  agent: 'http agent options',
  id: 'custom node id',
  headers: { 'custom': 'headers' }
  roles: {
    master: true,
    data: true,
    ingest: true,
    ml: false
  }
}

 |
+| `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).
 See [Authentication](/reference/connecting.md#authentication) for more details.
 *Default:* `null`

Basic authentication:


auth: {
  username: 'elastic',
  password: 'changeme'
}


[ApiKey](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key) authentication:


auth: {
  apiKey: 'base64EncodedKey'
}


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:


auth: {
  bearer: 'token'
}

 |
 | `maxRetries` | `number` - Max number of retries for each request.
*Default:* `3` |
 | `requestTimeout` | `number` - Max request timeout in milliseconds for each request.
*Default:* No value |
 | `pingTimeout` | `number` - Max ping request timeout in milliseconds for each request.
*Default:* `3000` |
@@ -33,17 +33,17 @@ const client = new Client({
 | `suggestCompression` | `boolean` - Adds `accept-encoding` header to every request.
*Default:* `false` |
 | `compression` | `string, boolean` - Enables gzip request body compression.
*Options:* `'gzip'`, `false`
*Default:* `false` |
 | `tls` | `http.SecureContextOptions` - tls [configuraton](https://nodejs.org/api/tls.md).
*Default:* `null` |
-| `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.
 *Default:* `null`

```js
const client = new Client({
  node: 'http://localhost:9200',
  proxy: 'http://localhost:8080'
})

const client = new Client({
  node: 'http://localhost:9200',
  proxy: 'http://user:pwd@localhost:8080'
})
```
 |
-| `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`.
 *Default:* `null`

```js
const client = new Client({
  node: 'http://localhost:9200',
  agent: { agent: 'options' }
})

const client = new Client({
  node: 'http://localhost:9200',
  // the function takes as parameter the option
  // object passed to the Connection constructor
  agent: (opts) => new CustomAgent()
})

const client = new Client({
  node: 'http://localhost:9200',
  // Disable agent and keep-alive
  agent: false
})
```
 |
-| `nodeFilter` | `function` - Takes a `Connection` and returns `true` if it can be sent a request, otherwise `false`.
 *Default:*

```js
() => true
```
 |
-| `nodeSelector` | `function` - custom selection strategy.
 *Options:* `'round-robin'`, `'random'`, custom function
 *Default:* `'round-robin'`
 *Custom function example:*

```js
function nodeSelector (connections) {
  const index = calculateIndex()
  return connections[index]
}
```
 |
-| `generateRequestId` | `function` - function to generate the request id for every request, it takes two parameters, the request parameters and options.
 By default it generates an incremental integer for every request.
 *Custom function example:*

```js
function generateRequestId (params, options) {
  // your id generation logic
  // must be syncronous
  return 'id'
}
```
 |
+| `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.
 *Default:* `null`


const client = new Client({
  node: 'http://localhost:9200',
  proxy: 'http://localhost:8080'
})

const client = new Client({
  node: 'http://localhost:9200',
  proxy: 'http://user:pwd@localhost:8080'
})

 |
+| `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`.
 *Default:* `null`


const client = new Client({
  node: 'http://localhost:9200',
  agent: { agent: 'options' }
})

const client = new Client({
  node: 'http://localhost:9200',
  // the function takes as parameter the option
  // object passed to the Connection constructor
  agent: (opts) => new CustomAgent()
})

const client = new Client({
  node: 'http://localhost:9200',
  // Disable agent and keep-alive
  agent: false
})

 |
+| `nodeFilter` | `function` - Takes a `Connection` and returns `true` if it can be sent a request, otherwise `false`.
 *Default:*


() => true

 |
+| `nodeSelector` | `function` - custom selection strategy.
 *Options:* `'round-robin'`, `'random'`, custom function
 *Default:* `'round-robin'`
 *Custom function example:*


function nodeSelector (connections) {
  const index = calculateIndex()
  return connections[index]
}

 |
+| `generateRequestId` | `function` - function to generate the request id for every request, it takes two parameters, the request parameters and options.
 By default it generates an incremental integer for every request.
 *Custom function example:*


function generateRequestId (params, options) {
  // your id generation logic
  // must be syncronous
  return 'id'
}

 |
 | `name` | `string, symbol` - The name to identify the client instance in the events.
*Default:* `elasticsearch-js` |
 | `opaqueIdPrefix` | `string` - A string that will be use to prefix any `X-Opaque-Id` header.
See [`X-Opaque-Id` support](/reference/observability.md#_x_opaque_id_support) for more details.
_Default:* `null` |
 | `headers` | `object` - A set of custom headers to send in every request.
*Default:* `{}` |
 | `context` | `object` - A custom object that you can use for observability in your events.It will be merged with the API level context option.
*Default:* `null` |
 | `enableMetaHeader` | `boolean` - If true, adds an header named `'x-elastic-client-meta'`, containing some minimal telemetry data,such as the client and platform version.
*Default:* `true` |
-| `cloud` | `object` - Custom configuration for connecting to [Elastic Cloud](https://cloud.elastic.co). See [Authentication](/reference/connecting.md) for more details.
 *Default:* `null`
 *Cloud configuration example:*

```js
const client = new Client({
  cloud: {
    id: ''
  },
  auth: {
    username: 'elastic',
    password: 'changeme'
  }
})
```
 |
+| `cloud` | `object` - Custom configuration for connecting to [Elastic Cloud](https://cloud.elastic.co). See [Authentication](/reference/connecting.md) for more details.
 *Default:* `null`
 *Cloud configuration example:*


const client = new Client({
  cloud: {
    id: ''
  },
  auth: {
    username: 'elastic',
    password: 'changeme'
  }
})

 |
 | `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.
*Default:* `true` |
 | `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.
*Default:* `null` |
 | `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
*Default:* `null` |

From e0a5785a45ba84d642aec7cbedeb7c2210351073 Mon Sep 17 00:00:00 2001
From: Josh Mock 
Date: Fri, 21 Mar 2025 14:35:43 -0500
Subject: [PATCH 5/6] Fix the fixin' fix

---
 docs/reference/basic-config.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/docs/reference/basic-config.md b/docs/reference/basic-config.md
index 03660a92a..da1bcb2a3 100644
--- a/docs/reference/basic-config.md
+++ b/docs/reference/basic-config.md
@@ -7,7 +7,9 @@ mapped_pages:
 
 This page shows you the possible basic configuration options that the clients offers.
 
-

+```js
+```
+
 const { Client } = require('@elastic/elasticsearch')
 
 const client = new Client({
@@ -16,6 +18,7 @@ const client = new Client({
   maxRetries: 5,
   sniffOnStart: true
 })
+
 ```
 
 |     |     |

From b51c54883987bd1f196aa22df01a22f6098f6640 Mon Sep 17 00:00:00 2001
From: Josh Mock 
Date: Fri, 21 Mar 2025 14:45:38 -0500
Subject: [PATCH 6/6] I rarely know what's happening

---
 docs/reference/basic-config.md | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/docs/reference/basic-config.md b/docs/reference/basic-config.md
index da1bcb2a3..04d5c5fb7 100644
--- a/docs/reference/basic-config.md
+++ b/docs/reference/basic-config.md
@@ -8,8 +8,6 @@ mapped_pages:
 This page shows you the possible basic configuration options that the clients offers.
 
 ```js
-```
-
 const { Client } = require('@elastic/elasticsearch')
 
 const client = new Client({
@@ -18,7 +16,6 @@ const client = new Client({
   maxRetries: 5,
   sniffOnStart: true
 })
-
 ```
 
 |     |     |