[Backport 8.0] Changelog for 8.0 (#1622)

Co-authored-by: Tomas Della Vedova <[email protected]>

Author: github-actions[bot]

docs/changelog.asciidoc

@@ -0,0 +1,307 @@
+[[changelog-client]]
+== Release notes
+
+[discrete]
+=== 8.0.0
+
+[discrete]
+==== Features
+
+[discrete]
+[discrete]
+===== Support for Elasticsearch `v8.0`
+
+You can find all the API changes
+https://www.elastic.co/guide/en/elasticsearch/reference/8.0/release-notes-8.0.0.html[here].
+
+[discrete]
+===== Drop old typescript definitions
+
+*Breaking: Yes* | *Migration effort: Medium*
+
+The current TypeScript definitions will be removed from the client, and the new definitions, which contain request and response definitions as well will be shipped by default.
+
+[discrete]
+===== Drop callback-style API
+
+*Breaking: Yes* | *Migration effort: Large*
+
+Maintaining both API styles is not a problem per se, but it makes error handling more convoluted due to async stack traces.
+Moving to a full-promise API will solve this issue.
+
+[source,js]
+----
+// callback-style api
+client.search({ params }, { options }, (err, result) => {
+ console.log(err || result)
+})
+
+// promise-style api
+client.search({ params }, { options })
+  .then(console.log)
+  .catch(console.log)
+  
+// async-style (sugar syntax on top of promises)
+const response = await client.search({ params }, { options })
+console.log(response)
+----
+
+If you are already using the promise-style API, this won't be a breaking change for you.
+
+[discrete]
+===== Remove the current abort API and use the new AbortController standard
+
+*Breaking: Yes* | *Migration effort: Small*
+
+The old abort API makes sense for callbacks but it's annoying to use with promises
+
+[source,js]
+----
+// callback-style api
+const request = client.search({ params }, { options }, (err, result) => {
+ console.log(err) // RequestAbortedError
+})
+
+request.abort()
+
+// promise-style api
+const promise = client.search({ params }, { options })
+
+promise
+  .then(console.log)
+  .catch(console.log) // RequestAbortedError
+
+promise.abort()
+----
+
+Node v12 has added the standard https://nodejs.org/api/globals.html#globals_class_abortcontroller[`AbortController`] API which is designed to work well with both callbacks and promises.
+[source,js]
+----
+const ac = new AbortController()
+client.search({ params }, { signal: ac.signal })
+  .then(console.log)
+  .catch(console.log) // RequestAbortedError
+
+ac.abort()
+----
+
+[discrete]
+===== Remove the body key from the request
+
+*Breaking: Yes* | *Migration effort: Small*
+
+Thanks to the new types we are developing now we know exactly where a parameter should go.
+The client API leaks HTTP-related notions in many places, and removing them would definitely improve the DX.
+
+This could be a rather big breaking change, so a double solution could be used during the 8.x lifecycle. (accepting body keys without them being wrapped in the body as well as the current solution).
+
+[source,js]
+----
+// from
+const response = await client.search({
+  index: 'test',
+  body: {
+    query: {
+      match_all: {}
+    }
+  }
+})
+
+// to
+const response = await client.search({
+  index: 'test',
+  query: {
+    match_all: {}
+  }
+})
+----
+
+[discrete]
+===== Migrate to new separate transport
+
+*Breaking: Yes* | *Migration effort: Small to none*
+
+The separated transport has been rewritten in TypeScript and has already dropped the callback style API.
+Given that now is separated, most of the Elasticsearch specific concepts have been removed, and the client will likely need to extend parts of it for reintroducing them.
+If you weren't extending the internals of the client, this won't be a breaking change for you.
+
+[discrete]
+===== The returned value of API calls is the body and not the HTTP related keys
+
+*Breaking: Yes* | *Migration effort: Small*
+
+The client API leaks HTTP-related notions in many places, and removing them would definitely improve the DX.
+The client will expose a new request-specific option to still get the full response details.
+
+[source,js]
+----
+// from
+const response = await client.search({
+  index: 'test',
+  body: {
+    query: {
+      match_all: {}
+    }
+  }
+})
+console.log(response) // { body: SearchResponse, statusCode: number, headers: object, warnings: array }
+
+// to
+const response = await client.search({
+  index: 'test',
+  query: {
+    match_all: {}
+  }
+})
+console.log(response) // SearchResponse
+
+// with a bit of TypeScript and JavaScript magic...
+const response = await client.search({
+  index: 'test',
+  query: {
+    match_all: {}
+  }
+}, {
+  meta: true
+})
+console.log(response) // { body: SearchResponse, statusCode: number, headers: object, warnings: array }
+----
+
+[discrete]
+===== Use a weighted connection pool
+
+*Breaking: Yes* | *Migration effort: Small to none*
+
+Move from the current cluster connection pool to a weight-based implementation.
+This new implementation offers better performances and runs less code in the background, the old connection pool can still be used.
+If you weren't extending the internals of the client, this won't be a breaking change for you.
+
+[discrete]
+===== Migrate to the "undici" http client
+
+*Breaking: Yes* | *Migration effort: Small to none*
+
+By default, the HTTP client will no longer be the default Node.js HTTP client, but https://github.com/nodejs/undici[undici] instead.
+Undici is a brand new HTTP client written from scratch, it offers vastly improved performances and has better support for promises.
+Furthermore, it offers comprehensive and predictable error handling. The old HTTP client can still be used.
+If you weren't extending the internals of the client, this won't be a breaking change for you.
+
+[discrete]
+===== Drop support for old camelCased keys
+
+*Breaking: Yes* | *Migration effort: Medium*
+
+Currently, every path or query parameter could be expressed in both `snake_case` and `camelCase`. Internally the client will convert everything to `snake_case`. 
+This was done in an effort to reduce the friction of migrating from the legacy to the new client, but now it no longer makes sense.
+If you are already using `snake_case` keys, this won't be a breaking change for you.
+
+[discrete]
+===== Rename `ssl` option to `tls`
+
+*Breaking: Yes* | *Migration effort: Small*
+
+People usually refers to this as `tls`, furthermore, internally we use the tls API and Node.js refers to it as tls everywhere.
+[source,js]
+----
+// before
+const client = new Client({
+  node: 'https://localhost:9200',
+  ssl: {
+    rejectUnauthorized: false
+  }
+})
+
+// after
+const client = new Client({
+  node: 'https://localhost:9200',
+  tls: {
+    rejectUnauthorized: false
+  }
+})
+----
+
+[discrete]
+===== Remove prototype poisoning protection
+
+*Breaking: Yes* | *Migration effort: Small*
+
+Prototype poisoning protection is very useful, but it can cause performances issues with big payloads.
+In v8 it will be removed, and the documentation will show how to add it back with a custom serializer.
+
+[discrete]
+===== Remove client extensions API
+
+*Breaking: Yes* | *Migration effort: Large*
+
+Nowadays the client support the entire Elasticsearch API, and the `transport.request` method can be used if necessary. The client extensions API have no reason to exist.
+[source,js]
+----
+client.extend('utility.index', ({ makeRequest }) => {
+  return function _index (params, options) {
+    // your code
+  }
+})
+
+client.utility.index(...)
+----
+
+If you weren't using client extensions, this won't be a breaking change for you.
+
+[discrete]
+===== Move to TypeScript
+
+*Breaking: No* | *Migration effort: None*
+
+The new separated transport is already written in TypeScript, and it makes sense that the client v8 will be fully written in TypeScript as well.
+
+[discrete]
+===== Move from emitter-like interface to a diagnostic method
+
+*Breaking: Yes* | *Migration effort: Small*
+
+Currently, the client offers a subset of methods of the `EventEmitter` class, v8 will ship with a `diagnostic` property which will be a proper event emitter.
+[source,js]
+----
+// from
+client.on('request', console.log)
+
+// to
+client.diagnostic.on('request', console.log)
+----
+
+[discrete]
+===== Remove username & password properties from Cloud configuration
+
+*Breaking: Yes* | *Migration effort: Small*
+
+The Cloud configuration does not support ApiKey and Bearer auth, while the `auth` options does.
+There is no need to keep the legacy basic auth support in the cloud configuration.
+[source,js]
+----
+// before
+const client = new Client({
+  cloud: {
+    id: '<cloud-id>',
+    username: 'elastic',
+    password: 'changeme'
+  }
+})
+
+// after
+const client = new Client({
+  cloud: {
+    id: '<cloud-id>'
+  },
+  auth: {
+    username: 'elastic',
+    password: 'changeme'
+  }
+})
+----
+
+If you are already passing the basic auth options in the `auth` configuration, this won't be a breaking change for you.
+
+[discrete]
+===== Calling `client.close` will reject new requests
+
+Once you call `client.close` every new request after that will be rejected with a `NoLivingConnectionsError`. In-flight requests will be executed normally unless an in-flight request requires a retry, in which case it will be rejected.