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

qena_shared_lib/__init__.py

@@ -0,0 +1,27 @@
+from . import (
+    application,
+    background,
+    dependencies,
+    exceptions,
+    http,
+    logging,
+    logstash,
+    rabbitmq,
+    scheduler,
+    security,
+    utils,
+)
+
+__all__ = [
+    "application",
+    "background",
+    "dependencies",
+    "exceptions",
+    "http",
+    "logging",
+    "logstash",
+    "rabbitmq",
+    "scheduler",
+    "security",
+    "utils",
+]

qena_shared_lib/application.py

@@ -0,0 +1,190 @@
+from enum import Enum
+from typing import TypeVar
+
+from fastapi import APIRouter, FastAPI
+from fastapi.exceptions import RequestValidationError
+from prometheus_fastapi_instrumentator import Instrumentator
+from punq import Container, Scope, empty
+from starlette.types import Lifespan
+
+from .exception_handlers import (
+    handle_general_http_exception,
+    handle_request_validation_error,
+    handle_service_exception,
+)
+from .exceptions import ServiceException
+from .http import ControllerBase
+
+__all__ = [
+    "Builder",
+    "Environment",
+]
+
+D = TypeVar("D")
+
+
+class Environment(Enum):
+    DEVELOPMENT = 0
+    PRODUCTION = 1
+
+
+class Builder:
+    def __init__(self):
+        self._environment = Environment.DEVELOPMENT
+        self._debug = False
+        self._title = "Qena shared lib"
+        self._description = "Qena shared tools for microservice"
+        self._version = "0.1.0"
+        self._lifespan = None
+        self._openapi_url = "/openapi.json"
+        self._docs_url = "/docs"
+        self._redoc_url = "/redoc"
+        self._metrics_endpoint = None
+        self._instrumentator = None
+        self._routers = []
+        self._container = Container()
+        self._built = False
+
+    def with_environment(self, environment: Environment) -> "Builder":
+        match environment:
+            case Environment.DEVELOPMENT:
+                self._environment = Environment.DEVELOPMENT
+                self._debug = True
+            case Environment.PRODUCTION:
+                self._environment = Environment.PRODUCTION
+                self._debug = False
+                self._openapi_url = None
+                self._docs_url = None
+                self._redoc_url = None
+
+        return self
+
+    def with_title(self, title: str) -> "Builder":
+        self._title = title
+
+        return self
+
+    def with_description(self, description: str) -> "Builder":
+        self._description = description
+
+        return self
+
+    def with_version(self, version: str) -> "Builder":
+        self._version = version
+
+        return self
+
+    def with_lifespan(self, lifespan: Lifespan) -> "Builder":
+        self._lifespan = lifespan
+
+        return self
+
+    def with_controllers(
+        self, controllers: list[type[ControllerBase]]
+    ) -> "Builder":
+        for index, controller in enumerate(controllers):
+            if not isinstance(controller, type) or not issubclass(
+                controller, ControllerBase
+            ):
+                raise TypeError(
+                    f"controller {index} is {type(ControllerBase)}, expected instance of type or subclass of `ControllerBase`"
+                )
+
+            self._container.register(
+                service=ControllerBase,
+                factory=controller,
+                scope=Scope.singleton,
+            )
+
+        return self
+
+    def with_routers(self, routers: list[APIRouter]) -> "Builder":
+        if any(not isinstance(router, APIRouter) for router in routers):
+            raise TypeError("some routers are not type `APIRouter`")
+
+        self._routers.extend(routers)
+
+        return self
+
+    def with_singleton(
+        self, service: type[D], factory=empty, instance=empty, **kwargs
+    ) -> "Builder":
+        self._container.register(
+            service=service,
+            factory=factory,
+            instance=instance,
+            scope=Scope.singleton,
+            **kwargs,
+        )
+
+        return self
+
+    def with_transient(
+        self, service: type[D], factory=empty, **kwargs
+    ) -> "Builder":
+        self._container.register(
+            service=service,
+            factory=factory,
+            scope=Scope.transient,
+            **kwargs,
+        )
+
+        return self
+
+    def with_metrics(self, endpoint: str = "/metrics") -> "Builder":
+        self._metrics_endpoint = endpoint
+        self._instrumentator = Instrumentator()
+
+        return self
+
+    def build(self) -> FastAPI:
+        if self._built:
+            raise RuntimeError("fastapi application aleady built")
+
+        app = FastAPI(
+            debug=self._debug,
+            title=self._title,
+            description=self._description,
+            version=self._version,
+            openapi_url=self._openapi_url,
+            docs_url=self._docs_url,
+            redoc_url=self._redoc_url,
+            lifespan=self._lifespan,
+        )
+        app.state.container = self._container
+
+        app.exception_handler(ServiceException)(handle_service_exception)
+        app.exception_handler(RequestValidationError)(
+            handle_request_validation_error
+        )
+        app.exception_handler(Exception)(handle_general_http_exception)
+
+        self._resolve_api_controllers(app)
+
+        if self._instrumentator is not None:
+            self._instrumentator.instrument(app).expose(
+                app=app,
+                endpoint=self._metrics_endpoint or "/metrics",
+                include_in_schema=False,
+            )
+
+        self._built = True
+
+        return app
+
+    def _resolve_api_controllers(self, app: FastAPI):
+        api_controller_routers = [
+            api_controller.register_route_handlers()
+            for api_controller in self._container.resolve_all(ControllerBase)
+        ]
+
+        for router in self._routers + api_controller_routers:
+            app.include_router(router)
+
+    @property
+    def environment(self) -> Environment:
+        return self._environment
+
+    @property
+    def container(self) -> Container:
+        return self._container

