switcher-client 0.1.2__py3-none-any.whl

switcher_client/__init__.py

@@ -0,0 +1,11 @@
+from switcher_client.client import Client
+from switcher_client.switcher import Switcher
+from switcher_client.lib.globals.global_context import ContextOptions
+from switcher_client.lib.snapshot_watcher import WatchSnapshotCallback
+
+__all__ = [
+    'Client',
+    'Switcher',
+    'ContextOptions',
+    'WatchSnapshotCallback',
+]

switcher_client/client.py

@@ -0,0 +1,262 @@
+from typing import Optional, Callable
+
+from switcher_client.lib.globals.global_auth import GlobalAuth
+from switcher_client.lib.globals.global_snapshot import GlobalSnapshot, LoadSnapshotOptions
+from switcher_client.lib.globals.global_context import Context, ContextOptions, DEFAULT_ENVIRONMENT
+from switcher_client.lib.remote_auth import RemoteAuth
+from switcher_client.lib.remote import Remote
+from switcher_client.lib.snapshot_auto_updater import SnapshotAutoUpdater
+from switcher_client.lib.snapshot_loader import check_switchers, load_domain, validate_snapshot, save_snapshot
+from switcher_client.lib.snapshot_watcher import SnapshotWatcher, WatchSnapshotCallback
+from switcher_client.lib.utils.execution_logger import ExecutionLogger
+from switcher_client.lib.utils.timed_match.timed_match import TimedMatch
+from switcher_client.lib.utils import get
+from switcher_client.errors import SnapshotNotFoundError
+from switcher_client.switcher import Switcher
+
+REGEX_MAX_BLACK_LIST = 'regex_max_black_list'
+REGEX_MAX_TIME_LIMIT = 'regex_max_time_limit'
+SNAPSHOT_AUTO_UPDATE_INTERVAL = 'snapshot_auto_update_interval'
+SILENT_MODE = 'silent_mode'
+
+class Client:
+    """
+    Quick start with the following steps:
+
+    1. Use `Client.build_context()` to build the context for the client.
+    2. Use `Client.get_switcher()` to create a new instance of Switcher.
+    3. Use the instance created to evaluate criteria.
+
+        Example:
+            Client.build_context(
+                domain='My Domain',                 # Your Switcher domain name
+                url='https://api.switcherapi.com',  # Switcher-API endpoint (optional)
+                api_key='[YOUR_API_KEY]',           # Your component's API key (optional)
+                component='MyApp',                  # Your application name (optional)
+                environment='default'               # Environment ('default' for production)
+            )
+
+            switcher = Client.get_switcher()
+            result = switcher.is_on('my_criteria')
+    """
+    _context: Context = Context.empty()
+    _switcher: dict[str, Switcher] = {}
+    _snapshot_auto_updater: SnapshotAutoUpdater = SnapshotAutoUpdater()
+    _snapshot_watcher: SnapshotWatcher = SnapshotWatcher()
+
+    # pylint: disable=too-many-arguments
+    @staticmethod
+    def build_context(*,
+        domain: str,
+        url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        component: Optional[str] = None,
+        environment: Optional[str] = DEFAULT_ENVIRONMENT,
+        options = ContextOptions()):
+        """
+        Build the context for the client
+
+        :param domain: Domain name
+        :param url:Switcher-API URL
+        :param api_key: Switcher-API key generated for the application/component
+        :param component: Application/component name
+        :param environment: Environment name
+        :param options: Optional parameters
+
+        """
+        Client._context = Context(
+            domain=domain, url=url,
+            api_key=api_key,
+            component=component,
+            environment=environment,
+            options=options)
+
+        # Default values
+        GlobalSnapshot.clear()
+
+        # Build Options
+        if options is not None:
+            Client._build_options(options)
+
+        # Initialize Auth
+        RemoteAuth.init(Client._context)
+
+    @staticmethod
+    def _build_options(options: ContextOptions):
+        options_handler = {
+            SNAPSHOT_AUTO_UPDATE_INTERVAL: Client.schedule_snapshot_auto_update,
+            SILENT_MODE: lambda: Client._init_silent_mode(get(options.silent_mode, '')),
+            REGEX_MAX_BLACK_LIST: lambda: TimedMatch.set_max_blacklisted(options.regex_max_black_list),
+            REGEX_MAX_TIME_LIMIT: lambda: TimedMatch.set_max_time_limit(options.regex_max_time_limit)
+        }
+
+        for option_key, handler in options_handler.items():
+            if hasattr(options, option_key) and getattr(options, option_key) is not None:
+                handler()
+
+    @staticmethod
+    def _init_silent_mode(silent_mode: str):
+        if silent_mode != '':
+            RemoteAuth.set_retry_options(silent_mode)
+            Client._context.options.silent_mode = silent_mode
+            Client.load_snapshot()
+
+    @staticmethod
+    def get_switcher(key: Optional[str] = None) -> Switcher:
+        """
+        Creates a new instance of Switcher.
+        Provide a key if you want to persist the instance.
+        """
+        key_value = get(key, '')
+        persisted_switcher = Client._switcher.get(key_value)
+
+        if persisted_switcher is not None:
+            return persisted_switcher
+
+        switcher = Switcher(Client._context, key_value) \
+            .restrict_relay(Client._context.options.restrict_relay)
+
+        if key_value != '':
+            Client._switcher[key_value] = switcher
+
+        return switcher
+
+
+    @staticmethod
+    def load_snapshot(options: Optional[LoadSnapshotOptions] = None) -> int:
+        """ Load Domain from snapshot """
+        snapshot_options = get(options, LoadSnapshotOptions())
+
+        GlobalSnapshot.init(load_domain(
+            get(Client._context.options.snapshot_location, ''),
+            get(Client._context.environment, DEFAULT_ENVIRONMENT)
+        ))
+
+        if Client._is_check_snapshot_available(snapshot_options.fetch_remote):
+            Client.check_snapshot()
+
+        return Client.snapshot_version()
+
+    @staticmethod
+    def check_snapshot():
+        """ Verifies if the current snapshot file is updated
+            Return true if an update has been made
+        """
+
+        if RemoteAuth.is_token_expired():
+            RemoteAuth.auth()
+
+        snapshot = validate_snapshot(
+            context=Client._context,
+            snapshot_version=Client.snapshot_version(),
+        )
+
+        if snapshot is not None:
+            if Client._context.options.snapshot_location is not None:
+                save_snapshot(
+                    snapshot=snapshot,
+                    snapshot_location=get(Client._context.options.snapshot_location, ''),
+                    environment=get(Client._context.environment, DEFAULT_ENVIRONMENT)
+                )
+
+            GlobalSnapshot.init(snapshot)
+            return True
+
+        return False
+
+    @staticmethod
+    def schedule_snapshot_auto_update(interval: Optional[int] = None,
+                                      callback: Optional[Callable[[Optional[Exception], bool], None]] = None):
+        """ Schedule Snapshot auto update """
+        callback = get(callback, lambda *_: None)
+
+        if interval is not None:
+            Client._context.options.snapshot_auto_update_interval = interval
+
+        if Client._context.options.snapshot_auto_update_interval is not None and \
+            Client._context.options.snapshot_auto_update_interval > 0:
+            Client._snapshot_auto_updater.schedule(
+                interval=Client._context.options.snapshot_auto_update_interval,
+                check_snapshot=Client.check_snapshot,
+                callback=callback
+            )
+
+    @staticmethod
+    def terminate_snapshot_auto_update():
+        """ Terminate Snapshot auto update """
+        Client._snapshot_auto_updater.terminate()
+
+    @staticmethod
+    def watch_snapshot(callback: Optional[WatchSnapshotCallback] = None) -> None:
+        """ Watch snapshot file for changes and invoke callbacks on result """
+        callback = get(callback, WatchSnapshotCallback())
+        snapshot_location = Client._context.options.snapshot_location
+
+        if snapshot_location is None:
+            callback.reject(SnapshotNotFoundError("Snapshot location is not defined in the context options"))
+            return
+
+        environment = get(Client._context.environment, DEFAULT_ENVIRONMENT)
+        Client._snapshot_watcher.watch_snapshot(snapshot_location, environment, callback)
+
+    @staticmethod
+    def unwatch_snapshot() -> None:
+        """ Stop watching the snapshot file """
+        Client._snapshot_watcher.unwatch_snapshot()
+
+    @staticmethod
+    def snapshot_version() -> int:
+        """ Get the version of the snapshot """
+        snapshot = GlobalSnapshot.snapshot()
+
+        if snapshot is None:
+            return 0
+
+        return snapshot.domain.version
+
+    @staticmethod
+    def check_switchers(switcher_keys: list[str]) -> None:
+        """ Verifies if switchers are properly configured """
+        if Client._context.options.local:
+            check_switchers(GlobalSnapshot.snapshot(), switcher_keys)
+        else:
+            Client._check_switchers_remote(switcher_keys)
+
+    @staticmethod
+    def get_execution(switcher: Switcher) -> ExecutionLogger:
+        """Retrieve execution log given a switcher"""
+        return ExecutionLogger.get_execution(switcher.key, switcher.inputs)
+
+    @staticmethod
+    def clear_logger() -> None:
+        """Clear all logged executions"""
+        ExecutionLogger.clear_logger()
+
+    @staticmethod
+    def clear_resources() -> None:
+        """ Clear all resources used by the Client """
+        Client.terminate_snapshot_auto_update()
+        Client.unwatch_snapshot()
+        ExecutionLogger.clear_logger()
+        GlobalSnapshot.clear()
+        TimedMatch.terminate_worker()
+
+    @staticmethod
+    def subscribe_notify_error(callback: Callable[[Exception], None]) -> None:
+        """
+        Subscribe to notify when an asynchronous error is thrown.
+        It is usually used when throttle and silent mode are enabled.
+        """
+        ExecutionLogger.subscribe_notify_error(callback)
+
+    @staticmethod
+    def _is_check_snapshot_available(fetch_remote = False) -> bool:
+        return Client.snapshot_version() == 0 and (fetch_remote or not Client._context.options.local)
+
+    @staticmethod
+    def _check_switchers_remote(switcher_keys: list[str]) -> None:
+        RemoteAuth.auth()
+        Remote.check_switchers(
+            token=GlobalAuth.get_token(),
+            switcher_keys=switcher_keys,
+            context=Client._context)

