qena-shared-lib 0.1.0__py3-none-any.whl

qena_shared_lib/scheduler.py

@@ -0,0 +1,402 @@
+from asyncio import Future, Task, iscoroutinefunction, sleep
+from dataclasses import dataclass
+from datetime import datetime
+from functools import partial
+from importlib import import_module
+from inspect import signature
+from os import name as osname
+from typing import Any, Callable, TypeVar
+from zoneinfo import ZoneInfo
+
+from cronsim import CronSim
+from prometheus_client import Enum as PrometheusEnum
+from punq import Container, Scope
+
+from .dependencies.miscellaneous import validate_annotation
+from .logging import LoggerProvider
+from .logstash import BaseLogstashSender
+from .utils import AsyncEventLoopMixin
+
+__all__ = [
+    "schedule",
+    "ScheduleManager",
+    "Scheduler",
+    "SchedulerBase",
+]
+
+S = TypeVar("S")
+SCHEDULER_ATTRIBUTE = "__scheduler__"
+SCHEDULED_TASK_ATTRIBUTE = "__scheduled_task__"
+
+
+@dataclass
+class ScheduledTask:
+    task: Callable
+    cron_expression: str
+    zone_info: ZoneInfo | None
+
+    def __post_init__(self):
+        self._next_run_in = None
+        self._ran = False
+        self._paramters = {}
+
+        for parameter_name, paramter in signature(self.task).parameters.items():
+            dependency = validate_annotation(paramter.annotation)
+
+            if dependency is None:
+                raise TypeError(
+                    f"scheduler parament annotation for `{parameter_name}` not valid, expected `Annotated[type, DependsOn(type)]`"
+                )
+
+            self._paramters[parameter_name] = dependency
+
+    @property
+    def next_run_in(self) -> int | None:
+        return self._next_run_in
+
+    @next_run_in.setter
+    def next_run_in(self, value: int):
+        self._next_run_in = value
+
+    @property
+    def ran(self) -> bool:
+        return self._ran
+
+    @ran.setter
+    def ran(self, value: bool):
+        self._ran = value
+
+    @property
+    def parameters(self) -> dict[str, type]:
+        return self._paramters
+
+
+class Scheduler:
+    def __init__(self):
+        self._scheduled_tasks: list[ScheduledTask] = []
+
+    def schedule(
+        self, cron_expression: str, timezone: str | None = None
+    ) -> Callable[[Callable], Callable]:
+        def wrapper(task: Callable) -> Callable:
+            self.add_task(
+                task=task, cron_expression=cron_expression, timezone=timezone
+            )
+
+            return task
+
+        return wrapper
+
+    def add_task(
+        self, task: Callable, cron_expression: str, timezone: str | None
+    ):
+        self._scheduled_tasks.append(
+            ScheduledTask(
+                task=task,
+                cron_expression=cron_expression,
+                zone_info=ZoneInfo(timezone) if timezone is not None else None,
+            )
+        )
+
+    def __call__(self, scheduler: type[S]) -> type[S]:
+        setattr(scheduler, SCHEDULER_ATTRIBUTE, self)
+
+        return scheduler
+
+    @property
+    def scheduled_tasks(self) -> list[ScheduledTask]:
+        return self._scheduled_tasks
+
+
+@dataclass
+class ScheduledTaskMeta:
+    cron_expression: str
+    timezone: str | None = None
+
+
+def schedule(
+    cron_expression: str, *, timezone: str | None = None
+) -> Callable[[Callable], Callable]:
+    def wrapper(task: Callable) -> Callable:
+        setattr(
+            task,
+            SCHEDULED_TASK_ATTRIBUTE,
+            ScheduledTaskMeta(
+                cron_expression=cron_expression, timezone=timezone
+            ),
+        )
+
+        return task
+
+    return wrapper
+
+
+class SchedulerBase:
+    def get_scheduler(self) -> Scheduler:
+        scheduler = getattr(self, SCHEDULER_ATTRIBUTE, None)
+
+        if scheduler is None or not isinstance(scheduler, Scheduler):
+            raise TypeError(
+                f"{self.__class__.__name__} not a scheduler, possibly no annotated with either `Scheduler`"
+            )
+
+        return scheduler
+
+    def register_scheduled_tasks(self) -> Scheduler:
+        scheduler = self.get_scheduler()
+
+        for attribute_name in dir(self):
+            attribute = getattr(self, attribute_name, None)
+
+            if attribute is None:
+                continue
+
+            scheduled_task_meta = getattr(
+                attribute, SCHEDULED_TASK_ATTRIBUTE, None
+            )
+
+            if scheduled_task_meta is None:
+                continue
+
+            if not isinstance(scheduled_task_meta, ScheduledTaskMeta):
+                raise TypeError(
+                    f"expected `{SCHEDULED_TASK_ATTRIBUTE}` to by of type `ScheduledTaskMeta`, got {type(scheduled_task_meta)}"
+                )
+
+            scheduler.add_task(
+                task=attribute,
+                cron_expression=scheduled_task_meta.cron_expression,
+                timezone=scheduled_task_meta.timezone,
+            )
+
+        return scheduler
+
+
+class ScheduleManager(AsyncEventLoopMixin):
+    SCHEDULE_MANAGER_STATE = PrometheusEnum(
+        name="schedule_manager_state",
+        documentation="Schedule manager state",
+        states=["running", "stopped"],
+    )
+
+    def __init__(
+        self,
+        schedulers: list[Scheduler | type[SchedulerBase]],
+        logstash: BaseLogstashSender,
+        container: Container | None = None,
+    ):
+        self._container = container or Container()
+        self._logstash = logstash
+        self._scheduled_tasks: list[ScheduledTask] = []
+
+        for index, scheduler in enumerate(schedulers):
+            if isinstance(scheduler, Scheduler):
+                self._scheduled_tasks.extend(scheduler.scheduled_tasks)
+            elif isinstance(scheduler, type) and issubclass(
+                scheduler, SchedulerBase
+            ):
+                self._container.register(
+                    service=SchedulerBase,
+                    factory=scheduler,
+                    scope=Scope.singleton,
+                )
+            else:
+                raise TypeError(
+                    f"scheduler {index} is {type(scheduler)}, expected instance of type or subclass of `Scheduler` or `type[SchedulerBase]`"
+                )
+
+        self._next_run_in = None
+        self._logger = LoggerProvider.default().get_logger("schedule_manager")
+
+    @property
+    def container(self) -> Container:
+        return self._container
+
+    @property
+    def next_run_in(self) -> int:
+        self._calculate_next_schedule()
+
+        return self._next_run_in or 0
+
+    @property
+    def scheduled_task_count(self) -> int:
+        return len(self._scheduled_tasks)
+
+    def start(self):
+        if not self._aquired_lock():
+            return
+
+        if (
+            getattr(self, "_scheduler_task", None) is not None
+            and not self._scheduler_task.done()
+        ):
+            return RuntimeError("scheduler already running")
+
+        self.use_schedulers()
+        self._logger.info(
+            "schedule manager started for %d %s",
+            self.scheduled_task_count,
+            "tasks" if self.scheduled_task_count > 1 else "task",
+        )
+
+        if self.scheduled_task_count == 0:
+            return
+
+        self._scheduler_task = self.loop.create_task(self._run_scheduler())
+
+        self._scheduler_task.add_done_callback(self._on_scheduler_done)
+        self.SCHEDULE_MANAGER_STATE.state("running")
+
+    def use_schedulers(self):
+        for scheduler in [
+            scheduler.register_scheduled_tasks()
+            for scheduler in self._container.resolve_all(SchedulerBase)
+        ]:
+            self._scheduled_tasks.extend(scheduler.scheduled_tasks)
+
+    def stop(self):
+        if not self._scheduler_task.done():
+            self._scheduler_task.cancel()
+
+        self.SCHEDULE_MANAGER_STATE.state("stopped")
+
+    def _on_scheduler_done(self, task: Task):
+        if task.cancelled():
+            return
+
+        exception = task.exception()
+
+        if exception is not None:
+            self._logstash.error(
+                message="error occured in schedule manager",
+                exception=exception,
+            )
+
+            return
+
+        self._logger.info("schedule manager stopping")
+
+    def _aquired_lock(self) -> bool:
+        if osname != "posix":
+            self._logger.warning("lock not supported in %s", osname)
+
+            return False
+
+        try:
+            fcntl = import_module("fcntl")
+            lockf = fcntl.lockf
+            LOCK_EX = fcntl.LOCK_EX
+            LOCK_NB = fcntl.LOCK_NB
+
+            self._fd = open(file="scheduler.lock", mode="w+", encoding="utf-8")
+
+            lockf(self._fd, LOCK_EX | LOCK_NB)
+        except OSError:
+            self._logger.warning("a schedule manager already running")
+
+            return False
+        except ModuleNotFoundError:
+            self._logger.exception("module `fcntl` no found")
+
+            return False
+
+        return True
+
+    async def _run_scheduler(self):
+        while True:
+            self._calculate_next_schedule()
+            self._logger.debug(
+                "next tasks will be executed after `%d` seconds",
+                self._next_run_in or 0,
+            )
+
+            await sleep(self._next_run_in or 0)
+            self._logger.debug(
+                "executing tasks after `%d` seconds since last execution",
+                self.next_run_in or 0,
+            )
+
+            for scheduled_task in self._scheduled_tasks:
+                next_run_in_diff = abs(
+                    (self._next_run_in or 0) - (scheduled_task.next_run_in or 0)
+                )
+
+                if next_run_in_diff > 60:
+                    continue
+
+                args = self._resolve_dependencies(scheduled_task)
+
+                if iscoroutinefunction(scheduled_task.task):
+                    self.loop.create_task(
+                        scheduled_task.task(**args)
+                    ).add_done_callback(self._on_task_done)
+                else:
+                    self.loop.run_in_executor(
+                        executor=None, func=scheduled_task.task
+                    ).add_done_callback(partial(self._on_task_done, **args))
+
+                scheduled_task.ran = True
+
+    def _resolve_dependencies(
+        self, scheduled_task: ScheduledTask
+    ) -> dict[str, Any]:
+        args = {}
+
+        if self._container is None:
+            return args
+
+        for parameter_name, dependency in scheduled_task.parameters.items():
+            args[parameter_name] = self._container.resolve(dependency)
+
+        return args
+
+    def _on_task_done(self, task_or_future: Task | Future):
+        if task_or_future.cancelled():
+            return
+
+        exception = task_or_future.exception()
+
+        if exception is not None:
+            self._logstash.error(
+                message="error occured while executing task",
+                exception=exception,
+            )
+
+    def _calculate_next_schedule(self):
+        prev_run_in = self._next_run_in or 0
+        self._next_run_in = None
+
+        for scheduled_task in self._scheduled_tasks:
+            if (
+                not scheduled_task.ran
+                and scheduled_task.next_run_in is not None
+            ):
+                scheduled_task.next_run_in = (
+                    scheduled_task.next_run_in - prev_run_in
+                )
+
+                if (
+                    self._next_run_in is not None
+                    and (scheduled_task.next_run_in or 0) < self._next_run_in
+                ) or self._next_run_in is None:
+                    self._next_run_in = scheduled_task.next_run_in
+
+                continue
+
+            current_datetime = datetime.now(tz=scheduled_task.zone_info)
+            next_datetime = next(
+                CronSim(
+                    expr=scheduled_task.cron_expression,
+                    dt=datetime.now(tz=scheduled_task.zone_info),
+                )
+            )
+            next_run_in = (next_datetime - current_datetime).seconds
+
+            if next_run_in == 0:
+                continue
+
+            if self._next_run_in is None or next_run_in < self._next_run_in:
+                self._next_run_in = next_run_in
+
+            scheduled_task.next_run_in = next_run_in
+            scheduled_task.ran = False