qena_shared_lib/background.py

@@ -0,0 +1,109 @@
+from asyncio import (
+    Queue,
+    Task,
+    gather,
+)
+from uuid import uuid4
+
+from prometheus_client import Enum as PrometheusEnum
+from starlette.background import BackgroundTask
+
+from .logging import LoggerProvider
+from .logstash import BaseLogstashSender
+from .utils import AsyncEventLoopMixin
+
+__all__ = [
+    "Background",
+    "BackgroundTask",
+]
+
+
+class Background(AsyncEventLoopMixin):
+    BACKGROUND_RUNNER_STATE = PrometheusEnum(
+        name="background_runner_state",
+        documentation="Background runner state",
+        states=["running", "stopped"],
+    )
+
+    def __init__(
+        self,
+        logstash: BaseLogstashSender,
+    ):
+        self._queue = Queue()
+        self._started = False
+        self._stopped = False
+        self._logstash = logstash
+        self._logger = LoggerProvider.default().get_logger("backgroud")
+        self._tasks: dict[str, Task] = {}
+
+    async def _task_manager(
+        self, task: BackgroundTask, task_id: str | None = None
+    ):
+        self._logger.info(
+            "running %s: %s with %s", task_id, task.func.__name__, task.args
+        )
+
+        if task_id is None:
+            task_id = str(uuid4())
+
+        try:
+            self._tasks[task_id] = self.loop.create_task(
+                task.func(*task.args, **task.kwargs)
+            )
+
+            await self._tasks[task_id]
+        except Exception:
+            self._logstash.error(
+                "exception occured when running background task {task.func.__name__} with id {task_id}"
+            )
+        finally:
+            self._logger.info("finished running %s", task.func.__name__)
+            self._tasks.pop(task_id, None)
+
+    def _run(self, task: BackgroundTask, task_id: str | None = None):
+        if not self._stopped and (
+            task_id is None or task_id not in self._tasks
+        ):
+            self.loop.create_task(self._task_manager(task, task_id))
+
+    async def _run_tasks(self):
+        while not self._stopped or not self._queue.empty():
+            task, task_id = await self._queue.get()
+
+            if task is None and task_id is None:
+                break
+
+            self._run(task=task, task_id=task_id)
+
+        tasks = [t for _, t in self._tasks.items() if not t.done()]
+
+        await gather(*tasks)
+
+    def add_task(self, task: BackgroundTask, task_id: str | None = None):
+        self._queue.put_nowait((task, task_id))
+
+    def start(self):
+        if self._started:
+            raise RuntimeError("background runner already running")
+
+        self.loop.create_task(self._run_tasks())
+        self.BACKGROUND_RUNNER_STATE.state("running")
+
+        self._started = True
+
+    def stop(self):
+        if self._stopped:
+            raise RuntimeError("background runner already stopped")
+
+        self._stopped = True
+        self._queue.put_nowait((None, None))
+        self.BACKGROUND_RUNNER_STATE.state("stopped")
+
+    def is_alive(self, task_id: str):
+        if task_id in self._tasks and not self._tasks[task_id].done():
+            return True
+
+        return False
+
+    def count(self):
+        return len(self._tasks)

