cs3client 0.0.1__py3-none-any.whl

cs3client/app.py

@@ -0,0 +1,84 @@
+"""
+app.py
+
+Authors: Rasmus Welander, Diogo Castro, Giuseppe Lo Presti.
+Emails: rasmus.oscar.welander@cern.ch, diogo.castro@cern.ch, giuseppe.lopresti@cern.ch
+Last updated: 30/08/2024
+"""
+
+import logging
+import cs3.app.registry.v1beta1.registry_api_pb2 as cs3arreg
+import cs3.app.registry.v1beta1.resources_pb2 as cs3arres
+import cs3.gateway.v1beta1.gateway_api_pb2 as cs3gw
+import cs3.app.provider.v1beta1.resources_pb2 as cs3apr
+from cs3.gateway.v1beta1.gateway_api_pb2_grpc import GatewayAPIStub
+
+from .cs3resource import Resource
+from .statuscodehandler import StatusCodeHandler
+from .config import Config
+
+
+class App:
+    """
+    App class to handle app related API calls with CS3 Gateway API.
+    """
+
+    def __init__(
+        self,
+        config: Config,
+        log: logging.Logger,
+        gateway: GatewayAPIStub,
+        status_code_handler: StatusCodeHandler,
+    ) -> None:
+        """
+        Initializes the App 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 status_code_handler: An instance of the StatusCodeHandler class.
+        """
+        self._status_code_handler: StatusCodeHandler = status_code_handler
+        self._gateway: GatewayAPIStub = gateway
+        self._log: logging.Logger = log
+        self._config: Config = config
+
+    def open_in_app(
+            self, auth_token: tuple, resource: Resource, view_mode: str = None, app: str = None
+    ) -> cs3apr.OpenInAppURL:
+        """
+        Open a file in an app, given the resource, view mode (VIEW_MODE_VIEW_ONLY, VIEW_MODE_READ_ONLY,
+        VIEW_MODE_READ_WRITE, VIEW_MODE_PREVIEW), and app name.
+
+        :param auth_token: tuple in the form ('x-access-token', <token>) (see auth.get_token/auth.check_token)
+        :param resource: Resource object containing the resource information.
+        :param view_mode: View mode of the app.
+        :param app: App name.
+        :return: URL to open the file in the app.
+        :raises: AuthenticationException (Operation not permitted)
+        :raises: NotFoundException (Resource not found)
+        :raises: UnknownException (Unknown error)
+        """
+        view_mode_type = None
+        if view_mode:
+            view_mode_type = cs3gw.OpenInAppRequest.ViewMode.Value(view_mode)
+        req = cs3gw.OpenInAppRequest(ref=resource.ref, view_mode=view_mode_type, app=app)
+        res = self._gateway.OpenInApp(request=req, metadata=[auth_token])
+        self._status_code_handler.handle_errors(res.status, "open in app", f"{resource.get_file_ref_str()}")
+        self._log.debug(f'msg="Invoked OpenInApp" {resource.get_file_ref_str()} trace="{res.status.trace}"')
+        return res.OpenInAppURL
+
+    def list_app_providers(self, auth_token: dict) -> list[cs3arres.ProviderInfo]:
+        """
+        list_app_providers lists all the app providers.
+
+        :param auth_token: tuple in the form ('x-access-token', <token>) (see auth.get_token/auth.check_token)
+        :return: List of app providers.
+        :raises: AuthenticationException (Operation not permitted)
+        :raises: UnknownException (Unknown error)
+        """
+        req = cs3arreg.ListAppProvidersRequest()
+        res = self._gateway.ListAppProviders(request=req, metadata=[auth_token])
+        self._status_code_handler.handle_errors(res.status, "list app providers")
+        self._log.debug(f'msg="Invoked ListAppProviders" res_count="{len(res.providers)}" trace="{res.status.trace}"')
+        return res.providers

cs3client/auth.py

