julee 0.1.0__py3-none-any.whl

julee/util/domain.py

@@ -0,0 +1,119 @@
+from pydantic import (
+    BaseModel,
+    Field,
+    field_validator,
+)
+from typing import Optional, Dict
+from datetime import datetime, timezone
+
+
+class FileMetadata(BaseModel):
+    """Metadata about a stored file."""
+
+    file_id: str
+    filename: Optional[str] = None
+    content_type: Optional[str] = None
+    size_bytes: Optional[int] = None
+    uploaded_at: str = Field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat()
+    )
+    metadata: Dict[str, str] = Field(default_factory=dict)
+
+
+class FileUploadArgs(BaseModel):
+    """
+    Arguments for file upload with security validation.
+
+    This model enforces security constraints at the domain level,
+    ensuring that all file uploads are validated before reaching
+    the repository layer.
+    """
+
+    file_id: str
+    filename: str
+    data: bytes
+    content_type: str
+    metadata: dict = Field(default_factory=dict)
+
+    @field_validator("filename")
+    @classmethod
+    def validate_filename(cls, v: str) -> str:
+        """Validate and sanitize filename to prevent path traversal
+        attacks."""
+        import os
+
+        if not v or not v.strip():
+            raise ValueError("Filename cannot be empty")
+
+        # Remove any path components to prevent directory traversal
+        sanitized = os.path.basename(v.strip())
+
+        # Check for dangerous patterns
+        dangerous_patterns = [
+            "..",
+            "~",
+            "$",
+            "`",
+            "|",
+            "&",
+            ";",
+            "(",
+            ")",
+            "{",
+            "}",
+            "[",
+            "]",
+        ]
+        for pattern in dangerous_patterns:
+            if pattern in sanitized:
+                raise ValueError(f"Filename contains dangerous pattern: {pattern}")
+
+        # Ensure filename has reasonable length
+        if len(sanitized) > 255:
+            raise ValueError("Filename too long (max 255 characters)")
+
+        # Ensure filename is not empty after sanitization
+        if not sanitized:
+            raise ValueError("Filename is empty after sanitization")
+
+        return sanitized
+
+    @field_validator("data")
+    @classmethod
+    def validate_file_size(cls, v: bytes) -> bytes:
+        """Validate file size to prevent resource exhaustion."""
+        max_size = 50 * 1024 * 1024  # 50MB limit
+        if len(v) > max_size:
+            raise ValueError(
+                f"File size {len(v)} bytes exceeds maximum allowed size of "
+                f"{max_size} bytes"
+            )
+
+        if len(v) == 0:
+            raise ValueError("File cannot be empty")
+
+        return v
+
+    @field_validator("content_type")
+    @classmethod
+    def validate_content_type(cls, v: str) -> str:
+        """Validate content type against allowed types."""
+        allowed_types = {
+            "text/plain",
+            "text/csv",
+            "application/json",
+            "application/pdf",
+            "image/jpeg",
+            "image/png",
+            "image/gif",
+            "application/zip",
+            "application/octet-stream",
+        }
+
+        if v not in allowed_types:
+            raise ValueError(
+                f"Content type '{v}' not allowed. Allowed types: "
+                f"{', '.join(sorted(allowed_types))}"
+            )
+
+        return v

julee/util/repos/minio/file_storage.py

