Introduce API Metrics/Telemetry

packages/bolt-connection/src/bolt/bolt-protocol-v1.js

@@ -27,6 +27,7 @@ import { Chunker } from '../channel'
 import { structure, v1 } from '../packstream'
 import RequestMessage, { SIGNATURES } from './request-message'
 import {
+  CompletedObserver,
   LoginObserver,
   LogoffObserver,
   ResetObserver,
@@ -454,6 +455,24 @@ export default class BoltProtocol {
     return observer
   }
 
+  /**
+   * Send a TELEMETRY through the underlying connection.
+   *
+   * @param {object} param0 Message params
+   * @param {number} param0.api The API called
+   * @param {object} param1 Configuration and callbacks callbacks
+   * @param {function()} param1.onCompleted Called when completed
+   * @param {function()} param1.onError Called when error
+   * @return {StreamObserver} the stream observer that monitors the corresponding server response.
+   */
+  telemetry ({ api }, { onError, onCompleted } = {}) {
+    const observer = new CompletedObserver()
+    if (onCompleted) {
+      onCompleted()
+    }
+    return observer
+  }
+
   _createPacker (chunker) {
     return new v1.Packer(chunker)
   }

packages/bolt-connection/src/bolt/bolt-protocol-v5x4.js

@@ -0,0 +1,61 @@
+/**
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import BoltProtocolV5x3 from './bolt-protocol-v5x3'
+
+import transformersFactories from './bolt-protocol-v5x4.transformer'
+import RequestMessage from './request-message'
+import { TelemetryObserver } from './stream-observers'
+import Transformer from './transformer'
+
+import { internal } from 'neo4j-driver-core'
+
+const {
+  constants: { BOLT_PROTOCOL_V5_4 }
+} = internal
+
+export default class BoltProtocol extends BoltProtocolV5x3 {
+  get version () {
+    return BOLT_PROTOCOL_V5_4
+  }
+
+  get transformer () {
+    if (this._transformer === undefined) {
+      this._transformer = new Transformer(Object.values(transformersFactories).map(create => create(this._config, this._log)))
+    }
+    return this._transformer
+  }
+
+  /**
+   * Send a TELEMETRY through the underlying connection.
+   *
+   * @param {object} param0 Message params
+   * @param {number} param0.api The API called
+   * @param {object} param1 Configuration and callbacks callbacks
+   * @param {function()} param1.onCompleted Called when completed
+   * @param {function()} param1.onError Called when error
+   * @return {StreamObserver} the stream observer that monitors the corresponding server response.
+   */
+  telemetry ({ api }, { onError, onCompleted } = {}) {
+    const observer = new TelemetryObserver({ onCompleted, onError })
+
+    this.write(RequestMessage.telemetry({ api }), observer, false)
+
+    return observer
+  }
+}

packages/bolt-connection/src/bolt/bolt-protocol-v5x4.transformer.js

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import v5x3 from './bolt-protocol-v5x3.transformer'
+
+export default {
+  ...v5x3
+}

packages/bolt-connection/src/bolt/create.js

@@ -30,6 +30,7 @@ import BoltProtocolV5x0 from './bolt-protocol-v5x0'
 import BoltProtocolV5x1 from './bolt-protocol-v5x1'
 import BoltProtocolV5x2 from './bolt-protocol-v5x2'
 import BoltProtocolV5x3 from './bolt-protocol-v5x3'
+import BoltProtocolV5x4 from './bolt-protocol-v5x4'
 // eslint-disable-next-line no-unused-vars
 import { Chunker, Dechunker } from '../channel'
 import ResponseHandler from './response-handler'
@@ -222,6 +223,14 @@ function createProtocol (
         log,
         onProtocolError,
         serversideRouting)
+    case 5.4:
+      return new BoltProtocolV5x4(server,
+        chunker,
+        packingConfig,
+        createResponseHandler,
+        log,
+        onProtocolError,
+        serversideRouting)
     default:
       throw newError('Unknown Bolt protocol version: ' + version)
   }

packages/bolt-connection/src/bolt/handshake.js

