4.0 verify connectivity (#351)

* Added stub tests RETURN 1 AS x

These have explicit HELLO messages.

* Implemented verify_connection for direct driver.

* Added script router_port_9001_one_read_port_9004_one_write_port_9006.script

* Added verify_connectivity to Neo4jDriver

This should be improved when better stub test is available for
clustering.

Author: martin-neotech

neo4j/__init__.py

@@ -242,6 +242,17 @@ def close(self):
         """
         self._pool.close()
 
+    def verify_connectivity(self, **config):
+        """ This verifies if the driver can connect to a remote server or a cluster
+        by establishing a network connection with the remote and possibly exchanging
+        a few data before closing the connection. It throws exception if fails to connect.
+
+        Use the exception to further understand the cause of the connectivity problem.
+
+        Note: Even if this method throws an exception, the driver still need to be closed via close() to free up all resources.
+        """
+        raise NotImplementedError
+
 
 class AsyncDriver:
 
@@ -307,6 +318,15 @@ def pipeline(self, **config):
                                          PipelineConfig.consume(config))
         return Pipeline(self._pool, pipeline_config)
 
+    def verify_connectivity(self, **config):
+        server_agent = None
+        with self.session(**config) as session:
+            result = session.run("RETURN 1 AS x")
+            value = result.single().value()
+            summary = result.summary()
+            server_agent = summary.server.agent
+        return server_agent
+
 
 class Neo4jDriver(Routing, Driver):
     """ A :class:`.Neo4jDriver` is created from a ``neo4j`` URI. The
@@ -343,6 +363,24 @@ def pipeline(self, **config):
                                          PipelineConfig.consume(config))
         return Pipeline(self._pool, pipeline_config)
 
+    def get_routing_table(self):
+        return self._pool.routing_table
+
+    def verify_connectivity(self, **config):
+        # TODO: Improve and update Stub Test Server to be able to test.
+        return self._verify_routing_connectivity()
+
+    def _verify_routing_connectivity(self):
+        table = self.get_routing_table()
+        routing_info = {}
+        for ix in list(table.routers):
+            routing_info[ix] = self._pool.fetch_routing_info(table.routers[0])
+
+        for key, val in routing_info.items():
+            if val is not None:
+                return routing_info
+        raise ServiceUnavailable("Could not connect to any routing servers.")
+
 
 class AsyncBoltDriver(Direct, AsyncDriver):
 

tests/stub/scripts/v3/disconnect_on_run.script

@@ -4,5 +4,5 @@
 !: AUTO RESET
 !: PORT 9001
 
-C: RUN "RETURN $x" {"x": 1} {}
+C: RUN "RETURN 1 AS x" {} {}
 S: <EXIT>

tests/stub/scripts/v3/return_1_port_9001.script

