Finishing foxx API

Author: apetenchea

arangoasync/exceptions.py

@@ -407,6 +407,10 @@ class FoxxConfigUpdateError(ArangoServerError):
     """Failed to update Foxx service configuration."""
 
 
+class FoxxCommitError(ArangoServerError):
+    """Failed to commit local Foxx service state."""
+
+
 class FoxxDependencyGetError(ArangoServerError):
     """Failed to retrieve Foxx service dependencies."""
 
@@ -423,6 +427,22 @@ class FoxxScriptListError(ArangoServerError):
     """Failed to retrieve Foxx service scripts."""
 
 
+class FoxxDevModeEnableError(ArangoServerError):
+    """Failed to enable development mode for Foxx service."""
+
+
+class FoxxDevModeDisableError(ArangoServerError):
+    """Failed to disable development mode for Foxx service."""
+
+
+class FoxxDownloadError(ArangoServerError):
+    """Failed to download Foxx service bundle."""
+
+
+class FoxxReadmeGetError(ArangoServerError):
+    """Failed to retrieve Foxx service readme."""
+
+
 class FoxxScriptRunError(ArangoServerError):
     """Failed to run Foxx service script."""
 
@@ -451,6 +471,10 @@ class FoxxServiceUpdateError(ArangoServerError):
     """Failed to update Foxx service."""
 
 
+class FoxxSwaggerGetError(ArangoServerError):
+    """Failed to retrieve Foxx service swagger."""
+
+
 class FoxxTestRunError(ArangoServerError):
     """Failed to run Foxx service tests."""
 

arangoasync/foxx.py

@@ -3,12 +3,17 @@
 from typing import Any, Optional
 
 from arangoasync.exceptions import (
+    FoxxCommitError,
     FoxxConfigGetError,
     FoxxConfigReplaceError,
     FoxxConfigUpdateError,
     FoxxDependencyGetError,
     FoxxDependencyReplaceError,
     FoxxDependencyUpdateError,
+    FoxxDevModeDisableError,
+    FoxxDevModeEnableError,
+    FoxxDownloadError,
+    FoxxReadmeGetError,
     FoxxScriptListError,
     FoxxScriptRunError,
     FoxxServiceCreateError,
@@ -17,6 +22,7 @@
     FoxxServiceListError,
     FoxxServiceReplaceError,
     FoxxServiceUpdateError,
+    FoxxSwaggerGetError,
     FoxxTestRunError,
 )
 from arangoasync.executor import ApiExecutor
@@ -638,3 +644,186 @@ def response_handler(resp: Response) -> str:
             return resp.raw_body.decode("utf-8")
 
         return await self._executor.execute(request, response_handler)
