new: get/put /_admin/server/mode (#312)

* new: `mode()`, `server_mode()`, `set_mode()` * fix: test getting read-only errors even after running `sys_db.set_mode("default")`. Probably sync issues..

Author: aMahanna

arango/cluster.py

@@ -11,6 +11,7 @@
  ClusterServerCountError,
  ClusterServerEngineError,
  ClusterServerIDError,
+ ClusterServerModeError,
  ClusterServerRoleError,
  ClusterServerStatisticsError,
  ClusterServerVersionError,
@@ -57,6 +58,27 @@ def response_handler(resp: Response) -> str:
 
  return self._execute(request, response_handler)
 
+ def server_mode(self) -> Result[str]:
+ """Return the server mode.
+
+ In a read-only server, all write operations will fail
+ with an error code of 1004 (ERROR_READ_ONLY). Creating or dropping
+ databases and collections will also fail with error code 11 (ERROR_FORBIDDEN).
+
+ :return: Server mode. Possible values are "default" or "readonly".
+ :rtype: str
+ :raise arango.exceptions.ClusterServerModeError: If retrieval fails.
+ """
+ request = Request(method="get", endpoint="/_admin/server/mode")
+
+ def response_handler(resp: Response) -> str:
+ if resp.is_success:
+ return str(resp.body["mode"])
+
+ raise ClusterServerModeError(resp, request)
+
+ return self._execute(request, response_handler)
+
  def server_version(self, server_id: str) -> Result[Json]:
  """Return the version of the given server.
 

arango/database.py

@@ -52,6 +52,8 @@
  ServerLogSettingError,
  ServerLogSettingSetError,
  ServerMetricsError,
+ ServerModeError,
+ ServerModeSetError,
  ServerReadLogError,
  ServerReloadRoutingError,
  ServerRequiredDBVersionError,
@@ -554,6 +556,56 @@ def response_handler(resp: Response) -> str:
 
  return self._execute(request, response_handler)
 
+ def mode(self) -> Result[str]:
+ """Return the server mode (default or read-only)
+
+ In a read-only server, all write operations will fail
+ with an error code of 1004 (ERROR_READ_ONLY). Creating or dropping
+ databases and collections will also fail with error code 11 (ERROR_FORBIDDEN).
+
+ :return: Server mode. Possible values are "default" or "readonly".
+ :rtype: str
+ :raise arango.exceptions.ServerModeError: If retrieval fails.
+ """
+ request = Request(method="get", endpoint="/_admin/server/mode")
+
+ def response_handler(resp: Response) -> str:
+ if resp.is_success:
+ return str(resp.body["mode"])
+
+ raise ServerModeError(resp, request)
+
+ return self._execute(request, response_handler)
+
+ def set_mode(self, mode: str) -> Result[Json]:
+ """Set the server mode to read-only or default.
+
+ Update mode information about a server. The JSON response will
+ contain a field mode with the value readonly or default.
+ In a read-only server all write operations will fail with an error
+ code of 1004 (ERROR_READ_ONLY). Creating or dropping of databases
+ and collections will also fail with error code 11 (ERROR_FORBIDDEN).
+
+ This is a protected API. It requires authentication and administrative
+ server rights.
+
+ :param mode: Server mode. Possible values are "default" or "readonly".
+ :type mode: str
+ :return: Server mode.
+ :rtype: str
+ :raise arango.exceptions.ServerModeSetError: If set fails.
+ """
+ request = Request(
+ method="put", endpoint="/_admin/server/mode", data={"mode": mode}
+ )
+
+ def response_handler(resp: Response) -> Json:
+ if resp.is_success:
+ return format_body(resp.body)
+ raise ServerModeSetError(resp, request)
+
+ return self._execute(request, response_handler)
+
  def time(self) -> Result[datetime]:
  """Return server system time.
 

arango/exceptions.py

@@ -695,7 +695,15 @@ class ServerMetricsError(ArangoServerError):
 
 
 class ServerRoleError(ArangoServerError):
- """Failed to retrieve server role in a cluster."""
+ """Failed to retrieve server role."""
+
+
+class ServerModeError(ArangoServerError):
+ """Failed to retrieve server mode."""
+
+
+class ServerModeSetError(ArangoServerError):
+ """Failed to set server mode."""
 
 
 class ServerTLSError(ArangoServerError):
@@ -980,7 +988,11 @@ class ClusterServerIDError(ArangoServerError):
 
 
 class ClusterServerRoleError(ArangoServerError):
- """Failed to retrieve server role."""
+ """Failed to retrieve server role in a cluster."""
+
+
+class ClusterServerModeError(ArangoServerError):
+ """Failed to retrieve server mode in a cluster."""
 
 
 class ClusterServerStatisticsError(ArangoServerError):

docs/admin.rst

@@ -32,9 +32,22 @@ database.
  # Retrieve the server time.
  sys_db.time()
 
- # Retrieve the server role in a cluster.
+ # Retrieve the server role.
  sys_db.role()
 
+ # Retrieve the server role in a cluster.
+ sys_db.cluster.server_role()
+
+ # Retrieve the server mode.
+ sys_db.mode()
+
+ # Retrieve the server mode in a cluster.
+ sys_db.cluster.server_mode()
+
+ # Set the server mode.
+ sys_db.set_mode('readonly')
+ sys_db.set_mode('default')
+
  # Retrieve the server statistics.
  sys_db.statistics()
 

tests/test_cluster.py

@@ -12,6 +12,7 @@
  ClusterServerCountError,
  ClusterServerEngineError,
  ClusterServerIDError,
+ ClusterServerModeError,
  ClusterServerRoleError,
  ClusterServerStatisticsError,
  ClusterServerVersionError,
@@ -43,6 +44,18 @@ def test_cluster_server_role(sys_db, bad_db, cluster):
  assert err.value.error_code in {FORBIDDEN, DATABASE_NOT_FOUND}
 
 
+def test_cluster_server_mode(sys_db, bad_db, cluster):
+ if not cluster:
+ pytest.skip("Only tested in a cluster setup")
+
+ result = sys_db.cluster.server_mode()
+ assert result == "default"
+
+ with assert_raises(ClusterServerModeError) as err:
+ bad_db.cluster.server_mode()
+ assert err.value.error_code in {FORBIDDEN, DATABASE_NOT_FOUND}
+
+
 def test_cluster_health(sys_db, bad_db, cluster):
  if not cluster:
  pytest.skip("Only tested in a cluster setup")

tests/test_database.py

@@ -25,6 +25,7 @@
  ServerLogLevelError,
  ServerLogLevelSetError,
  ServerMetricsError,
+ ServerModeSetError,
  ServerReadLogError,
  ServerReloadRoutingError,
  ServerRequiredDBVersionError,
@@ -138,6 +139,19 @@ def test_database_misc_methods(client, sys_db, db, bad_db, cluster, secret):
  bad_db.role()
  assert err.value.error_code in {11, 1228}
 
+ # Test get/set server mode
+ assert sys_db.mode() == "default"
+ with assert_raises(ServerModeSetError):
+ sys_db.set_mode("badmode")
+ assert err.value.error_code in {11, 1228}
+
+ with assert_raises(ServerModeSetError):
+ db.set_mode("readonly")
+ assert err.value.error_code in {11, 1228}
+
+ result = sys_db.set_mode("default")
+ assert result == {"mode": "default"}
+
  # Test get server status
  status = db.status()
  assert "host" in status