Merge branch '7.x' of https://github.com/elastic/elasticsearch-js into 7.x

Author: delvedor

docs/connecting.asciidoc

@@ -8,6 +8,7 @@ This page contains the information you need to connect and use the Client with
 
 * <<auth-reference, Authentication options>>
 * <<client-usage, Using the client>>
+* <<client-faas-env, Using the Client in a Function-as-a-Service Environment>>
 * <<client-connect-proxy, Connecting through a proxy>>
 * <<client-error-handling, Handling errors>>
 * <<product-check, Automatic product check>>
@@ -419,6 +420,76 @@ _Default:_ `null`
 _Default:_ `null`
 |===
 
+[discrete]
+[[client-faas-env]]
+=== Using the Client in a Function-as-a-Service Environment
+
+This section illustrates the best practices for leveraging the {es} client in a Function-as-a-Service (FaaS) environment.
+The most influential optimization is to initialize the client outside of the function, the global scope.
+This practice does not only improve performance but also enables background functionality as – for example – https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how[sniffing].
+The following examples provide a skeleton for the best practices.
+
+[discrete]
+==== GCP Cloud Functions
+
+[source,js]
+----
+'use strict'
+
+const { Client } = require('@elastic/elasticsearch')
+
+const client = new Client({
+  // client initialisation
+})
+
+exports.testFunction = async function (req, res) {
+  // use the client
+}
+----
+
+[discrete]
+==== AWS Lambda
+
+[source,js]
+----
+'use strict'
+
+const { Client } = require('@elastic/elasticsearch')
+
+const client = new Client({
+  // client initialisation
+})
+
+exports.handler = async function (event, context) {
+  // use the client
+}
+----
+
+[discrete]
+==== Azure Functions
+
+[source,js]
+----
+'use strict'
+
+const { Client } = require('@elastic/elasticsearch')
+
+const client = new Client({
+  // client initialisation
+})
+
+module.exports = async function (context, req) {
+  // use the client
+}
+----
+
+Resources used to assess these recommendations:
+
+- https://cloud.google.com/functions/docs/bestpractices/tips#use_global_variables_to_reuse_objects_in_future_invocations[GCP Cloud Functions: Tips & Tricks]
+- https://docs.aws.amazon.com/lambda/latest/dg/best-practices.html[Best practices for working with AWS Lambda functions]
+- https://docs.microsoft.com/en-us/azure/azure-functions/functions-reference-python?tabs=azurecli-linux%2Capplication-level#global-variables[Azure Functions Python developer guide]
+- https://docs.aws.amazon.com/lambda/latest/operatorguide/global-scope.html[AWS Lambda: Comparing the effect of global scope]
+
 
 [discrete]
 [[client-connect-proxy]]

lib/Transport.js

