nexo-schemas 0.0.16__py3-none-any.whl

nexo/schemas/operation/context.py

@@ -0,0 +1,68 @@
+from pydantic import BaseModel, Field
+from typing import Generic
+from nexo.types.dict import OptStrToAnyDict
+from nexo.types.enum import StrEnumT
+from .enums import (
+    Origin as OriginEnum,
+    Layer as LayerEnum,
+    Target as TargetEnum,
+)
+
+
+class Component(BaseModel, Generic[StrEnumT]):
+    type: StrEnumT = Field(..., description="Component's type")
+    details: OptStrToAnyDict = Field(None, description="Component's details")
+
+
+class Origin(Component[OriginEnum]):
+    pass
+
+
+class OriginMixin(BaseModel):
+    origin: Origin = Field(..., description="Operation's origin")
+
+
+class Layer(Component[LayerEnum]):
+    pass
+
+
+class LayerMixin(BaseModel):
+    layer: Layer = Field(..., description="Operation's layer")
+
+
+class Target(Component[TargetEnum]):
+    pass
+
+
+class TargetMixin(BaseModel):
+    target: Target = Field(..., description="Operation's target")
+
+
+class Context(TargetMixin, LayerMixin, OriginMixin):
+    pass
+
+
+class ContextMixin(BaseModel):
+    context: Context = Field(..., description="Operation's context")
+
+
+UTILITY_OPERATION_CONTEXT = Context(
+    origin=Origin(type=OriginEnum.UTILITY, details=None),
+    layer=Layer(type=LayerEnum.INTERNAL, details=None),
+    target=Target(type=TargetEnum.INTERNAL, details=None),
+)
+
+
+def generate(
+    origin: OriginEnum,
+    layer: LayerEnum,
+    target: TargetEnum = TargetEnum.INTERNAL,
+    origin_details: OptStrToAnyDict = None,
+    layer_details: OptStrToAnyDict = None,
+    target_details: OptStrToAnyDict = None,
+) -> Context:
+    return Context(
+        origin=Origin(type=origin, details=origin_details),
+        layer=Layer(type=layer, details=layer_details),
+        target=Target(type=target, details=target_details),
+    )

nexo/schemas/operation/dependency.py

@@ -0,0 +1,26 @@
+from fastapi import Header
+from fastapi.requests import HTTPConnection
+from typing import Callable
+from uuid import UUID
+from nexo.enums.connection import Header as HeaderEnum
+from nexo.types.uuid import OptUUID
+from .enums import IdSource
+from .extractor import extract_operation_id
+
+
+def get_operation_id(
+    source: IdSource = IdSource.STATE, *, generate: bool = False
+) -> Callable[..., UUID]:
+
+    def dependency(
+        conn: HTTPConnection,
+        # the following operation_id is for documentation purpose only
+        _operation_id: OptUUID = Header(
+            None,
+            alias=HeaderEnum.X_OPERATION_ID.value,
+            description="Operation's ID",
+        ),
+    ) -> UUID:
+        return extract_operation_id(source, conn=conn, generate=generate)
+
+    return dependency

nexo/schemas/operation/enums.py

