GQL errors and update to bolt protocol (#1225)

Implements GQL compliant properties on the Neo4jError object as a preview, which handles both error messages from the database and driver-side errors. Also polyfills these properties if an error is created without them. Old error messages and codes will still be available even for new GQL compliant errors to accommodate existing error handling.

Author: MaxAake

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

@@ -45,6 +45,12 @@ const {
   txConfig: { TxConfig }
 } = internal
 
+const DEFAULT_DIAGNOSTIC_RECORD = Object.freeze({
+  OPERATION: '',
+  OPERATION_CODE: '0',
+  CURRENT_SCHEMA: '/'
+})
+
 export default class BoltProtocol {
   /**
    * @callback CreateResponseHandler Creates the response handler
@@ -164,6 +170,13 @@ export default class BoltProtocol {
     return metadata
   }
 
+  enrichErrorMetadata (metadata) {
+    return {
+      ...metadata,
+      diagnostic_record: metadata.diagnostic_record !== null ? { ...DEFAULT_DIAGNOSTIC_RECORD, ...metadata.diagnostic_record } : null
+    }
+  }
+
   /**
    * Perform initialization and authentication of the underlying connection.
    * @param {Object} param

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

@@ -0,0 +1,59 @@
+/**
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [https://neo4j.com]
+ *
+ * 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 BoltProtocolV5x6 from './bolt-protocol-v5x6'
+
+import transformersFactories from './bolt-protocol-v5x5.transformer'
+import Transformer from './transformer'
+
+import { internal } from 'neo4j-driver-core'
+
+const {
+  constants: { BOLT_PROTOCOL_V5_7 }
+} = internal
+
+const DEFAULT_DIAGNOSTIC_RECORD = Object.freeze({
+  OPERATION: '',
+  OPERATION_CODE: '0',
+  CURRENT_SCHEMA: '/'
+})
+
+export default class BoltProtocol extends BoltProtocolV5x6 {
+  get version () {
+    return BOLT_PROTOCOL_V5_7
+  }
+
+  get transformer () {
+    if (this._transformer === undefined) {
+      this._transformer = new Transformer(Object.values(transformersFactories).map(create => create(this._config, this._log)))
+    }
+    return this._transformer
+  }
+
+  /**
+   *
+   * @param {object} metadata
+   * @returns {object}
+   */
+  enrichErrorMetadata (metadata) {
+    return {
+      ...metadata,
+      cause: (metadata.cause !== null && metadata.cause !== undefined) ? this.enrichErrorMetadata(metadata.cause) : null,
+      code: metadata.neo4j_code,
+      diagnostic_record: metadata.diagnostic_record !== null ? { ...DEFAULT_DIAGNOSTIC_RECORD, ...metadata.diagnostic_record } : null
+    }
+  }
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [https://neo4j.com]
+ *
+ * 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 v5x6 from './bolt-protocol-v5x6.transformer'
+
+export default {
+  ...v5x6
+}

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

@@ -31,6 +31,7 @@ import BoltProtocolV5x3 from './bolt-protocol-v5x3'
 import BoltProtocolV5x4 from './bolt-protocol-v5x4'
 import BoltProtocolV5x5 from './bolt-protocol-v5x5'
 import BoltProtocolV5x6 from './bolt-protocol-v5x6'
+import BoltProtocolV5x7 from './bolt-protocol-v5x7'
 // eslint-disable-next-line no-unused-vars
 import { Chunker, Dechunker } from '../channel'
 import ResponseHandler from './response-handler'
@@ -64,6 +65,7 @@ export default function create ({
   const createResponseHandler = protocol => {
     const responseHandler = new ResponseHandler({
       transformMetadata: protocol.transformMetadata.bind(protocol),
+      enrichErrorMetadata: protocol.enrichErrorMetadata.bind(protocol),
       log,
       observer
     })
@@ -247,6 +249,14 @@ function createProtocol (
         log,
         onProtocolError,
         serversideRouting)
+    case 5.7:
+      return new BoltProtocolV5x7(server,
+        chunker,
+        packingConfig,
+        createResponseHandler,
+        log,
+        onProtocolError,
+        serversideRouting)
     default:
       throw newError('Unknown Bolt protocol version: ' + version)
   }

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

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

packages/bolt-connection/src/bolt/response-handler.js

@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { newError, json } from 'neo4j-driver-core'
+import { newError, newGQLError, json } from 'neo4j-driver-core'
 
 // Signature bytes for each response message type
 const SUCCESS = 0x70 // 0111 0000 // SUCCESS <metadata>
@@ -70,10 +70,11 @@ export default class ResponseHandler {
    * @param {Logger} log The logger
    * @param {ResponseHandler~Observer} observer Object which will be notified about errors
    */
-  constructor ({ transformMetadata, log, observer } = {}) {
+  constructor ({ transformMetadata, enrichErrorMetadata, log, observer } = {}) {
     this._pendingObservers = []
     this._log = log
     this._transformMetadata = transformMetadata || NO_OP_IDENTITY
+    this._enrichErrorMetadata = enrichErrorMetadata || NO_OP_IDENTITY
     this._observer = Object.assign(
       {
         onObserversCountChange: NO_OP,
@@ -115,11 +116,7 @@ export default class ResponseHandler {
           this._log.debug(`S: FAILURE ${json.stringify(msg)}`)
         }
         try {
-          const standardizedCode = _standardizeCode(payload.code)
-          const error = newError(payload.message, standardizedCode)
-          this._currentFailure = this._observer.onErrorApplyTransformation(
-            error
-          )
+          this._currentFailure = this._handleErrorPayload(this._enrichErrorMetadata(payload))
           this._currentObserver.onError(this._currentFailure)
         } finally {
           this._updateCurrentObserver()
@@ -196,6 +193,23 @@ export default class ResponseHandler {
   _resetFailure () {
     this._currentFailure = null
   }
+
+  _handleErrorPayload (payload) {
+    const standardizedCode = _standardizeCode(payload.code)
+    const cause = payload.cause != null ? this._handleErrorCause(payload.cause) : undefined
+    const error = newError(payload.message, standardizedCode, cause, payload.gql_status, payload.description, payload.diagnostic_record)
+    return this._observer.onErrorApplyTransformation(
+      error
+    )
+  }
+
+  _handleErrorCause (payload) {
+    const cause = payload.cause != null ? this._handleErrorCause(payload.cause) : undefined
+    const error = newGQLError(payload.message, cause, payload.gql_status, payload.description, payload.diagnostic_record)
+    return this._observer.onErrorApplyTransformation(
+      error
+    )
+  }
 }
 
 /**

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

@@ -441,7 +441,7 @@ export default class ChannelConnection extends Connection {
             reject(error)
           } else {
             const neo4jError = this._handleProtocolError(
-              'Received FAILURE as a response for RESET: ' + error
+              `Received FAILURE as a response for RESET: ${error}`
             )
             reject(neo4jError)
           }

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

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