Renaming to OverloadControlDatabase

Author: apetenchea

arango/database.py

@@ -2,7 +2,7 @@
     "StandardDatabase",
     "AsyncDatabase",
     "BatchDatabase",
-    "QueueBoundedDatabase",
+    "OverloadControlDatabase",
     "TransactionDatabase",
 ]
 
@@ -81,7 +81,7 @@
     AsyncApiExecutor,
     BatchApiExecutor,
     DefaultApiExecutor,
-    QueueBoundedApiExecutor,
+    OverloadControlApiExecutor,
     TransactionApiExecutor,
 )
 from arango.formatter import (
@@ -2521,18 +2521,18 @@ def begin_transaction(
             max_size=max_size,
         )
 
-    def begin_queue_bounded_execution(
-        self, max_queue_time_seconds: float = 0.0
-    ) -> "QueueBoundedDatabase":
-        """Begin queue bounded execution.
+    def begin_controlled_execution(
+        self, max_queue_time_seconds: Optional[float] = None
+    ) -> "OverloadControlDatabase":
+        """Begin a controlled connection, with options to handle server-side overload.
 
         :param max_queue_time_seconds: Maximum time in seconds a request can be queued
-            on the server-side. If set to 0, the server ignores this setting.
-        :type max_queue_time_seconds: float
+            on the server-side. If set to 0 or None, the server ignores this setting.
+        :type max_queue_time_seconds: Optional[float]
         :return: Database API wrapper object specifically for queue bounded execution.
-        :rtype: arango.database.QueueBoundedDatabase
+        :rtype: arango.database.OverloadControlDatabase
         """
-        return QueueBoundedDatabase(self._conn, max_queue_time_seconds)
+        return OverloadControlDatabase(self._conn, max_queue_time_seconds)
 
 
 class AsyncDatabase(Database):
@@ -2706,27 +2706,29 @@ def abort_transaction(self) -> bool:
         return self._executor.abort()
 
 
-class QueueBoundedDatabase(Database):
-    """Database API wrapper tailored specifically to hande time-bound requests.
+class OverloadControlDatabase(Database):
+    """Database API wrapper tailored to gracefully handle server overload scenarios.
 
-    See :func:`arango.database.StandardDatabase.begin_queue_bounded_execution`.
+    See :func:`arango.database.StandardDatabase.begin_controlled_execution`.
 
     :param connection: HTTP connection.
     :param max_queue_time_seconds: Maximum server-side queuing time in seconds.
         If the server-side queuing time exceeds the client's specified limit,
         the request will be rejected.
-    :type max_queue_time_seconds: float
+    :type max_queue_time_seconds: Optional[float]
     """
 
-    def __init__(self, connection: Connection, max_queue_time_seconds: float) -> None:
-        self._executor: QueueBoundedApiExecutor
+    def __init__(
+        self, connection: Connection, max_queue_time_seconds: Optional[float] = None
+    ) -> None:
+        self._executor: OverloadControlApiExecutor
         super().__init__(
             connection=connection,
-            executor=QueueBoundedApiExecutor(connection, max_queue_time_seconds),
+            executor=OverloadControlApiExecutor(connection, max_queue_time_seconds),
         )
 
     def __repr__(self) -> str:  # pragma: no cover
-        return f"<QueueBoundedDatabase {self.name}>"
+        return f"<OverloadControlDatabase {self.name}>"
 
     @property
     def last_queue_time(self) -> float:
@@ -2738,19 +2740,19 @@ def last_queue_time(self) -> float:
         return self._executor.queue_time_seconds
 
     @property
-    def max_queue_time(self) -> float:
+    def max_queue_time(self) -> Optional[float]:
         """Return the maximum server-side queuing time in seconds.
 
         :return: Maximum server-side queuing time in seconds.
-        :rtype: float
+        :rtype: Optional[float]
         """
         return self._executor.max_queue_time_seconds
 
-    def adjust_max_queue_time(self, max_queue_time_seconds: float) -> None:
+    def adjust_max_queue_time(self, max_queue_time_seconds: Optional[float]) -> None:
         """Adjust the maximum server-side queuing time in seconds.
 
         :param max_queue_time_seconds: New maximum server-side queuing time
-            in seconds.
-        :type max_queue_time_seconds: float
+            in seconds. Setting it to None disables the limit.
+        :type max_queue_time_seconds: Optional[float]
         """
         self._executor.max_queue_time_seconds = max_queue_time_seconds

arango/exceptions.py

@@ -232,13 +232,13 @@ class BatchExecuteError(ArangoServerError):
     """Failed to execute batch API request."""
 
 
-######################################
-# Queue Bounded Execution Exceptions #
-######################################
+#########################################
+# Overload Control Execution Exceptions #
+#########################################
 
 
-class QueueBoundedExecutorError(ArangoServerError):
-    """Failed to execute queue-bounded API request."""
+class OverloadControlExecutorError(ArangoServerError):
+    """Failed to execute overload controlled API request."""
 
 
 #########################

arango/executor.py

@@ -4,7 +4,7 @@
     "AsyncApiExecutor",
     "BatchApiExecutor",
     "TransactionApiExecutor",
-    "QueueBoundedApiExecutor",
+    "OverloadControlApiExecutor",
 ]
 
 from collections import OrderedDict
