orionis 0.253.0__py3-none-any.whl → 0.266.0__py3-none-any.whl

orionis/luminate/foundation/config/roots/paths.py

@@ -0,0 +1,446 @@
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Dict
+from orionis.luminate.foundation.config.exceptions.integrity import OrionisIntegrityException
+
+@dataclass(frozen=True, kw_only=True)
+class Paths:
+    """
+    A frozen dataclass representing the canonical directory and file structure
+    for a Laravel-inspired Python project.
+
+    This class provides type-safe access to all standard project paths and includes
+    validation to ensure path integrity. All paths are relative to the project root.
+
+    Attributes are organized into logical groups:
+    - Application components (controllers, models, services)
+    - Resources (views, assets, translations)
+    - Routing configuration
+    - Configuration and database
+    - Storage locations
+    """
+
+    # --- Application Paths ---
+    console_scheduler: str = field(
+        default='app/console/kernel.py',
+        metadata={
+            'description': 'Path to the console scheduler (Kernel) file.',
+            'type': 'file',
+            'required': True
+        }
+    )
+
+    console_commands: str = field(
+        default='app/console/commands',
+        metadata={
+            'description': 'Directory containing custom Artisan-style console commands.',
+            'type': 'directory',
+            'required': True
+        }
+    )
+
+    http_controllers: str = field(
+        default='app/http/controllers',
+        metadata={
+            'description': 'Directory containing HTTP controller classes.',
+            'type': 'directory',
+            'required': True
+        }
+    )
+
+    http_middleware: str = field(
+        default='app/http/middleware',
+        metadata={
+            'description': 'Directory containing HTTP middleware classes.',
+            'type': 'directory',
+            'required': True
+        }
+    )
+
+    http_requests: str = field(
+        default='app/http/requests',
+        metadata={
+            'description': 'Directory containing HTTP form request validation classes.',
+            'type': 'directory',
+            'required': False
+        }
+    )
+
+    models: str = field(
+        default='app/models',
+        metadata={
+            'description': 'Directory containing ORM model classes.',
+            'type': 'directory',
+            'required': True
+        }
+    )
+
+    providers: str = field(
+        default='app/providers',
+        metadata={
+            'description': 'Directory containing service provider classes.',
+            'type': 'directory',
+            'required': True
+        }
+    )
+
+    events: str = field(
+        default='app/events',
+        metadata={
+            'description': 'Directory containing event classes.',
+            'type': 'directory',
+            'required': False
+        }
+    )
+
+    listeners: str = field(
+        default='app/listeners',
+        metadata={
+            'description': 'Directory containing event listener classes.',
+            'type': 'directory',
+            'required': False
+        }
+    )
+
+    notifications: str = field(
+        default='app/notifications',
+        metadata={
+            'description': 'Directory containing notification classes.',
+            'type': 'directory',
+            'required': False
+        }
+    )
+
+    jobs: str = field(
+        default='app/jobs',
+        metadata={
+            'description': 'Directory containing queued job classes.',
+            'type': 'directory',
+            'required': False
+        }
+    )
+
+    policies: str = field(
+        default='app/policies',
+        metadata={
+            'description': 'Directory containing authorization policy classes.',
+            'type': 'directory',
+            'required': False
+        }
+    )
+
+    exceptions: str = field(
+        default='app/exceptions',
+        metadata={
+            'description': 'Directory containing exception handler classes.',
+            'type': 'directory',
+            'required': True
+        }
+    )
+
+    services: str = field(
+        default='app/services',
+        metadata={
+            'description': 'Directory containing business logic service classes.',
+            'type': 'directory',
+            'required': False
+        }
+    )
+
+    # --- Resource Paths ---
+    views: str = field(
+        default='resources/views',
+        metadata={
+            'description': 'Directory containing template view files.',
+            'type': 'directory',
+            'required': True
+        }
+    )
+
+    lang: str = field(
+        default='resources/lang',
+        metadata={
+            'description': 'Directory containing internationalization files.',
+            'type': 'directory',
+            'required': False
+        }
+    )
+
+    assets: str = field(
+        default='resources/assets',
+        metadata={
+            'description': 'Directory containing frontend assets (JS, CSS, images).',
+            'type': 'directory',
+            'required': False
+        }
+    )
+
+    # --- Routing Paths ---
+    routes_web: str = field(
+        default='routes/web.py',
+        metadata={
+            'description': 'Path to the web routes definition file.',
+            'type': 'file',
+            'required': True
+        }
+    )
+
+    routes_api: str = field(
+        default='routes/api.py',
+        metadata={
+            'description': 'Path to the API routes definition file.',
+            'type': 'file',
+            'required': False
+        }
+    )
+
+    routes_console: str = field(
+        default='routes/console.py',
+        metadata={
+            'description': 'Path to the console routes definition file.',
+            'type': 'file',
+            'required': False
+        }
+    )
+
+    routes_channels: str = field(
+        default='routes/channels.py',
+        metadata={
+            'description': 'Path to the broadcast channels routes file.',
+            'type': 'file',
+            'required': False
+        }
+    )
+
+    # --- Configuration & Database Paths ---
+    config: str = field(
+        default='config',
+        metadata={
+            'description': 'Directory containing application configuration files.',
+            'type': 'directory',
+            'required': True
+        }
+    )
+
+    migrations: str = field(
+        default='database/migrations',
+        metadata={
+            'description': 'Directory containing database migration files.',
+            'type': 'directory',
+            'required': True
+        }
+    )
+
+    seeders: str = field(
+        default='database/seeders',
+        metadata={
+            'description': 'Directory containing database seeder files.',
+            'type': 'directory',
+            'required': False
+        }
+    )
+
+    factories: str = field(
+        default='database/factories',
+        metadata={
+            'description': 'Directory containing model factory files.',
+            'type': 'directory',
+            'required': False
+        }
+    )
+
+    # --- Storage Paths ---
+    storage_logs: str = field(
+        default='storage/logs',
+        metadata={
+            'description': 'Directory containing application log files.',
+            'type': 'directory',
+            'required': True
+        }
+    )
+
+    storage_framework: str = field(
+        default='storage/framework',
+        metadata={
+            'description': 'Directory for framework-generated files (cache, sessions, views).',
+            'type': 'directory',
+            'required': True
+        }
+    )
+
+    storage_sessions: str = field(
+        default='storage/framework/sessions',
+        metadata={
+            'description': 'Directory containing session files.',
+            'type': 'directory',
+            'required': False
+        }
+    )
+
+    storage_cache: str = field(
+        default='storage/framework/cache',
+        metadata={
+            'description': 'Directory containing framework cache files.',
+            'type': 'directory',
+            'required': False
+        }
+    )
+
+    storage_views: str = field(
+        default='storage/framework/views',
+        metadata={
+            'description': 'Directory containing compiled view files.',
+            'type': 'directory',
+            'required': False
+        }
+    )
+
+    def __post_init__(self) -> None:
+        """
+        Validates all path fields after initialization.
+
+        Raises:
+            OrionisIntegrityException: If any path is invalid (empty or not a string)
+        """
+        for field_name, field_info in self.__dataclass_fields__.items():
+            value = getattr(self, field_name)
+            metadata:dict = field_info.metadata
+
+            if not isinstance(value, str) or not value.strip():
+                raise OrionisIntegrityException(
+                    f"Invalid path value for '{field_name}': {value!r}. Must be non-empty string."
+                )
+
+            if metadata.get('required', False) and not value:
+                raise OrionisIntegrityException(
+                    f"Required path '{field_name}' cannot be empty."
+                )
+
+    # --- Path Accessors ---
+    def getConsoleScheduler(self) -> Path:
+        """Get Path object for console scheduler file."""
+        return Path(self.console_scheduler)
+
+    def getConsoleCommands(self) -> Path:
+        """Get Path object for console commands directory."""
+        return Path(self.console_commands)
+
+    def getHttpControllers(self) -> Path:
+        """Get Path object for HTTP controllers directory."""
+        return Path(self.http_controllers)
+
+    def getHttpMiddleware(self) -> Path:
+        """Get Path object for HTTP middleware directory."""
+        return Path(self.http_middleware)
+
+    def getHttpRequests(self) -> Path:
+        """Get Path object for HTTP requests directory."""
+        return Path(self.http_requests)
+
+    def getModels(self) -> Path:
+        """Get Path object for models directory."""
+        return Path(self.models)
+
+    def getProviders(self) -> Path:
+        """Get Path object for service providers directory."""
+        return Path(self.providers)
+
+    def getEvents(self) -> Path:
+        """Get Path object for events directory."""
+        return Path(self.events)
+
+    def getListeners(self) -> Path:
+        """Get Path object for event listeners directory."""
+        return Path(self.listeners)
+
+    def getNotifications(self) -> Path:
+        """Get Path object for notifications directory."""
+        return Path(self.notifications)
+
+    def getJobs(self) -> Path:
+        """Get Path object for queued jobs directory."""
+        return Path(self.jobs)
+
+    def getPolicies(self) -> Path:
+        """Get Path object for authorization policies directory."""
+        return Path(self.policies)
+
+    def getExceptions(self) -> Path:
+        """Get Path object for exceptions directory."""
+        return Path(self.exceptions)
+
+    def getServices(self) -> Path:
+        """Get Path object for services directory."""
+        return Path(self.services)
+
+    def getViews(self) -> Path:
+        """Get Path object for views directory."""
+        return Path(self.views)
+
+    def getLang(self) -> Path:
+        """Get Path object for language files directory."""
+        return Path(self.lang)
+
+    def getAssets(self) -> Path:
+        """Get Path object for assets directory."""
+        return Path(self.assets)
+
+    def getRoutesWeb(self) -> Path:
+        """Get Path object for web routes file."""
+        return Path(self.routes_web)
+
+    def getRoutesApi(self) -> Path:
+        """Get Path object for API routes file."""
+        return Path(self.routes_api)
+
+    def getRoutesConsole(self) -> Path:
+        """Get Path object for console routes file."""
+        return Path(self.routes_console)
+
+    def getRoutesChannels(self) -> Path:
+        """Get Path object for broadcast channels routes file."""
+        return Path(self.routes_channels)
+
+    def getConfig(self) -> Path:
+        """Get Path object for config directory."""
+        return Path(self.config)
+
+    def getMigrations(self) -> Path:
+        """Get Path object for migrations directory."""
+        return Path(self.migrations)
+
+    def getSeeders(self) -> Path:
+        """Get Path object for seeders directory."""
+        return Path(self.seeders)
+
+    def getFactories(self) -> Path:
+        """Get Path object for model factories directory."""
+        return Path(self.factories)
+
+    def getStorageLogs(self) -> Path:
+        """Get Path object for logs directory."""
+        return Path(self.storage_logs)
+
+    def getStorageFramework(self) -> Path:
+        """Get Path object for framework storage directory."""
+        return Path(self.storage_framework)
+
+    def getStorageSessions(self) -> Path:
+        """Get Path object for sessions storage directory."""
+        return Path(self.storage_sessions)
+
+    def getStorageCache(self) -> Path:
+        """Get Path object for cache storage directory."""
+        return Path(self.storage_cache)
+
+    def getStorageViews(self) -> Path:
+        """Get Path object for compiled views storage directory."""
+        return Path(self.storage_views)
+
+    def toDict(self) -> Dict[str, str]:
+        """
+        Returns a dictionary representation of all paths.
+        Returns:
+            Dict[str, str]: Dictionary mapping field names to path strings
+        """
+        return asdict(self)