switcher_client/errors/__init__.py

@@ -0,0 +1,44 @@
+class RemoteError(Exception):
+    """ Base class for remote errors """
+    def __init__(self, message):
+        self.message = message
+        super().__init__(self.message)
+
+class RemoteAuthError(RemoteError):
+    """ Raised when there is an authentication error with the remote service """
+
+class RemoteCriteriaError(RemoteError):
+    """ Raised when there is a criteria error with the remote service """
+
+class RemoteSwitcherError(RemoteError):
+    """ Raised when there is a switcher error with the remote service """
+    def __init__(self, not_found: list):
+        super().__init__(f'{", ".join(not_found)} not found')
+
+class LocalSwitcherError(Exception):
+    """ Raised when there is a switcher error with the local service """
+    def __init__(self, not_found: list):
+        self.message = f'{", ".join(not_found)} not found'
+        super().__init__(self.message)
+
+class LocalCriteriaError(Exception):
+    """ Raised when there is a criteria error with the local service """
+    def __init__(self, message):
+        self.message = message
+        super().__init__(self.message)
+
+class SnapshotNotFoundError(Exception):
+    """ Raised when a snapshot is not found """
+    def __init__(self, message):
+        self.message = message
+        super().__init__(self.message)
+
+__all__ = [
+    'RemoteError',
+    'RemoteAuthError',
+    'RemoteCriteriaError',
+    'RemoteSwitcherError',
+    'LocalSwitcherError',
+    'LocalCriteriaError',
+    'SnapshotNotFoundError'
+]