@@ -0,0 +1,141 @@
+"""
+auth.py
+
+Authors: Rasmus Welander, Diogo Castro, Giuseppe Lo Presti.
+Emails: rasmus.oscar.welander@cern.ch, diogo.castro@cern.ch, giuseppe.lopresti@cern.ch
+Last updated: 30/08/2024
+"""
+
+import grpc
+import jwt
+import datetime
+import logging
+from typing import Union
+from cs3.gateway.v1beta1.gateway_api_pb2 import AuthenticateRequest
+from cs3.auth.registry.v1beta1.registry_api_pb2 import ListAuthProvidersRequest
+from cs3.gateway.v1beta1.gateway_api_pb2_grpc import GatewayAPIStub
+from cs3.rpc.v1beta1.code_pb2 import CODE_OK
+
+from .cs3client import CS3Client
+from .exceptions.exceptions import AuthenticationException, SecretNotSetException
+from .config import Config
+
+
+class Auth:
+    """
+    Auth class to handle authentication and token validation with CS3 Gateway API.
+    """
+
+    def __init__(self, cs3_client: CS3Client) -> None:
+        """
+        Initializes the Auth class with configuration, logger, and gateway stub,
+        NOTE that token OR the client secret has to be set when instantiating the auth object.
+
+        :param config: Config object containing the configuration parameters.
+        :param log: Logger instance for logging.
+        :param gateway: GatewayAPIStub instance for interacting with CS3 Gateway.
+        """
+        self._gateway: GatewayAPIStub = cs3_client._gateway
+        self._log: logging.Logger = cs3_client._log
+        self._config: Config = cs3_client._config
+        # The user should be able to change the client secret (e.g. token) and client id at runtime
+        self._client_secret: Union[str, None] = self._config.auth_client_secret
+        self._client_id: Union[str, None] = self._config.auth_client_id
+        self._token: Union[str, None] = None
+
+    def set_client_secret(self, token: str) -> None:
+        """
+        Sets the client secret, exists so that the user can change the client secret (e.g. token, password) at runtime,
+        without having to create a new Auth object. Note client secret has to be set when
+        instantiating the client object or through the configuration.
+
+        :param token: Auth token/password.
+        """
+        self._client_secret = token
+
+    def set_client_id(self, id: str) -> None:
+        """
+        Sets the client id, exists so that the user can change the client id at runtime, without having to create
+        a new Auth object. Settings this (either through config or here) is optional unless you are using
+        basic authentication.
+
+        :param token: id.
+        """
+        self._client_id = id
+
+    def get_token(self) -> tuple[str, str]:
+        """
+        Attempts to get a valid authentication token. If the token is not valid, a new token is requested
+        if the client secret is set, if only the token is set then an exception will be thrown stating that
+        the credentials have expired.
+
+        :return tuple: A tuple containing the header key and the token.
+        :raises: AuthenticationException (token expired, or failed to authenticate)
+        :raises: SecretNotSetException (neither token or client secret was set)
+        """
+
+        if not self._client_secret:
+            self._log.error("Attempted to authenticate, client secret was not set")
+            raise SecretNotSetException("The client secret (e.g. token, passowrd) is not set")
+
+        try:
+            self.check_token(self._token)
+        except AuthenticationException:
+            # Token has expired or has not been set, obtain another one.
+            req = AuthenticateRequest(
+                type=self._config.auth_login_type,
+                client_id=self._client_id,
+                client_secret=self._client_secret,
+            )
+            # Send the authentication request to the CS3 Gateway
+            res = self._gateway.Authenticate(req)
+
+            if res.status.code != CODE_OK:
+                self._log.error(f'msg="Failed to authenticate" '
+                                f'user="{self._client_id if self._client_id else "no_id_set"}" '
+                                f'error_code="{res.status}"')
+                raise AuthenticationException(
+                    f'Failed to authenticate: user="{self._client_id if self._client_id else "no_id_set"}" '
+                    f'error_code="{res.status}"'
+                )
+            self._token = res.token
+        self._log.debug(f'msg="Authenticated user" user="{self._client_id if self._client_id else "no_id_set"}"')
+        return ("x-access-token", self._token)
+
+    def list_auth_providers(self) -> list[str]:
+        """
+        list authentication providers
+
+        :return: a list of the supported authentication types
+        :raises: ConnectionError (Could not connect to host)
+        """
+        try:
+            res = self._gateway.ListAuthProviders(request=ListAuthProvidersRequest())
+            if res.status.code != CODE_OK:
+                self._log.error(f'msg="List auth providers request failed" error_code="{res.status}"')
+                raise Exception(res.status.message)
+        except grpc.RpcError as e:
+            self._log.error("List auth providers request failed")
+            raise ConnectionError(e)
+        return res.types
+
+    @classmethod
+    def check_token(cls, token: str) -> tuple:
+        """
+        Checks if the given token is set and valid.
+
+        :param token: JWT token as a string.
+        :return tuple: A tuple containing the header key and the token.
+        :raises: ValueError (Token missing)
+        :raises: AuthenticationException (Token is expired)
+        """
+        if not token:
+            raise AuthenticationException("Token not set")
+        # Decode the token without verifying the signature
+        decoded_token = jwt.decode(jwt=token, algorithms=["HS256"], options={"verify_signature": False})
+        now = datetime.datetime.now().timestamp()
+        token_expiration = decoded_token.get("exp")
+        if token_expiration and now > token_expiration:
+            raise AuthenticationException("Token has expired")
+
+        return ("x-access-token", token)