@@ -17,7 +17,7 @@
     AsyncExecuteError,
     BatchExecuteError,
     BatchStateError,
-    QueueBoundedExecutorError,
+    OverloadControlExecutorError,
     TransactionAbortError,
     TransactionCommitError,
     TransactionInitError,
@@ -34,7 +34,7 @@
     "AsyncApiExecutor",
     "BatchApiExecutor",
     "TransactionApiExecutor",
-    "QueueBoundedApiExecutor",
+    "OverloadControlApiExecutor",
 ]
 
 T = TypeVar("T")
@@ -433,7 +433,7 @@ def abort(self) -> bool:
         raise TransactionAbortError(resp, request)
 
 
-class QueueBoundedApiExecutor:
+class OverloadControlApiExecutor:
     """Allows setting the maximum acceptable server-side queuing time
         for client requests.
 
@@ -444,39 +444,43 @@ class QueueBoundedApiExecutor:
     :type max_queue_time_seconds: float
     """
 
-    def __init__(self, connection: Connection, max_queue_time_seconds: float) -> None:
+    def __init__(
+        self, connection: Connection, max_queue_time_seconds: Optional[float] = None
+    ) -> None:
         self._conn = connection
         self._max_queue_time_seconds = max_queue_time_seconds
         self._queue_time_seconds = 0.0
 
     @property
     def context(self) -> str:  # pragma: no cover
-        return "queue-bounded"
+        return "overload-control"
 
     @property
     def queue_time_seconds(self) -> float:
         """Return the most recent request queuing/de-queuing time.
+            Defaults to 0 if no request has been sent.
 
         :return: Server-side queuing time in seconds.
         :rtype: float
         """
         return self._queue_time_seconds
 
     @property
-    def max_queue_time_seconds(self) -> float:
+    def max_queue_time_seconds(self) -> Optional[float]:
         """Return the maximum server-side queuing time.
 
         :return: Maximum server-side queuing time in seconds.
-        :rtype: float
+        :rtype: Optional[float]
         """
         return self._max_queue_time_seconds
 
     @max_queue_time_seconds.setter
-    def max_queue_time_seconds(self, value: float) -> None:
+    def max_queue_time_seconds(self, value: Optional[float]) -> None:
         """Set the maximum server-side queuing time.
+            Setting it to None disables the feature.
 
         :param value: Maximum server-side queuing time in seconds.
-        :type value: float
+        :type value: Optional[float]
         """
         self._max_queue_time_seconds = value
 
@@ -493,13 +497,14 @@ def execute(
         :type response_handler: callable
         :return: API execution result.
         """
-        request.headers["x-arango-queue-time-seconds"] = str(
-            self._max_queue_time_seconds
-        )
+        if self._max_queue_time_seconds is not None:
+            request.headers["x-arango-queue-time-seconds"] = str(
+                self._max_queue_time_seconds
+            )
         resp = self._conn.send_request(request)
 
         if not resp.is_success:
-            raise QueueBoundedExecutorError(resp, request)
+            raise OverloadControlExecutorError(resp, request)
 
         if "X-Arango-Queue-Time-Seconds" in resp.headers:
             self._queue_time_seconds = float(

tests/test_overload.py

@@ -0,0 +1,49 @@
+import warnings
+
+from arango import errno
+from arango.exceptions import OverloadControlExecutorError
+
+
+def flood_with_requests(controlled_db, async_db):
+    """
+    Flood the database with requests.
+    It is impossible to predict what the last recorded queue time will be.
+    We can only try and make it as large as possible. However, if the system
+    is fast enough, it may still be 0.
+    """
+    controlled_db.aql.execute("RETURN SLEEP(0.5)", count=True)
+    for _ in range(3):
+        for _ in range(500):
+            async_db.aql.execute("RETURN SLEEP(0.5)", count=True)
+        controlled_db.aql.execute("RETURN SLEEP(0.5)", count=True)
+        if controlled_db.last_queue_time >= 0:
+            break
+
+
+def test_overload_control(db):
+    controlled_db = db.begin_controlled_execution(100)
+    assert controlled_db.max_queue_time == 100
+
+    async_db = db.begin_async_execution(return_result=True)
+
+    flood_with_requests(controlled_db, async_db)
+    assert controlled_db.last_queue_time >= 0
+
+    # We can only emit a warning here. The test will still pass.
+    if controlled_db.last_queue_time == 0:
+        warnings.warn(
+            f"last_queue_time of {controlled_db} is 0, test may be unreliable"
+        )
+
+    controlled_db.adjust_max_queue_time(0.0001)
+    try:
+        flood_with_requests(controlled_db, async_db)
+        assert controlled_db.last_queue_time >= 0
+    except OverloadControlExecutorError as e:
+        assert e.http_code == errno.HTTP_PRECONDITION_FAILED
+        assert e.error_code == errno.QUEUE_TIME_REQUIREMENT_VIOLATED
+    else:
+        warnings.warn(
+            f"last_queue_time of {controlled_db} is {controlled_db.last_queue_time},"
+            f"test may be unreliable"
+        )