switcher_client/lib/__init__.py

@@ -0,0 +1,7 @@
+from .remote_auth import RemoteAuth
+from .types import ResultDetail
+
+__all__ = [
+    'RemoteAuth',
+    'ResultDetail',
+]

switcher_client/lib/compat.py

@@ -0,0 +1,8 @@
+import sys
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+__all__ = ['Self']

switcher_client/lib/globals/__init__.py

@@ -0,0 +1,10 @@
+from .global_auth import GlobalAuth
+from .global_context import Context, ContextOptions
+from .global_retry import RetryOptions
+
+__all__ = [
+    "GlobalAuth",
+    "Context",
+    "ContextOptions",
+    "RetryOptions",
+]

switcher_client/lib/globals/global_auth.py

@@ -0,0 +1,28 @@
+from dataclasses import dataclass
+
+@dataclass
+class GlobalAuth:
+    """ GlobalAuth manages the global authentication state, including the token and its expiration time. """
+    __token = None
+    __exp = None
+
+    @staticmethod
+    def init():
+        GlobalAuth.__token = None
+        GlobalAuth.__exp = None
+
+    @staticmethod
+    def get_token():
+        return GlobalAuth.__token
+
+    @staticmethod
+    def get_exp():
+        return GlobalAuth.__exp
+
+    @staticmethod
+    def set_token(token: str):
+        GlobalAuth.__token = token
+
+    @staticmethod
+    def set_exp(exp: str):
+        GlobalAuth.__exp = exp

