Merge branch 'main' into fix-geo-json-param

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

@@ -8,7 +8,7 @@
 
 from datetime import datetime
 from numbers import Number
-from typing import Any, List, Optional, Sequence, Union
+from typing import Any, Dict, List, Optional, Sequence, Union
 from warnings import warn
 
 from arango.api import ApiGroup
@@ -27,10 +27,12 @@
     CollectionCreateError,
     CollectionDeleteError,
     CollectionListError,
+    DatabaseCompactError,
     DatabaseCreateError,
     DatabaseDeleteError,
     DatabaseListError,
     DatabasePropertiesError,
+    DatabaseSupportInfoError,
     GraphCreateError,
     GraphDeleteError,
     GraphListError,
@@ -44,11 +46,16 @@
     ServerEchoError,
     ServerEncryptionError,
     ServerEngineError,
+    ServerExecuteError,
     ServerLicenseGetError,
     ServerLicenseSetError,
     ServerLogLevelError,
     ServerLogLevelSetError,
+    ServerLogSettingError,
+    ServerLogSettingSetError,
     ServerMetricsError,
+    ServerModeError,
+    ServerModeSetError,
     ServerReadLogError,
     ServerReloadRoutingError,
     ServerRequiredDBVersionError,
@@ -224,6 +231,36 @@ def response_handler(resp: Response) -> Json:
 
         return self._execute(request, response_handler)
 
