Update events

docs/observability.asciidoc

@@ -37,6 +37,15 @@ client.on('response', (err, result) => {
 The client emits the following events:
 [cols=2*]
 |===
+|`prepare-request`
+a|Emitted once the user invokes any API.
+[source,js]
+----
+client.on('prepare-request', (err, result) => {
+  console.log(err, result)
+})
+----
+
 |`request`
 a|Emitted before sending the actual request to Elasticsearch _(emitted multiple times in case of retries)_.
 [source,js]
@@ -86,8 +95,8 @@ meta: {
   context: any;
   name: string;
   request: {
-    params: TransportRequestParams;
-    options: TransportRequestOptions;
+    params: TransportRequestParams; // serialized by the client
+    options: TransportRequestOptions; // serialized by the client
     id: any;
   };
   connection: Connection;
@@ -100,6 +109,29 @@ meta: {
 };
 ----
 
+`result` value in `prepare-request` will be:
+[source,ts]
+----
+params: TransportRequestParams; // as provided by the user
+options: TransportRequestOptions; // as provided by the user
+meta: {
+  context: any;
+  name: string;
+  request: {
+    params: null;
+    options: null;
+    id: any;
+  };
+  connection: null;
+  attempts: number;
+  aborted: boolean;
+  sniff?: {
+    hosts: any[];
+    reason: string;
+  };
+};
+----
+
 While the `result` value in `resurrect` will be:
 [source,ts]
 ----

index.d.ts

@@ -9,6 +9,7 @@ import { ConnectionOptions as TlsConnectionOptions } from 'tls';
 import Transport, {
   ApiResponse,
   RequestEvent,
+  PrepareRequestEvent,
   TransportRequestParams,
   TransportRequestOptions,
   nodeFilterFn,
@@ -621,6 +622,7 @@ declare class Client extends EventEmitter {
 
 declare const events: {
   RESPONSE: string;
+  PREPARE_REQUEST: string;
   REQUEST: string;
   SNIFF: string;
   RESURRECT: string;
@@ -636,6 +638,7 @@ export {
   errors,
   ApiResponse,
   RequestEvent,
+  PrepareRequestEvent,
   ResurrectEvent,
   RequestParams,
   ClientOptions,

index.js

@@ -244,6 +244,7 @@ function getAuth (node) {
 
 const events = {
   RESPONSE: 'response',
+  PREPARE_REQUEST: 'prepare-request',
   REQUEST: 'request',
   SNIFF: 'sniff',
   RESURRECT: 'resurrect'

lib/Transport.d.ts

@@ -63,6 +63,27 @@ export interface RequestEvent<T = any, C = any> {
   };
 }
 
+export interface PrepareRequestEvent<C = any> {
+  params: TransportRequestParams;
+  options: TransportRequestOptions;
+  meta: {
+    context: C;
+    name: string;
+    request: {
+      params: null;
+      options: null;
+      id: any;
+    };
+    connection: null;
+    attempts: number;
+    aborted: boolean;
+    sniff?: {
+      hosts: any[];
+      reason: string;
+    };
+  };
+}
+
 // ApiResponse and RequestEvent are the same thing
 // we are doing this for have more clear names
 export interface ApiResponse<T = any, C = any> extends RequestEvent<T, C> {}

lib/Transport.js

@@ -104,13 +104,8 @@ class Transport {
     const compression = options.compression || this.compression
     var request = { abort: noop }
 
-    const makeRequest = () => {
-      if (meta.aborted === true) return
-      meta.connection = this.getConnection({ requestId: meta.request.id })
-      if (meta.connection === null) {
-        return callback(new NoLivingConnectionsError('There are not living connections'), result)
-      }
-
+    const prepareRequest = () => {
+      this.emit('prepare-request', null, { params, options, meta })
       // TODO: make this assignment FAST
       const headers = Object.assign({}, this.headers, options.headers)
 
@@ -120,6 +115,7 @@ class Transport {
           try {
             params.body = this.serializer.serialize(params.body)
           } catch (err) {
+            this.emit('request', err, result)
             return callback(err, result)
           }
         }
@@ -143,6 +139,7 @@ class Transport {
           try {
             params.body = this.serializer.ndserialize(params.bulkBody)
           } catch (err) {
+            this.emit('request', err, result)
             return callback(err, result)
           }
         } else {
@@ -170,11 +167,27 @@ class Transport {
 
       meta.request.params = params
       meta.request.options = options
-      this.emit('request', null, result)
 
       // handles request timeout
       params.timeout = toMs(options.requestTimeout || this.requestTimeout)
       if (options.asStream === true) params.asStream = true
+      return makeRequest()
+    }
+
+    const makeRequest = () => {
+      if (meta.aborted === true) {
+        this.emit('request', null, result)
+        return
+      }
+
+      meta.connection = this.getConnection({ requestId: meta.request.id })
+      if (meta.connection === null) {
+        const err = new NoLivingConnectionsError('There are not living connections')
+        this.emit('request', err, result)
+        return callback(err, result)
+      }
+
+      this.emit('request', null, result)
       // perform the actual http request
       return meta.connection.request(params, onResponse)
     }
@@ -298,7 +311,7 @@ class Transport {
       })
     }
 
-    request = makeRequest()
+    request = prepareRequest()
 
     return {
       abort: () => {

test/behavior/observability.test.js

@@ -24,7 +24,7 @@ test('Request id', t => {
   })
 
   t.test('Custom generateRequestId', t => {
-    t.plan(7)
+    t.plan(9)
 
     const options = { context: { winter: 'is coming' } }
 
@@ -38,6 +38,11 @@ test('Request id', t => {
       }
     })
 
+    client.on('prepare-request', (err, { meta }) => {
+      t.error(err)
+      t.strictEqual(meta.request.id, 'custom-id')
+    })
+
     client.on('request', (err, { meta }) => {
       t.error(err)
       t.strictEqual(meta.request.id, 'custom-id')
@@ -52,13 +57,18 @@ test('Request id', t => {
   })
 
   t.test('Custom request id in method options', t => {
-    t.plan(5)
+    t.plan(7)
 
     const client = new Client({
       node: 'http://localhost:9200',
       Connection: MockConnection
     })
 
+    client.on('prepare-request', (err, { meta }) => {
+      t.error(err)
+      t.strictEqual(meta.request.id, 'custom-id')
+    })
+
     client.on('request', (err, { meta }) => {
       t.error(err)
       t.strictEqual(meta.request.id, 'custom-id')
@@ -89,7 +99,7 @@ test('Request id', t => {
     })
 
     t.test('sniffOnConnectionFault - should use the request id', t => {
-      t.plan(5)
+      t.plan(7)
 
       const client = new Client({
         nodes: ['http://localhost:9200', 'http://localhost:9201'],
@@ -98,6 +108,10 @@ test('Request id', t => {
         maxRetries: 0
       })
 
+      client.on('prepare-request', (e, { meta }) => {
+        t.strictEqual(meta.request.id, 'custom')
+      })
+
       client.on('request', (e, { meta }) => {
         t.strictEqual(meta.request.id, 'custom')
       })
@@ -151,13 +165,18 @@ test('Request id', t => {
 
 test('Request context', t => {
   t.test('no value', t => {
-    t.plan(5)
+    t.plan(7)
 
     const client = new Client({
       node: 'http://localhost:9200',
       Connection: MockConnection
     })
 
+    client.on('prepare-request', (err, { meta }) => {
+      t.error(err)
+      t.strictEqual(meta.context, null)
+    })
+
     client.on('request', (err, { meta }) => {
       t.error(err)
       t.strictEqual(meta.context, null)
@@ -172,13 +191,18 @@ test('Request context', t => {
   })
 
   t.test('custom value', t => {
-    t.plan(5)
+    t.plan(7)
 
     const client = new Client({
       node: 'http://localhost:9200',
       Connection: MockConnection
     })
 
+    client.on('prepare-request', (err, { meta }) => {
+      t.error(err)
+      t.deepEqual(meta.context, { winter: 'is coming' })
+    })
+
     client.on('request', (err, { meta }) => {
       t.error(err)
       t.deepEqual(meta.context, { winter: 'is coming' })
@@ -206,13 +230,18 @@ test('Client name', t => {
   })
 
   t.test('Is present in the event metadata', t => {
-    t.plan(6)
+    t.plan(8)
     const client = new Client({
       node: 'http://localhost:9200',
       Connection: MockConnection,
       name: 'cluster'
     })
 
+    client.on('prepare-request', (err, { meta }) => {
+      t.error(err)
+      t.strictEqual(meta.name, 'cluster')
+    })
+
     client.on('request', (err, { meta }) => {
       t.error(err)
       t.strictEqual(meta.name, 'cluster')
@@ -246,7 +275,7 @@ test('Client name', t => {
     })
 
     t.test('sniffOnConnectionFault', t => {
-      t.plan(5)
+      t.plan(7)
 
       const client = new Client({
         nodes: ['http://localhost:9200', 'http://localhost:9201'],
@@ -255,6 +284,10 @@ test('Client name', t => {
         maxRetries: 0
       })
 
+      client.on('prepare-request', (e, { meta }) => {
+        t.strictEqual(meta.name, 'elasticsearch-js')
+      })
+
       client.on('request', (e, { meta }) => {
         t.strictEqual(meta.name, 'elasticsearch-js')
       })