@@ -0,0 +1,213 @@
+import io
+import logging
+import os
+from typing import Optional
+
+from minio import Minio  # type: ignore[import-untyped]
+from minio.error import S3Error  # type: ignore[import-untyped]
+
+from julee.util.domain import FileMetadata, FileUploadArgs
+from julee.util.repositories import FileStorageRepository
+
+logger = logging.getLogger(__name__)
+
+
+class MinioFileStorageRepository(FileStorageRepository):
+    """
+    Minio implementation of FileStorageRepository.
+    Uses Minio for persistence of large files/payloads.
+    """
+
+    def __init__(
+        self,
+        endpoint: Optional[str] = None,
+        access_key: Optional[str] = None,
+        secret_key: Optional[str] = None,
+        secure: bool = False,
+        bucket_name: Optional[str] = None,
+    ):
+        self._endpoint = (
+            endpoint
+            if endpoint is not None
+            else os.environ.get("MINIO_ENDPOINT", "localhost:9000")
+        )
+        self._access_key = (
+            access_key
+            if access_key is not None
+            else os.environ.get("MINIO_ROOT_USER", "minioadmin")
+        )
+        self._secret_key = (
+            secret_key
+            if secret_key is not None
+            else os.environ.get("MINIO_ROOT_PASSWORD", "minioadmin")
+        )
+        self._secure = secure
+        self._bucket_name = (
+            bucket_name
+            if bucket_name is not None
+            else os.environ.get("MINIO_BUCKET_NAME", "file-storage")
+        )
+
+        self._client: Optional[Minio] = None
+        logger.debug(
+            "MinioFileStorageRepository initialized",
+            extra={
+                "endpoint": self._endpoint,
+                "bucket_name": self._bucket_name,
+            },
+        )
+
+    async def _get_client(self) -> Minio:
+        """Lazily initialize and return the Minio client."""
+        if self._client is None:
+            logger.debug(
+                "Creating new Minio client instance",
+                extra={"endpoint": self._endpoint, "secure": self._secure},
+            )
+            self._client = Minio(
+                self._endpoint,
+                access_key=self._access_key,
+                secret_key=self._secret_key,
+                secure=self._secure,
+            )
+            try:
+                # Ensure bucket exists
+                if not self._client.bucket_exists(self._bucket_name):
+                    logger.info(
+                        "Minio bucket does not exist, creating now",
+                        extra={"bucket_name": self._bucket_name},
+                    )
+                    self._client.make_bucket(self._bucket_name)
+                else:
+                    logger.debug(
+                        "Minio bucket already exists",
+                        extra={"bucket_name": self._bucket_name},
+                    )
+            except S3Error as e:
+                logger.error(
+                    f"Error checking or creating Minio bucket: {e}",
+                    extra={
+                        "bucket_name": self._bucket_name,
+                        "error_code": e.code,
+                    },
+                )
+                raise
+        return self._client
+
+    async def upload_file(self, args: FileUploadArgs) -> FileMetadata:
+        """Upload a file to Minio storage."""
+        client = await self._get_client()
+        logger.info(
+            "Uploading file to Minio",
+            extra={
+                "file_id": args.file_id,
+                "filename": args.filename,
+                "content_type": args.content_type,
+                "size_bytes": len(args.data),
+            },
+        )
+        try:
+            # Minio put_object is idempotent if object name is the same
+            client.put_object(
+                self._bucket_name,
+                args.file_id,
+                io.BytesIO(args.data),
+                len(args.data),
+                content_type=args.content_type,
+                metadata=args.metadata,
+            )
+            logger.info(
+                "File uploaded successfully to Minio",
+                extra={"file_id": args.file_id},
+            )
+            return FileMetadata(
+                file_id=args.file_id,
+                filename=args.filename,
+                content_type=args.content_type,
+                size_bytes=len(args.data),
+                metadata=args.metadata,
+            )
+        except S3Error as e:
+            logger.error(
+                f"Error uploading file to Minio: {e}",
+                extra={"file_id": args.file_id, "error_code": e.code},
+            )
+            raise
+
+    async def download_file(self, file_id: str) -> Optional[bytes]:
+        """Download a file from Minio storage by its ID."""
+        client = await self._get_client()
+        logger.info(
+            "Attempting to download file from Minio",
+            extra={"file_id": file_id},
+        )
+        try:
+            response = client.get_object(self._bucket_name, file_id)
+            file_data: bytes = response.read()
+            response.close()
+            response.release_conn()
+            logger.info(
+                "File downloaded successfully from Minio",
+                extra={"file_id": file_id, "size_bytes": len(file_data)},
+            )
+            return file_data
+        except S3Error as e:
+            if e.code == "NoSuchKey":
+                logger.warning("File not found in Minio", extra={"file_id": file_id})
+                return None
+            logger.error(
+                f"Error downloading file from Minio: {e}",
+                extra={"file_id": file_id, "error_code": e.code},
+            )
+            raise
+
+    async def get_file_metadata(self, file_id: str) -> Optional[FileMetadata]:
+        """Retrieve metadata for a stored file from Minio."""
+        client = await self._get_client()
+        logger.info(
+            "Attempting to get file metadata from Minio",
+            extra={"file_id": file_id},
+        )
+        try:
+            stat = client.stat_object(self._bucket_name, file_id)
+            logger.info(
+                "File metadata retrieved successfully from Minio",
+                extra={
+                    "file_id": file_id,
+                    "size_bytes": stat.size,
+                    "content_type": stat.content_type,
+                },
+            )
+            uploaded_at_str: Optional[str] = (
+                stat.last_modified.isoformat() if stat.last_modified else None
+            )
+            # Extract filename and metadata more explicitly
+            filename = (
+                stat.metadata.get("X-Amz-Meta-Filename") if stat.metadata else None
+            )
+            metadata = (
+                {k.replace("X-Amz-Meta-", ""): v for k, v in stat.metadata.items()}
+                if stat.metadata
+                else {}
+            )
+
+            return FileMetadata(
+                file_id=file_id,
+                filename=filename,  # Minio prepends X-Amz-Meta-
+                content_type=stat.content_type,
+                size_bytes=stat.size,
+                uploaded_at=uploaded_at_str or "",  # Provide empty string if None
+                metadata=metadata,
+            )
+        except S3Error as e:
+            if e.code == "NoSuchKey":
+                logger.warning(
+                    "File metadata not found in Minio",
+                    extra={"file_id": file_id},
+                )
+                return None
+            logger.error(
+                f"Error getting file metadata from Minio: {e}",
+                extra={"file_id": file_id, "error_code": e.code},
+            )
+            raise

