nexo-schemas 0.0.16__py3-none-any.whl

nexo/schemas/operation/action/resource.py

@@ -0,0 +1,371 @@
+import re
+from fastapi import status, HTTPException, Request
+from pydantic import Field
+from typing import (
+    Annotated,
+    Callable,
+    Generic,
+    Literal,
+    Mapping,
+    Type,
+    TypeVar,
+    overload,
+)
+from ..enums import (
+    ResourceOperationType,
+    ResourceOperationTypeT,
+    OptResourceOperationType,
+    ResourceOperationUpdateType,
+    OptResourceOperationUpdateType,
+    ResourceOperationDataUpdateType,
+    OptResourceOperationDataUpdateType,
+    ResourceOperationStatusUpdateType,
+    OptResourceOperationStatusUpdateType,
+)
+from .base import BaseOperationAction
+
+
+class ResourceOperationAction(
+    BaseOperationAction[ResourceOperationTypeT], Generic[ResourceOperationTypeT]
+):
+    pass
+
+
+class CreateResourceOperationAction(
+    ResourceOperationAction[Literal[ResourceOperationType.CREATE]]
+):
+    type: Literal[ResourceOperationType.CREATE] = ResourceOperationType.CREATE
+
+
+CREATE_RESOURCE_OPERATION_ACTION = CreateResourceOperationAction()
+
+
+class ReadResourceOperationAction(
+    ResourceOperationAction[Literal[ResourceOperationType.READ]]
+):
+    type: Literal[ResourceOperationType.READ] = ResourceOperationType.READ
+
+
+class UpdateResourceOperationAction(
+    ResourceOperationAction[Literal[ResourceOperationType.UPDATE]]
+):
+    type: Literal[ResourceOperationType.UPDATE] = ResourceOperationType.UPDATE
+    update_type: Annotated[
+        OptResourceOperationUpdateType,
+        Field(None, description="Update type (optional)"),
+    ] = None
+    data_update_type: Annotated[
+        OptResourceOperationDataUpdateType,
+        Field(None, description="Data update type (optional)"),
+    ] = None
+    status_update_type: Annotated[
+        OptResourceOperationStatusUpdateType,
+        Field(None, description="Status update type (optional)"),
+    ] = None
+
+
+class DeleteResourceOperationAction(
+    ResourceOperationAction[Literal[ResourceOperationType.DELETE]]
+):
+    type: Literal[ResourceOperationType.DELETE] = ResourceOperationType.DELETE
+
+
+ResourceOperationActions = (
+    CreateResourceOperationAction,
+    ReadResourceOperationAction,
+    UpdateResourceOperationAction,
+    DeleteResourceOperationAction,
+)
+
+
+AnyResourceOperationAction = (
+    CreateResourceOperationAction
+    | ReadResourceOperationAction
+    | UpdateResourceOperationAction
+    | DeleteResourceOperationAction
+)
+
+
+AnyResourceOperationActionT = TypeVar(
+    "AnyResourceOperationActionT", bound=AnyResourceOperationAction
+)
+
+
+OptAnyResourceOperationAction = AnyResourceOperationAction | None
+
+
+TYPE_ACTION_MODEL_MAP: Mapping[ResourceOperationType, Type] = {
+    ResourceOperationType.CREATE: CreateResourceOperationAction,
+    ResourceOperationType.READ: ReadResourceOperationAction,
+    ResourceOperationType.UPDATE: UpdateResourceOperationAction,
+    ResourceOperationType.DELETE: DeleteResourceOperationAction,
+}
+
+
+class ResourceOperationActionFactory:
+    @overload
+    @staticmethod
+    def generate(
+        type_: Literal[ResourceOperationType.CREATE],
+        /,
+    ) -> CreateResourceOperationAction: ...
+    @overload
+    @staticmethod
+    def generate(
+        type_: Literal[ResourceOperationType.READ],
+        /,
+    ) -> ReadResourceOperationAction: ...
+    @overload
+    @staticmethod
+    def generate(
+        type_: Literal[ResourceOperationType.UPDATE],
+        *,
+        update_type: OptResourceOperationUpdateType = ...,
+        data_update_type: OptResourceOperationDataUpdateType = ...,
+        status_update_type: OptResourceOperationStatusUpdateType = ...,
+    ) -> UpdateResourceOperationAction: ...
+    @overload
+    @staticmethod
+    def generate(
+        type_: Literal[ResourceOperationType.DELETE],
+        /,
+    ) -> DeleteResourceOperationAction: ...
+    @overload
+    @staticmethod
+    def generate(
+        type_: ResourceOperationType,
+        *,
+        update_type: OptResourceOperationUpdateType = None,
+        data_update_type: OptResourceOperationDataUpdateType = None,
+        status_update_type: OptResourceOperationStatusUpdateType = None,
+    ) -> AnyResourceOperationAction: ...
+    @staticmethod
+    def generate(
+        type_: ResourceOperationType,
+        *,
+        update_type: OptResourceOperationUpdateType = None,
+        data_update_type: OptResourceOperationDataUpdateType = None,
+        status_update_type: OptResourceOperationStatusUpdateType = None,
+    ) -> AnyResourceOperationAction:
+        if type_ is ResourceOperationType.CREATE:
+            return CreateResourceOperationAction()
+
+        elif type_ is ResourceOperationType.READ:
+            return ReadResourceOperationAction()
+
+        elif type_ is ResourceOperationType.UPDATE:
+            return UpdateResourceOperationAction(
+                update_type=update_type,
+                data_update_type=data_update_type,
+                status_update_type=status_update_type,
+            )
+
+        elif type_ is ResourceOperationType.DELETE:
+            return DeleteResourceOperationAction()
+
+    @overload
+    @staticmethod
+    def extract(
+        *,
+        request: Request,
+        from_state: bool = True,
+        strict: Literal[False],
+    ) -> AnyResourceOperationAction: ...
+    @overload
+    @staticmethod
+    def extract(
+        type_: Literal[ResourceOperationType.CREATE],
+        *,
+        request: Request,
+        from_state: bool = True,
+        strict: Literal[True],
+    ) -> CreateResourceOperationAction: ...
+    @overload
+    @staticmethod
+    def extract(
+        type_: Literal[ResourceOperationType.READ],
+        *,
+        request: Request,
+        from_state: bool = True,
+        strict: Literal[True],
+    ) -> ReadResourceOperationAction: ...
+    @overload
+    @staticmethod
+    def extract(
+        type_: Literal[ResourceOperationType.UPDATE],
+        *,
+        request: Request,
+        from_state: bool = True,
+        strict: Literal[True],
+    ) -> UpdateResourceOperationAction: ...
+    @overload
+    @staticmethod
+    def extract(
+        type_: Literal[ResourceOperationType.DELETE],
+        *,
+        request: Request,
+        from_state: bool = True,
+        strict: Literal[True],
+    ) -> DeleteResourceOperationAction: ...
+    @overload
+    @staticmethod
+    def extract(
+        type_: OptResourceOperationType = None,
+        *,
+        request: Request,
+        from_state: bool = True,
+        strict: bool = False,
+    ) -> AnyResourceOperationAction: ...
+    @staticmethod
+    def extract(
+        type_: OptResourceOperationType = None,
+        *,
+        request: Request,
+        from_state: bool = True,
+        strict: bool = False,
+    ) -> AnyResourceOperationAction:
+        if from_state:
+            action = request.state.operation_action
+            if not strict:
+                if not isinstance(action, ResourceOperationActions):
+                    raise HTTPException(
+                        status_code=status.HTTP_400_BAD_REQUEST,
+                        detail=f"Invalid resource_operation_action in request's state: {action}",
+                    )
+                return action
+
+            else:
+                if type_ is None:
+                    raise HTTPException(
+                        status_code=status.HTTP_400_BAD_REQUEST,
+                        detail="Argument 'type_' must be given for strict extraction",
+                    )
+                model = TYPE_ACTION_MODEL_MAP[type_]
+                if not isinstance(action, model):
+                    raise HTTPException(
+                        status_code=status.HTTP_400_BAD_REQUEST,
+                        detail=f"Mismatched 'resource_operation_action' type, expected '{model.__name__}' but received '{type(action).__name__}'",
+                    )
+                return action
+
+        else:
+            action = None
+            update_type = None
+            data_update_type = None
+            status_update_type = None
+
+            if request.method == "POST":
+                action = CreateResourceOperationAction()
+            elif request.method == "GET":
+                action = ReadResourceOperationAction()
+            elif request.method in ["PATCH", "PUT"]:
+                if request.method == "PUT":
+                    update_type = ResourceOperationUpdateType.DATA
+                    data_update_type = ResourceOperationDataUpdateType.FULL
+                elif request.method == "PATCH":
+                    status_pattern = re.search(
+                        r"/status/(delete|restore|deactivate|activate)(?:/.*)?$",
+                        request.url.path,
+                    )
+                    if status_pattern:
+                        update_type = ResourceOperationUpdateType.STATUS
+                        action = status_pattern.group(1)
+                        try:
+                            status_update_type = ResourceOperationStatusUpdateType(
+                                action
+                            )
+                        except ValueError:
+                            # This shouldn't happen since regex already validates, but keep for safety
+                            pass
+                    else:
+                        update_type = ResourceOperationUpdateType.DATA
+                        data_update_type = ResourceOperationDataUpdateType.PARTIAL
+                action = UpdateResourceOperationAction(
+                    update_type=update_type,
+                    data_update_type=data_update_type,
+                    status_update_type=status_update_type,
+                )
+            elif request.method == "DELETE":
+                action = DeleteResourceOperationAction()
+
+            if action is None:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="Unable to determine resource operation action",
+                )
+
+            if not strict:
+                if not isinstance(action, ResourceOperationActions):
+                    raise HTTPException(
+                        status_code=status.HTTP_400_BAD_REQUEST,
+                        detail=f"Invalid resource_operation_action in request's state: {action}",
+                    )
+                return action
+
+            else:
+                if type_ is None:
+                    raise HTTPException(
+                        status_code=status.HTTP_400_BAD_REQUEST,
+                        detail="Argument 'type_' must be given for strict extraction",
+                    )
+                model = TYPE_ACTION_MODEL_MAP[type_]
+                if not isinstance(action, model):
+                    raise HTTPException(
+                        status_code=status.HTTP_400_BAD_REQUEST,
+                        detail=f"Mismatched 'resource_operation_action' type, expected '{model.__name__}' but received '{type(action).__name__}'",
+                    )
+                return action
+
+    @overload
+    @staticmethod
+    def as_dependency(
+        *,
+        from_state: bool = True,
+        strict: Literal[False],
+    ) -> Callable[..., AnyResourceOperationAction]: ...
+    @overload
+    @staticmethod
+    def as_dependency(
+        type_: Literal[ResourceOperationType.CREATE],
+        *,
+        from_state: bool = True,
+        strict: Literal[True],
+    ) -> Callable[..., CreateResourceOperationAction]: ...
+    @overload
+    @staticmethod
+    def as_dependency(
+        type_: Literal[ResourceOperationType.READ],
+        *,
+        from_state: bool = True,
+        strict: Literal[True],
+    ) -> Callable[..., ReadResourceOperationAction]: ...
+    @overload
+    @staticmethod
+    def as_dependency(
+        type_: Literal[ResourceOperationType.UPDATE],
+        *,
+        from_state: bool = True,
+        strict: Literal[True],
+    ) -> Callable[..., UpdateResourceOperationAction]: ...
+    @overload
+    @staticmethod
+    def as_dependency(
+        type_: Literal[ResourceOperationType.DELETE],
+        *,
+        from_state: bool = True,
+        strict: Literal[True],
+    ) -> Callable[..., DeleteResourceOperationAction]: ...
+    @staticmethod
+    def as_dependency(
+        type_: OptResourceOperationType = None,
+        *,
+        from_state: bool = True,
+        strict: bool = False,
+    ) -> Callable[..., AnyResourceOperationAction]:
+
+        def dependency(request: Request) -> AnyResourceOperationAction:
+            return ResourceOperationActionFactory.extract(
+                type_, request=request, from_state=from_state, strict=strict
+            )
+
+        return dependency