qena_shared_lib/dependencies/__init__.py

@@ -0,0 +1,19 @@
+from punq import (
+    Container,
+    InvalidForwardReferenceError,
+    InvalidRegistrationError,
+    MissingDependencyError,
+    Scope,
+)
+
+from . import http, miscellaneous
+
+__all__ = [
+    "Container",
+    "http",
+    "InvalidForwardReferenceError",
+    "InvalidRegistrationError",
+    "miscellaneous",
+    "MissingDependencyError",
+    "Scope",
+]

qena_shared_lib/dependencies/http.py

@@ -0,0 +1,62 @@
+from typing import Any, TypeVar
+
+from fastapi import Depends, FastAPI, Request
+from punq import Container, Scope, empty
+
+__all__ = [
+    "add_service",
+    "DependsOn",
+    "get_service",
+]
+
+D = TypeVar("D")
+
+
+def get_container(app: FastAPI) -> Container:
+    if not hasattr(app.state, "container"):
+        raise RuntimeError(
+            "application does include container, possibly not created with builder"
+        )
+
+    if not isinstance(app.state.container, Container):
+        raise TypeError("container is not type of `punq.Container`")
+
+    return app.state.container
+
+
+def add_service(
+    app: FastAPI,
+    service: type[D],
+    factory=empty,
+    instance: D = empty,
+    scope: Scope = Scope.transient,
+    **kwargs,
+):
+    get_container(app).register(
+        service=service,
+        factory=factory,
+        instance=instance,
+        scope=scope,
+        **kwargs,
+    )
+
+
+def get_service(app: FastAPI, service_key: type[D]) -> D:
+    service = get_container(app).resolve(service_key=service_key)
+
+    if not isinstance(service, service_key):
+        raise TypeError(f"`{service}` not a `{service_key}`")
+
+    return service
+
+
+class DependencyResolver:
+    def __init__(self, dependency: type):
+        self._dependency = dependency
+
+    def __call__(self, request: Request) -> Any:
+        return get_service(app=request.app, service_key=self._dependency)
+
+
+def DependsOn(dependency: type) -> Any:
+    return Depends(DependencyResolver(dependency))

qena_shared_lib/dependencies/miscellaneous.py

@@ -0,0 +1,35 @@
+from dataclasses import dataclass
+from inspect import Parameter
+from typing import Annotated, get_args, get_origin
+
+__all__ = [
+    "DependsOn",
+    "validate_annotation",
+]
+
+
+@dataclass
+class DependsOn:
+    dependency: type
+
+
+def validate_annotation(parameter: Parameter | type) -> type | None:
+    if isinstance(parameter, Parameter):
+        annotation = parameter.annotation
+    else:
+        annotation = parameter
+
+    if annotation is Parameter.empty or get_origin(annotation) is not Annotated:
+        return None
+
+    args = get_args(annotation)
+
+    if len(args) != 2:
+        return None
+
+    _, dependency_metadata = args
+
+    if not isinstance(dependency_metadata, DependsOn):
+        return None
+
+    return dependency_metadata.dependency

qena_shared_lib/exception_handlers.py