julee/util/repos/temporal/__init__.py

@@ -0,0 +1,11 @@
+"""
+Temporal repository utilities.
+
+This module provides utilities for working with Temporal repositories,
+including the temporal_activity_registration decorator for automatically
+wrapping repository methods as Temporal activities.
+"""
+
+from julee.util.temporal.decorators import temporal_activity_registration
+
+__all__ = ["temporal_activity_registration"]

julee/util/repos/temporal/client_proxies/file_storage.py

@@ -0,0 +1,68 @@
+import logging
+from typing import Optional
+
+from temporalio.client import Client
+
+from julee.util.domain import FileMetadata, FileUploadArgs
+from julee.util.repositories import FileStorageRepository
+
+logger = logging.getLogger(__name__)
+
+
+class TemporalFileStorageRepository(FileStorageRepository):
+    """
+    Client-side proxy for FileStorageRepository that calls activities.
+    This proxy ensures that all interactions with the FileStorageRepository
+    are performed via Temporal activities, maintaining workflow determinism.
+    """
+
+    def __init__(
+        self,
+        client: Client,
+        concrete_repo: Optional[FileStorageRepository] = None,
+    ):
+        self.client = client
+        self.concrete_repo = concrete_repo
+        logger.debug("Initialized TemporalFileStorageRepository")
+
+    async def upload_file(self, args: FileUploadArgs) -> FileMetadata:
+        """Upload a file via Temporal activity."""
+        logger.debug(f"Client calling activity to upload file: {args.file_id}")
+
+        handle = await self.client.start_workflow(
+            "util.file_storage.minio.upload_file",
+            args,
+            id=f"upload-{args.file_id}",
+            task_queue="order-fulfillment-queue",
+        )
+
+        result = await handle.result()
+        return result  # type: ignore[no-any-return]
+
+    async def download_file(self, file_id: str) -> Optional[bytes]:
+        """Download a file via Temporal activity."""
+        logger.debug(f"Client calling activity to download file: {file_id}")
+
+        handle = await self.client.start_workflow(
+            "util.file_storage.minio.download_file",
+            file_id,
+            id=f"download-{file_id}",
+            task_queue="order-fulfillment-queue",
+        )
+
+        result = await handle.result()
+        return result  # type: ignore[no-any-return]
+
+    async def get_file_metadata(self, file_id: str) -> Optional[FileMetadata]:
+        """Retrieve file metadata via Temporal activity."""
+        logger.debug(f"Client calling activity to get file metadata: {file_id}")
+
+        handle = await self.client.start_workflow(
+            "util.file_storage.minio.get_file_metadata",
+            file_id,
+            id=f"metadata-{file_id}",
+            task_queue="order-fulfillment-queue",
+        )
+
+        result = await handle.result()
+        return result  # type: ignore[no-any-return]

julee/util/repos/temporal/data_converter.py