nexo/schemas/operation/action/status.py

@@ -0,0 +1,8 @@
+from ..enums import ResourceOperationStatusUpdateType
+from .base import BaseOperationAction
+
+
+class StatusUpdateOperationAction(
+    BaseOperationAction[ResourceOperationStatusUpdateType]
+):
+    pass

nexo/schemas/operation/action/system.py

@@ -0,0 +1,6 @@
+from ..enums import SystemOperationType
+from .base import SimpleOperationAction
+
+
+class SystemOperationAction(SimpleOperationAction[SystemOperationType]):
+    pass

nexo/schemas/operation/action/websocket.py

@@ -0,0 +1,6 @@
+from ..enums import WebSocketOperationType
+from .base import SimpleOperationAction
+
+
+class WebSocketOperationAction(SimpleOperationAction[WebSocketOperationType]):
+    pass

nexo/schemas/operation/base.py

@@ -0,0 +1,289 @@
+import os
+from functools import cached_property
+from google.cloud.pubsub_v1.publisher.futures import Future
+from logging import Logger
+from typing import Generic
+from nexo.logging.enums import LogLevel
+from nexo.types.boolean import BoolT, OptBool
+from nexo.types.dict import (
+    OptStrToStrDict,
+    StrToAnyDict,
+    StrToStrDict,
+)
+from nexo.utils.exception import extract_details
+from nexo.utils.merger import merge_dicts
+from ..application import ApplicationContextMixin
+from ..connection import OptConnectionContextT, ConnectionContextMixin
+from ..google import ListOfPublisherHandlers
+from ..error import OptAnyErrorT, ErrorMixin
+from ..mixins.general import Success
+from ..resource import OptResourceT, ResourceMixin
+from ..response import (
+    OptResponseContextT,
+    ResponseContextMixin,
+    OptResponseT,
+    ResponseMixin,
+)
+from ..security.authentication import (
+    OptAnyAuthentication,
+    AuthenticationMixin,
+)
+from ..security.authorization import OptAnyAuthorization, AuthorizationMixin
+from ..security.impersonation import OptImpersonation, ImpersonationMixin
+from .action import (
+    ActionMixin,
+    ActionT,
+)
+from .context import ContextMixin
+from .enums import OperationType as OperationTypeEnum, ListOfOperationTypes
+from .mixins import Id, OperationType, Summary, TimestampMixin
+
+
+class BaseOperation(
+    ResponseContextMixin[OptResponseContextT],
+    ResponseMixin[OptResponseT],
+    ImpersonationMixin[OptImpersonation],
+    AuthorizationMixin[OptAnyAuthorization],
+    AuthenticationMixin[OptAnyAuthentication],
+    ConnectionContextMixin[OptConnectionContextT],
+    ErrorMixin[OptAnyErrorT],
+    Success[BoolT],
+    Summary,
+    TimestampMixin,
+    ResourceMixin[OptResourceT],
+    ActionMixin[ActionT],
+    ContextMixin,
+    OperationType,
+    Id,
+    ApplicationContextMixin,
+    Generic[
+        ActionT,
+        OptResourceT,
+        BoolT,
+        OptAnyErrorT,
+        OptConnectionContextT,
+        OptResponseT,
+        OptResponseContextT,
+    ],
+):
+    @property
+    def log_message(self) -> str:
+        message = f"Operation {self.id} - {self.type} - "
+
+        success_information = "success" if self.success else "failed"
+
+        if self.response_context is not None:
+            success_information += f" {self.response_context.status_code}"
+
+        message += f"{success_information} - "
+
+        duration: float = self.timestamp.duration
+        if duration < 1:
+            duration_str = f"{int(duration * 1000)}ms"
+        else:
+            duration_str = f"{duration:.2f}s"
+
+        message += f"{duration_str} - "
+
+        if self.connection_context is not None:
+            message += (
+                f"{self.connection_context.method} {self.connection_context.url} - "
+                f"IP: {self.connection_context.ip_address} - "
+            )
+
+        if self.authentication is None:
+            authentication = "No Authentication"
+        else:
+            if not self.authentication.user.is_authenticated:
+                authentication = "Unauthenticated"
+            else:
+                authentication = (
+                    "Authenticated | "
+                    f"Organization: {self.authentication.user.organization} | "
+                    f"Username: {self.authentication.user.display_name} | "
+                    f"Email: {self.authentication.user.identity}"
+                )
+
+        message += f"{authentication} - "
+        message += self.summary
+
+        return message
+
+    @property
+    def labels(self) -> StrToStrDict:
+        labels = {
+            "environment": self.application_context.environment,
+            "service_key": self.application_context.service_key,
+            "instance_id": self.application_context.instance_id,
+            "operation_id": str(self.id),
+            "operation_type": self.type,
+            "success": str(self.success),
+        }
+
+        if self.connection_context is not None:
+            if self.connection_context.method is not None:
+                labels["method"] = self.connection_context.method
+            labels["url"] = self.connection_context.url
+        if self.response_context is not None:
+            labels["status_code"] = str(self.response_context.status_code)
+
+        return labels
+
+    def log_labels(
+        self,
+        *,
+        additional_labels: OptStrToStrDict = None,
+        override_labels: OptStrToStrDict = None,
+    ) -> StrToStrDict:
+        if override_labels is not None:
+            return override_labels
+
+        labels = self.labels
+        if additional_labels is not None:
+            for k, v in additional_labels.items():
+                if k in labels.keys():
+                    raise ValueError(
+                        f"Key '{k}' already exist in labels, override the labels if necessary"
+                    )
+                labels[k] = v
+            labels = merge_dicts(labels, additional_labels)
+        return labels
+
+    def log_extra(
+        self,
+        *,
+        additional_extra: OptStrToStrDict = None,
+        override_extra: OptStrToStrDict = None,
+        additional_labels: OptStrToStrDict = None,
+        override_labels: OptStrToStrDict = None,
+    ) -> StrToAnyDict:
+        labels = self.log_labels(
+            additional_labels=additional_labels, override_labels=override_labels
+        )
+
+        if override_extra is not None:
+            extra = override_extra
+        else:
+            extra = {
+                "json_fields": {"operation": self.model_dump(mode="json")},
+                "labels": labels,
+            }
+            if additional_extra is not None:
+                extra = merge_dicts(extra, additional_extra)
+
+        return extra
+
+    def log(
+        self,
+        logger: Logger,
+        level: LogLevel,
+        *,
+        exc_info: OptBool = None,
+        additional_extra: OptStrToStrDict = None,
+        override_extra: OptStrToStrDict = None,
+        additional_labels: OptStrToStrDict = None,
+        override_labels: OptStrToStrDict = None,
+    ):
+        try:
+            message = self.log_message
+            extra = self.log_extra(
+                additional_extra=additional_extra,
+                override_extra=override_extra,
+                additional_labels=additional_labels,
+                override_labels=override_labels,
+            )
+            logger.log(
+                level,
+                message,
+                exc_info=exc_info,
+                extra=extra,
+            )
+        except Exception as e:
+            labels = self.log_labels(
+                additional_labels=additional_labels, override_labels=override_labels
+            )
+            logger.error(
+                f"Failed logging {self.type} Operation {self.id}",
+                exc_info=True,
+                extra={
+                    "json_fields": {"exc_details": extract_details(e)},
+                    "labels": labels,
+                },
+            )
+
+    @cached_property
+    def allowed_to_publish(self) -> bool:
+        # 1. Read from env (comma-separated string)
+        raw_value = (
+            os.getenv("PUBLISHABLE_OPERATIONS", "")
+            .strip()
+            .removeprefix("[")
+            .removesuffix("]")
+            .replace(" ", "")
+        )
+
+        # 2. Parse into list of OperationType
+        publishable_ops: ListOfOperationTypes = []
+        if raw_value:
+            for v in raw_value.split(","):
+                v = v.strip().replace('"', "").lower()
+                try:
+                    publishable_ops.append(OperationTypeEnum(v))
+                except ValueError:
+                    continue  # ignore invalid values
+
+        # 3. Check if self.type is allowed
+        return self.type in publishable_ops
+
+    def publish(
+        self,
+        logger: Logger,
+        publishers: ListOfPublisherHandlers = [],
+        *,
+        additional_labels: OptStrToStrDict = None,
+        override_labels: OptStrToStrDict = None,
+    ) -> list[Future]:
+        if not self.allowed_to_publish:
+            return []
+
+        labels = self.log_labels(
+            additional_labels=additional_labels, override_labels=override_labels
+        )
+        futures: list[Future] = []
+        for publisher in publishers:
+            topic_path = publisher.client.topic_path(
+                publisher.project_id, publisher.topic_id
+            )
+            try:
+                future: Future = publisher.client.publish(
+                    topic_path,
+                    data=self.model_dump_json().encode(),
+                    **self.application_context.model_dump(mode="json"),
+                )
+                message_id: str = future.result()
+
+                logger.debug(
+                    f"Successfully published {self.type} Operation {self.id} message {message_id} to {topic_path}",
+                    extra={
+                        "json_fields": {
+                            "operation": self.model_dump(mode="json"),
+                            "message_id": message_id,
+                            "topic_path": topic_path,
+                        },
+                        "labels": labels,
+                    },
+                )
+
+                futures.append(future)
+            except Exception as e:
+                logger.error(
+                    f"Failed publishing {self.type} Operation {self.id}",
+                    exc_info=True,
+                    extra={
+                        "json_fields": {"exc_details": extract_details(e)},
+                        "labels": labels,
+                    },
+                )
+                raise
+
+        return futures