+
+    async def enable_development(self, mount: str) -> Result[Json]:
+        """Puts the service into development mode.
+
+        While the service is running in development mode, it is reloaded from
+        the file system, and its setup script (if any) is re-executed every
+        time the service handles a request.
+
+        In a cluster with multiple coordinators, changes to the filesystem on
+        one coordinator is not reflected across other coordinators.
+
+        Args:
+            mount (str): Service mount path.
+
+        Returns:
+            dict: Service metadata.
+
+        Raises:
+            FoxxDevModeEnableError: If the operation fails.
+
+        References:
+           - `enable-the-development-mode <https://docs.arangodb.com/stable/develop/http-api/foxx/#enable-the-development-mode>`__
+        """  # noqa: E501
+        request = Request(
+            method=Method.POST,
+            endpoint="/_api/foxx/development",
+            params={"mount": mount},
+        )
+
+        def response_handler(resp: Response) -> Json:
+            if not resp.is_success:
+                raise FoxxDevModeEnableError(resp, request)
+            result: Json = self.deserializer.loads(resp.raw_body)
+            return result
+
+        return await self._executor.execute(request, response_handler)
+
+    async def disable_development(self, mount: str) -> Result[Json]:
+        """Puts the service into production mode.
+
+        In a cluster with multiple coordinators, the services on all other
+        coordinators are replaced with the version on the calling coordinator.
+
+        Args:
+            mount (str): Service mount path.
+
+        Returns:
+            dict: Service metadata.
+
+        Raises:
+            FoxxDevModeDisableError: If the operation fails.
+
+        References:
+            - `disable-the-development-mode <https://docs.arangodb.com/stable/develop/http-api/foxx/#disable-the-development-mode>`__
+        """  # noqa: E501
+        request = Request(
+            method=Method.DELETE,
+            endpoint="/_api/foxx/development",
+            params={"mount": mount},
+        )
+
+        def response_handler(resp: Response) -> Json:
+            if not resp.is_success:
+                raise FoxxDevModeDisableError(resp, request)
+            result: Json = self.deserializer.loads(resp.raw_body)
+            return result
+
+        return await self._executor.execute(request, response_handler)
+
+    async def readme(self, mount: str) -> Result[str]:
+        """Return the service readme.
+
+        Args:
+            mount (str): Service mount path.
+
+        Returns:
+            str: Service readme content.
+
+        Raises:
+            FoxxReadmeGetError: If retrieval fails.
+
+        References:
+            - `get-the-service-readme <https://docs.arangodb.com/stable/develop/http-api/foxx/#get-the-service-readme>`__
+        """  # noqa: E501
+        request = Request(
+            method=Method.GET,
+            endpoint="/_api/foxx/readme",
+            params={"mount": mount},
+        )
+
+        def response_handler(resp: Response) -> str:
+            if not resp.is_success:
+                raise FoxxReadmeGetError(resp, request)
+            return resp.raw_body.decode("utf-8")
+
+        return await self._executor.execute(request, response_handler)
+
+    async def swagger(self, mount: str) -> Result[Json]:
+        """Return the Swagger API description for the given service.
+
+        Args:
+            mount (str): Service mount path.
+
+        Returns:
+            dict: Swagger API description.
+
+        Raises:
+            FoxxSwaggerGetError: If retrieval fails.
+
+        References:
+           - `get-the-swagger-description <https://docs.arangodb.com/stable/develop/http-api/foxx/#get-the-swagger-description>`__
+        """  # noqa: E501
+        request = Request(
+            method=Method.GET, endpoint="/_api/foxx/swagger", params={"mount": mount}
+        )
+
+        def response_handler(resp: Response) -> Json:
+            if not resp.is_success:
+                raise FoxxSwaggerGetError(resp, request)
+            result: Json = self.deserializer.loads(resp.raw_body)
+            return result
+
+        return await self._executor.execute(request, response_handler)
+
+    async def download(self, mount: str) -> Result[bytes]:
+        """Downloads a zip bundle of the service directory.
+
+        When development mode is enabled, this always creates a new bundle.
+        Otherwise, the bundle will represent the version of a service that is
+        installed on that ArangoDB instance.
+
+        Args:
+            mount (str): Service mount path.
+
+        Returns:
+            bytes: Service bundle zip in raw bytes form.
+
+        Raises:
+            FoxxDownloadError: If download fails.
+
+        References:
+           - `download-a-service-bundle <https://docs.arangodb.com/stable/develop/http-api/foxx/#download-a-service-bundle>`__
+        """  # noqa: E501
+        request = Request(
+            method=Method.POST, endpoint="/_api/foxx/download", params={"mount": mount}
+        )
+
+        def response_handler(resp: Response) -> bytes:
+            if not resp.is_success:
+                raise FoxxDownloadError(resp, request)
+            return resp.raw_body
+
+        return await self._executor.execute(request, response_handler)
+
+    async def commit(self, replace: Optional[bool] = None) -> None:
+        """Commit local service state of the coordinator to the database.
+
+        This can be used to resolve service conflicts between coordinators
+        that cannot be fixed automatically due to missing data.
+
+        Args:
+            replace (bool | None): If set to `True`, any existing service files in the database
+                will be overwritten.
+
+        Raises:
+            FoxxCommitError: If commit fails.
+
+        References:
+            - `commit-the-local-service-state <https://docs.arangodb.com/stable/develop/http-api/foxx/#commit-the-local-service-state>`__
+        """  # noqa: E501
+        params: Params = {}
+        if replace is not None:
+            params["replace"] = replace
+
+        request = Request(
+            method=Method.POST, endpoint="/_api/foxx/commit", params=params
+        )
+
+        def response_handler(resp: Response) -> None:
+            if not resp.is_success:
+                raise FoxxCommitError(resp, request)
+
+        await self._executor.execute(request, response_handler)