@@ -0,0 +1,123 @@
+"""
+Custom Temporal data converter with support for temporal_validation context.
+
+This module provides a custom Pydantic data converter that automatically
+adds temporal_validation=True context when deserializing Pydantic models.
+This allows domain models to implement context-aware validation that can
+be more permissive during Temporal serialization/deserialization.
+"""
+
+from typing import Any, Optional, Type
+
+from pydantic import TypeAdapter
+from temporalio.contrib.pydantic import (
+    PydanticJSONPlainPayloadConverter,
+    ToJsonOptions,
+)
+from temporalio.converter import (
+    DataConverter,
+    CompositePayloadConverter,
+    DefaultPayloadConverter,
+    JSONPlainPayloadConverter,
+)
+import temporalio.api.common.v1
+
+
+class TemporalValidationPydanticConverter(PydanticJSONPlainPayloadConverter):
+    """Custom Pydantic JSON converter that adds temporal_validation context.
+
+    This converter extends the standard PydanticJSONPlainPayloadConverter
+    to automatically add temporal_validation=True context when deserializing
+    Pydantic models. This allows domain models to implement more permissive
+    validation during Temporal operations while maintaining strict validation
+    for direct instantiation.
+    """
+
+    def from_payload(
+        self,
+        payload: temporalio.api.common.v1.Payload,
+        type_hint: Optional[Type] = None,
+    ) -> Any:
+        """Deserialize payload with temporal_validation context.
+
+        This method overrides the base implementation to always add
+        temporal_validation=True to the validation context. This allows
+        Pydantic models to detect when they're being deserialized by
+        Temporal and apply appropriate validation rules.
+
+        Args:
+            payload: The Temporal payload to deserialize
+            type_hint: Optional type hint for the expected return type
+
+        Returns:
+            Deserialized object with temporal validation context applied
+        """
+        # Convert Optional[Type] to Type, defaulting to Any (same as original)
+        _type_hint = type_hint if type_hint is not None else Any
+
+        # Always add temporal_validation context for Pydantic model validation
+        return TypeAdapter(_type_hint).validate_json(
+            payload.data, context={"temporal_validation": True}
+        )
+
+
+class TemporalValidationPayloadConverter(CompositePayloadConverter):
+    """Custom payload converter that uses temporal validation context.
+
+    This payload converter extends CompositePayloadConverter to use our
+    custom TemporalValidationPydanticConverter for JSON serialization,
+    ensuring all Pydantic models get temporal_validation context.
+    """
+
+    def __init__(self, to_json_options: Optional[ToJsonOptions] = None) -> None:
+        """Initialize with custom JSON converter adding temporal context."""
+        # Create our custom JSON converter with temporal validation
+        json_payload_converter = TemporalValidationPydanticConverter(to_json_options)
+
+        # Initialize CompositePayloadConverter, replacing JSON converter
+
+        super().__init__(
+            *(
+                (
+                    c
+                    if not isinstance(c, JSONPlainPayloadConverter)
+                    else json_payload_converter
+                )
+                for c in (DefaultPayloadConverter.default_encoding_payload_converters)
+            )
+        )
+
+
+def create_temporal_data_converter(
+    to_json_options: Optional[ToJsonOptions] = None,
+) -> DataConverter:
+    """Create a data converter with temporal validation support.
+
+    This factory function creates a DataConverter that uses our custom
+    TemporalValidationPayloadConverter for serialization. This
+    ensures that all Pydantic models are deserialized with the
+    temporal_validation context.
+
+    Args:
+        to_json_options: Optional configuration for JSON serialization
+
+    Returns:
+        DataConverter configured with temporal validation support
+    """
+    return DataConverter(payload_converter_class=TemporalValidationPayloadConverter)
+
+
+# Default temporal data converter with validation context support
+temporal_data_converter = create_temporal_data_converter()
+"""Default Temporal data converter with temporal_validation context support.
+
+This data converter automatically adds temporal_validation=True context
+when deserializing Pydantic models, allowing domain models to implement
+context-aware validation rules.
+
+Usage:
+    client = Client(
+        data_converter=temporal_data_converter,
+        ...
+    )
+"""

julee/util/repos/temporal/minio_file_storage.py

@@ -0,0 +1,12 @@
+from julee.util.temporal.decorators import temporal_activity_registration
+from julee.util.repos.minio.file_storage import MinioFileStorageRepository
+
+
+@temporal_activity_registration("util.file_storage.minio")
+class TemporalMinioFileStorageRepository(MinioFileStorageRepository):
+    """
+    Temporal activity wrapper for MinioFileStorageRepository.
+    All async methods automatically wrapped as activities.
+    """
+
+    pass

julee/util/repos/temporal/proxies/file_storage.py

