Added checkpoint API, examples and tests

Author: Rasmus Oscar Welander

examples/checkpoints_api_example.py

@@ -0,0 +1,41 @@
+"""
+checkpoints_api_example.py
+
+Example script to demonstrate the usage of the checkpoint API in the CS3Client class.
+note that these are examples, and is not meant to be run as a script.
+
+Authors: Rasmus Welander, Diogo Castro, Giuseppe Lo Presti.
+Emails: [email protected], [email protected], [email protected]
+Last updated: 19/08/2024
+"""
+
+import logging
+import configparser
+from cs3client import CS3Client
+from cs3resource import Resource
+
+config = configparser.ConfigParser()
+with open("default.conf") as fdef:
+    config.read_file(fdef)
+# log
+log = logging.getLogger(__name__)
+
+client = CS3Client(config, "cs3client", log)
+# client.auth.set_token("<your_token_here>")
+# OR
+client.auth.set_client_secret("<your_client_secret_here>")
+
+res = None
+
+markdown_resource = Resource.from_file_ref_and_endpoint("/eos/user/r/rwelande/test.md")
+
+res = client.checkpoint.list_file_versions(markdown_resource)
+
+if res is not None:
+    for ver in res:
+        print(ver)
+
+res = client.checkpoint.restore_file_version(markdown_resource, "1722936250.0569fa2f")
+if res is not None:
+    for ver in res:
+        print(ver)

src/checkpoint.py

@@ -0,0 +1,85 @@
+"""
+checkpoint.py
+
+Authors: Rasmus Welander, Diogo Castro, Giuseppe Lo Presti.
+Emails: [email protected], [email protected], [email protected]
+Last updated: 19/08/2024
+"""
+
+from typing import Generator
+import logging
+from auth import Auth
+import cs3.storage.provider.v1beta1.resources_pb2 as cs3spr
+import cs3.storage.provider.v1beta1.provider_api_pb2 as cs3spp
+from cs3.gateway.v1beta1.gateway_api_pb2_grpc import GatewayAPIStub
+from config import Config
+from statuscodehandler import StatusCodeHandler
+from cs3resource import Resource
+
+
+class Checkpoint:
+    """
+    Checkpoint class to handle checkpoint related API calls with CS3 Gateway API.
+    """
+
+    def __init__(
+        self,
+        config: Config,
+        log: logging.Logger,
+        gateway: GatewayAPIStub,
+        auth: Auth,
+        status_code_handler: StatusCodeHandler,
+    ) -> None:
+        """
+        Initializes the checkpoint class with configuration, logger, auth, and gateway stub,
+
+        :param config: Config object containing the configuration parameters.
+        :param log: Logger instance for logging.
+        :param gateway: GatewayAPIStub instance for interacting with CS3 Gateway.
+        :param auth: An instance of the auth class.
+        :param status_code_handler: An instance of the StatusCodeHandler class.
+        """
+        self._gateway: GatewayAPIStub = gateway
+        self._log: logging.Logger = log
+        self._config: Config = config
+        self._auth: Auth = auth
+        self._status_code_handler: StatusCodeHandler = status_code_handler
+
+    def list_file_versions(
+        self, resource: Resource, page_token: str = "", page_size: int = 0
+    ) -> Generator[cs3spr.FileVersion, any, any]:
+        """
+        List all versions of a file.
+
+        :param resource: Resource object containing the resource information.
+        :param page_token: Token for pagination.
+        :param page_size: Number of file versions to return.
+                          (default is zero, where the server decides the number of versions to return)
+        :return: List of file versions (None if no versions are found).
+        :raises: AuthenticationException (Operation not permitted)
+        :raises: NotFoundException (File not found)
+        :raises: UnknownException (Unknown error)
+        """
+        req = cs3spp.ListFileVersionsRequest(ref=resource.ref, page_token=page_token, page_size=page_size)
+        res = self._gateway.ListFileVersions(request=req, metadata=[self._auth.get_token()])
+        self._status_code_handler.handle_errors(res.status, "list file versions", f"{resource.get_file_ref_str()}")
+        self._log.debug(f'msg="list file versions" {resource.get_file_ref_str()}  trace="{res.status.trace}"')
+        return res.versions
+
+    def restore_file_version(self, resource: Resource, version_key: str, lock_id: str = None) -> None:
+        """
+        Restore a file to a previous version.
+
+        :param resource: Resource object containing the resource information.
+        :param version_key: Key of the version to restore.
+        :param lock_id: Lock ID of the file (OPTIONAL).
+        :return: None (Success)
+        :raises: AuthenticationException (Operation not permitted)
+        :raises: NotFoundException (File not found)
+        :raises: UnknownException (Unknown error)
+        """
+        req = cs3spp.RestoreFileVersionRequest(ref=resource.ref, key=version_key, lock_id=lock_id)
+        res = self._gateway.RestoreFileVersion(request=req, metadata=[self._auth.get_token()])
+        self._status_code_handler.handle_errors(res.status, "restore file version", f"{resource.get_file_ref_str()}")
+        self._log.debug(f'msg="restore file version" {resource.get_file_ref_str()}  trace="{res.status.trace}"')
+        return