cs3client/checkpoint.py

@@ -0,0 +1,86 @@
+"""
+checkpoint.py
+
+Authors: Rasmus Welander, Diogo Castro, Giuseppe Lo Presti.
+Emails: rasmus.oscar.welander@cern.ch, diogo.castro@cern.ch, giuseppe.lopresti@cern.ch
+Last updated: 30/08/2024
+"""
+
+from typing import Generator
+import logging
+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,
+        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 status_code_handler: An instance of the StatusCodeHandler class.
+        """
+        self._gateway: GatewayAPIStub = gateway
+        self._log: logging.Logger = log
+        self._config: Config = config
+        self._status_code_handler: StatusCodeHandler = status_code_handler
+
+    def list_file_versions(
+        self, auth_token: tuple, resource: Resource, page_token: str = "", page_size: int = 0
+    ) -> Generator[cs3spr.FileVersion, any, any]:
+        """
+        List all versions of a file.
+
+        :param auth_token: tuple in the form ('x-access-token', <token>) (see auth.get_token/auth.check_token)
+        :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=[auth_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, auth_token: tuple, resource: Resource, version_key: str, lock_id: str = None
+    ) -> None:
+        """
+        Restore a file to a previous version.
+
+        :param auth_token: tuple in the form ('x-access-token', <token>) (see auth.get_token/auth.check_token)
+        :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=[auth_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

cs3client/config.py

@@ -0,0 +1,198 @@
+"""
+config.py
+
+Authors: Rasmus Welander, Diogo Castro, Giuseppe Lo Presti.
+Emails: rasmus.oscar.welander@cern.ch, diogo.castro@cern.ch, giuseppe.lopresti@cern.ch
+Last updated: 29/07/2024
+"""
+
+from configparser import ConfigParser
+
+
+class Config:
+    """
+    A class to read and store the configuration parameters provided to the CS3 client.
+    """
+
+    def __init__(self, config: ConfigParser, config_category: str) -> None:
+        """
+        Initializes the Config class with the configuration parameters.
+
+        :param config: Dictionary containing configuration parameters.
+        :param config_category: The category of the configuration parameters.
+        """
+        self._config_category: str = config_category
+        self._config: ConfigParser = config
+
+    @property
+    def host(self) -> str:
+        """
+        The host property returns the host address and port from the configuration.
+
+        :return: host address:port
+        """
+        return self._config.get(self._config_category, "host")
+
+    @property
+    def chunk_size(self) -> int:
+        """
+        The chunk_size property returns the chunk_size value from the configuration,
+        fallback to 4194304 if not present.
+
+        :return: The chunk size value.
+        """
+        return self._config.getint(self._config_category, "chunk_size", fallback=4194304)
+
+    @property
+    def grpc_timeout(self) -> int:
+        """
+        The grpc_timeout property returns the grpc_timeout value from the configuration,
+        fallback to 10 if not present.
+
+        :return: The grpc timeout value.
+        """
+        return self._config.getint(self._config_category, "grpc_timeout", fallback=10)
+
+    @property
+    def http_timeout(self) -> int:
+        """
+        The http_timeout property returns the http_timeout value from the configuration,
+        fallback to 10 if not present.
+
+        :return: The http timeout value.
+        """
+        return self._config.getint(self._config_category, "http_timeout", fallback=10)
+
+    @property
+    def ssl_enabled(self) -> bool:
+        """
+        The ssl_enabled property returns the ssl_enabled value from the configuration,
+        fallback to True if not present.
+
+        :return: ssl_enabled value.
+        """
+        return self._config.getboolean(self._config_category, "ssl_enabled", fallback=False)
+
+    @property
+    def ssl_verify(self) -> bool:
+        """
+        The ssl_verify property returns the ssl_verify value from the configuration,
+
+        :return: ssl_verify
+        """
+        return self._config.getboolean(self._config_category, "ssl_verify", fallback=False)
+
+    @property
+    def ssl_client_cert(self) -> str:
+        """
+        The ssl_client_cert property returns the ssl_client_cert value from the configuration,
+        if not present, fallback to an empty string since it is not required if ssl is not enabled.
+
+        :return: ssl_client_cert
+        """
+        return self._config.get(self._config_category, "ssl_client_cert", fallback=None)
+
+    @property
+    def ssl_client_key(self) -> str:
+        """
+        The ssl_client_key property returns the ssl_client_key value from the configuration,
+        if not present, fallback to an empty string since it is not required if ssl is not enabled.
+
+        :return: ssl_client_key
+        """
+        return self._config.get(self._config_category, "ssl_client_key", fallback=None)
+
+    @property
+    def ssl_ca_cert(self) -> str:
+        """
+        The ssl_ca_cert property returns the ssl_ca_cert value from the configuration,
+        if not present, fallback to an empty string since it is not required if ssl is not enabled.
+
+        :return: ssl_ca_cert
+        """
+        return self._config.get(self._config_category, "ssl_ca_cert", fallback=None)
+
+    @property
+    def auth_login_type(self) -> str:
+        """
+        The auth_login_type property returns the auth_login_type value from the configuration.
+        e.g. basic, bearer, oauth, machine.
+
+        :return: auth_login_type
+        """
+        return self._config.get(self._config_category, "auth_login_type", fallback="basic")
+
+    @property
+    def auth_client_id(self) -> str:
+        """
+        The auth_client_id property returns the auth_client_id value from the configuration,
+
+        :return: auth_client_id
+        """
+        return self._config.get(self._config_category, "auth_client_id", fallback=None)
+
+    @property
+    def auth_client_secret(self) -> str:
+        """
+        The auth_client_secret property returns the auth_client_secret value from the configuration,
+
+        :return: auth_client_secret
+        """
+        return self._config.get(self._config_category, "auth_client_secret", fallback=None)
+
+    @property
+    def tus_enabled(self) -> bool:
+        """
+        The tus_enabled property returns the tus_enabled value from the configuration,
+
+        :return: tus_enabled
+        """
+        return self._config.getboolean(self._config_category, "tus_enabled", fallback=False)
+
+    # For the lock implementation
+    @property
+    def lock_by_setting_attr(self) -> bool:
+        """
+        The lock_by_setting_attr property returns the lock_by_setting_attr value from the configuration,
+        fallback to False if not present.
+
+        The lock by setting attribute setting should be set if the storage provider does not
+        implement locking functionality. In which case the client will use the fallback mechanism
+        by locking resources by setting metadata attributes. If lock_not_impl is set to false and
+        lock_by_setting_attr is set to true, the client will attempt to lock normally first,
+        and if that fails, it will attempt to lock by setting metadata attributes.
+
+
+        :return: lock_by_setting_attr
+        """
+        return self._config.getboolean(self._config_category, "lock_by_setting_attr", fallback=False)
+
+    # For the lock implementation
+    @property
+    def lock_not_impl(self) -> bool:
+        """
+        The lock_not_impl property returns the lock_not_impl value from the configuration,
+        fallback to False if not present.
+
+        The lock not implemented setting should be set if the storage provider
+        does not implement locking functionality. In which case the client will use the
+        fallback mechanism by locking resources by setting metadata attributes if the
+        lock_by_setting_attr is set to True.
+
+        :return: lock_not_impl
+        """
+        return self._config.getboolean(self._config_category, "lock_not_impl", fallback=False)
+
+    # For the lock implementation
+    @property
+    def lock_expiration(self) -> int:
+        """
+        The lock_expiration property returns the lock_expiration value from the configuration,
+        fallback to 1800 if not present.
+
+        The lock expiration setting is used to determine the time
+        in seconds before a lock is considered expired.
+
+        :return: lock_expiration
+        """
+        return self._config.getint(self._config_category, "lock_expiration", fallback=1800)

cs3client/cs3client.py

@@ -0,0 +1,73 @@
+"""
+cs3client.py
+
+Authors: Rasmus Welander, Diogo Castro, Giuseppe Lo Presti.
+Emails: rasmus.oscar.welander@cern.ch, diogo.castro@cern.ch, giuseppe.lopresti@cern.ch
+Last updated: 30/08/2024
+"""
+
+import grpc
+import logging
+import cs3.gateway.v1beta1.gateway_api_pb2_grpc as cs3gw_grpc
+from configparser import ConfigParser
+
+from .file import File
+from .user import User
+from .share import Share
+from .statuscodehandler import StatusCodeHandler
+from .app import App
+from .checkpoint import Checkpoint
+from .config import Config
+
+
+class CS3Client:
+    """
+    Client class to interact with the CS3 API.
+    """
+
+    def __init__(self, config: ConfigParser, config_category: str, log: logging.Logger) -> None:
+        """
+        Initializes the CS3Client class with configuration and logger.
+        :param config: Dictionary containing configuration parameters.
+        :param config_category: Category of the configuration parameters.
+        :param log: Logger instance for logging.
+        """
+
+        self._config: Config = Config(config, config_category)
+        self._log: logging.Logger = log
+
+        try:
+            self.channel: grpc.Channel = self._create_channel()
+            grpc.channel_ready_future(self.channel).result(timeout=self._config.grpc_timeout)
+        except grpc.FutureTimeoutError as e:
+            log.error(f'msg="Failed to connect to Reva via GRPC" error="{e}"')
+            raise TimeoutError("Failed to connect to Reva via GRPC")
+
+        self._gateway: cs3gw_grpc.GatewayAPIStub = cs3gw_grpc.GatewayAPIStub(self.channel)
+        self._status_code_handler: StatusCodeHandler = StatusCodeHandler(self._log, self._config)
+        self.file: File = File(self._config, self._log, self._gateway, self._status_code_handler)
+        self.user: User = User(self._config, self._log, self._gateway, self._status_code_handler)
+        self.app: App = App(self._config, self._log, self._gateway, self._status_code_handler)
+        self.checkpoint: Checkpoint = Checkpoint(
+            self._config, self._log, self._gateway, self._status_code_handler
+        )
+        self.share = Share(self._config, self._log, self._gateway, self._status_code_handler)
+
+    def _create_channel(self) -> grpc.Channel:
+        """
+        create_channel creates a gRPC channel to the specified host.
+
+        :return: gRPC channel to the specified host.
+        """
+
+        if self._config.ssl_enabled:
+
+            credentials = grpc.ssl_channel_credentials(
+                root_certificates=self._config.ssl_ca_cert,
+                private_key=self._config.ssl_client_key,
+                certificate_chain=self._config.ssl_client_cert,
+            )
+            channel = grpc.secure_channel(self._config.host, credentials)
+        else:
+            channel = grpc.insecure_channel(self._config.host)
+        return channel