@@ -0,0 +1,12 @@
+!: BOLT 3
+!: AUTO GOODBYE
+!: AUTO RESET
+!: PORT 9001
+
+C: HELLO {"user_agent": "test", "scheme": "basic", "principal": "test", "credentials": "test"}
+S: SUCCESS {"server": "Neo4j/3.0.0", "connection_id": "123e4567-e89b-12d3-a456-426655440000"}
+C: RUN "RETURN 1 AS x" {} {}
+   PULL_ALL
+S: SUCCESS {"fields": ["x"]}
+   RECORD [1]
+   SUCCESS {"bookmark": "neo4j:bookmark-test-1", type": "r", "t_last": 5}

tests/stub/scripts/v4x0/disconnect_on_run.script

@@ -4,5 +4,5 @@
 !: AUTO RESET
 !: PORT 9001
 
-C: RUN "RETURN $x" {"x": 1} {}
+C: RUN "RETURN 1 AS x" {} {}
 S: <EXIT>

tests/stub/scripts/v4x0/return_1_port_9001.script

@@ -0,0 +1,12 @@
+!: BOLT 4
+!: AUTO GOODBYE
+!: AUTO RESET
+!: PORT 9001
+
+C: HELLO {"user_agent": "test", "scheme": "basic", "principal": "test", "credentials": "test"}
+S: SUCCESS {"server": "Neo4j/4.0.0", "connection_id": "123e4567-e89b-12d3-a456-426655440000"}
+C: RUN "RETURN 1 AS x" {} {}
+   PULL {"n": -1}
+S: SUCCESS {"fields": ["x"]}
+   RECORD [1]
+   SUCCESS {"bookmark": "neo4j:bookmark-test-1", type": "r", "t_last": 5, "db": "system"}

tests/stub/scripts/v4x0/router_port_9001_one_read_port_9004_one_write_port_9006.script

@@ -0,0 +1,13 @@
+!: BOLT 4
+!: AUTO GOODBYE
+!: AUTO RESET
+!: PORT 9001
+
+C: HELLO {"user_agent": "test", "scheme": "basic", "principal": "test", "credentials": "test"}
+S: SUCCESS {"server": "Neo4j/4.0.0", "connection_id": "123e4567-e89b-12d3-a456-426655440000"}
+
+C: RUN "CALL dbms.cluster.routing.getRoutingTable($context)" {"context":{}} {}
+   PULL {"n": -1}
+S: SUCCESS {"fields": ["ttl", "servers"]}
+   RECORD [300, [{"role":"ROUTE", "addresses":["127.0.0.1:9001", "127.0.0.1:9002"]}, {"role":"READ", "addresses":["127.0.0.1:9004"]}, {"role":"WRITE", "addresses":["127.0.0.1:9006"]}]]
+   SUCCESS {"bookmark": "neo4j:bookmark-test-1", type": "r", "t_last": 5, "db": "system"}

tests/stub/test_directdriver.py

@@ -50,6 +50,48 @@ def test_bolt_uri_constructs_bolt_driver(driver_info, test_script):
             assert isinstance(driver, BoltDriver)
 
 
+def test_direct_driver_with_wrong_port(driver_info):
+    # python -m pytest tests/stub/test_directdriver.py -s -v -k test_direct_driver_with_wrong_port
+    uri = "bolt://127.0.0.1:9002"
+    with pytest.raises(ServiceUnavailable):
+        driver = GraphDatabase.driver(uri, auth=driver_info["auth_token"], user_agent="test")
+        # assert isinstance(driver, BoltDriver)
+        # with pytest.raises(ServiceUnavailable):
+        #     driver.verify_connectivity()
+
+
+@pytest.mark.parametrize(
+    "test_script, test_expected",
+    [
+        ("v3/return_1_port_9001.script", "Neo4j/3.0.0"),
+        ("v4x0/return_1_port_9001.script", "Neo4j/4.0.0"),
+    ]
+)
+def test_direct_verify_connectivity(driver_info, test_script, test_expected):
+    # python -m pytest tests/stub/test_directdriver.py -s -v -k test_direct_verify_connectivity
+    with StubCluster(test_script):
+        uri = "bolt://127.0.0.1:9001"
+        with GraphDatabase.driver(uri, auth=driver_info["auth_token"], user_agent="test") as driver:
+            assert isinstance(driver, BoltDriver)
+            assert driver.verify_connectivity() == test_expected
+
+
+@pytest.mark.parametrize(
+    "test_script",
+    [
+        "v3/disconnect_on_run.script",
+        "v4x0/disconnect_on_run.script",
+    ]
+)
+def test_direct_verify_connectivity_disconnect_on_run(driver_info, test_script):
+    # python -m pytest tests/stub/test_directdriver.py -s -v -k test_direct_verify_connectivity_disconnect_on_run
+    with StubCluster(test_script):
+        uri = "bolt://127.0.0.1:9001"
+        with GraphDatabase.driver(uri, auth=driver_info["auth_token"]) as driver:
+            with pytest.raises(ServiceUnavailable):
+                driver.verify_connectivity()
+
+
 @pytest.mark.parametrize(
     "test_script",
     [
@@ -64,7 +106,7 @@ def test_direct_disconnect_on_run(driver_info, test_script):
         with GraphDatabase.driver(uri, auth=driver_info["auth_token"]) as driver:
             with pytest.raises(ServiceUnavailable):
                 with driver.session() as session:
-                    session.run("RETURN $x", {"x": 1}).consume()
+                    session.run("RETURN 1 AS x").consume()
 
 
 @pytest.mark.parametrize(

tests/stub/test_routingdriver.py

@@ -57,6 +57,45 @@ def test_bolt_plus_routing_uri_constructs_neo4j_driver(driver_info, test_script)
             assert isinstance(driver, Neo4jDriver)
 
 
+@pytest.mark.parametrize(
+    "test_script",
+    [
+        "v3/router.script",
+        "v4x0/router_port_9001_one_read_port_9004_one_write_port_9006.script",
+    ]
+)
+def test_neo4j_driver_verify_connectivity(driver_info, test_script):
+    # python -m pytest tests/stub/test_routingdriver.py -s -v -k test_neo4j_driver_verify_connectivity
+    uri = "bolt+routing://127.0.0.1:9001"
+    with StubCluster(test_script):
+        driver = GraphDatabase.driver(uri, auth=driver_info["auth_token"], user_agent="test")
+        assert isinstance(driver, Neo4jDriver)
+
+    with StubCluster(test_script):
+        assert driver.verify_connectivity() is not None
+        driver.close()
+
+
+@pytest.mark.parametrize(
+    "test_script",
+    [
+        "v3/router.script",
+        "v4x0/router_port_9001_one_read_port_9004_one_write_port_9006.script",
+    ]
+)
+def test_neo4j_driver_verify_connectivity_server_down(driver_info, test_script):
+    # python -m pytest tests/stub/test_routingdriver.py -s -v -k test_neo4j_driver_verify_connectivity_server_down
+    uri = "bolt+routing://127.0.0.1:9001"
+    with StubCluster(test_script):
+        driver = GraphDatabase.driver(uri, auth=driver_info["auth_token"], user_agent="test")
+        assert isinstance(driver, Neo4jDriver)
+
+        with pytest.raises(ServiceUnavailable):
+            driver.verify_connectivity()
+
+        driver.close()
+
+
 @pytest.mark.parametrize(
     "test_script",
     [