@@ -0,0 +1,165 @@
+from typing import Any
+
+from fastapi import Request, Response, status
+from fastapi.encoders import jsonable_encoder
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+
+from .dependencies.http import get_service
+from .exceptions import ServiceException, Severity
+from .logging import LoggerProvider
+from .logstash._base import BaseLogstashSender
+
+__all__ = [
+    "handle_service_exception",
+    "handle_request_validation_error",
+    "handle_general_http_exception",
+]
+
+
+def handle_service_exception(
+    request: Request, exception: ServiceException
+) -> Response:
+    logstash = get_service(app=request.app, service_key=BaseLogstashSender)
+    logger_provider = get_service(app=request.app, service_key=LoggerProvider)
+    logger = logger_provider.get_logger("http.exception_handler")
+    exception_severity = exception.severity or Severity.LOW
+    message = exception.message
+    tags = [
+        "HTTP",
+        request.method,
+        request.url.path,
+        exception.__class__.__name__,
+    ]
+
+    if exception.tags:
+        exception.tags.extend(tags)
+
+    extra = {
+        "serviceType": "HTTP",
+        "method": request.method,
+        "path": request.url.path,
+        "exception": exception.__class__.__name__,
+    }
+
+    if exception.extra:
+        exception.extra.update(extra)
+
+    exc_info = (
+        (type(exception), exception, exception.__traceback__)
+        if exception.extract_exc_info
+        else None
+    )
+
+    match exception_severity:
+        case Severity.LOW:
+            logstash_logger_method = logstash.info
+            logger_method = logger.info
+        case Severity.MEDIUM:
+            logstash_logger_method = logstash.warning
+            logger_method = logger.warning
+        case _:
+            message = "something went wrong"
+            logstash_logger_method = logstash.error
+            logger_method = logger.error
+
+    if exception.logstash_logging:
+        logstash_logger_method(
+            message=exception.message,
+            tags=exception.tags or tags,
+            extra=exception.extra or extra,
+            exception=exception if exception.extract_exc_info else None,
+        )
+    else:
+        logger_method(
+            "\n%s %s\n%s",
+            request.method,
+            request.url.path,
+            exception.message,
+            exc_info=exc_info,
+        )
+
+    content: dict[str, Any] = {
+        "severity": exception_severity.name
+        if exception_severity
+        else Severity.LOW.name,
+        "message": message,
+    }
+
+    if exception.response_code is not None:
+        content["code"] = exception.response_code
+
+    if exception.corrective_action is not None:
+        content["correctiveAction"] = exception.corrective_action
+
+    if exception.body is not None:
+        content.update(dict(exception.body))
+
+    return JSONResponse(
+        content=content,
+        status_code=exception.status_code
+        or _status_code_from_severity(exception.severity),
+        headers=exception.headers,
+    )
+
+
+def handle_request_validation_error(
+    request: Request, error: RequestValidationError
+) -> Response:
+    logger_provider = get_service(app=request.app, service_key=LoggerProvider)
+    logger = logger_provider.get_logger("http.exception_handler")
+    message = "invalid request data"
+
+    logger.warning("\n%s %s\n%s", request.method, request.url.path, message)
+
+    return JSONResponse(
+        content={
+            "severity": Severity.MEDIUM.name,
+            "message": message,
+            "code": 100,
+            "detail": jsonable_encoder(error.errors()),
+        },
+        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+    )
+
+
+def handle_general_http_exception(
+    request: Request, exception: Exception
+) -> Response:
+    logstash = get_service(app=request.app, service_key=BaseLogstashSender)
+
+    logstash.error(
+        message=f"something went wrong on endpoint `{request.method} {request.url.path}`",
+        tags=[
+            "HTTP",
+            request.method,
+            request.url.path,
+            exception.__class__.__name__,
+        ],
+        extra={
+            "serviceType": "HTTP",
+            "method": request.method,
+            "path": request.url.path,
+            "exception": exception.__class__.__name__,
+        },
+        exception=exception,
+    )
+
+    return JSONResponse(
+        content={
+            "severity": Severity.HIGH.name,
+            "message": "something went wrong",
+        },
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+    )
+
+
+def _status_code_from_severity(severity: Severity | None) -> int:
+    if (
+        severity is None
+        or severity == Severity.LOW
+        or severity == Severity.MEDIUM
+    ):
+        return status.HTTP_400_BAD_REQUEST
+
+    return status.HTTP_500_INTERNAL_SERVER_ERROR