Adding more REST methods (#29)

* Improving REST API coverage

* Fixing cluster-only properties

* Fixing enterprise-only features

Author: apetenchea

arangoasync/collection.py

@@ -9,6 +9,7 @@
     HTTP_PRECONDITION_FAILED,
 )
 from arangoasync.exceptions import (
+    CollectionPropertiesError,
     DocumentGetError,
     DocumentInsertError,
     DocumentParseError,
@@ -18,7 +19,7 @@
 from arangoasync.request import Method, Request
 from arangoasync.response import Response
 from arangoasync.serialization import Deserializer, Serializer
-from arangoasync.typings import Json, Params, Result
+from arangoasync.typings import CollectionProperties, Json, Params, Result
 
 T = TypeVar("T")
 U = TypeVar("U")
@@ -48,9 +49,6 @@ def __init__(
         self._doc_deserializer = doc_deserializer
         self._id_prefix = f"{self._name}/"
 
-    def __repr__(self) -> str:
-        return f"<StandardCollection {self.name}>"
-
     def _validate_id(self, doc_id: str) -> str:
         """Check the collection name in the document ID.
 
@@ -148,6 +146,15 @@ def name(self) -> str:
         """
         return self._name
 
+    @property
+    def db_name(self) -> str:
+        """Return the name of the current database.
+
+        Returns:
+            str: Database name.
+        """
+        return self._executor.db_name
+
 
 class StandardCollection(Collection[T, U, V]):
     """Standard collection API wrapper.
@@ -168,6 +175,33 @@ def __init__(
     ) -> None:
         super().__init__(executor, name, doc_serializer, doc_deserializer)
 
+    def __repr__(self) -> str:
+        return f"<StandardCollection {self.name}>"
+
+    async def properties(self) -> Result[CollectionProperties]:
+        """Return the full properties of the current collection.
+
+        Returns:
+            CollectionProperties: Properties.
+
+        Raises:
+            CollectionPropertiesError: If retrieval fails.
+
+        References:
+            - `get-the-properties-of-a-collection <https://docs.arangodb.com/stable/develop/http-api/collections/#get-the-properties-of-a-collection>`__
+        """  # noqa: E501
+        request = Request(
+            method=Method.GET,
+            endpoint=f"/_api/collection/{self.name}/properties",
+        )
+
+        def response_handler(resp: Response) -> CollectionProperties:
+            if not resp.is_success:
+                raise CollectionPropertiesError(resp, request)
+            return CollectionProperties(self._executor.deserialize(resp.raw_body))
+
+        return await self._executor.execute(request, response_handler)
+
     async def get(
         self,
         document: str | Json,
@@ -269,6 +303,9 @@ async def insert(
             bool | dict: Document metadata (e.g. document id, key, revision) or `True`
                 if **silent** is set to `True`.
 
+        Raises:
+            DocumentInsertError: If insertion fails.
+
         References:
             - `create-a-document <https://docs.arangodb.com/stable/develop/http-api/documents/#create-a-document>`__
         """  # noqa: E501

arangoasync/database.py

@@ -87,6 +87,10 @@ class CollectionListError(ArangoServerError):
     """Failed to retrieve collections."""
 
 
+class CollectionPropertiesError(ArangoServerError):
+    """Failed to retrieve collection properties."""
+
+
 class ClientConnectionAbortedError(ArangoClientError):
     """The connection was aborted."""
 
@@ -107,6 +111,10 @@ class DatabaseListError(ArangoServerError):
     """Failed to retrieve databases."""
 
 
+class DatabasePropertiesError(ArangoServerError):
+    """Failed to retrieve database properties."""
+
+
 class DeserializationError(ArangoClientError):
     """Failed to deserialize the server response."""
 
@@ -131,6 +139,30 @@ class JWTRefreshError(ArangoClientError):
     """Failed to refresh the JWT token."""
 
 
+class JWTSecretListError(ArangoServerError):
+    """Failed to retrieve information on currently loaded JWT secrets."""
+
+
+class JWTSecretReloadError(ArangoServerError):
+    """Failed to reload JWT secrets."""
+
+
+class PermissionGetError(ArangoServerError):
+    """Failed to retrieve user permission."""
+
+
+class PermissionListError(ArangoServerError):
+    """Failed to list user permissions."""
+
+
+class PermissionResetError(ArangoServerError):
+    """Failed to reset user permission."""
+
+
+class PermissionUpdateError(ArangoServerError):
+    """Failed to update user permission."""
+
+
 class SerializationError(ArangoClientError):
     """Failed to serialize the request."""
 
@@ -157,3 +189,11 @@ class UserGetError(ArangoServerError):
 
 class UserListError(ArangoServerError):
     """Failed to retrieve users."""
+
+
+class UserReplaceError(ArangoServerError):
+    """Failed to replace user."""
+
+
+class UserUpdateError(ArangoServerError):
+    """Failed to update user."""

arangoasync/exceptions.py

@@ -29,6 +29,10 @@ def connection(self) -> Connection:
     def context(self) -> str:
         return "default"
 
+    @property
+    def db_name(self) -> str:
+        return self._conn.db_name
+
     @property
     def serializer(self) -> Serializer[Json]:
         return self._conn.serializer

arangoasync/executor.py

@@ -200,6 +200,12 @@ async def doc_col(db):
     await db.delete_collection(col_name)
 
 
+@pytest.fixture
+def bad_col(db):
+    col_name = generate_col_name()
+    return db.collection(col_name)
+
+
 @pytest_asyncio.fixture(scope="session", autouse=True)
 async def teardown():
     yield

arangoasync/typings.py

@@ -119,10 +119,17 @@ async def test_client_jwt_auth(url, sys_db_name, basic_auth_root):
 
 
 @pytest.mark.asyncio
-async def test_client_jwt_superuser_auth(url, sys_db_name, basic_auth_root, token):
+async def test_client_jwt_superuser_auth(
+    url, sys_db_name, basic_auth_root, token, enterprise
+):
     # successful authentication
     async with ArangoClient(hosts=url) as client:
-        await client.db(sys_db_name, auth_method="superuser", token=token, verify=True)
+        db = await client.db(
+            sys_db_name, auth_method="superuser", token=token, verify=True
+        )
+        if enterprise:
+            await db.jwt_secrets()
+            await db.reload_jwt_secrets()
 
     # token missing
     async with ArangoClient(hosts=url) as client:

tests/conftest.py

@@ -0,0 +1,20 @@
+import pytest
+
+from arangoasync.exceptions import CollectionPropertiesError
+
+
+def test_collection_attributes(db, doc_col):
+    assert doc_col.db_name == db.name
+    assert doc_col.name.startswith("test_collection")
+    assert repr(doc_col) == f"<StandardCollection {doc_col.name}>"
+
+
+@pytest.mark.asyncio
+async def test_collection_misc_methods(doc_col, bad_col):
+    # Properties
+    properties = await doc_col.properties()
+    assert properties.name == doc_col.name
+    assert properties.is_system is False
+    assert len(properties.format()) > 1
+    with pytest.raises(CollectionPropertiesError):
+        await bad_col.properties()

tests/test_client.py

@@ -1,3 +1,5 @@
+import asyncio
+
 import pytest
 
 from arangoasync.collection import StandardCollection
@@ -8,22 +10,51 @@
     DatabaseCreateError,
     DatabaseDeleteError,
     DatabaseListError,
+    DatabasePropertiesError,
+    JWTSecretListError,
+    JWTSecretReloadError,
+    ServerStatusError,
 )
 from arangoasync.typings import CollectionType, KeyOptions, UserInfo
 from tests.helpers import generate_col_name, generate_db_name, generate_username
 
 
 @pytest.mark.asyncio
-async def test_database_misc_methods(sys_db):
+async def test_database_misc_methods(sys_db, db, bad_db, cluster):
+    # Status
     status = await sys_db.status()
     assert status["server"] == "arango"
+    with pytest.raises(ServerStatusError):
+        await bad_db.status()
+
+    sys_properties, db_properties = await asyncio.gather(
+        sys_db.properties(), db.properties()
+    )
+    assert sys_properties.is_system is True
+    assert db_properties.is_system is False
+    assert sys_properties.name == sys_db.name
+    assert db_properties.name == db.name
+    if cluster:
+        assert db_properties.replication_factor == 3
+        assert db_properties.write_concern == 2
+
+    with pytest.raises(DatabasePropertiesError):
+        await bad_db.properties()
+    assert len(db_properties.format()) > 1
+
+    # JWT secrets
+    with pytest.raises(JWTSecretListError):
+        await bad_db.jwt_secrets()
+    with pytest.raises(JWTSecretReloadError):
+        await bad_db.reload_jwt_secrets()
 
 
 @pytest.mark.asyncio
 async def test_create_drop_database(
     arango_client,
     sys_db,
     db,
+    bad_db,
     basic_auth_root,
     password,
     cluster,
@@ -60,12 +91,19 @@ async def test_create_drop_database(
     dbs = await sys_db.databases()
     assert db_name in dbs
     assert "_system" in dbs
+    dbs = await sys_db.databases_accessible_to_user()
+    assert db_name in dbs
+    assert "_system" in dbs
+    dbs = await db.databases_accessible_to_user()
+    assert db.name in dbs
 
     # Cannot list databases without permission
     with pytest.raises(DatabaseListError):
         await db.databases()
     with pytest.raises(DatabaseListError):
         await db.has_database(db_name)
+    with pytest.raises(DatabaseListError):
+        await bad_db.databases_accessible_to_user()
 
     # Databases can only be dropped from the system database
     with pytest.raises(DatabaseDeleteError):

tests/test_collection.py

@@ -1,8 +1,21 @@
 import pytest
 
-from arangoasync.exceptions import UserCreateError, UserDeleteError, UserListError
+from arangoasync.auth import Auth
+from arangoasync.errno import USER_NOT_FOUND
+from arangoasync.exceptions import (
+    CollectionCreateError,
+    DocumentInsertError,
+    PermissionResetError,
+    PermissionUpdateError,
+    UserCreateError,
+    UserDeleteError,
+    UserGetError,
+    UserListError,
+    UserReplaceError,
+    UserUpdateError,
+)
 from arangoasync.typings import UserInfo
-from tests.helpers import generate_string, generate_username
+from tests.helpers import generate_col_name, generate_string, generate_username
 
 
 @pytest.mark.asyncio
@@ -44,6 +57,10 @@ async def test_user_management(sys_db, db, bad_db):
     assert user.user == username
     assert user.active is True
 
+    # Get non-existing user
+    with pytest.raises(UserGetError):
+        await sys_db.user(generate_username())
+
     # Create already existing user
     with pytest.raises(UserCreateError):
         await sys_db.create_user(
@@ -55,6 +72,48 @@ async def test_user_management(sys_db, db, bad_db):
             )
         )
 
+    # Update existing user
+    new_user = await sys_db.update_user(
+        UserInfo(
+            user=username,
+            password=password,
+            active=False,
+            extra={"bar": "baz"},
+        )
+    )
+    assert new_user["user"] == username
+    assert new_user["active"] is False
+    assert new_user["extra"] == {"foo": "bar", "bar": "baz"}
+    assert await sys_db.user(username) == new_user
+
+    # Update missing user
+    with pytest.raises(UserUpdateError) as err:
+        await sys_db.update_user(
+            UserInfo(user=generate_username(), password=generate_string())
+        )
+    assert err.value.error_code == USER_NOT_FOUND
+
+    # Replace existing user
+    new_user = await sys_db.replace_user(
+        UserInfo(
+            user=username,
+            password=password,
+            active=True,
+            extra={"baz": "qux"},
+        )
+    )
+    assert new_user["user"] == username
+    assert new_user["active"] is True
+    assert new_user["extra"] == {"baz": "qux"}
+    assert await sys_db.user(username) == new_user
+
+    # Replace missing user
+    with pytest.raises(UserReplaceError) as err:
+        await sys_db.replace_user(
+            {"user": generate_username(), "password": generate_string()}
+        )
+    assert err.value.error_code == USER_NOT_FOUND
+
     # Delete the newly created user
     assert await sys_db.delete_user(username) is True
     users = await sys_db.users()
@@ -73,3 +132,60 @@ async def test_user_management(sys_db, db, bad_db):
         await bad_db.users()
     with pytest.raises(UserListError):
         await bad_db.has_user(username)
+
+
+@pytest.mark.asyncio
+async def test_user_change_permissions(sys_db, arango_client, db):
+    username = generate_username()
+    password = generate_string()
+    auth = Auth(username, password)
+
+    # Set read-only permissions
+    await sys_db.create_user(UserInfo(username, password))
+
+    # Should not be able to update permissions without permission
+    with pytest.raises(PermissionUpdateError):
+        await db.update_permission(username, "ro", db.name)
+
+    await sys_db.update_permission(username, "ro", db.name)
+
+    # Verify read-only permissions
+    permission = await sys_db.permission(username, db.name)
+    assert permission == "ro"
+
+    # Should not be able to create a collection
+    col_name = generate_col_name()
+    db2 = await arango_client.db(db.name, auth=auth, verify=True)
+    with pytest.raises(CollectionCreateError):
+        await db2.create_collection(col_name)
+
+    all_permissions = await sys_db.permissions(username)
+    assert "_system" in all_permissions
+    assert db.name in all_permissions
+    all_permissions = await sys_db.permissions(username, full=False)
+    assert all_permissions[db.name] == "ro"
+
+    # Set read-write permissions
+    await sys_db.update_permission(username, "rw", db.name)
+
+    # Should be able to create collection
+    col = await db2.create_collection(col_name)
+    await col.insert({"_key": "test"})
+
+    # Reset permissions
+    with pytest.raises(PermissionResetError):
+        await db.reset_permission(username, db.name)
+    await sys_db.reset_permission(username, db.name)
+    with pytest.raises(DocumentInsertError):
+        await col.insert({"_key": "test"})
+
+    # Allow rw access
+    await sys_db.update_permission(username, "rw", db.name)
+    await col.insert({"_key": "test2"})
+
+    # No access to collection
+    await sys_db.update_permission(username, "none", db.name, col_name)
+    with pytest.raises(DocumentInsertError):
+        await col.insert({"_key": "test"})
+
+    await db.delete_collection(col_name)