@@ -0,0 +1,58 @@
+import logging
+from typing import Optional
+
+from temporalio import workflow
+
+from julee.util.domain import FileMetadata, FileUploadArgs
+from julee.util.repositories import FileStorageRepository
+
+logger = logging.getLogger(__name__)
+
+
+class WorkflowFileStorageRepositoryProxy(FileStorageRepository):
+    """
+    Workflow implementation of FileStorageRepository that calls activities.
+    This proxy ensures that all interactions with the FileStorageRepository
+    are performed via Temporal activities, maintaining workflow determinism.
+    """
+
+    def __init__(self) -> None:
+        # Activity timeout can be configured, but for simplicity, we use a
+        # default here or could retrieve from workflow config.
+        # This timeout should be generous enough for large file transfers.
+        self.activity_timeout = workflow.timedelta(seconds=600)  # 10 minutes
+        logger.debug("Initialized WorkflowFileStorageRepositoryProxy")
+
+    async def upload_file(self, args: FileUploadArgs) -> FileMetadata:
+        """Upload a file to storage via Temporal activity."""
+        logger.debug(f"Workflow calling activity to upload file: {args.file_id}")
+        # The activity name follows the general util pattern:
+        # {domain}.{subdomain}.{implementation}.{method}
+        result = await workflow.execute_activity(
+            "util.file_storage.minio.upload_file",
+            args,
+            start_to_close_timeout=self.activity_timeout,
+        )
+        return FileMetadata.model_validate(result)
+
+    async def download_file(self, file_id: str) -> Optional[bytes]:
+        """Download a file from storage via Temporal activity."""
+        logger.debug(f"Workflow calling activity to download file: {file_id}")
+        result = await workflow.execute_activity(
+            "util.file_storage.minio.download_file",
+            file_id,
+            start_to_close_timeout=self.activity_timeout,
+        )
+        return result  # type: ignore[no-any-return]
+
+    async def get_file_metadata(self, file_id: str) -> Optional[FileMetadata]:
+        """Retrieve file metadata via Temporal activity."""
+        logger.debug(f"Workflow calling activity to get file metadata: {file_id}")
+        result = await workflow.execute_activity(
+            "util.file_storage.minio.get_file_metadata",
+            file_id,
+            start_to_close_timeout=self.activity_timeout,
+        )
+        if result is None:
+            return None
+        return FileMetadata.model_validate(result)

julee/util/repositories.py

@@ -0,0 +1,55 @@
+from typing import Protocol, Optional, runtime_checkable
+from julee.util.domain import FileMetadata, FileUploadArgs
+
+
+@runtime_checkable
+class FileStorageRepository(Protocol):
+    """Handles storage and retrieval of large files/payloads.
+
+    Architectural Purpose:
+    This repository is designed to manage large data payloads that might
+    exceed Temporal's payload size limits or are better stored externally.
+    It allows workflows to store references to files rather than the files
+    themselves, maintaining workflow determinism while handling large data.
+    """
+
+    async def upload_file(self, args: FileUploadArgs) -> FileMetadata:
+        """Upload a file to storage.
+
+        Args:
+            args: FileUploadArgs containing file_id, data, and metadata.
+
+        Returns:
+            FileMetadata object with details about the uploaded file.
+
+        Implementation Notes:
+        - Must be idempotent: uploading the same file_id multiple times is
+          safe.
+        - Should return metadata including the actual size and content type.
+        - Must perform security validation: file size limits, content type
+          verification, and filename sanitization.
+        - Should reject files that don't match declared content type.
+        """
+        ...
+
+    async def download_file(self, file_id: str) -> Optional[bytes]:
+        """Download a file from storage by its ID.
+
+        Args:
+            file_id: Unique identifier of the file.
+
+        Returns:
+            File content as bytes if found, None otherwise.
+        """
+        ...
+
+    async def get_file_metadata(self, file_id: str) -> Optional[FileMetadata]:
+        """Retrieve metadata for a stored file.
+
+        Args:
+            file_id: Unique identifier of the file.
+
+        Returns:
+            FileMetadata object if found, None otherwise.
+        """
+        ...

julee/util/temporal/__init__.py

@@ -0,0 +1,22 @@
+"""
+Temporal utilities package.
+
+This package provides utility functions and classes for working with
+Temporal workflows and activities.
+"""
+
+from .activities import (
+    collect_activities_from_instances,
+    discover_protocol_methods,
+)
+from .decorators import (
+    temporal_activity_registration,
+    temporal_workflow_proxy,
+)
+
+__all__ = [
+    "collect_activities_from_instances",
+    "discover_protocol_methods",
+    "temporal_activity_registration",
+    "temporal_workflow_proxy",
+]