nexo/schemas/operation/constants.py

@@ -0,0 +1,18 @@
+from typing import Mapping
+from nexo.enums.status import DataStatus, SeqOfDataStatuses
+from .enums import ResourceOperationStatusUpdateType
+
+
+STATUS_UPDATE_RULES: Mapping[ResourceOperationStatusUpdateType, SeqOfDataStatuses] = {
+    ResourceOperationStatusUpdateType.DELETE: (DataStatus.INACTIVE, DataStatus.ACTIVE),
+    ResourceOperationStatusUpdateType.RESTORE: (DataStatus.DELETED,),
+    ResourceOperationStatusUpdateType.DEACTIVATE: (DataStatus.ACTIVE,),
+    ResourceOperationStatusUpdateType.ACTIVATE: (DataStatus.INACTIVE,),
+}
+
+STATUS_UPDATE_RESULT: Mapping[ResourceOperationStatusUpdateType, DataStatus] = {
+    ResourceOperationStatusUpdateType.DELETE: DataStatus.DELETED,
+    ResourceOperationStatusUpdateType.RESTORE: DataStatus.ACTIVE,
+    ResourceOperationStatusUpdateType.DEACTIVATE: DataStatus.INACTIVE,
+    ResourceOperationStatusUpdateType.ACTIVATE: DataStatus.ACTIVE,
+}