diff --git a/docs/authentication.asciidoc b/docs/authentication.asciidoc deleted file mode 100644 index f7f741b05..000000000 --- a/docs/authentication.asciidoc +++ /dev/null @@ -1,133 +0,0 @@ -[[auth-reference]] -== Authentication - -This document contains code snippets to show you how to connect to various {es} -providers. - - -[discrete] -=== Elastic Cloud - -If you are using https://www.elastic.co/cloud[Elastic Cloud], the client offers -an easy way to connect to it via the `cloud` option. You must pass the Cloud ID -that you can find in the cloud console, then your username and password inside -the `auth` option. - -NOTE: When connecting to Elastic Cloud, the client will automatically enable -both request and response compression by default, since it yields significant -throughput improvements. Moreover, the client will also set the ssl option -`secureProtocol` to `TLSv1_2_method` unless specified otherwise. You can still -override this option by configuring them. - -IMPORTANT: Do not enable sniffing when using Elastic Cloud, since the nodes are -behind a load balancer, Elastic Cloud will take care of everything for you. -Take a look https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how[here] -to know more. - -[source,js] ----- -const { Client } = require('@elastic/elasticsearch') -const client = new Client({ - cloud: { - id: 'name:bG9jYWxob3N0JGFiY2QkZWZnaA==', - }, - auth: { - username: 'elastic', - password: 'changeme' - } -}) ----- - - -[discrete] -=== Basic authentication - -You can provide your credentials by passing the `username` and `password` -parameters via the `auth` option. - -NOTE: If you provide both basic authentication credentials and the Api Key configuration, the Api Key will take precedence. - -[source,js] ----- -const { Client } = require('@elastic/elasticsearch') -const client = new Client({ - node: 'https://localhost:9200', - auth: { - username: 'elastic', - password: 'changeme' - } -}) ----- - - -Otherwise, you can provide your credentials in the node(s) URL. - -[source,js] ----- -const { Client } = require('@elastic/elasticsearch') -const client = new Client({ - node: 'https://username:password@localhost:9200' -}) ----- - - -[discrete] -=== ApiKey authentication - -You can use the -https://www.elastic.co/guide/en/elasticsearch/reference/7.x/security-api-create-api-key.html[ApiKey] -authentication by passing the `apiKey` parameter via the `auth` option. The -`apiKey` parameter can be either a base64 encoded string or an object with the -values that you can obtain from the -https://www.elastic.co/guide/en/elasticsearch/reference/7.x/security-api-create-api-key.html[create api key endpoint]. - -NOTE: If you provide both basic authentication credentials and the Api Key configuration, the Api Key will take precedence. - -[source,js] ----- -const { Client } = require('@elastic/elasticsearch') -const client = new Client({ - node: 'https://localhost:9200', - auth: { - apiKey: 'base64EncodedKey' - } -}) ----- - -[source,js] ----- -const { Client } = require('@elastic/elasticsearch') -const client = new Client({ - node: 'https://localhost:9200', - auth: { - apiKey: { - id: 'foo', - api_key: 'bar' - } - } -}) ----- - - -[discrete] -=== SSL configuration - -Without any additional configuration you can specify `https://` node urls, and -the certificates used to sign these requests will be verified. To turn off certificate verification, you must specify an `ssl` object in the top level config and set `rejectUnauthorized: false`. The default `ssl` values are the same that Node.js's https://nodejs.org/api/tls.html#tls_tls_connect_options_callback[`tls.connect()`] -uses. - -[source,js] ----- -const { Client } = require('@elastic/elasticsearch') -const client = new Client({ - node: 'https://localhost:9200', - auth: { - username: 'elastic', - password: 'changeme' - }, - ssl: { - ca: fs.readFileSync('./cacert.pem'), - rejectUnauthorized: false - } -}) ----- \ No newline at end of file diff --git a/docs/usage.asciidoc b/docs/connecting.asciidoc similarity index 59% rename from docs/usage.asciidoc rename to docs/connecting.asciidoc index c808bbf17..4854a096a 100644 --- a/docs/usage.asciidoc +++ b/docs/connecting.asciidoc @@ -1,5 +1,164 @@ +[[client-connecting]] +== Connecting + +This page contains the information you need to connect and use the Client with +{es}. + +**On this page** + +* <> +* <> +* <> +* <> + +[discrete] +[[authentication]] +=== Authentication + +This document contains code snippets to show you how to connect to various {es} +providers. + + +[discrete] +[[auth-ec]] +==== Elastic Cloud + +If you are using https://www.elastic.co/cloud[Elastic Cloud], the client offers +an easy way to connect to it via the `cloud` option. You must pass the Cloud ID +that you can find in the cloud console, then your username and password inside +the `auth` option. + +NOTE: When connecting to Elastic Cloud, the client will automatically enable +both request and response compression by default, since it yields significant +throughput improvements. Moreover, the client will also set the ssl option +`secureProtocol` to `TLSv1_2_method` unless specified otherwise. You can still +override this option by configuring them. + +IMPORTANT: Do not enable sniffing when using Elastic Cloud, since the nodes are +behind a load balancer, Elastic Cloud will take care of everything for you. +Take a look https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how[here] +to know more. + +[source,js] +---- +const { Client } = require('@elastic/elasticsearch') +const client = new Client({ + cloud: { + id: 'name:bG9jYWxob3N0JGFiY2QkZWZnaA==', + }, + auth: { + username: 'elastic', + password: 'changeme' + } +}) +---- + + +[discrete] +[[auth-apikey]] +==== ApiKey authentication + +You can use the +https://www.elastic.co/guide/en/elasticsearch/reference/7.x/security-api-create-api-key.html[ApiKey] +authentication by passing the `apiKey` parameter via the `auth` option. The +`apiKey` parameter can be either a base64 encoded string or an object with the +values that you can obtain from the +https://www.elastic.co/guide/en/elasticsearch/reference/7.x/security-api-create-api-key.html[create api key endpoint]. + +NOTE: If you provide both basic authentication credentials and the ApiKey +configuration, the ApiKey takes precedence. + +[source,js] +---- +const { Client } = require('@elastic/elasticsearch') +const client = new Client({ + node: 'https://localhost:9200', + auth: { + apiKey: 'base64EncodedKey' + } +}) +---- + +[source,js] +---- +const { Client } = require('@elastic/elasticsearch') +const client = new Client({ + node: 'https://localhost:9200', + auth: { + apiKey: { + id: 'foo', + api_key: 'bar' + } + } +}) +---- + + +[discrete] +[[auth-basic]] +==== Basic authentication + +You can provide your credentials by passing the `username` and `password` +parameters via the `auth` option. + +NOTE: If you provide both basic authentication credentials and the Api Key +configuration, the Api Key will take precedence. + +[source,js] +---- +const { Client } = require('@elastic/elasticsearch') +const client = new Client({ + node: 'https://localhost:9200', + auth: { + username: 'elastic', + password: 'changeme' + } +}) +---- + + +Otherwise, you can provide your credentials in the node(s) URL. + +[source,js] +---- +const { Client } = require('@elastic/elasticsearch') +const client = new Client({ + node: 'https://username:password@localhost:9200' +}) +---- + + +[discrete] +[[auth-ssl]] +==== SSL configuration + +Without any additional configuration you can specify `https://` node urls, and +the certificates used to sign these requests will be verified. To turn off +certificate verification, you must specify an `ssl` object in the top level +config and set `rejectUnauthorized: false`. The default `ssl` values are the +same that Node.js's +https://nodejs.org/api/tls.html#tls_tls_connect_options_callback[`tls.connect()`] +uses. + +[source,js] +---- +const { Client } = require('@elastic/elasticsearch') +const client = new Client({ + node: 'https://localhost:9200', + auth: { + username: 'elastic', + password: 'changeme' + }, + ssl: { + ca: fs.readFileSync('./cacert.pem'), + rejectUnauthorized: false + } +}) +---- + +[discrete] [[client-usage]] -== Usage +=== Usage Using the client is straightforward, it supports all the public APIs of {es}, and every method exposes the same signature. @@ -33,7 +192,7 @@ client.search({ }) ---- -The returned value of every API call is formed as follows: +The returned value of every API call is designed as follows: [source,ts] ---- @@ -82,11 +241,13 @@ client.search({ [discrete] -=== Aborting a request +==== Aborting a request -If needed, you can abort a running request by calling the `request.abort()` method returned by the API. +If needed, you can abort a running request by calling the `request.abort()` +method returned by the API. -CAUTION: If you abort a request, the request will fail with a `RequestAbortedError`. +CAUTION: If you abort a request, the request will fail with a +`RequestAbortedError`. [source,js] @@ -113,6 +274,7 @@ request.abort() ---- The same behavior is valid for the promise style API as well. + [source,js] ---- const request = client.search({ @@ -136,7 +298,8 @@ request.abort() [discrete] -=== Request specific options +==== Request specific options + If needed you can pass request specific options in a second object: [source,js] @@ -214,13 +377,14 @@ _Default:_ `null` [discrete] +[[client-connect-proxy]] === Connecting through a proxy ~Added~ ~in~ ~`v7.10.0`~ -If you need to pass through an http(s) proxy for connecting to Elasticsearch, the client offers -out of the box a handy configuration for helping you with it. Under the hood it -uses the https://github.com/delvedor/hpagent[`hpagent`] module. +If you need to pass through an http(s) proxy for connecting to {es}, the client +offers out of the box a handy configuration for helping you with it. Under the +hood, it uses the https://github.com/delvedor/hpagent[`hpagent`] module. [source,js] ---- @@ -256,6 +420,7 @@ const client = new Client({ [discrete] +[[client-error-handling]] === Error handling The client exposes a variety of error objects that you can use to enhance your diff --git a/docs/index.asciidoc b/docs/index.asciidoc index f40d92aaa..c1e6bc831 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -5,12 +5,11 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[] include::introduction.asciidoc[] include::installation.asciidoc[] +include::connecting.asciidoc[] include::changelog.asciidoc[] -include::usage.asciidoc[] include::configuration.asciidoc[] include::reference.asciidoc[] include::breaking-changes.asciidoc[] -include::authentication.asciidoc[] include::observability.asciidoc[] include::child.asciidoc[] include::extend.asciidoc[] @@ -18,3 +17,4 @@ include::helpers.asciidoc[] include::typescript.asciidoc[] include::testing.asciidoc[] include::examples/index.asciidoc[] +include::redirects.asciidoc[] diff --git a/docs/introduction.asciidoc b/docs/introduction.asciidoc index f20963bb0..d2f4b61f1 100644 --- a/docs/introduction.asciidoc +++ b/docs/introduction.asciidoc @@ -17,44 +17,6 @@ about the features of the client. * TypeScript support out of the box. -[discrete] -[[js-compatibility-matrix]] -=== Compatibility matrix - -The minimum supported version of Node.js is `v8`. - -The library is compatible with all {es} versions since 5.x. We recommend you to -use the same major version of the client as the {es} instance that you are -using. - - -[%header,cols=2*] -|=== -|{es} Version -|Client Version - -|`master` -|`master` - -|`7.x` -|`7.x` - -|`6.x` -|`6.x` - -|`5.x` -|`5.x` -|=== - - -[discrete] -==== Browser - -WARNING: There is no official support for the browser environment. It exposes -your {es} instance to everyone, which could lead to security issues. We -recommend you to write a lightweight proxy that uses this client instead. - - [discrete] === Quick start diff --git a/docs/redirects.asciidoc b/docs/redirects.asciidoc new file mode 100644 index 000000000..a7d0ec46d --- /dev/null +++ b/docs/redirects.asciidoc @@ -0,0 +1,9 @@ +"appendix",role="exclude",id="redirects"] += Deleted pages + +The following pages have moved or been deleted. + +[role="exclude",id="auth-reference"] +== Authentication + +This page has moved. See <>. diff --git a/index.js b/index.js index d575bc2d8..c3c278efc 100644 --- a/index.js +++ b/index.js @@ -41,6 +41,24 @@ const kEventEmitter = Symbol('elasticsearchjs-event-emitter') const ESAPI = require('./api') +/* istanbul ignore next */ +if (nodeMajor < 10) { + process.emitWarning('You are using a version of Node.js that is currently in EOL. ' + + 'The support for this version will be dropped in 7.12. ' + + 'Please refer to https://ela.st/nodejs-support for additional information.', + 'DeprecationWarning' + ) +} + +/* istanbul ignore next */ +if (nodeMajor >= 10 && nodeMajor < 12) { + process.emitWarning('You are using a version of Node.js that will reach EOL in April 2021. ' + + 'The support for this version will be dropped in 7.13. ' + + 'Please refer to https://ela.st/nodejs-support for additional information.', + 'DeprecationWarning' + ) +} + class Client extends ESAPI { constructor (opts = {}) { super({ ConfigurationError })