xitzin 0.4.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

xitzin/__init__.py

@@ -22,7 +22,9 @@ Example:
 
 from .application import Xitzin
 from .cgi import CGIConfig, CGIHandler, CGIScript
+from .middleware import VirtualHostMiddleware
 from .scgi import SCGIApp, SCGIConfig, SCGIHandler
+from .staticfiles import StaticFiles, StaticFilesConfig
 from .exceptions import (
     BadRequest,
     CertificateNotAuthorized,
@@ -55,6 +57,8 @@ __all__ = [
     "Input",
     "Redirect",
     "Link",
+    # Middleware
+    "VirtualHostMiddleware",
     # CGI support
     "CGIConfig",
     "CGIHandler",
@@ -63,6 +67,9 @@ __all__ = [
     "SCGIApp",
     "SCGIConfig",
     "SCGIHandler",
+    # Static files
+    "StaticFiles",
+    "StaticFilesConfig",
     # Exceptions
     "GeminiException",
     "InputRequired",

xitzin/application.py

@@ -26,6 +26,7 @@ from .responses import Input, Redirect, convert_response
 from .routing import MountedRoute, Route, Router, TitanRoute
 
 if TYPE_CHECKING:
+    from .staticfiles import StaticFiles
     from .tasks import BackgroundTask
     from .templating import TemplateEngine
 
@@ -399,6 +400,127 @@ class Xitzin:
 
         self.mount(path, handler, name=name)
 
+    def static(
+        self,
+        path: str,
+        directory: Path | str,
+        *,
+        name: str | None = None,
+        index_files: list[str] | None = None,
+        directory_listing: bool = False,
+        max_file_size: int = 100 * 1024 * 1024,
+        mime_types: dict[str, str] | None = None,
+        follow_symlinks: bool = False,
+    ) -> "StaticFiles":
+        """Mount a static file directory at a path prefix.
+
+        This is a convenience method that creates a StaticFiles handler and
+        mounts it. Returns the handler so you can add a custom 404 handler.
+
+        Args:
+            path: Mount point prefix (e.g., "/files", "/static").
+            directory: Directory to serve files from.
+            name: Optional name for the mount.
+            index_files: Files to serve for directory requests.
+                Defaults to ["index.gmi", "index.gemini"].
+            directory_listing: Enable directory listing when no index found.
+            max_file_size: Maximum file size to serve (bytes). Default: 100 MiB.
+            mime_types: Custom MIME type mappings by extension.
+            follow_symlinks: Whether to follow symbolic links.
+
+        Returns:
+            The StaticFiles handler, for adding custom 404 handling.
+
+        Example:
+            # Simple usage
+            app.static("/files", "./public")
+
+            # With directory listing
+            app.static("/docs", "./documentation", directory_listing=True)
+
+            # With custom 404 handler
+            static = app.static("/images", "./static/images")
+
+            @static.not_found
+            def image_not_found(request, path_info):
+                return "# Image Not Found"
+        """
+        from .staticfiles import StaticFiles
+
+        handler = StaticFiles(
+            directory,
+            index_files=index_files,
+            directory_listing=directory_listing,
+            max_file_size=max_file_size,
+            mime_types=mime_types,
+            follow_symlinks=follow_symlinks,
+        )
+        self.mount(path, handler, name=name)
+        return handler
+
+    def vhost(
+        self,
+        hosts: dict[str, "Xitzin"],
+        *,
+        default_app: "Xitzin | None" = None,
+        fallback_status: int = 53,
+        fallback_handler: Callable[[Request], Any] | None = None,
+    ) -> None:
+        """Configure virtual hosting for this application.
+
+        This is a convenience method that creates and registers VirtualHostMiddleware.
+        The middleware routes requests to different apps based on hostname.
+
+        Args:
+            hosts: Mapping of hostname patterns to Xitzin apps.
+                Patterns can be exact ("example.com") or wildcards ("*.example.com").
+                Exact matches are checked first, then wildcards in definition order.
+            default_app: Default app when no pattern matches.
+            fallback_status: Status code for unmatched hosts (default: 53).
+                Common values: 53 (Proxy Refused), 51 (Not Found), 59 (Bad Request).
+            fallback_handler: Custom handler for unmatched hosts.
+                Takes precedence over default_app and fallback_status.
+
+        Example:
+            main_app = Xitzin(title="Main")
+            blog_app = Xitzin(title="Blog")
+            api_app = Xitzin(title="API")
+
+            @blog_app.gemini("/")
+            def blog_home(request: Request):
+                return "# Blog Home"
+
+            @api_app.gemini("/")
+            def api_home(request: Request):
+                return "# API Home"
+
+            @main_app.gemini("/")
+            def main_home(request: Request):
+                return "# Main Home"
+
+            # Configure as gateway
+            main_app.vhost({
+                "blog.example.com": blog_app,
+                "*.api.example.com": api_app,
+            }, default_app=main_app)
+
+            main_app.run()
+        """
+        from .middleware import VirtualHostMiddleware
+
+        vhost_mw = VirtualHostMiddleware(
+            hosts,
+            default_app=default_app,
+            fallback_status=fallback_status,
+            fallback_handler=fallback_handler,
+        )
+
+        @self.middleware
+        async def virtual_host_dispatcher(
+            request: Request, call_next: Callable[..., Any]
+        ) -> GeminiResponse:
+            return await vhost_mw(request, call_next)
+
     def on_startup(self, handler: Callable[[], Any]) -> Callable[[], Any]:
         """Register a startup event handler.
 
@@ -559,64 +681,56 @@ class Xitzin:
         """
         request = Request(raw_request, self)
 
-        try:
-            # Check mounted routes first
-            mount_match = self._router.match_mount(request.path)
-            if mount_match is not None:
-                mounted_route, path_info = mount_match
-
-                # Build middleware chain for mounted handler
-                async def call_mounted_handler(req: Request) -> GeminiResponse:
+        # Build middleware chain around the entire routing logic
+        async def route_and_handle(req: Request) -> GeminiResponse:
+            try:
+                # Check mounted routes first
+                mount_match = self._router.match_mount(req.path)
+                if mount_match is not None:
+                    mounted_route, path_info = mount_match
                     result = await mounted_route.call_handler(req, path_info)
                     return convert_response(result, req)
 
-                # Apply middleware
-                handler = call_mounted_handler
-                for mw in reversed(self._middleware):
-                    handler = self._wrap_middleware(mw, handler)
-
-                return await handler(request)
-
-            # Match regular route
-            match = self._router.match(request.path)
-            if match is None:
-                raise NotFound(f"No route matches: {request.path}")
+                # Match regular route
+                match = self._router.match(req.path)
+                if match is None:
+                    raise NotFound(f"No route matches: {req.path}")
 
-            route, params = match
+                route, params = match
 
-            # Handle input flow
-            if route.input_prompt and not request.query:
-                return Input(
-                    route.input_prompt, route.sensitive_input
-                ).to_gemini_response()
+                # Handle input flow
+                if route.input_prompt and not req.query:
+                    return Input(
+                        route.input_prompt, route.sensitive_input
+                    ).to_gemini_response()
 
-            # Add query to params for input routes
-            if route.input_prompt and request.query:
-                params["query"] = request.query
+                # Add query to params for input routes
+                if route.input_prompt and req.query:
+                    params["query"] = req.query
 
-            # Build middleware chain
-            async def call_handler(req: Request) -> GeminiResponse:
+                # Call the handler
                 result = await route.call_handler(req, params)
                 return convert_response(result, req)
 
-            # Apply middleware (in reverse order so first registered runs first)
-            handler = call_handler
-            for mw in reversed(self._middleware):
-                handler = self._wrap_middleware(mw, handler)
+            except GeminiException as e:
+                return GeminiResponse(status=e.status_code, meta=e.message)
+            except Exception:
+                # Log the error and return a generic failure
+                import traceback
 
-            return await handler(request)
+                traceback.print_exc()
+                return GeminiResponse(
+                    status=StatusCode.TEMPORARY_FAILURE,
+                    meta="Internal server error",
+                )
 
-        except GeminiException as e:
-            return GeminiResponse(status=e.status_code, meta=e.message)
-        except Exception:
-            # Log the error and return a generic failure
-            import traceback
+        # Apply middleware around the entire routing logic
+        # This allows middleware to intercept requests before routing
+        handler = route_and_handle
+        for mw in reversed(self._middleware):
+            handler = self._wrap_middleware(mw, handler)
 
-            traceback.print_exc()
-            return GeminiResponse(
-                status=StatusCode.TEMPORARY_FAILURE,
-                meta="Internal server error",
-            )
+        return await handler(request)
 
     async def _handle_titan_request(
         self, raw_request: NauyacaTitanRequest
@@ -627,41 +741,42 @@ class Xitzin:
         """
         request = TitanRequest(raw_request, self)
 
-        try:
-            # Match Titan route
-            match = self._router.match_titan(request.path)
-            if match is None:
-                raise NotFound(f"No Titan route matches: {request.path}")
+        # Build middleware chain around the entire routing logic
+        async def route_and_handle(req: TitanRequest) -> GeminiResponse:
+            try:
+                # Match Titan route
+                match = self._router.match_titan(req.path)
+                if match is None:
+                    raise NotFound(f"No Titan route matches: {req.path}")
 
-            route, params = match
+                route, params = match
 
-            # Validate auth token if required
-            if route.auth_tokens is not None:
-                if not request.token or request.token not in route.auth_tokens:
-                    raise CertificateRequired("Valid authentication token required")
+                # Validate auth token if required
+                if route.auth_tokens is not None:
+                    if not req.token or req.token not in route.auth_tokens:
+                        raise CertificateRequired("Valid authentication token required")
 
-            # Build middleware chain
-            async def call_handler(req: TitanRequest) -> GeminiResponse:
+                # Call the handler
                 result = await route.call_handler(req, params)
                 return convert_response(result, req)
 
-            # Apply middleware (in reverse order so first registered runs first)
-            handler = call_handler
-            for mw in reversed(self._middleware):
-                handler = self._wrap_middleware(mw, handler)
+            except GeminiException as e:
+                return GeminiResponse(status=e.status_code, meta=e.message)
+            except Exception:
+                import traceback
 
-            return await handler(request)
+                traceback.print_exc()
+                return GeminiResponse(
+                    status=StatusCode.TEMPORARY_FAILURE,
+                    meta="Internal server error",
+                )
 
-        except GeminiException as e:
-            return GeminiResponse(status=e.status_code, meta=e.message)
-        except Exception:
-            import traceback
+        # Apply middleware around the entire routing logic
+        handler = route_and_handle
+        for mw in reversed(self._middleware):
+            handler = self._wrap_middleware(mw, handler)
 
-            traceback.print_exc()
-            return GeminiResponse(
-                status=StatusCode.TEMPORARY_FAILURE,
-                meta="Internal server error",
-            )
+        return await handler(request)
 
     def _wrap_middleware(
         self,

xitzin/middleware.py

@@ -7,6 +7,7 @@ and modify responses before they are sent to clients.
 from __future__ import annotations
 
 import asyncio
+import re
 import time
 from abc import ABC
 from collections import OrderedDict
@@ -18,6 +19,7 @@ from nauyaca.protocol.response import GeminiResponse
 from nauyaca.protocol.status import StatusCode
 
 if TYPE_CHECKING:
+    from .application import Xitzin
     from .requests import Request
 
 # Type alias for middleware call_next function
@@ -382,3 +384,185 @@ class UserSessionMiddleware(BaseMiddleware):
                 currsize=len(self._async_cache),
             )
         return self._sync_cached_loader.cache_info()
+
+
+class VirtualHostMiddleware(BaseMiddleware):
+    """Middleware for hostname-based virtual hosting.
+
+    Routes requests to different Xitzin applications based on the hostname
+    in the request URL. Supports exact hostname matches and wildcard patterns.
+
+    Example:
+        from xitzin import Xitzin
+        from xitzin.middleware import VirtualHostMiddleware
+
+        blog_app = Xitzin(title="Blog")
+        api_app = Xitzin(title="API")
+        main_app = Xitzin(title="Gateway")
+
+        @blog_app.gemini("/")
+        def blog_home(request):
+            return "# Blog Home"
+
+        @api_app.gemini("/")
+        def api_home(request):
+            return "# API Home"
+
+        @main_app.gemini("/")
+        def main_home(request):
+            return "# Main Home"
+
+        # Create virtual host middleware
+        vhost_mw = VirtualHostMiddleware({
+            "blog.example.com": blog_app,
+            "*.api.example.com": api_app,
+        }, default_app=main_app)
+
+        @main_app.middleware
+        async def vhost(request, call_next):
+            return await vhost_mw(request, call_next)
+
+        main_app.run()
+    """
+
+    def __init__(
+        self,
+        hosts: dict[str, "Xitzin"],
+        *,
+        default_app: "Xitzin | None" = None,
+        fallback_status: int = 53,
+        fallback_handler: (
+            Callable[["Request"], Any] | Callable[["Request"], Awaitable[Any]] | None
+        ) = None,
+    ) -> None:
+        """Create virtual host middleware.
+
+        Args:
+            hosts: Mapping of hostname patterns to Xitzin apps.
+                Keys can be exact hostnames ("example.com") or wildcard patterns
+                ("*.example.com"). Exact matches are checked first, then wildcards
+                in definition order.
+            default_app: Default app to use when no pattern matches.
+                Takes precedence over fallback_status.
+            fallback_status: Status code to return when no match and no default_app.
+                Defaults to 53 (Proxy Request Refused). Common values:
+                - 53: Proxy Request Refused (default)
+                - 51: Not Found
+                - 59: Bad Request
+            fallback_handler: Custom handler function for unmatched hosts.
+                Receives the request and must return a response. Takes precedence
+                over both default_app and fallback_status. Can be sync or async.
+        """
+        self._default_app = default_app
+        self._fallback_status = fallback_status
+        self._fallback_handler = fallback_handler
+        self._is_fallback_async = (
+            iscoroutinefunction(fallback_handler) if fallback_handler else False
+        )
+
+        # Separate exact and wildcard patterns for efficiency
+        self._exact_hosts: dict[str, "Xitzin"] = {}
+        self._wildcard_patterns: list[tuple[re.Pattern[str], "Xitzin"]] = []
+
+        for pattern, app in hosts.items():
+            if pattern.startswith("*."):
+                compiled = self._compile_wildcard_pattern(pattern)
+                if compiled:
+                    self._wildcard_patterns.append((compiled, app))
+            else:
+                self._exact_hosts[pattern.lower()] = app
+
+    def _compile_wildcard_pattern(self, pattern: str) -> re.Pattern[str] | None:
+        """Convert wildcard pattern to regex.
+
+        Supports patterns like:
+        - *.example.com -> matches "blog.example.com", "api.example.com"
+
+        Args:
+            pattern: Wildcard pattern string starting with "*.".
+
+        Returns:
+            Compiled regex pattern, or None if invalid.
+        """
+        if not pattern.startswith("*."):
+            return None
+
+        # Extract domain part after "*."
+        domain = pattern[2:]
+        # Escape special regex chars in domain
+        domain_escaped = re.escape(domain)
+        # Replace the wildcard with a pattern that matches any non-dot chars
+        regex = f"^[^.]+\\.{domain_escaped}$"
+
+        return re.compile(regex, re.IGNORECASE)
+
+    def _match_hostname(self, hostname: str) -> "Xitzin | None":
+        """Find the app for a given hostname.
+
+        Checks exact matches first, then wildcard patterns in order.
+
+        Args:
+            hostname: The hostname from the request.
+
+        Returns:
+            Matching Xitzin app, or None if no match.
+        """
+        hostname_lower = hostname.lower()
+
+        # Try exact match first
+        if hostname_lower in self._exact_hosts:
+            return self._exact_hosts[hostname_lower]
+
+        # Try wildcard patterns
+        for pattern, app in self._wildcard_patterns:
+            if pattern.match(hostname_lower):
+                return app
+
+        return None
+
+    async def before_request(
+        self, request: "Request"
+    ) -> "Request | GeminiResponse | None":
+        """Route request to appropriate app based on hostname."""
+        from .requests import TitanRequest
+        from .responses import convert_response
+
+        hostname = request.hostname
+
+        # Find matching app
+        app = self._match_hostname(hostname)
+
+        # Handle no match
+        if app is None:
+            # Priority 1: Custom fallback handler
+            if self._fallback_handler:
+                if self._is_fallback_async:
+                    result = await self._fallback_handler(request)
+                else:
+                    loop = asyncio.get_running_loop()
+                    result = await loop.run_in_executor(
+                        None, self._fallback_handler, request
+                    )
+                return convert_response(result, request)
+
+            # Priority 2: Default app
+            if self._default_app:
+                app = self._default_app
+            else:
+                # Priority 3: Fallback status
+                return GeminiResponse(
+                    status=StatusCode(self._fallback_status),
+                    meta="Host not configured for this server",
+                )
+
+        # If the matched app is the same as the request's app, return None
+        # to continue processing through the normal route chain (avoid recursion)
+        if request._app is not None and app is request._app:
+            return None
+
+        # Dispatch to matched app
+        if isinstance(request, TitanRequest):
+            response = await app._handle_titan_request(request._raw_request)
+        else:
+            response = await app._handle_request(request._raw_request)
+        return response

xitzin/staticfiles.py

@@ -0,0 +1,487 @@
+"""Static file serving for Xitzin applications.
+
+This module provides static file serving capabilities for Xitzin,
+enabling capsules to serve files from a directory with configurable
+options for directory listings, MIME types, and security settings.
+
+Example:
+    from xitzin import Xitzin
+    from xitzin.staticfiles import StaticFiles
+
+    app = Xitzin()
+
+    # Mount static files at a path
+    app.mount("/files", StaticFiles("./public"))
+
+    # Or use the convenience method
+    app.static("/docs", "./documentation", directory_listing=True)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import mimetypes
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable
+
+from nauyaca.protocol.response import GeminiResponse
+from nauyaca.protocol.status import StatusCode
+
+from .exceptions import BadRequest, NotFound
+from .responses import Redirect
+
+if TYPE_CHECKING:
+    from .requests import Request
+
+# Default MIME types for Gemini/common files
+DEFAULT_MIME_TYPES: dict[str, str] = {
+    ".gmi": "text/gemini",
+    ".gemini": "text/gemini",
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".html": "text/html",
+    ".css": "text/css",
+    ".js": "text/javascript",
+    ".json": "application/json",
+    ".xml": "application/xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".svg": "image/svg+xml",
+    ".webp": "image/webp",
+    ".pdf": "application/pdf",
+    ".zip": "application/zip",
+    ".gz": "application/gzip",
+    ".tar": "application/x-tar",
+}
+
+# MIME types that should be read as binary
+BINARY_MIME_PREFIXES = (
+    "image/",
+    "video/",
+    "audio/",
+    "application/pdf",
+    "application/zip",
+    "application/gzip",
+    "application/x-tar",
+    "application/octet-stream",
+)
+
+
+@dataclass
+class StaticFilesConfig:
+    """Configuration for static file serving.
+
+    Attributes:
+        index_files: Files to serve for directory requests.
+        directory_listing: Enable directory listing when no index found.
+        max_file_size: Maximum file size to serve (bytes).
+        mime_types: Custom MIME type mappings by extension.
+        follow_symlinks: Whether to follow symbolic links.
+    """
+
+    index_files: list[str] = field(
+        default_factory=lambda: ["index.gmi", "index.gemini"]
+    )
+    directory_listing: bool = False
+    max_file_size: int = 100 * 1024 * 1024  # 100 MiB
+    mime_types: dict[str, str] = field(default_factory=dict)
+    follow_symlinks: bool = False
+
+
+def _format_file_size(size: int) -> str:
+    """Format file size in human-readable form.
+
+    Args:
+        size: Size in bytes.
+
+    Returns:
+        Human-readable size string (e.g., "1.5 KB", "100 MB").
+    """
+    value: float = float(size)
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if value < 1024:
+            if unit == "B":
+                return f"{int(value)} {unit}"
+            if value < 10:
+                return f"{value:.1f} {unit}"
+            return f"{int(value)} {unit}"
+        value /= 1024
+    return f"{int(value)} PB"
+
+
+class StaticFiles:
+    """Serve static files from a directory.
+
+    This handler serves files from a specified directory, with support
+    for directory indexes, directory listings, custom MIME types,
+    and security controls.
+
+    Example:
+        from xitzin.staticfiles import StaticFiles
+
+        # Basic usage
+        handler = StaticFiles("./public")
+        app.mount("/files", handler)
+
+        # With configuration
+        handler = StaticFiles(
+            "./docs",
+            directory_listing=True,
+            max_file_size=50 * 1024 * 1024,
+        )
+
+        @handler.not_found
+        def custom_404(request, path_info):
+            return "# File Not Found"
+
+        app.mount("/docs", handler)
+    """
+
+    def __init__(
+        self,
+        directory: Path | str,
+        *,
+        config: StaticFilesConfig | None = None,
+        index_files: list[str] | None = None,
+        directory_listing: bool | None = None,
+        max_file_size: int | None = None,
+        mime_types: dict[str, str] | None = None,
+        follow_symlinks: bool | None = None,
+    ) -> None:
+        """Create a static file handler.
+
+        Args:
+            directory: Directory to serve files from.
+            config: Configuration object (overridden by other params).
+            index_files: Files to serve for directory requests.
+            directory_listing: Enable directory listing when no index found.
+            max_file_size: Maximum file size to serve (bytes).
+            mime_types: Custom MIME type mappings by extension.
+            follow_symlinks: Whether to follow symbolic links.
+
+        Raises:
+            ValueError: If directory doesn't exist or isn't a directory.
+        """
+        self.directory = Path(directory).resolve()
+        self._not_found_handler: Callable[[Any, str], Any] | None = None
+
+        if not self.directory.exists():
+            raise ValueError(f"Directory not found: {directory}")
+        if not self.directory.is_dir():
+            raise ValueError(f"Path is not a directory: {directory}")
+
+        # Start with config defaults, override with explicit parameters
+        base_config = config or StaticFilesConfig()
+
+        self.index_files = (
+            index_files if index_files is not None else base_config.index_files
+        )
+        self.directory_listing = (
+            directory_listing
+            if directory_listing is not None
+            else base_config.directory_listing
+        )
+        self.max_file_size = (
+            max_file_size if max_file_size is not None else base_config.max_file_size
+        )
+        self.follow_symlinks = (
+            follow_symlinks
+            if follow_symlinks is not None
+            else base_config.follow_symlinks
+        )
+
+        # Build MIME type mapping: defaults + config + explicit
+        self._mime_types = {**DEFAULT_MIME_TYPES}
+        self._mime_types.update(base_config.mime_types)
+        if mime_types:
+            self._mime_types.update(mime_types)
+
+    def not_found(
+        self, handler: Callable[[Any, str], Any]
+    ) -> Callable[[Any, str], Any]:
+        """Register a custom not-found handler.
+
+        The handler receives (request, path_info) and should return a response.
+
+        Example:
+            @handler.not_found
+            def custom_404(request, path_info):
+                return f"# Not Found\\n\\nFile {path_info} doesn't exist."
+        """
+        self._not_found_handler = handler
+        return handler
+
+    async def __call__(self, request: Request, path_info: str) -> GeminiResponse:
+        """Handle a request for a static file.
+
+        Args:
+            request: The Gemini request.
+            path_info: Path after the mount prefix (e.g., "/docs/page.gmi").
+
+        Returns:
+            GeminiResponse with the file content or error.
+
+        Raises:
+            NotFound: If file doesn't exist (and no custom handler).
+            BadRequest: If path validation fails.
+        """
+        try:
+            # Normalize path_info
+            path_info = path_info.lstrip("/") if path_info else ""
+
+            # Resolve and validate path
+            file_path = self._resolve_path(path_info)
+
+            # Handle directory
+            if file_path.is_dir():
+                return await self._serve_directory(request, file_path, path_info)
+
+            # Handle file
+            return await self._serve_file(file_path)
+
+        except NotFound:
+            if self._not_found_handler is not None:
+                result = self._not_found_handler(request, path_info)
+                if asyncio.iscoroutine(result):
+                    result = await result
+                return self._convert_handler_result(result)
+            raise
+
+    def _resolve_path(self, path_info: str) -> Path:
+        """Resolve path_info to a validated filesystem path.
+
+        Args:
+            path_info: Requested path relative to mount point.
+
+        Returns:
+            Resolved Path object.
+
+        Raises:
+            BadRequest: If path contains traversal attempts.
+            NotFound: If resolved path doesn't exist.
+        """
+        # Reject obvious traversal attempts early
+        if ".." in path_info:
+            raise BadRequest("Invalid path")
+
+        # Build candidate path
+        if path_info:
+            candidate = self.directory / path_info
+        else:
+            candidate = self.directory
+
+        # Resolve the path, handling symlinks based on config
+        if self.follow_symlinks:
+            resolved = candidate.resolve()
+        else:
+            # Resolve parent but not the final component
+            resolved = candidate.parent.resolve() / candidate.name
+            # Check if final component is a symlink
+            if resolved.is_symlink():
+                raise BadRequest("Symbolic links not allowed")
+            # Now fully resolve to catch any issues
+            resolved = resolved.resolve()
+
+        # Security check: ensure path is within allowed directory
+        try:
+            resolved.relative_to(self.directory)
+        except ValueError:
+            raise BadRequest("Invalid path") from None
+
+        # Check existence
+        if not resolved.exists():
+            raise NotFound("File not found")
+
+        return resolved
+
+    def _get_mime_type(self, file_path: Path) -> str:
+        """Determine MIME type for a file.
+
+        Args:
+            file_path: Path to the file.
+
+        Returns:
+            MIME type string.
+        """
+        suffix = file_path.suffix.lower()
+
+        # Check custom mappings first
+        if suffix in self._mime_types:
+            return self._mime_types[suffix]
+
+        # Try stdlib mimetypes
+        guessed, _ = mimetypes.guess_type(str(file_path))
+        if guessed:
+            return guessed
+
+        # Default to text/gemini for Gemini-centric behavior
+        return "text/gemini"
+
+    def _is_binary_mime(self, mime_type: str) -> bool:
+        """Check if MIME type indicates binary content.
+
+        Args:
+            mime_type: MIME type string.
+
+        Returns:
+            True if content should be read as binary.
+        """
+        return mime_type.startswith(BINARY_MIME_PREFIXES)
+
+    async def _serve_file(self, file_path: Path) -> GeminiResponse:
+        """Serve a file with appropriate MIME type.
+
+        Args:
+            file_path: Path to the file.
+
+        Returns:
+            GeminiResponse with file content.
+
+        Raises:
+            BadRequest: If file exceeds size limit.
+            NotFound: If file cannot be read.
+        """
+        # Check file size before reading
+        try:
+            size = file_path.stat().st_size
+        except OSError:
+            raise NotFound("File not found") from None
+
+        if size > self.max_file_size:
+            raise BadRequest(
+                f"File too large ({_format_file_size(size)}, "
+                f"max {_format_file_size(self.max_file_size)})"
+            )
+
+        mime_type = self._get_mime_type(file_path)
+        is_binary = self._is_binary_mime(mime_type)
+
+        try:
+            if is_binary:
+                # Read binary in thread to avoid blocking
+                body: str | bytes = await asyncio.to_thread(file_path.read_bytes)
+            else:
+                body = await asyncio.to_thread(file_path.read_text, encoding="utf-8")
+        except UnicodeDecodeError:
+            # Fall back to binary if text decode fails
+            body = await asyncio.to_thread(file_path.read_bytes)
+        except OSError:
+            raise NotFound("File not found") from None
+
+        return GeminiResponse(
+            status=StatusCode.SUCCESS,
+            meta=mime_type,
+            body=body,
+        )
+
+    async def _serve_directory(
+        self, request: Request, dir_path: Path, path_info: str
+    ) -> GeminiResponse:
+        """Serve a directory request.
+
+        Args:
+            request: The Gemini request.
+            dir_path: Path to the directory.
+            path_info: Original path_info for this request.
+
+        Returns:
+            GeminiResponse with index file, directory listing, or redirect.
+
+        Raises:
+            NotFound: If no index and directory listing disabled.
+        """
+        # Ensure trailing slash for directories
+        if path_info and not request.path.endswith("/"):
+            redirect_url = request.path + "/"
+            return Redirect(redirect_url, permanent=False).to_gemini_response()
+
+        # Try to find an index file
+        for index_name in self.index_files:
+            index_path = dir_path / index_name
+            if index_path.is_file():
+                return await self._serve_file(index_path)
+
+        # Generate directory listing if enabled
+        if self.directory_listing:
+            listing = self._generate_directory_listing(dir_path, path_info)
+            return GeminiResponse(
+                status=StatusCode.SUCCESS,
+                meta="text/gemini",
+                body=listing,
+            )
+
+        raise NotFound("Directory index not found")
+
+    def _generate_directory_listing(self, dir_path: Path, request_path: str) -> str:
+        """Generate a Gemini directory listing.
+
+        Args:
+            dir_path: Path to the directory.
+            request_path: The request path for display.
+
+        Returns:
+            Gemtext directory listing.
+        """
+        display_path = "/" + request_path if request_path else "/"
+        lines = [f"# Index of {display_path}", ""]
+
+        # Parent directory link (if not at root)
+        if request_path:
+            lines.append("=> ../ ..")
+            lines.append("")
+
+        # Collect and sort entries: directories first, then files
+        entries = []
+        try:
+            for entry in dir_path.iterdir():
+                # Skip hidden files
+                if entry.name.startswith("."):
+                    continue
+
+                # Skip symlinks if not following them
+                if not self.follow_symlinks and entry.is_symlink():
+                    continue
+
+                entries.append(entry)
+        except OSError:
+            pass
+
+        # Sort: directories first, then alphabetically by name
+        entries.sort(key=lambda p: (not p.is_dir(), p.name.lower()))
+
+        # Generate links
+        for entry in entries:
+            name = entry.name
+            if entry.is_dir():
+                lines.append(f"=> {name}/ {name}/")
+            else:
+                try:
+                    size = _format_file_size(entry.stat().st_size)
+                    lines.append(f"=> {name} {name} ({size})")
+                except OSError:
+                    lines.append(f"=> {name} {name}")
+
+        return "\n".join(lines)
+
+    def _convert_handler_result(self, result: Any) -> GeminiResponse:
+        """Convert a custom handler result to GeminiResponse.
+
+        Args:
+            result: Handler return value.
+
+        Returns:
+            GeminiResponse.
+        """
+        # Import here to avoid circular import
+        from .responses import convert_response
+
+        return convert_response(result)
+
+
+__all__ = [
+    "StaticFiles",
+    "StaticFilesConfig",
+]

{xitzin-0.4.0.dist-info → xitzin-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: xitzin
-Version: 0.4.0
+Version: 0.6.0
 Summary: A Gemini Application Framework
 Keywords: gemini,protocol,framework,async,geminispace
 Author: Alan Velasco

{xitzin-0.4.0.dist-info → xitzin-0.6.0.dist-info}/RECORD

@@ -1,18 +1,19 @@
-xitzin/__init__.py,sha256=GMfAmzBJ6TMZJWfF38r1k0y-vswOdLw9xfWpPfYMcqc,1851
-xitzin/application.py,sha256=axL5G4lRz0KTNLsNQkCGxWD0MGDpIH6Xe9OKkxJlJw8,27851
+xitzin/__init__.py,sha256=EHeBz-bmQ02KwVlmT7WUtp0MVQGTDcqR-m8uIibCJD4,2062
+xitzin/application.py,sha256=OkdaHt0aSRgo6NEEUA1ZwMy08eYWefzReUsZeBowVnY,32135
 xitzin/auth.py,sha256=hHhrP_fYToY6J6CCU8vgAsWbYn6K16LUxkeDMzZTF2Q,5304
 xitzin/cgi.py,sha256=nggSuQ0gXIKdBKWHqH_CNZ6UlVGaB3VAOu3ZRPc43ek,18046
 xitzin/exceptions.py,sha256=82z-CjyC0FwFbo9hGTjjmurlL_Vd4rTVdgkmQoFLXT0,3883
-xitzin/middleware.py,sha256=dZhrbOJPCrrbMiwrbRzxElsC7UDrWc7lvnQ5c0xBHts,12542
+xitzin/middleware.py,sha256=rES7C1gujvP-1evpXfqng9uZ91rzJdqfob-nvGBtTAo,19042
 xitzin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 xitzin/requests.py,sha256=1mbm5F8oywLPNpSdh2inn7K1IEeI3H5meOwj8jldi1Q,7783
 xitzin/responses.py,sha256=QVH4B-qVHP7hxi0hIrOJhdCiHDf4PDCpSZ1fAD8iNkk,6525
 xitzin/routing.py,sha256=8Kl3FV6EWZ6nW0bDTqJ-qysNyJ1iSRtCKicCAai8Lmk,18093
 xitzin/scgi.py,sha256=t-ixEwrQR-bIRj56DkzBsvGyN75E5R0gasIjMfq5LFY,13665
 xitzin/sqlmodel.py,sha256=lZvDzYAgnG8S2K-EYnx6PkO7D68pjM06uQLSKUZ9yY4,4500
+xitzin/staticfiles.py,sha256=jSbEdUIDq4aktP_-CX5US0IObrUBPF7M7eHUr28VhG8,15214
 xitzin/tasks.py,sha256=_smEXy-THge8wmQqWDtX3iUmAmoHniw_qqZBlKjCdqA,4597
 xitzin/templating.py,sha256=spjxb05wgwKA4txOMbWJuwEVMaoLovo13_ukbXAcBDY,6040
 xitzin/testing.py,sha256=wMiToopD2TAqTsreVqOrIUNCayORNQQennxR_GwMBSY,10980
-xitzin-0.4.0.dist-info/WHEEL,sha256=XV0cjMrO7zXhVAIyyc8aFf1VjZ33Fen4IiJk5zFlC3g,80
-xitzin-0.4.0.dist-info/METADATA,sha256=Zv-Rde7LWIcf_FQfclXu77BzGipWf6_n0fOXVzkvk0A,3456
-xitzin-0.4.0.dist-info/RECORD,,
+xitzin-0.6.0.dist-info/WHEEL,sha256=5DEXXimM34_d4Gx1AuF9ysMr1_maoEtGKjaILM3s4w4,80
+xitzin-0.6.0.dist-info/METADATA,sha256=yMpMV5_cxjYK26sDgN70-CX4Z9nDnVxCu0oHjfsYxPc,3456
+xitzin-0.6.0.dist-info/RECORD,,

{xitzin-0.4.0.dist-info → xitzin-0.6.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.9.26
+Generator: uv 0.9.29
 Root-Is-Purelib: true
 Tag: py3-none-any