qena_shared_lib/security.py

@@ -0,0 +1,205 @@
+from asyncio import Future
+from enum import Enum
+from os import environ
+from typing import AbstractSet, Annotated, Any
+
+from fastapi import Depends, Header
+from jwt import JWT, AbstractJWKBase, jwk_from_dict
+from jwt.exceptions import JWTDecodeError
+from jwt.utils import get_int_from_datetime, get_time_from_int
+from passlib.context import CryptContext
+from pydantic import BaseModel, Field, ValidationError
+
+from .dependencies.http import DependsOn
+from .exceptions import Unauthorized
+from .utils import AsyncEventLoopMixin
+
+__all__ = [
+    "EndpointACL",
+    "get_int_from_datetime",
+    "get_time_from_int",
+    "jwk_from_dict",
+    "JwtAdapter",
+    "PasswordHasher",
+    "PermissionMatch",
+    "UserInfo",
+]
+
+
+MESSAGE = "you are not authorized to access request resouce"
+RESPONSE_CODE = int(environ.get("UNAUTHORIZED_RESPONSE_CODE") or 0)
+
+
+class PasswordHasher(AsyncEventLoopMixin):
+    def __init__(self):
+        self._crypt_context = CryptContext(
+            schemes=["bcrypt"], deprecated="auto"
+        )
+
+    def hash(self, password: str) -> Future[str]:
+        return self.loop.run_in_executor(
+            None, self._crypt_context.hash, password
+        )
+
+    def verify(self, password: str, password_hash: str) -> Future[bool]:
+        return self.loop.run_in_executor(
+            None, self._crypt_context.verify, password, password_hash
+        )
+
+
+class JwtAdapter(AsyncEventLoopMixin):
+    def __init__(self):
+        self._jwt = JWT()
+
+    def encode(
+        self,
+        payload: dict[str, Any],
+        key: AbstractJWKBase | None = None,
+        algorithm: str = "HS256",
+        optional_headers: dict[str, str] | None = None,
+    ) -> Future[str]:
+        return self.loop.run_in_executor(
+            None, self._jwt.encode, payload, key, algorithm, optional_headers
+        )
+
+    def decode(
+        self,
+        message: str,
+        key: AbstractJWKBase | None = None,
+        do_verify: bool = True,
+        algorithms: AbstractSet[str] | None = None,
+        do_time_check: bool = True,
+    ) -> Future[dict[str, Any]]:
+        return self.loop.run_in_executor(
+            None,
+            self._jwt.decode,
+            message,
+            key,
+            do_verify,
+            algorithms,
+            do_time_check,
+        )
+
+
+class UserInfo(BaseModel):
+    user_id: str = Field(alias="userId")
+    user_type: str = Field(alias="type")
+    user_permissions: list[str] | None = Field(
+        default=None, alias="permissions"
+    )
+
+
+async def extract_user_info(
+    jwt_adapter: Annotated[JwtAdapter, DependsOn(JwtAdapter)],
+    token: Annotated[
+        str | None, Header(alias=environ.get("TOKEN_HEADER") or "authorization")
+    ] = None,
+    user_agent: Annotated[str | None, Header(alias="user-agent")] = None,
+) -> UserInfo:
+    extra = {"userAgent": user_agent} if user_agent is not None else None
+
+    if token is None:
+        raise Unauthorized(
+            message=MESSAGE,
+            response_code=RESPONSE_CODE,
+            extra=extra,
+        )
+
+    try:
+        payload = await jwt_adapter.decode(
+            message=token, do_verify=False, do_time_check=True
+        )
+    except JWTDecodeError as e:
+        raise Unauthorized(
+            message=MESSAGE,
+            response_code=RESPONSE_CODE,
+            extra=extra,
+            extract_exc_info=True,
+        ) from e
+
+    try:
+        user_info = UserInfo.model_validate(payload)
+    except ValidationError as e:
+        raise Unauthorized(
+            message=MESSAGE,
+            response_code=RESPONSE_CODE,
+            extra=extra,
+            extract_exc_info=True,
+        ) from e
+
+    return user_info
+
+
+class PermissionMatch(Enum):
+    SOME = 0
+    ALL = 1
+
+
+def EndpointACL(
+    user_type: str | None = None,
+    permissions: list[str] | None = None,
+    permission_match_strategy: PermissionMatch | None = None,
+) -> Any:
+    return Depends(
+        EndpointAclValidator(
+            user_type=user_type,
+            permissions=permissions,
+            permission_match_strategy=permission_match_strategy,
+        )
+    )
+
+
+class EndpointAclValidator:
+    def __init__(
+        self,
+        user_type: str | None = None,
+        permissions: list[str] | None = None,
+        permission_match_strategy: PermissionMatch | None = None,
+    ):
+        self._user_type = user_type
+        self._permissions = permissions
+        self._permission_match_strategy = (
+            permission_match_strategy or PermissionMatch.SOME
+        )
+
+    def __call__(
+        self, user_info: Annotated[UserInfo, Depends(extract_user_info)]
+    ) -> UserInfo:
+        if (
+            self._user_type is not None
+            and (
+                user_info.user_type is None
+                or user_info.user_type != self._user_type
+            )
+        ) or (
+            self._permissions is not None
+            and (
+                user_info.user_permissions is None
+                or not self._permissions_match(user_info.user_permissions)
+            )
+        ):
+            raise Unauthorized(
+                message=MESSAGE,
+                response_code=RESPONSE_CODE,
+                tags=[user_info.user_id],
+                extra={
+                    "userId": user_info.user_id,
+                    "userYype": user_info.user_type,
+                    "userPermissions": str(user_info.user_permissions or []),
+                    "requiredUserType": self._user_type or "None",
+                    "requiredPermissions": str(self._permissions or []),
+                    "permissionMatchStrategy": self._permission_match_strategy.name,
+                },
+            )
+
+        return user_info
+
+    def _permissions_match(self, user_permissions: list[str]) -> bool:
+        assert self._permissions is not None
+
+        if self._permission_match_strategy == PermissionMatch.ALL:
+            return sorted(self._permissions) == sorted(user_permissions)
+
+        return any(
+            permission in self._permissions for permission in user_permissions
+        )

qena_shared_lib/utils.py

@@ -0,0 +1,28 @@
+from asyncio import AbstractEventLoop, get_running_loop
+
+__all__ = ["AsyncEventLoopMixin"]
+
+ABSTRACT_EVENT_LOOP_ATTRIBUTE = "__abstract_event_loop__"
+
+
+class AsyncEventLoopMixin:
+    @property
+    def loop(self) -> AbstractEventLoop:
+        previous_running_loop = getattr(
+            self, ABSTRACT_EVENT_LOOP_ATTRIBUTE, None
+        )
+        current_running_loop = None
+
+        try:
+            current_running_loop = get_running_loop()
+        except RuntimeError:
+            if previous_running_loop is None:
+                raise
+
+        if previous_running_loop is None or (
+            current_running_loop is not None
+            and previous_running_loop != current_running_loop
+        ):
+            setattr(self, ABSTRACT_EVENT_LOOP_ATTRIBUTE, current_running_loop)
+
+        return getattr(self, ABSTRACT_EVENT_LOOP_ATTRIBUTE)