@@ -36,13 +36,13 @@ const {
 
 const noop = () => {}
 
-const productCheckEmitter = new EventEmitter()
 const clientVersion = require('../package.json').version
 const userAgent = `elasticsearch-js/${clientVersion} (${os.platform()} ${os.release()}-${os.arch()}; Node.js ${process.version})`
 const MAX_BUFFER_LENGTH = buffer.constants.MAX_LENGTH
 const MAX_STRING_LENGTH = buffer.constants.MAX_STRING_LENGTH
 const kProductCheck = Symbol('product check')
 const kApiVersioning = Symbol('api versioning')
+const kEventEmitter = Symbol('event emitter')
 
 class Transport {
   constructor (opts) {
@@ -71,6 +71,7 @@ class Transport {
     this.opaqueIdPrefix = opts.opaqueIdPrefix
     this[kProductCheck] = 0 // 0 = to be checked, 1 = checking, 2 = checked-ok, 3 checked-notok, 4 checked-nodefault
     this[kApiVersioning] = process.env.ELASTIC_CLIENT_APIVERSIONING === 'true'
+    this[kEventEmitter] = new EventEmitter()
 
     this.nodeFilter = opts.nodeFilter || defaultNodeFilter
     if (typeof opts.nodeSelector === 'function') {
@@ -182,6 +183,7 @@ class Transport {
 
     const makeRequest = () => {
       if (meta.aborted === true) {
+        this.emit('request', new RequestAbortedError(), result)
         return process.nextTick(callback, new RequestAbortedError(), result)
       }
       meta.connection = this.getConnection({ requestId: meta.request.id })
@@ -459,7 +461,7 @@ class Transport {
         prepareRequest()
       } else {
         // wait for product check to finish
-        productCheckEmitter.once('product-check', (error, status) => {
+        this[kEventEmitter].once('product-check', (error, status) => {
           if (status === false) {
             const err = error || new ProductNotSupportedError(result)
             if (this[kProductCheck] === 4) {
@@ -563,48 +565,48 @@ class Transport {
             'The client is unable to verify that the server is Elasticsearch due to security privileges on the server side. Some functionality may not be compatible if the server is running an unsupported product.',
             'ProductNotSupportedSecurityError'
           )
-          productCheckEmitter.emit('product-check', null, true)
+          this[kEventEmitter].emit('product-check', null, true)
         } else {
           this[kProductCheck] = 0
-          productCheckEmitter.emit('product-check', err, false)
+          this[kEventEmitter].emit('product-check', err, false)
         }
       } else {
         debug('Checking elasticsearch version', result.body, result.headers)
         if (result.body.version == null || typeof result.body.version.number !== 'string') {
           debug('Can\'t access Elasticsearch version')
-          return productCheckEmitter.emit('product-check', null, false)
+          return this[kEventEmitter].emit('product-check', null, false)
         }
         const tagline = result.body.tagline
         const version = result.body.version.number.split('.')
         const major = Number(version[0])
         const minor = Number(version[1])
         if (major < 6) {
-          return productCheckEmitter.emit('product-check', null, false)
+          return this[kEventEmitter].emit('product-check', null, false)
         } else if (major >= 6 && major < 7) {
           if (tagline !== 'You Know, for Search') {
             debug('Bad tagline')
-            return productCheckEmitter.emit('product-check', null, false)
+            return this[kEventEmitter].emit('product-check', null, false)
           }
         } else if (major === 7 && minor < 14) {
           if (tagline !== 'You Know, for Search') {
             debug('Bad tagline')
-            return productCheckEmitter.emit('product-check', null, false)
+            return this[kEventEmitter].emit('product-check', null, false)
           }
 
           if (result.body.version.build_flavor !== 'default') {
             debug('Bad build_flavor')
             this[kProductCheck] = 4
-            return productCheckEmitter.emit('product-check', null, false)
+            return this[kEventEmitter].emit('product-check', null, false)
           }
         } else {
           if (result.headers['x-elastic-product'] !== 'Elasticsearch') {
             debug('x-elastic-product not recognized')
-            return productCheckEmitter.emit('product-check', null, false)
+            return this[kEventEmitter].emit('product-check', null, false)
           }
         }
         debug('Valid Elasticsearch distribution')
         this[kProductCheck] = 2
-        productCheckEmitter.emit('product-check', null, true)
+        this[kEventEmitter].emit('product-check', null, true)
       }
     })
   }

package.json

@@ -12,7 +12,7 @@
   },
   "homepage": "http://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/index.html",
   "version": "7.16.0",
-  "versionCanary": "7.16.0-canary.1",
+  "versionCanary": "7.16.0-canary.2",
   "keywords": [
     "elasticsearch",
     "elastic",

test/acceptance/product-check.test.js

@@ -20,7 +20,7 @@
 'use strict'
 
 const { test } = require('tap')
-const { Client } = require('../../')
+const { Client, errors } = require('../../')
 const {
   connection: {
     MockConnectionTimeout,
@@ -1285,3 +1285,64 @@ test('Observability events should have all the expected properties', t => {
     t.equal(err.message, 'The client noticed that the server is not Elasticsearch and we do not support this unknown product.')
   })
 })
+
+test('Abort a request while running the product check', t => {
+  t.plan(4)
+  const MockConnection = buildMockConnection({
+    onRequest (params) {
+      return {
+        statusCode: 200,
+        headers: {
+          'x-elastic-product': 'Elasticsearch'
+        },
+        body: {
+          name: '1ef419078577',
+          cluster_name: 'docker-cluster',
+          cluster_uuid: 'cQ5pAMvRRTyEzObH4L5mTA',
+          version: {
+            number: '8.0.0-SNAPSHOT',
+            build_flavor: 'default',
+            build_type: 'docker',
+            build_hash: '5fb4c050958a6b0b6a70a6fb3e616d0e390eaac3',
+            build_date: '2021-07-10T01:45:02.136546168Z',
+            build_snapshot: true,
+            lucene_version: '8.9.0',
+            minimum_wire_compatibility_version: '7.15.0',
+            minimum_index_compatibility_version: '7.0.0'
+          },
+          tagline: 'You Know, for Search'
+        }
+      }
+    }
+  })
+
+  const client = new Client({
+    node: 'http://localhost:9200',
+    Connection: MockConnection
+  })
+
+  client.on('request', (err, event) => {
+    if (event.meta.request.params.path.includes('search')) {
+      t.ok(err instanceof errors.RequestAbortedError)
+    }
+  })
+
+  // the response event won't be executed for the search
+  client.on('response', (err, event) => {
+    t.error(err)
+    t.equal(event.meta.request.params.path, '/')
+  })
+
+  const req = client.search({
+    index: 'foo',
+    body: {
+      query: {
+        match_all: {}
+      }
+    }
+  }, (err, result) => {
+    t.ok(err instanceof errors.RequestAbortedError)
+  })
+
+  setImmediate(() => req.abort())
+})