Add support for impersonation (#599)

* Add support for impersonation

* Add docs for impersonation

* Add unit tests for impersonation

* Acquire RT without impersonated user if possible

  This is an optimization saving a few bytes over the wire.
  When there is an explicit database configured for a session, there is no need
  to send the impersonated user along with the `ROUTE` request. The only
  difference this would make is that insufficient permissions would be noticed
  when fetching the RT instead of when performing any actual action on the
  session. Since routing is part of the global driver/pool operations and not
  coupled to sessions, doing it this way seems like the logical conclusion.

* Only prefer initial router if RT got initialized w/o writers
  
  Previously, the driver would prefer the initial router for fetching a new RT
  whenever the current RT had no writers (left). However, if should check what
  the RT looked like when it was received.

Author: robsdedude

docs/source/api.rst

@@ -486,7 +486,12 @@ Name of the database to query.
 
 .. Note::
 
-   The default database can be set on the Neo4j instance settings.
+    The default database can be set on the Neo4j instance settings.
+
+.. Note::
+    It is recommended to always specify the database explicitly when possible.
+    This allows the driver to work more efficiently, as it will not have to
+    resolve the home database first.
 
 
 .. code-block:: python
@@ -499,6 +504,41 @@ Name of the database to query.
 :Default: ``neo4j.DEFAULT_DATABASE``
 
 
+.. _impersonated-user-ref:
+
+``impersonated_user``
+---------------------
+Name of the user to impersonate.
+This means that all actions in the session will be executed in the security
+context of the impersonated user. For this, the user for which the
+:class:``Driver`` has been created needs to have the appropriate permissions.
+
+:Type: ``str``, None
+
+
+.. py:data:: None
+   :noindex:
+
+   Will not perform impersonation.
+
+
+.. Note::
+
+    The server or all servers of the cluster need to support impersonation when.
+    Otherwise, the driver will raise :py:exc:`.ConfigurationError`
+    as soon as it encounters a server that does not.
+
+
+.. code-block:: python
+
+   from neo4j import GraphDatabase
+   driver = GraphDatabase.driver(uri, auth=(user, password))
+   session = driver.session(impersonated_user="alice")
+
+
+:Default: ``None``
+
+
 .. _default-access-mode-ref:
 
 ``default_access_mode``

neo4j/__init__.py

@@ -329,11 +329,9 @@ def supports_multi_db(self):
         :return: Returns true if the server or cluster the driver connects to supports multi-databases, otherwise false.
         :rtype: bool
         """
-        cx = self._pool.acquire(access_mode=READ_ACCESS, timeout=self._pool.workspace_config.connection_acquisition_timeout, database=self._pool.workspace_config.database)
-        support = cx.supports_multiple_databases
-        self._pool.release(cx)
-
-        return support
+        with self.session() as session:
+            session._connect(READ_ACCESS)
+            return session._connection.supports_multiple_databases
 
 
 class BoltDriver(Direct, Driver):
@@ -447,6 +445,7 @@ def _verify_routing_connectivity(self):
                 routing_info[ix] = self._pool.fetch_routing_info(
                     address=table.routers[0],
                     database=self._default_workspace_config.database,
+                    imp_user=self._default_workspace_config.impersonated_user,
                     bookmarks=None,
                     timeout=self._default_workspace_config
                                 .connection_acquisition_timeout

neo4j/conf.py

@@ -283,6 +283,10 @@ class WorkspaceConfig(Config):
     #: Fetch Size
     fetch_size = 1000
 
+    #: User to impersonate
+    impersonated_user = None
+    # Note that you need appropriate permissions to do so.
+
 
 class SessionConfig(WorkspaceConfig):
     """ Session configuration.