switcher_client/lib/globals/global_context.py

@@ -0,0 +1,95 @@
+from dataclasses import dataclass
+from typing import Optional
+
+DEFAULT_ENVIRONMENT = 'default'
+DEFAULT_LOCAL = False
+DEFAULT_LOGGER = False
+DEFAULT_FREEZE = False
+DEFAULT_RESTRICT_RELAY = True
+DEFAULT_REGEX_MAX_BLACKLISTED = 100
+DEFAULT_REGEX_MAX_TIME_LIMIT = 3000
+
+@dataclass
+class ContextOptions:
+    """
+    :param local: When enabled it will use the local snapshot (file or in-memory).
+        If not set, it will use the remote API
+    :param logger: When enabled it allows inspecting the result details with
+        Client.get_execution(switcher). If not set, it will not log the result details
+    :param freeze: This option prevents the execution of background cache update when
+        using throttle. Use Client.clear_logger() to reset the in-memory cache if
+        snapshot are renewed
+    :param snapshot_location: The location of the snapshot file.
+        If not set, it will use the in-memory snapshot
+    :param snapshot_auto_update_interval: The interval in milliseconds to auto-update
+        the snapshot. If not set, it will not auto-update the snapshot
+    :param silent_mode: When defined it will switch to local during the specified time
+        before it switches back to remote, e.g. 5s (s: seconds - m: minutes - h: hours)
+    :param throttle_max_workers: The maximum number of workers to use for background
+        refresh when throttle is enabled. If None, the default value is based on the
+        number of CPUs. Default is None
+    :param regex_max_black_list: The maximum number of blacklisted regex inputs.
+        If not set, it will use the default value of 100
+    :param regex_max_time_limit: The maximum time limit in milliseconds for regex
+        matching. If not set, it will use the default value of 3000 ms
+    :param restrict_relay: When enabled it will restrict the use of relay when local
+        is enabled. Default is True
+    :param cert_path: The path to the SSL certificate file for secure connections.
+        If not set, it will use the default system certificates
+    """
+    # pylint: disable=too-many-arguments, too-many-instance-attributes
+    def __init__(self, *,
+                local: bool = DEFAULT_LOCAL,
+                logger: bool = DEFAULT_LOGGER,
+                freeze: bool = DEFAULT_FREEZE,
+                regex_max_black_list: int = DEFAULT_REGEX_MAX_BLACKLISTED,
+                regex_max_time_limit: int = DEFAULT_REGEX_MAX_TIME_LIMIT,
+                restrict_relay: bool = DEFAULT_RESTRICT_RELAY,
+                snapshot_location: Optional[str] = None,
+                snapshot_auto_update_interval: Optional[int] = None,
+                silent_mode: Optional[str] = None,
+                throttle_max_workers: Optional[int] = None,
+                cert_path: Optional[str] = None):
+        self.local = local
+        self.logger = logger
+        self.freeze = freeze
+        self.snapshot_location = snapshot_location
+        self.snapshot_auto_update_interval = snapshot_auto_update_interval
+        self.silent_mode = silent_mode
+        self.restrict_relay = restrict_relay
+        self.throttle_max_workers = throttle_max_workers
+        self.regex_max_black_list = regex_max_black_list
+        self.regex_max_time_limit = regex_max_time_limit
+        self.cert_path = cert_path
+
+@dataclass
+class Context:
+    """
+    :param domain: Your Switcher domain name
+    :param url: Switcher-API endpoint URL.
+    :param api_key: The API key for authentication
+    :param component: Your application identifier
+    :param environment: Target environment name. If not set, it will use the default environment
+    :param options: The context options
+    """
+    # pylint: disable=too-many-arguments
+    def __init__(self, *,
+                 domain: Optional[str], url: Optional[str], api_key: Optional[str], component: Optional[str],
+                 environment: Optional[str], options: ContextOptions = ContextOptions()):
+        self.domain = domain
+        self.url = url
+        self.api_key = api_key
+        self.component = component
+        self.environment = environment
+        self.options = options
+
+    @classmethod
+    def empty(cls):
+        return cls(
+            domain='',
+            url='',
+            api_key='',
+            component='',
+            environment=DEFAULT_ENVIRONMENT,
+            options=ContextOptions()
+        )