@@ -0,0 +1,168 @@
+from enum import StrEnum
+from typing import TypeVar
+from nexo.types.string import ListOfStrs
+
+
+class IdSource(StrEnum):
+    HEADER = "header"
+    STATE = "state"
+
+    @classmethod
+    def choices(cls) -> ListOfStrs:
+        return [e.value for e in cls]
+
+
+class OperationType(StrEnum):
+    RESOURCE = "resource"
+    REQUEST = "request"
+    SYSTEM = "system"
+    WEBSOCKET = "websocket"
+
+    @classmethod
+    def choices(cls) -> ListOfStrs:
+        return [e.value for e in cls]
+
+
+OptOperationType = OperationType | None
+ListOfOperationTypes = list[OperationType]
+
+
+class SystemOperationType(StrEnum):
+    BACKGROUND_JOB = "background_job"
+    CONFIGURATION_UPDATE = "configuration_update"
+    CRON_JOB = "cron_job"
+    DATABASE_CONNECTION = "database_connection"
+    DISPOSAL = "disposal"
+    HEALTH_CHECK = "health_check"
+    HEARTBEAT = "heartbeat"
+    METRIC_REPORT = "metric_report"
+    INITIALIZATION = "initialization"
+    STARTUP = "startup"
+    SHUTDOWN = "shutdown"
+    SYSTEM_ALERT = "system_alert"
+
+    @classmethod
+    def choices(cls) -> ListOfStrs:
+        return [e.value for e in cls]
+
+
+OptSystemOperationType = SystemOperationType | None
+
+
+class WebSocketOperationType(StrEnum):
+    CONNECT = "connect"
+    DISCONNECT = "disconnect"
+    ERROR = "error"
+    RECEIVE = "receive"
+    SEND = "send"
+
+    @classmethod
+    def choices(cls) -> ListOfStrs:
+        return [e.value for e in cls]
+
+
+OptWebSocketOperationType = WebSocketOperationType | None
+
+
+class ResourceOperationType(StrEnum):
+    CREATE = "create"
+    READ = "read"
+    UPDATE = "update"
+    DELETE = "delete"
+
+    @classmethod
+    def choices(cls) -> ListOfStrs:
+        return [e.value for e in cls]
+
+
+ResourceOperationTypeT = TypeVar("ResourceOperationTypeT", bound=ResourceOperationType)
+OptResourceOperationType = ResourceOperationType | None
+
+
+class ResourceOperationUpdateType(StrEnum):
+    DATA = "data"
+    STATUS = "status"
+
+    @classmethod
+    def choices(cls) -> ListOfStrs:
+        return [e.value for e in cls]
+
+
+OptResourceOperationUpdateType = ResourceOperationUpdateType | None
+
+
+class ResourceOperationDataUpdateType(StrEnum):
+    FULL = "full"
+    PARTIAL = "partial"
+
+    @classmethod
+    def choices(cls) -> ListOfStrs:
+        return [e.value for e in cls]
+
+
+OptResourceOperationDataUpdateType = ResourceOperationDataUpdateType | None
+
+
+class ResourceOperationStatusUpdateType(StrEnum):
+    ACTIVATE = "activate"
+    DEACTIVATE = "deactivate"
+    RESTORE = "restore"
+    DELETE = "delete"
+
+    @classmethod
+    def choices(cls) -> ListOfStrs:
+        return [e.value for e in cls]
+
+
+OptResourceOperationStatusUpdateType = ResourceOperationStatusUpdateType | None
+
+
+class Origin(StrEnum):
+    SERVICE = "service"
+    CLIENT = "client"
+    UTILITY = "utility"
+
+    @classmethod
+    def choices(cls) -> ListOfStrs:
+        return [e.value for e in cls]
+
+
+OptOrigin = Origin | None
+
+
+class Layer(StrEnum):
+    INFRASTRUCTURE = "infrastructure"
+    CONFIGURATION = "configuration"
+    UTILITY = "utility"
+    MIDDLEWARE = "middleware"
+    CONTROLLER = "controller"
+    SERVICE = "service"
+    REPOSITORY = "repository"
+    INTERNAL = "internal"
+    OTHER = "other"
+
+    @classmethod
+    def choices(cls) -> ListOfStrs:
+        return [e.value for e in cls]
+
+
+OptLayer = Layer | None
+
+
+class Target(StrEnum):
+    MONITORING = "monitoring"
+    CACHE = "cache"
+    CONTROLLER = "controller"
+    DATABASE = "database"
+    INTERNAL = "internal"
+    MICROSERVICE = "microservice"
+    SERVICE = "service"
+    REPOSITORY = "repository"
+    THIRD_PARTY = "third_party"
+
+    @classmethod
+    def choices(cls) -> ListOfStrs:
+        return [e.value for e in cls]
+
+
+OptLayer = Layer | None

nexo/schemas/operation/extractor.py

@@ -0,0 +1,36 @@
+from fastapi import status, HTTPException
+from fastapi.requests import HTTPConnection
+from uuid import UUID, uuid4
+from nexo.enums.connection import Header
+from .enums import IdSource
+
+
+def extract_operation_id(
+    source: IdSource = IdSource.STATE, *, conn: HTTPConnection, generate: bool = False
+) -> UUID:
+    if source is IdSource.HEADER:
+        operation_id = conn.headers.get(Header.X_OPERATION_ID.value, None)
+        try:
+            operation_id = UUID(operation_id)
+        except Exception:
+            pass
+    elif source is IdSource.STATE:
+        operation_id = getattr(conn.state, "operation_id", None)
+    if operation_id is not None and not isinstance(operation_id, UUID):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Invalid operation id: {operation_id}",
+        )
+
+    if operation_id is not None:
+        return operation_id
+
+    if generate:
+        operation_id = uuid4()
+        conn.state.operation_id = operation_id
+        return operation_id
+
+    raise HTTPException(
+        status_code=status.HTTP_400_BAD_REQUEST,
+        detail="Unable to determine operation_id",
+    )

nexo/schemas/operation/mixins.py

@@ -0,0 +1,53 @@
+from datetime import datetime, timezone
+from pydantic import BaseModel, Field, model_validator
+from typing import Annotated, Self
+from uuid import UUID
+from ..mixins.identity import UUIDId
+from ..mixins.timestamp import ExecutionTimestamp, CompletionTimestamp, Duration
+from .enums import OperationType as OperationTypeEnum
+
+
+class Id(UUIDId[UUID]):
+    pass
+
+
+class OperationType(BaseModel):
+    type: Annotated[OperationTypeEnum, Field(..., description="Operation's type")]
+
+
+class Timestamp(
+    Duration[float],
+    CompletionTimestamp[datetime],
+    ExecutionTimestamp[datetime],
+):
+    duration: Annotated[float, Field(0.0, ge=0.0, description="Duration")] = 0.0
+
+    @model_validator(mode="after")
+    def calculate_duration(self) -> Self:
+        self.duration = (self.completed_at - self.executed_at).total_seconds()
+        return self
+
+    @classmethod
+    def now(cls) -> "Timestamp":
+        now = datetime.now(tz=timezone.utc)
+        return cls(executed_at=now, completed_at=now, duration=0)
+
+    @classmethod
+    def completed_now(cls, executed_at: datetime) -> "Timestamp":
+        completed_at = datetime.now(tz=timezone.utc)
+        return cls(
+            executed_at=executed_at,
+            completed_at=completed_at,
+            duration=(completed_at - executed_at).total_seconds(),
+        )
+
+
+OptTimestamp = Timestamp | None
+
+
+class TimestampMixin(BaseModel):
+    timestamp: Annotated[Timestamp, Field(..., description="Operation's timestamp")]
+
+
+class Summary(BaseModel):
+    summary: Annotated[str, Field(..., description="Operation's summary")]