tests/test_foxx.py

@@ -1,16 +1,22 @@
+import asyncio
 import json
 
 import aiofiles
 import aiohttp
 import pytest
 
 from arangoasync.exceptions import (
+    FoxxCommitError,
     FoxxConfigGetError,
     FoxxConfigReplaceError,
     FoxxConfigUpdateError,
     FoxxDependencyGetError,
     FoxxDependencyReplaceError,
     FoxxDependencyUpdateError,
+    FoxxDevModeDisableError,
+    FoxxDevModeEnableError,
+    FoxxDownloadError,
+    FoxxReadmeGetError,
     FoxxScriptListError,
     FoxxScriptRunError,
     FoxxServiceCreateError,
@@ -19,6 +25,7 @@
     FoxxServiceListError,
     FoxxServiceReplaceError,
     FoxxServiceUpdateError,
+    FoxxSwaggerGetError,
     FoxxTestRunError,
 )
 from tests.helpers import generate_service_mount
@@ -28,7 +35,7 @@
 
 
 @pytest.mark.asyncio
-async def test_foxx(db, bad_db, cluster):
+async def test_foxx(db, bad_db):
     # Test errors
     with pytest.raises(FoxxServiceGetError):
         await bad_db.foxx.service(service_name)
@@ -61,6 +68,18 @@ async def test_foxx(db, bad_db, cluster):
         await bad_db.foxx.replace_dependencies(mount="foo", options={})
     with pytest.raises(FoxxDependencyUpdateError):
         await bad_db.foxx.update_dependencies(mount="foo", options={})
+    with pytest.raises(FoxxDevModeEnableError):
+        await bad_db.foxx.enable_development("foo")
+    with pytest.raises(FoxxDevModeDisableError):
+        await bad_db.foxx.disable_development("foo")
+    with pytest.raises(FoxxReadmeGetError):
+        await bad_db.foxx.readme("foo")
+    with pytest.raises(FoxxSwaggerGetError):
+        await bad_db.foxx.swagger("foo")
+    with pytest.raises(FoxxDownloadError):
+        await bad_db.foxx.download("foo")
+    with pytest.raises(FoxxCommitError):
+        await bad_db.foxx.commit()
 
     services = await db.foxx.services()
     assert isinstance(services, list)
@@ -197,3 +216,30 @@ async def test_foxx(db, bad_db, cluster):
     # Run tests on missing service
     with pytest.raises(FoxxTestRunError):
         await db.foxx.run_tests("foo")
+
+    # Development mode
+    result = await db.foxx.enable_development(mount1)
+    assert result["mount"] == mount1
+    result = await db.foxx.disable_development(mount1)
+    assert result["mount"] == mount1
+
+    # Readme
+    result = await db.foxx.readme(mount1)
+    assert isinstance(result, str)
+
+    # Swagger
+    result = await db.foxx.swagger(mount1)
+    assert isinstance(result, dict)
+
+    # Download service
+    result = await db.foxx.download(mount1)
+    assert isinstance(result, bytes)
+
+    # Commit
+    await db.foxx.commit(replace=True)
+
+    # Delete remaining services
+    await asyncio.gather(
+        db.foxx.delete_service(mount1),
+        db.foxx.delete_service(mount2),
+    )