switcher_client/lib/globals/global_retry.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass
+
+@dataclass
+class RetryOptions:
+    """
+    RetryOptions holds the configuration for retrying authentication in silent mode,
+    including the retry time and the duration to wait between retries.
+    """
+
+    def __init__(self, retry_time: int, retry_duration_in: str):
+        """
+        :param retry_time: The maximum number of retries
+        :param retry_duration_in: The duration to wait between retries (e.g. '5s' (s: seconds - m: minutes - h: hours))
+        """
+        self.retry_time = retry_time
+        self.retry_duration_in = retry_duration_in

switcher_client/lib/globals/global_snapshot.py

@@ -0,0 +1,33 @@
+from dataclasses import dataclass
+
+from switcher_client.lib.types import Snapshot
+
+@dataclass
+class GlobalSnapshot:
+    """
+    GlobalSnapshot manages the global snapshot state,
+    allowing it to be set, cleared, and retrieved across the application.
+    """
+
+    @staticmethod
+    def init(snapshot: Snapshot | None):
+        GlobalSnapshot.snapshotStore = snapshot
+
+    @staticmethod
+    def clear():
+        GlobalSnapshot.snapshotStore = None
+
+    @staticmethod
+    def snapshot() -> Snapshot | None:
+        return GlobalSnapshot.snapshotStore
+
+@dataclass
+class LoadSnapshotOptions:
+    """
+    LoadSnapshotOptions holds the options for loading a snapshot,
+    including whether to fetch it remotely and whether to watch for changes.
+    """
+
+    def __init__(self, fetch_remote: bool = False, watch_snapshot: bool = False):
+        self.fetch_remote = fetch_remote
+        self.watch_snapshot = watch_snapshot

switcher_client/lib/remote.py