orionis/luminate/foundation/config/session/entities/session.py

@@ -0,0 +1,147 @@
+from dataclasses import asdict, dataclass, field
+from typing import Optional
+from orionis.luminate.foundation.config.exceptions.integrity import OrionisIntegrityException
+from orionis.luminate.foundation.config.session.enums.same_site_policy import SameSitePolicy
+from orionis.luminate.foundation.config.session.helpers.secret_key import SecretKey
+from orionis.luminate.services.environment.env import Env
+
+@dataclass(unsafe_hash=True, kw_only=True)
+class Session:
+    """
+    Configuration for Starlette session middleware.
+
+    Attributes:
+        secret_key (str): Secret key for signing session cookies (required).
+        session_cookie (str): Name of the session cookie. Defaults to 'session'.
+        max_age (Optional[int]): Session expiration in seconds. None for browser session.
+        same_site (Literal['lax', 'strict', 'none']): SameSite cookie policy.
+        path (str): Cookie path. Defaults to '/'.
+        https_only (bool): Restrict cookies to HTTPS. Defaults to False.
+        domain (Optional[str]): Cookie domain for cross-subdomain usage.
+    """
+    secret_key: str = field(
+        default_factory=lambda: Env.get('APP_KEY', SecretKey.random()),
+        metadata={
+            "description": "Secret key for signing session cookies (required).",
+            "default": "APP_KEY"
+        }
+    )
+
+    session_cookie: str = field(
+        default_factory=lambda: Env.get('SESSION_COOKIE_NAME', 'orionis_session'),
+        metadata={
+            "description": "Name of the session cookie.",
+            "default": "orionis_session"
+        }
+    )
+
+    max_age: Optional[int] = field(
+        default_factory=lambda: Env.get('SESSION_MAX_AGE', 30*60),
+        metadata={
+            "description": "Session expiration in seconds. None for browser session.",
+            "default": "1800 (30 minutes)"
+        }
+    )
+
+    same_site: str | SameSitePolicy = field(
+        default_factory=lambda: Env.get('SESSION_SAME_SITE', SameSitePolicy.LAX),
+        metadata={
+            "description": "SameSite cookie policy.",
+            "options": ["lax", "strict", "none"],
+            "default": "lax"
+        }
+    )
+
+    path: str = field(
+        default_factory=lambda: Env.get('SESSION_PATH', '/'),
+        metadata={
+            "description": "Cookie path.",
+            "default": "/"
+        }
+    )
+
+    https_only: bool = field(
+        default_factory=lambda: Env.get('SESSION_HTTPS_ONLY', False),
+        metadata={
+            "description": "Restrict cookies to HTTPS.",
+            "default": False
+        }
+    )
+
+    domain: Optional[str] = field(
+        default_factory=lambda: Env.get('SESSION_DOMAIN'),
+        metadata={
+            "description": "Cookie domain for cross-subdomain usage.",
+            "default": None
+        }
+    )
+
+    def __post_init__(self):
+        """
+        Validates the initialization parameters of the session entity.
+        Raises:
+            OrionisIntegrityException: If any of the following conditions are not met:
+                - `secret_key` must be a non-empty string.
+                - `secret_key` must be at least 32 characters long.
+                - `max_age` must be an integer or None.
+                - `same_site` must be one of: 'lax', 'strict', 'none'.
+                - If `same_site` is 'none', `https_only` must be True.
+                - `domain` must be a string or None.
+        """
+
+        # Validate secret_key
+        if not isinstance(self.secret_key, str) or not self.secret_key.strip():
+            raise OrionisIntegrityException("Session secret_key must be a non-empty string")
+
+        # Validate session_cookie
+        if not isinstance(self.session_cookie, str) or not self.session_cookie.strip():
+            raise OrionisIntegrityException("session_cookie must be a non-empty string")
+        if any(c in self.session_cookie for c in ' ;,'):
+            raise OrionisIntegrityException("session_cookie must not contain spaces, semicolons, or commas")
+
+        # Validate max_age
+        if self.max_age is not None:
+            if not isinstance(self.max_age, int):
+                raise OrionisIntegrityException("max_age must be an integer or None")
+            if self.max_age <= 0:
+                raise OrionisIntegrityException("max_age must be a positive integer if set")
+
+        # Validate same_site
+        if not isinstance(self.same_site, (str, SameSitePolicy)):
+            raise OrionisIntegrityException("same_site must be a string or SameSitePolicy")
+        if isinstance(self.same_site, str):
+            options = SameSitePolicy._member_names_
+            _value = self.same_site.upper().strip()
+            if _value not in options:
+                raise OrionisIntegrityException(f"same_site must be one of: {', '.join(options)}")
+            else:
+                self.same_site = SameSitePolicy[_value].value
+        elif isinstance(self.same_site, SameSitePolicy):
+            self.same_site = self.same_site.value
+
+        # Validate path
+        if not isinstance(self.path, str) or not self.path.startswith('/'):
+            raise OrionisIntegrityException("path must be a string starting with '/'")
+
+        # Validate https_only
+        if not isinstance(self.https_only, bool):
+            raise OrionisIntegrityException("https_only must be a boolean value")
+
+        # Validate domain
+        if self.domain is not None:
+            if not isinstance(self.domain, str) or not self.domain.strip():
+                raise OrionisIntegrityException("domain must be a non-empty string or None")
+            if self.domain.startswith('.') or self.domain.endswith('.'):
+                raise OrionisIntegrityException("domain must not start or end with a dot")
+            if '..' in self.domain:
+                raise OrionisIntegrityException("domain must not contain consecutive dots")
+
+    def toDict(self) -> dict:
+        """
+        Converts the Session entity instance into a dictionary.
+
+        Returns:
+            dict: A dictionary representation of the Session instance, with all fields serialized.
+        """
+        return asdict(self)
+

orionis/luminate/foundation/config/session/enums/same_site_policy.py

@@ -0,0 +1,14 @@
+from enum import Enum
+
+class SameSitePolicy(Enum):
+    """
+    Enumeration representing the possible values for the SameSite attribute of cookies.
+
+    Attributes:
+        LAX (str): Cookies are withheld on cross-site subrequests, but sent when a user navigates to the URL from an external site (e.g., following a link).
+        STRICT (str): Cookies are only sent in a first-party context and not with requests initiated by third party websites.
+        NONE (str): Cookies are sent in all contexts, i.e., in responses to both first-party and cross-origin requests.
+    """
+    LAX = "lax"
+    STRICT = "strict"
+    NONE = "none"

orionis/luminate/foundation/config/session/helpers/secret_key.py

@@ -0,0 +1,16 @@
+import secrets
+
+class SecretKey:
+
+    @staticmethod
+    def random(length: int = 32) -> str:
+        """
+        Generates a cryptographically secure random key of the specified length (in bytes), returned as a hex string.
+
+        Args:
+            length (int): Length of the key in bytes. Default is 32.
+
+        Returns:
+            str: A random key as a hexadecimal string.
+        """
+        return secrets.token_hex(length)