Clean-up, refactoring, and documentation

Author: robsdedude

docs/source/api.rst

@@ -160,7 +160,8 @@ Driver Configuration
 
 Additional configuration can be provided via the :class:`neo4j.Driver` constructor.
 
-
++ :ref:`session-connection-timeout-ref`
++ :ref:`update-routing-table-timeout-ref`
 + :ref:`connection-acquisition-timeout-ref`
 + :ref:`connection-timeout-ref`
 + :ref:`encrypted-ref`
@@ -175,12 +176,55 @@ Additional configuration can be provided via the :class:`neo4j.Driver` construct
 + :ref:`user-agent-ref`
 
 
+.. _session-connection-timeout-ref:
+
+``session_connection_timeout``
+------------------------------
+The maximum amount of time in seconds the session will wait when trying to
+establish a usable read/write connection to the remote host.
+This encompasses *everything* that needs to happen for this, including,
+if necessary, updating the routing table, fetching a connection from the pool,
+and, if necessary fully establishing a new connection with the reader/writer.
+
+Since this process may involve updating the routing table, acquiring a
+connection from the pool, or establishing a new connection, it should be chosen
+larger than :ref:`update-routing-table-timeout-ref`,
+:ref:`connection-acquisition-timeout-ref`, and :ref:`connection-timeout-ref`.
+
+:Type: ``float``
+:Default: ``120.0``
+
+
+.. _update-routing-table_timeout-ref:
+
+``update_routing_table_timeout``
+--------------------------------
+The maximum amount of time in seconds the driver will attempt to fetch a new
+routing table. This encompasses *everything* that needs to happen for this,
+including fetching connections from the pool, performing handshakes, and
+requesting and receiving a fresh routing table.
+
+Since this process may involve acquiring a connection from the pool, or
+establishing a new connection, it should be chosen larger than
+:ref:`connection-acquisition-timeout-ref` and :ref:`connection-timeout-ref`.
+
+This setting only has an effect for :ref:`neo4j-driver-ref`, but not for
+:ref:`bolt-driver-ref` as it does no routing at all.
+
+:Type: ``float``
+:Default: ``90.0``
+
+
 .. _connection-acquisition-timeout-ref:
 
 ``connection_acquisition_timeout``
 ----------------------------------
-The maximum amount of time in seconds a session will wait when requesting a connection from the connection pool.
-Since the process of acquiring a connection may involve creating a new connection, ensure that the value of this configuration is higher than the configured :ref:`connection-timeout-ref`.
+The maximum amount of time in seconds the driver will wait to either acquire an
+idle connection from the pool (including potential liveness checks) or create a
+new connection when the pool is not full and all existing connection are in use.
+
+Since this process may involve opening a new connection including handshakes,
+it should be chosen larger than :ref:`connection-timeout-ref`.
 
 :Type: ``float``
 :Default: ``60.0``
@@ -190,7 +234,11 @@ Since the process of acquiring a connection may involve creating a new connectio
 
 ``connection_timeout``
 ----------------------
-The maximum amount of time in seconds to wait for a TCP connection to be established.
+The maximum amount of time in seconds to wait for a TCP connection to be
+established.
+
+This *does not* include any handshake(s), or authentication required before the
+connection can be used to perform database related work.
 
 :Type: ``float``
 :Default: ``30.0``
@@ -224,7 +272,6 @@ Specify whether TCP keep-alive should be enabled.
 
 ``max_connection_lifetime``
 ---------------------------
-
 The maximum duration in seconds that the driver will keep a connection for before being removed from the pool.
 
 :Type: ``float``

neo4j/_async/io/__init__.py

@@ -29,15 +29,13 @@
     "AsyncNeo4jPool",
     "check_supported_server_product",
     "ConnectionErrorHandler",
-    "time_remaining",
 ]
 
 
 from ._bolt import AsyncBolt
 from ._common import (
     check_supported_server_product,
     ConnectionErrorHandler,
-    time_remaining,
 )
 from ._pool import (
     AsyncBoltPool,

neo4j/_async/io/_bolt.py

@@ -357,12 +357,6 @@ def time_remaining():
             connection.socket.set_deadline(time_remaining())
             try:
                 await connection.hello()
-            except SocketDeadlineExceeded as e:
-                # connection._defunct = True
-                log.debug("[#%04X]  S: <TIMEOUT>", connection.local_port)
-                raise ServiceUnavailable(
-                    "Timeout during initial handshake occurred"
-                ) from e
             finally:
                 connection.socket.set_deadline(None)
         except Exception:
@@ -595,7 +589,7 @@ async def _set_defunct(self, message, error=None, silent=False):
         direct_driver = isinstance(self.pool, AsyncBoltPool)
 
         if error:
-            log.debug("[#%04X] %s", self.socket.getsockname()[1], error)
+            log.debug("[#%04X]  %r", self.socket.getsockname()[1], error)
         log.error(message)
         # We were attempting to receive data but the connection
         # has unexpectedly terminated. So, we need to close the

neo4j/_async/io/_common.py

@@ -21,9 +21,9 @@
 import logging
 import socket
 from struct import pack as struct_pack
-from time import perf_counter
 
 from ..._async_compat.util import AsyncUtil
+from ..._exceptions import SocketDeadlineExceeded
 from ...exceptions import (
     Neo4jError,
     ServiceUnavailable,
@@ -39,13 +39,6 @@
 log = logging.getLogger("neo4j")
 
 
-def time_remaining(t0, timeout):
-    if timeout is None:
-        return None
-    t = timeout - (perf_counter() - t0)
-    return t if t > 0 else 0
-
-
 class AsyncMessageInbox:
 
     def __init__(self, s, on_error):
@@ -78,7 +71,7 @@ async def _yield_messages(self, sock):
                     # Reset for new message
                     unpacker.reset()
 
-        except (OSError, socket.timeout) as error:
+        except (OSError, socket.timeout, SocketDeadlineExceeded) as error:
             await AsyncUtil.callback(self.on_error, error)
 
     async def pop(self):