@@ -78,7 +78,7 @@ function parseNegotiatedResponse (buffer, log) {
  */
 function newHandshakeBuffer () {
   return createHandshakeMessage([
-    [version(5, 3), version(5, 0)],
+    [version(5, 4), version(5, 0)],
     [version(4, 4), version(4, 2)],
     version(4, 1),
     version(3, 0)

packages/bolt-connection/src/bolt/request-message.js

@@ -38,6 +38,9 @@ const GOODBYE = 0x02 // 0000 0010 // GOODBYE
 const BEGIN = 0x11 // 0001 0001 // BEGIN <metadata>
 const COMMIT = 0x12 // 0001 0010 // COMMIT
 const ROLLBACK = 0x13 // 0001 0011 // ROLLBACK
+
+const TELEMETRY = 0x54 // 0101 0100 // TELEMETRY <api>
+
 const ROUTE = 0x66 // 0110 0110 // ROUTE
 
 const LOGON = 0x6A // LOGON
@@ -61,6 +64,7 @@ const SIGNATURES = Object.freeze({
   BEGIN,
   COMMIT,
   ROLLBACK,
+  TELEMETRY,
   ROUTE,
   LOGON,
   LOGOFF,
@@ -367,6 +371,15 @@ export default class RequestMessage {
     )
   }
 
+  static telemetry ({ api }) {
+    const parsedApi = int(api)
+    return new RequestMessage(
+      TELEMETRY,
+      [parsedApi],
+      () => `TELEMETRY ${parsedApi.toString()}`
+    )
+  }
+
   /**
    * Generate the ROUTE message, this message is used to fetch the routing table from the server
    *

packages/bolt-connection/src/bolt/stream-observers.js

@@ -526,6 +526,38 @@ class ResetObserver extends StreamObserver {
   }
 }
 
+class TelemetryObserver extends ResultStreamObserver {
+  /**
+   *
+   * @param {Object} param -
+   * @param {function(err: Error)} param.onError
+   * @param {function(metadata)} param.onCompleted
+   */
+  constructor ({ onError, onCompleted } = {}) {
+    super()
+    this._onError = onError
+    this._onCompleted = onCompleted
+  }
+
+  onNext (record) {
+    this.onError(
+      newError('Received RECORD when logging off ' + json.stringify(record))
+    )
+  }
+
+  onError (error) {
+    if (this._onError) {
+      this._onError(error)
+    }
+  }
+
+  onCompleted (metadata) {
+    if (this._onCompleted) {
+      this._onCompleted(metadata)
+    }
+  }
+}
+
 class FailedObserver extends ResultStreamObserver {
   constructor ({ error, onError }) {
     super({ beforeError: onError })
@@ -708,5 +740,6 @@ export {
   FailedObserver,
   CompletedObserver,
   RouteObserver,
-  ProcedureRouteObserver
+  ProcedureRouteObserver,
+  TelemetryObserver
 }

packages/bolt-connection/src/connection/connection-channel.js

@@ -87,7 +87,8 @@ export function createChannelConnection (
         serversideRouting,
         chunker,
         config.notificationFilter,
-        createProtocol
+        createProtocol,
+        config.telemetryDisabled
       )
 
       // forward all pending bytes to the dechunker
@@ -121,7 +122,8 @@ export default class ChannelConnection extends Connection {
     serversideRouting = null,
     chunker, // to be removed,
     notificationFilter,
-    protocolSupplier
+    protocolSupplier,
+    telemetryDisabled
   ) {
     super(errorHandler)
     this._authToken = null
@@ -137,6 +139,8 @@ export default class ChannelConnection extends Connection {
     this._log = createConnectionLogger(this, log)
     this._serversideRouting = serversideRouting
     this._notificationFilter = notificationFilter
+    this._telemetryDisabledDriverConfig = telemetryDisabled === true
+    this._telemetryDisabledConnection = true
 
     // connection from the database, returned in response for HELLO message and might not be available
     this._dbConnectionId = null
@@ -157,13 +161,31 @@ export default class ChannelConnection extends Connection {
   }
 
   beginTransaction (config) {
+    this._sendTelemetryIfEnabled(config)
     return this._protocol.beginTransaction(config)
   }
 
   run (query, parameters, config) {
+    this._sendTelemetryIfEnabled(config)
     return this._protocol.run(query, parameters, config)
   }
 
+  _sendTelemetryIfEnabled (config) {
+    if (this._telemetryDisabledConnection ||
+        this._telemetryDisabledDriverConfig ||
+        config == null ||
+        config.apiTelemetryConfig == null) {
+      return
+    }
+
+    this._protocol.telemetry({
+      api: config.apiTelemetryConfig.api
+    }, {
+      onCompleted: config.apiTelemetryConfig.onTelemetrySuccess,
+      onError: config.beforeError
+    })
+  }
+
   commitTransaction (config) {
     return this._protocol.commitTransaction(config)
   }
@@ -290,6 +312,11 @@ export default class ChannelConnection extends Connection {
                   )
                 }
               }
+
+              const telemetryEnabledHint = metadata.hints['telemetry.enabled']
+              if (telemetryEnabledHint === true) {
+                this._telemetryDisabledConnection = false
+              }
             }
           }
           resolve(self)

packages/bolt-connection/test/bolt/__snapshots__/bolt-protocol-v5x4.test.js.snap

@@ -0,0 +1,61 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`#unit BoltProtocolV5x4 .packable() should pack not pack graph types (Node) 1`] = `"It is not allowed to pass nodes in query parameters, given: (c:a {a:"b"})"`;
+
+exports[`#unit BoltProtocolV5x4 .packable() should pack not pack graph types (Path) 1`] = `"It is not allowed to pass paths in query parameters, given: [object Object]"`;
+
+exports[`#unit BoltProtocolV5x4 .packable() should pack not pack graph types (Relationship) 1`] = `"It is not allowed to pass relationships in query parameters, given: (e)-[:a {b:"c"}]->(f)"`;
+
+exports[`#unit BoltProtocolV5x4 .packable() should pack not pack graph types (UnboundRelationship) 1`] = `"It is not allowed to pass unbound relationships in query parameters, given: -[:a {b:"c"}]->"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (Date with less fields) 1`] = `"Wrong struct size for Date, expected 1 but was 0"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (Date with more fields) 1`] = `"Wrong struct size for Date, expected 1 but was 2"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (DateTimeWithZoneId with less fields) 1`] = `"Wrong struct size for DateTimeWithZoneId, expected 3 but was 2"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (DateTimeWithZoneId with more fields) 1`] = `"Wrong struct size for DateTimeWithZoneId, expected 3 but was 4"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (DateTimeWithZoneOffset with less fields) 1`] = `"Wrong struct size for DateTimeWithZoneOffset, expected 3 but was 2"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (DateTimeWithZoneOffset with more fields) 1`] = `"Wrong struct size for DateTimeWithZoneOffset, expected 3 but was 4"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (Duration with less fields) 1`] = `"Wrong struct size for Duration, expected 4 but was 3"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (Duration with more fields) 1`] = `"Wrong struct size for Duration, expected 4 but was 5"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (LocalDateTime with less fields) 1`] = `"Wrong struct size for LocalDateTime, expected 2 but was 1"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (LocalDateTime with more fields) 1`] = `"Wrong struct size for LocalDateTime, expected 2 but was 3"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (LocalTime with less fields) 1`] = `"Wrong struct size for LocalTime, expected 1 but was 0"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (LocalTime with more fields) 1`] = `"Wrong struct size for LocalTime, expected 1 but was 2"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (Node with less fields) 1`] = `"Wrong struct size for Node, expected 4 but was 3"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (Node with more fields) 1`] = `"Wrong struct size for Node, expected 4 but was 5"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (Path with less fields) 1`] = `"Wrong struct size for Path, expected 3 but was 2"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (Path with more fields) 1`] = `"Wrong struct size for Path, expected 3 but was 4"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (Point with less fields) 1`] = `"Wrong struct size for Point2D, expected 3 but was 2"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (Point with more fields) 1`] = `"Wrong struct size for Point2D, expected 3 but was 4"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (Point3D with less fields) 1`] = `"Wrong struct size for Point3D, expected 4 but was 3"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (Point3D with more fields) 1`] = `"Wrong struct size for Point3D, expected 4 but was 5"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (Relationship with less fields) 1`] = `"Wrong struct size for Relationship, expected 8 but was 5"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (Relationship with more fields) 1`] = `"Wrong struct size for Relationship, expected 8 but was 9"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (Time with less fields) 1`] = `"Wrong struct size for Time, expected 2 but was 1"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (Time with more fileds) 1`] = `"Wrong struct size for Time, expected 2 but was 3"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (UnboundRelationship with less fields) 1`] = `"Wrong struct size for UnboundRelationship, expected 4 but was 3"`;
+
+exports[`#unit BoltProtocolV5x4 .unpack() should not unpack with wrong size (UnboundRelationship with more fields) 1`] = `"Wrong struct size for UnboundRelationship, expected 4 but was 5"`;

packages/bolt-connection/test/bolt/behaviour/index.js

@@ -18,3 +18,4 @@
  */
 
 export * as notificationFilterBehaviour from './notification-filter'
+export * as telemetryBehaviour from './telemetry'