tests/test_checkpoint.py

@@ -0,0 +1,92 @@
+"""
+test_checkpoint.py
+
+Tests that the App class methods work as expected.
+
+Authors: Rasmus Welander, Diogo Castro, Giuseppe Lo Presti.
+Emails: [email protected], [email protected], [email protected]
+Last updated: 19/08/2024
+"""
+
+from exceptions.exceptions import (
+    AuthenticationException,
+    NotFoundException,
+    UnknownException,
+)
+
+from cs3resource import Resource
+
+import cs3.rpc.v1beta1.code_pb2 as cs3code
+from fixtures import (  # noqa: F401 (they are used, the framework is not detecting it)
+    mock_config,
+    mock_logger,
+    mock_authentication,
+    mock_gateway,
+    checkpoint_instance,
+    mock_status_code_handler,
+)
+
+from unittest.mock import Mock, patch
+
+import pytest
+
+# Test cases for the Checkpoint class
+
+
+@pytest.mark.parametrize(
+    "status_code, status_message, expected_exception, versions",
+    [
+        (cs3code.CODE_OK, None, None, [Mock(), Mock()]),
+        (cs3code.CODE_UNAUTHENTICATED, "error", AuthenticationException, None),
+        (cs3code.CODE_NOT_FOUND, "error", NotFoundException, None),
+        (-2, "error", UnknownException, None),
+    ],
+)
+def test_list_file_versions(
+    checkpoint_instance, status_code, status_message, expected_exception, versions  # noqa: F811 (not a redefinition)
+):
+    resource = Resource.from_file_ref_and_endpoint(endpoint="", file="testfile")
+    page_token = "page_token"
+    page_size = 10
+
+    mock_response = Mock()
+    mock_response.status.code = status_code
+    mock_response.status.message = status_message
+    mock_response.versions = versions
+
+    with patch.object(checkpoint_instance._gateway, "ListFileVersions", return_value=mock_response):
+        if expected_exception:
+            with pytest.raises(expected_exception):
+                checkpoint_instance.list_file_versions(resource, page_token, page_size)
+        else:
+            result = checkpoint_instance.list_file_versions(resource, page_token, page_size)
+            assert result == versions
+
+
+@pytest.mark.parametrize(
+    "status_code, status_message, expected_exception",
+    [
+        (cs3code.CODE_OK, None, None),
+        (cs3code.CODE_UNAUTHENTICATED, "error", AuthenticationException),
+        (cs3code.CODE_NOT_FOUND, "error", NotFoundException),
+        (-2, "error", UnknownException),
+    ],
+)
+def test_restore_file_version(
+    checkpoint_instance, status_code, status_message, expected_exception  # noqa: F811 (not a redefinition)
+):
+    resource = Resource.from_file_ref_and_endpoint(endpoint="", file="testfile")
+    version_key = "version_key"
+    lock_id = "lock_id"
+
+    mock_response = Mock()
+    mock_response.status.code = status_code
+    mock_response.status.message = status_message
+
+    with patch.object(checkpoint_instance._gateway, "RestoreFileVersion", return_value=mock_response):
+        if expected_exception:
+            with pytest.raises(expected_exception):
+                checkpoint_instance.restore_file_version(resource, version_key, lock_id)
+        else:
+            result = checkpoint_instance.restore_file_version(resource, version_key, lock_id)
+            assert result is None