+    def execute(self, command: str) -> Result[Any]:
+        """Execute raw Javascript command on the server.
+
+        Executes the JavaScript code in the body on the server as
+        the body of a function with no arguments. If you have a
+        return statement then the return value you produce will be returned
+        as 'application/json'.
+
+        NOTE: this method endpoint will only be usable if the server
+        was started with the option `--javascript.allow-admin-execute true`.
+        The default value of this option is false, which disables the execution
+        of user-defined code and disables this API endpoint entirely.
+        This is also the recommended setting for production.
+
+        :param command: Javascript command to execute.
+        :type command: str
+        :return: Return value of **command**, if any.
+        :rtype: Any
+        :raise arango.exceptions.ServerExecuteError: If execution fails.
+        """
+        request = Request(method="post", endpoint="/_admin/execute", data=command)
+
+        def response_handler(resp: Response) -> Any:
+            if not resp.is_success:
+                raise ServerExecuteError(resp, request)
+
+            return resp.body
+
+        return self._execute(request, response_handler)
+
     def execute_transaction(
         self,
         command: str,
@@ -439,6 +476,47 @@ def response_handler(resp: Response) -> Json:
 
         return self._execute(request, response_handler)
 
+    def compact(
+        self,
+        change_level: Optional[bool] = None,
+        compact_bottom_most_level: Optional[bool] = None,
+    ) -> Result[Json]:
+        """Compact all databases.
+
+        NOTE: This command can cause a full rewrite of all data in all databases,
+        which may take very long for large databases. It should thus only be used with
+        care and only when additional I/O load can be tolerated for a prolonged time.
+
+        This method can be used to reclaim disk space after substantial data deletions
+        have taken place, by compacting the entire database system data.
+
+        This method requires superuser access.
+
+        :param change_level: Whether or not compacted data should be moved to
+            the minimum possible level. Default value is False.
+        :type change_level: bool | None
+        :param compact_bottom_most_level: Whether or not to compact the
+            bottom-most level of data. Default value is False.
+        :type compact_bottom_most_level: bool | None
+        :return: Collection compact.
+        :rtype: dict
+        :raise arango.exceptions.CollectionCompactError: If retrieval fails.
+        """
+        data = {}
+        if change_level is not None:
+            data["changeLevel"] = change_level
+        if compact_bottom_most_level is not None:
+            data["compactBottomMostLevel"] = compact_bottom_most_level
+
+        request = Request(method="put", endpoint="/_admin/compact", data=data)
+
+        def response_handler(resp: Response) -> Json:
+            if resp.is_success:
+                return format_body(resp.body)
+            raise DatabaseCompactError(resp, request)
+
+        return self._execute(request, response_handler)
+
     def required_db_version(self) -> Result[str]:
         """Return required version of target database.
 
@@ -510,6 +588,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.
 
@@ -526,14 +654,23 @@ def response_handler(resp: Response) -> datetime:
 
         return self._execute(request, response_handler)
 
-    def echo(self) -> Result[Json]:
-        """Return details of the last request (e.g. headers, payload).
+    def echo(self, body: Optional[Any] = None) -> Result[Json]:
+        """Return details of the last request (e.g. headers, payload),
+        or echo the given request body.
 
+        :param body: The body of the request. Can be of any type
+            and is simply forwarded. If not set, the details of the last
+            request are returned.
+        :type body: dict | list | str | int | float | None
         :return: Details of the last request.
         :rtype: dict
         :raise arango.exceptions.ServerEchoError: If retrieval fails.
         """
-        request = Request(method="get", endpoint="/_admin/echo")
+        request = (
+            Request(method="get", endpoint="/_admin/echo")
+            if body is None
+            else Request(method="post", endpoint="/_admin/echo", data=body)
+        )
 
         def response_handler(resp: Response) -> Json:
             if not resp.is_success:
@@ -749,6 +886,52 @@ def response_handler(resp: Response) -> Json:
 
         return self._execute(request, response_handler)
 
+    def log_settings(self) -> Result[Json]:
+        """Return the structured log settings.
+
+        :return: Current log settings. False values are not returned.
+        :rtype: dict
+        """
+        request = Request(method="get", endpoint="/_admin/log/structured")
+
+        def response_handler(resp: Response) -> Json:
+            if not resp.is_success:
+                raise ServerLogSettingError(resp, request)
+            result: Json = resp.body
+            return result
+
+        return self._execute(request, response_handler)
+
+    def set_log_settings(self, **kwargs: Dict[str, Any]) -> Result[Json]:
+        """Set the structured log settings.
+
+        This method takes arbitrary keyword arguments where the keys are the
+        structured log parameters and the values are true or false, for either
+        enabling or disabling the parameters.
+
+        .. code-block:: python
+
+            arango.set_log_settings(
+                database=True,
+                url=True,
+                username=False,
+            )
+
+        :param kwargs: Structured log parameters.
+        :type kwargs: Dict[str, Any]
+        :return: New log settings. False values are not returned.
+        :rtype: dict
+        """
+        request = Request(method="put", endpoint="/_admin/log/structured", data=kwargs)
+
+        def response_handler(resp: Response) -> Json:
+            if not resp.is_success:
+                raise ServerLogSettingSetError(resp, request)
+            result: Json = resp.body
+            return result
+
+        return self._execute(request, response_handler)
+
     def log_levels(self, server_id: Optional[str] = None) -> Result[Json]:
         """Return current logging levels.
 
@@ -775,7 +958,7 @@ def response_handler(resp: Response) -> Json:
         return self._execute(request, response_handler)
 
     def set_log_levels(
-        self, server_id: Optional[str] = None, **kwargs: str
+        self, server_id: Optional[str] = None, **kwargs: Dict[str, Any]
     ) -> Result[Json]:
         """Set the logging levels.
 
@@ -797,6 +980,8 @@ def set_log_levels(
             JWT authentication whereas Coordinators also support authentication
             using usernames and passwords.
         :type server_id: str | None
+        :param kwargs: Logging levels.
+        :type kwargs: Dict[str, Any]
         :return: New logging levels.
         :rtype: dict
         """
@@ -2675,6 +2860,38 @@ def response_handler(resp: Response) -> bool:
 
         return self._execute(request, response_handler)
 
+    ###########
+    # Support #
+    ###########
+
+    def support_info(self) -> Result[Json]:
+        """Return information about the deployment.
+
+        Retrieves deployment information for support purposes.
+        The endpoint returns data about the ArangoDB version used,
+        the host (operating system, server ID, CPU and storage capacity,
+        current utilization, a few metrics) and the other servers in the
+        deployment (in case of Active Failover or cluster deployments).
+
+        NOTE: This method can only be accessed from inside the **_system** database.
+        The is a policy control startup option `--server.support-info-api` that controls
+        if and to whom the API is made available.
+
+        :return: Deployment information.
+        :rtype: dict
+        :raise arango.exceptions.DatabaseSupportInfoError: If retrieval fails.
+        """
+        request = Request(method="get", endpoint="/_admin/support-info")
+
+        def response_handler(resp: Response) -> Json:
+            if resp.is_success:
+                result: Json = resp.body
+                return result
+
+            raise DatabaseSupportInfoError(resp, request)
+
+        return self._execute(request, response_handler)
+
 
 class StandardDatabase(Database):
     """Standard database API wrapper."""