@@ -0,0 +1,153 @@
+from typing import Optional
+
+import json
+import ssl
+import httpx
+
+from switcher_client.errors import RemoteAuthError, RemoteError, RemoteCriteriaError, RemoteSwitcherError
+from switcher_client.lib.globals.global_context import DEFAULT_ENVIRONMENT, Context
+from switcher_client.lib.types import ResultDetail
+from switcher_client.lib.utils import get, get_entry
+from switcher_client.switcher_data import SwitcherData
+
+class Remote:
+    """
+    Remote handles all interactions with the remote switcher service,
+    including authentication, criteria checks, and snapshot resolution.
+    """
+    _client: Optional[httpx.Client] = None
+
+    @staticmethod
+    def auth(context: Context):
+        url = f'{context.url}/criteria/auth'
+        response = Remote._do_post(context, url, {
+            'domain': context.domain,
+            'component': context.component,
+            'environment': context.environment,
+        }, {
+            'switcher-api-key': context.api_key,
+            'Content-Type': 'application/json',
+        })
+
+        if response.status_code == 200:
+            return response.json()['token'], response.json()['exp']
+
+        raise RemoteAuthError('Invalid API key')
+
+    @staticmethod
+    def check_api_health(context: Context) -> bool:
+        url = f'{context.url}/check'
+        response = Remote._do_get(context, url)
+
+        return response.status_code == 200
+
+    @staticmethod
+    def check_criteria(token: Optional[str], context: Context, switcher: SwitcherData) -> ResultDetail:
+        url = f'{context.url}/criteria?showReason={str(switcher.show_details).lower()}&key={switcher.key}'
+        entry = get_entry(switcher.inputs)
+        response = Remote._do_post(context, url, { 'entry': [e.to_dict() for e in entry] }, Remote._get_header(token))
+
+        if response.status_code == 200:
+            json_response = response.json()
+            return ResultDetail(
+                result=json_response['result'],
+                reason=json_response.get('reason', None),
+                metadata=json_response.get('metadata', {})
+            )
+
+        raise RemoteCriteriaError(f'[check_criteria] failed with status: {response.status_code}')
+
+    @staticmethod
+    def check_switchers(token: Optional[str], switcher_keys: list[str], context: Context) -> None:
+        url = f'{context.url}/criteria/switchers_check'
+        response = Remote._do_post(context, url, { 'switchers': switcher_keys }, Remote._get_header(token))
+
+        if response.status_code != 200:
+            raise RemoteError(f'[check_switchers] failed with status: {response.status_code}')
+
+        not_found = response.json().get('not_found', [])
+        if len(not_found) > 0:
+            raise RemoteSwitcherError(not_found)
+
+    @staticmethod
+    def check_snapshot_version(token: Optional[str], context: Context, snapshot_version: int) -> bool:
+        url = f'{context.url}/criteria/snapshot_check/{snapshot_version}'
+        response = Remote._do_get(context, url, Remote._get_header(token))
+
+        if response.status_code == 200:
+            return response.json().get('status', False)
+
+        raise RemoteError(f'[check_snapshot_version] failed with status: {response.status_code}')
+
+    @staticmethod
+    def resolve_snapshot(token: Optional[str], context: Context) -> str | None:
+        domain = get(context.domain, '')
+        environment = get(context.environment, DEFAULT_ENVIRONMENT)
+        component = get(context.component, '')
+
+        data = {
+            "query": f"""
+                query domain {{
+                    domain(name: "{domain}", environment: "{environment}", _component: "{component}") {{
+                    name version activated
+                    group {{ name activated
+                        config {{ key activated
+                            strategies {{ strategy activated operation values }}
+                            relay {{ type  activated }}
+                            components
+                        }}
+                    }}
+                }}
+            }}
+            """
+        }
+
+        response = Remote._do_post(context, f'{context.url}/graphql', data, Remote._get_header(token))
+
+        if response.status_code == 200:
+            return json.dumps(response.json().get('data', {}), indent=4)
+
+        raise RemoteError(f'[resolve_snapshot] failed with status: {response.status_code}')
+
+    @classmethod
+    def _get_client(cls, context: Context) -> httpx.Client:
+        if cls._client is None or cls._client.is_closed:
+            cls._client = httpx.Client(
+                timeout=30.0,
+                limits=httpx.Limits(
+                    max_keepalive_connections=20,
+                    max_connections=100,
+                    keepalive_expiry=30.0
+                ),
+                http2=True,
+                verify=cls._get_context(context)
+            )
+        return cls._client
+
+    @staticmethod
+    def _do_post(context: Context, url: str, data: dict, headers: Optional[dict] = None) -> httpx.Response:
+        client = Remote._get_client(context)
+        return client.post(url, json=data, headers=headers)
+
+    @staticmethod
+    def _do_get(context: Context, url: str, headers: Optional[dict] = None) -> httpx.Response:
+        client = Remote._get_client(context)
+        return client.get(url, headers=headers)
+
+    @staticmethod
+    def _get_header(token: Optional[str]) -> dict:
+        return {
+            'Authorization': f'Bearer {token}',
+            'Content-Type': 'application/json',
+        }
+
+    @staticmethod
+    def _get_context(context: Context) -> bool | ssl.SSLContext:
+        cert_path = context.options.cert_path
+        if cert_path is None:
+            return True
+
+        ctx = ssl.create_default_context()
+        ctx.minimum_version = ssl.TLSVersion.TLSv1_2
+        ctx.load_cert_chain(certfile=cert_path)
+        return ctx