xitzin 0.3.0__tar.gz → 0.5.0__tar.gz

{xitzin-0.3.0 → xitzin-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: xitzin
-Version: 0.3.0
+Version: 0.5.0
 Summary: A Gemini Application Framework
 Keywords: gemini,protocol,framework,async,geminispace
 Author: Alan Velasco
@@ -25,11 +25,11 @@ Requires-Dist: typing-extensions>=4.15.0
 Requires-Dist: sqlmodel>=0.0.22 ; extra == 'sqlmodel'
 Requires-Dist: croniter>=1.0.0 ; extra == 'tasks'
 Requires-Python: >=3.10
-Project-URL: Changelog, https://xitzin.readthedocs.io/changelog/
-Project-URL: Documentation, https://xitzin.readthedocs.io
 Project-URL: Homepage, https://github.com/alanbato/xitzin
-Project-URL: Issues, https://github.com/alanbato/xitzin/issues
+Project-URL: Documentation, https://xitzin.readthedocs.io
 Project-URL: Repository, https://github.com/alanbato/xitzin.git
+Project-URL: Issues, https://github.com/alanbato/xitzin/issues
+Project-URL: Changelog, https://xitzin.readthedocs.io/changelog/
 Provides-Extra: sqlmodel
 Provides-Extra: tasks
 Description-Content-Type: text/markdown

{xitzin-0.3.0 → xitzin-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xitzin"
-version = "0.3.0"
+version = "0.5.0"
 description = "A Gemini Application Framework"
 readme = "README.md"
 license = { text = "MIT" }

{xitzin-0.3.0 → xitzin-0.5.0}/src/xitzin/__init__.py

@@ -22,6 +22,7 @@ Example:
 
 from .application import Xitzin
 from .cgi import CGIConfig, CGIHandler, CGIScript
+from .middleware import VirtualHostMiddleware
 from .scgi import SCGIApp, SCGIConfig, SCGIHandler
 from .exceptions import (
     BadRequest,
@@ -42,7 +43,7 @@ from .exceptions import (
     TaskConfigurationError,
     TemporaryFailure,
 )
-from .requests import Request
+from .requests import Request, TitanRequest
 from .responses import Input, Link, Redirect, Response
 
 __all__ = [
@@ -50,10 +51,13 @@ __all__ = [
     "Xitzin",
     # Request/Response
     "Request",
+    "TitanRequest",
     "Response",
     "Input",
     "Redirect",
     "Link",
+    # Middleware
+    "VirtualHostMiddleware",
     # CGI support
     "CGIConfig",
     "CGIHandler",

{xitzin-0.3.0 → xitzin-0.5.0}/src/xitzin/application.py

@@ -11,13 +11,19 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any, Callable
 
 from nauyaca.protocol.request import GeminiRequest
+from nauyaca.protocol.request import TitanRequest as NauyacaTitanRequest
 from nauyaca.protocol.response import GeminiResponse
 from nauyaca.protocol.status import StatusCode
 
-from .exceptions import GeminiException, NotFound, TaskConfigurationError
-from .requests import Request
+from .exceptions import (
+    CertificateRequired,
+    GeminiException,
+    NotFound,
+    TaskConfigurationError,
+)
+from .requests import Request, TitanRequest
 from .responses import Input, Redirect, convert_response
-from .routing import MountedRoute, Route, Router
+from .routing import MountedRoute, Route, Router, TitanRoute
 
 if TYPE_CHECKING:
     from .tasks import BackgroundTask
@@ -227,6 +233,45 @@ class Xitzin:
 
         return decorator
 
+    def titan(
+        self,
+        path: str,
+        *,
+        name: str | None = None,
+        auth_tokens: list[str] | None = None,
+    ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        """Register a Titan upload handler.
+
+        Titan is the upload companion protocol to Gemini. This decorator
+        registers a handler for Titan upload requests.
+
+        Args:
+            path: URL path pattern (e.g., "/upload/{filename}").
+            name: Optional route name. Defaults to function name.
+            auth_tokens: List of valid authentication tokens. If provided,
+                requests without a valid token are rejected with status 60.
+
+        Returns:
+            Decorator function.
+
+        Example:
+            @app.titan("/upload/{filename}", auth_tokens=["secret123"])
+            def upload(request: TitanRequest, content: bytes,
+                       mime_type: str, token: str | None, filename: str):
+                if request.is_delete():
+                    Path(f"./uploads/{filename}").unlink()
+                    return "# Deleted"
+                Path(f"./uploads/{filename}").write_bytes(content)
+                return "# Upload successful"
+        """
+
+        def decorator(handler: Callable[..., Any]) -> Callable[..., Any]:
+            route = TitanRoute(path, handler, name=name, auth_tokens=auth_tokens)
+            self._router.add_titan_route(route)
+            return handler
+
+        return decorator
+
     def mount(
         self,
         path: str,
@@ -354,6 +399,69 @@ class Xitzin:
 
         self.mount(path, handler, name=name)
 
+    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.
 
@@ -514,73 +622,111 @@ 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)
+                # Match regular route
+                match = self._router.match(req.path)
+                if match is None:
+                    raise NotFound(f"No route matches: {req.path}")
+
+                route, params = match
+
+                # 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 req.query:
+                    params["query"] = req.query
+
+                # Call the handler
+                result = await route.call_handler(req, params)
+                return convert_response(result, req)
+
+            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
+
+                traceback.print_exc()
+                return GeminiResponse(
+                    status=StatusCode.TEMPORARY_FAILURE,
+                    meta="Internal server error",
+                )
+
+        # 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)
+
+        return await handler(request)
 
-                return await handler(request)
+    async def _handle_titan_request(
+        self, raw_request: NauyacaTitanRequest
+    ) -> GeminiResponse:
+        """Handle an incoming Titan upload request.
 
-            # Match regular route
-            match = self._router.match(request.path)
-            if match is None:
-                raise NotFound(f"No route matches: {request.path}")
+        This is the Titan request processing logic, separate from Gemini.
+        """
+        request = TitanRequest(raw_request, self)
 
-            route, params = match
+        # 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}")
 
-            # Handle input flow
-            if route.input_prompt and not request.query:
-                return Input(
-                    route.input_prompt, route.sensitive_input
-                ).to_gemini_response()
+                route, params = match
 
-            # Add query to params for input routes
-            if route.input_prompt and request.query:
-                params["query"] = request.query
+                # 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: 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:
+                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 as e:
-            # Log the error and return a generic failure
-            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=f"Internal error: {type(e).__name__}",
-            )
+        return await handler(request)
 
     def _wrap_middleware(
         self,
         middleware: Callable[..., Any],
-        next_handler: Callable[[Request], Any],
-    ) -> Callable[[Request], Any]:
+        next_handler: Callable[..., Any],
+    ) -> Callable[..., Any]:
         """Wrap a handler with middleware."""
 
-        async def wrapped(request: Request) -> GeminiResponse:
+        async def wrapped(request: Any) -> GeminiResponse:
             if asyncio.iscoroutinefunction(middleware):
                 return await middleware(request, next_handler)
             return middleware(request, next_handler)
@@ -659,11 +805,30 @@ class Xitzin:
             async def handle(request: GeminiRequest) -> GeminiResponse:
                 return await self._handle_request(request)
 
+            # Create Titan upload handler if Titan routes are registered
+            upload_handler = None
+            if self._router.has_titan_routes():
+                from nauyaca.server.handler import UploadHandler
+
+                class XitzinUploadHandler(UploadHandler):
+                    """Wrapper to route Titan uploads to Xitzin handlers."""
+
+                    def __init__(self, app: "Xitzin") -> None:
+                        self._app = app
+
+                    async def handle_upload(
+                        self, request: NauyacaTitanRequest
+                    ) -> GeminiResponse:
+                        return await self._app._handle_titan_request(request)
+
+                upload_handler = XitzinUploadHandler(self)
+                print("[Xitzin] Titan upload support enabled")
+
             # Use TLSServerProtocol for manual TLS handling
             # (supports self-signed client certs)
             def create_protocol() -> TLSServerProtocol:
                 return TLSServerProtocol(
-                    lambda: GeminiServerProtocol(handle, None),  # type: ignore[arg-type]
+                    lambda: GeminiServerProtocol(handle, None, upload_handler),
                     ssl_context,
                 )
 

{xitzin-0.3.0 → xitzin-0.5.0}/src/xitzin/auth.py

@@ -6,6 +6,7 @@ Gemini client certificate authentication.
 
 from __future__ import annotations
 
+import hmac
 from dataclasses import dataclass
 from functools import wraps
 from typing import TYPE_CHECKING, Any, Callable
@@ -89,6 +90,27 @@ def require_certificate(handler: Callable[..., Any]) -> Callable[..., Any]:
     return wrapper
 
 
+def _timing_safe_fingerprint_check(fingerprint: str, allowed: list[str]) -> bool:
+    """Check if fingerprint matches any allowed value using timing-safe comparison.
+
+    This prevents timing attacks that could reveal valid fingerprints.
+
+    Args:
+        fingerprint: The fingerprint to check.
+        allowed: List of allowed fingerprints.
+
+    Returns:
+        True if fingerprint matches any allowed value.
+    """
+    # Encode once for comparison
+    fp_bytes = fingerprint.encode("utf-8")
+
+    for allowed_fp in allowed:
+        if hmac.compare_digest(fp_bytes, allowed_fp.encode("utf-8")):
+            return True
+    return False
+
+
 def require_fingerprint(
     *allowed_fingerprints: str,
 ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
@@ -97,6 +119,8 @@ def require_fingerprint(
     If the client certificate fingerprint is not in the allowed list,
     returns status 61 (certificate not authorized).
 
+    Uses timing-safe comparison to prevent fingerprint enumeration attacks.
+
     Args:
         *allowed_fingerprints: SHA-256 fingerprints that are allowed.
 
@@ -111,7 +135,7 @@ def require_fingerprint(
         def admin_panel(request: Request):
             return "# Admin Panel"
     """
-    allowed_set = set(allowed_fingerprints)
+    allowed_list = list(allowed_fingerprints)
 
     def decorator(handler: Callable[..., Any]) -> Callable[..., Any]:
         @wraps(handler)
@@ -119,7 +143,9 @@ def require_fingerprint(
             if not request.client_cert_fingerprint:
                 raise CertificateRequired("Client certificate required")
 
-            if request.client_cert_fingerprint not in allowed_set:
+            if not _timing_safe_fingerprint_check(
+                request.client_cert_fingerprint, allowed_list
+            ):
                 raise CertificateNotAuthorized("Certificate not authorized")
 
             return handler(request, *args, **kwargs)

{xitzin-0.3.0 → xitzin-0.5.0}/src/xitzin/cgi.py

@@ -26,10 +26,13 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+import structlog
 from nauyaca.protocol.response import GeminiResponse
 
 from .exceptions import BadRequest, CGIError, NotFound
 
+logger = structlog.get_logger("xitzin.cgi")
+
 if TYPE_CHECKING:
     from .requests import Request
 
@@ -56,7 +59,7 @@ class CGIConfig:
     max_header_size: int = 8192
     streaming: bool = False
     check_execute_permission: bool = True
-    inherit_environment: bool = True
+    inherit_environment: bool = False
     app_state_keys: list[str] = field(default_factory=list)
 
 
@@ -379,10 +382,14 @@ class CGIHandler:
 
             # Check exit code
             if process.returncode != 0:
-                error_msg = stderr.decode("utf-8", errors="replace")[:200]
-                if error_msg:
-                    raise CGIError(
-                        f"CGI script exited with code {process.returncode}: {error_msg}"
+                # Log stderr server-side but don't expose to client
+                if stderr:
+                    error_detail = stderr.decode("utf-8", errors="replace")[:500]
+                    logger.error(
+                        "cgi_script_failed",
+                        script=str(script_path),
+                        returncode=process.returncode,
+                        stderr=error_detail,
                     )
                 raise CGIError(f"CGI script exited with code {process.returncode}")
 
@@ -420,7 +427,7 @@ class CGIScript:
         *,
         timeout: float = 30.0,
         check_execute_permission: bool = True,
-        inherit_environment: bool = True,
+        inherit_environment: bool = False,
         app_state_keys: list[str] | None = None,
     ) -> None:
         """Create a single-script CGI handler.
@@ -530,10 +537,14 @@ class CGIScript:
                 ) from None
 
             if process.returncode != 0:
-                error_msg = stderr.decode("utf-8", errors="replace")[:200]
-                if error_msg:
-                    raise CGIError(
-                        f"CGI script exited with code {process.returncode}: {error_msg}"
+                # Log stderr server-side but don't expose to client
+                if stderr:
+                    error_detail = stderr.decode("utf-8", errors="replace")[:500]
+                    logger.error(
+                        "cgi_script_failed",
+                        script=str(self.script_path),
+                        returncode=process.returncode,
+                        stderr=error_detail,
                     )
                 raise CGIError(f"CGI script exited with code {process.returncode}")
 

{xitzin-0.3.0 → xitzin-0.5.0}/src/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
@@ -202,7 +204,9 @@ class RateLimitMiddleware(BaseMiddleware):
         """Get a unique identifier for the client."""
         if request.client_cert_fingerprint:
             return f"cert:{request.client_cert_fingerprint}"
-        # Fall back to a placeholder (in production, use IP from transport)
+        # Use IP address when available for anonymous clients
+        if request.remote_addr:
+            return f"ip:{request.remote_addr}"
         return "unknown"
 
     def _is_rate_limited(self, client_id: str) -> bool:
@@ -309,7 +313,7 @@ class UserSessionMiddleware(BaseMiddleware):
             return self._async_cache[fingerprint]
 
         self._cache_misses += 1
-        user = await self._user_loader(fingerprint)  # type: ignore[misc]
+        user = await self._user_loader(fingerprint)
 
         # Add to cache
         self._async_cache[fingerprint] = user
@@ -380,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-0.3.0 → xitzin-0.5.0}/src/xitzin/requests.py

@@ -9,6 +9,7 @@ from typing import TYPE_CHECKING, Any
 from urllib.parse import unquote_plus
 
 from nauyaca.protocol.request import GeminiRequest
+from nauyaca.protocol.request import TitanRequest as NauyacaTitanRequest
 
 if TYPE_CHECKING:
     from cryptography.x509 import Certificate
@@ -148,3 +149,105 @@ class Request:
 
     def __repr__(self) -> str:
         return f"Request({self._raw_request.raw_url!r})"
+
+
+class TitanRequest:
+    """Wraps a Nauyaca TitanRequest for Titan upload handlers.
+
+    Handlers receive this object as their first argument for @app.titan routes.
+
+    Example:
+        @app.titan("/upload/{filename}", auth_tokens=["secret"])
+        def upload(request: TitanRequest, content: bytes,
+                   mime_type: str, token: str | None, filename: str):
+            if request.is_delete():
+                return "# Deleted"
+            Path(f"./uploads/{filename}").write_bytes(content)
+            return "# Upload successful"
+
+    Attributes:
+        app: The Xitzin application instance.
+        state: Arbitrary state storage for this request.
+        path: The URL path component.
+        content: The uploaded content bytes.
+        mime_type: Content MIME type.
+        token: Authentication token (if provided).
+        size: Content size in bytes.
+    """
+
+    def __init__(
+        self, raw_request: NauyacaTitanRequest, app: Xitzin | None = None
+    ) -> None:
+        self._raw_request = raw_request
+        self._app = app
+        self._state = RequestState()
+
+    @property
+    def app(self) -> Xitzin:
+        """The Xitzin application handling this request."""
+        if self._app is None:
+            msg = "Request is not bound to an application"
+            raise RuntimeError(msg)
+        return self._app
+
+    @property
+    def state(self) -> RequestState:
+        """Arbitrary state storage for this request."""
+        return self._state
+
+    @property
+    def path(self) -> str:
+        """The URL path component."""
+        return self._raw_request.path
+
+    @property
+    def content(self) -> bytes:
+        """The uploaded content bytes."""
+        return self._raw_request.content
+
+    @property
+    def mime_type(self) -> str:
+        """Content MIME type."""
+        return self._raw_request.mime_type
+
+    @property
+    def token(self) -> str | None:
+        """Authentication token (if provided)."""
+        return self._raw_request.token
+
+    @property
+    def size(self) -> int:
+        """Content size in bytes."""
+        return self._raw_request.size
+
+    def is_delete(self) -> bool:
+        """Check if this is a delete request (zero-byte upload)."""
+        return self._raw_request.is_delete()
+
+    @property
+    def hostname(self) -> str:
+        """The server hostname from the URL."""
+        return self._raw_request.hostname
+
+    @property
+    def port(self) -> int:
+        """The server port from the URL."""
+        return self._raw_request.port
+
+    @property
+    def client_cert(self) -> Certificate | None:
+        """The client's TLS certificate, if provided."""
+        return self._raw_request.client_cert
+
+    @property
+    def client_cert_fingerprint(self) -> str | None:
+        """SHA-256 fingerprint of the client certificate."""
+        return self._raw_request.client_cert_fingerprint
+
+    @property
+    def raw_url(self) -> str:
+        """The original URL from the request."""
+        return self._raw_request.raw_url
+
+    def __repr__(self) -> str:
+        return f"TitanRequest({self._raw_request.raw_url!r})"

{xitzin-0.3.0 → xitzin-0.5.0}/src/xitzin/responses.py

@@ -14,7 +14,6 @@ from nauyaca.protocol.status import StatusCode
 
 if TYPE_CHECKING:
     from .application import Xitzin
-    from .requests import Request
 
 
 class ResponseConvertible(Protocol):
@@ -156,7 +155,7 @@ class Link:
         return self.to_gemtext()
 
 
-def convert_response(result: Any, request: Request | None = None) -> GeminiResponse:
+def convert_response(result: Any, request: Any = None) -> GeminiResponse:
     """Convert a handler return value to a GeminiResponse.
 
     Handlers can return:
@@ -168,7 +167,7 @@ def convert_response(result: Any, request: Request | None = None) -> GeminiRespo
 
     Args:
         result: The return value from a handler.
-        request: The current request (for URL tracking).
+        request: The current request (Request or TitanRequest, for URL tracking).
 
     Returns:
         A GeminiResponse instance.

{xitzin-0.3.0 → xitzin-0.5.0}/src/xitzin/routing.py

@@ -282,6 +282,143 @@ class MountedRoute:
         return f"MountedRoute({self.path_prefix!r}, name={self.name!r})"
 
 
+class TitanRoute:
+    """Route for Titan upload handlers with integrated authentication.
+
+    Similar to Route, but designed for Titan uploads with:
+    - Token-based authentication
+    - Explicit content/mime_type/token parameters passed to handlers
+
+    Example:
+        route = TitanRoute(
+            "/upload/{filename}",
+            upload_handler,
+            auth_tokens=["secret123"]
+        )
+    """
+
+    def __init__(
+        self,
+        path: str,
+        handler: Callable[..., Any],
+        *,
+        name: str | None = None,
+        auth_tokens: list[str] | None = None,
+    ) -> None:
+        """Create a new Titan route.
+
+        Args:
+            path: Path template with optional parameters (e.g., "/upload/{filename}").
+            handler: The handler function to call.
+            name: Route name for identification. Defaults to handler function name.
+            auth_tokens: List of valid authentication tokens. If provided,
+                requests without a valid token are rejected with status 60.
+        """
+        self.path = path
+        self.handler = handler
+        self.name = (
+            name if name is not None else getattr(handler, "__name__", "<anonymous>")
+        )
+        self.auth_tokens = set(auth_tokens) if auth_tokens else None
+
+        self._param_pattern, self._param_names = self._compile_path(path)
+        self._type_hints = self._get_handler_type_hints(handler)
+        self._is_async = asyncio.iscoroutinefunction(handler)
+
+    def _compile_path(self, path: str) -> tuple[re.Pattern[str], list[str]]:
+        """Convert a path template to a regex pattern.
+
+        Same logic as Route._compile_path().
+        """
+        param_names: list[str] = []
+
+        def replace_param(match: re.Match[str]) -> str:
+            name = match.group(1)
+            param_type = match.group(2)
+            param_names.append(name)
+
+            if param_type == "path":
+                return f"(?P<{name}>.+)"
+            return f"(?P<{name}>[^/]+)"
+
+        escaped = re.escape(path)
+        escaped = escaped.replace(r"\{", "{").replace(r"\}", "}")
+        regex_path = PATH_PARAM_PATTERN.sub(replace_param, escaped)
+
+        return re.compile(f"^{regex_path}$"), param_names
+
+    def _get_handler_type_hints(self, handler: Callable[..., Any]) -> dict[str, type]:
+        """Extract type hints from handler function.
+
+        Excludes 'request', 'content', 'mime_type', 'token', and 'return'.
+        """
+        try:
+            hints = get_type_hints(handler)
+            # Remove non-path-parameter hints
+            hints.pop("request", None)
+            hints.pop("content", None)
+            hints.pop("mime_type", None)
+            hints.pop("token", None)
+            hints.pop("return", None)
+            return hints
+        except Exception:
+            return {}
+
+    def matches(self, path: str) -> bool:
+        """Check if this route matches the given path."""
+        return self._param_pattern.match(path) is not None
+
+    def extract_params(self, path: str) -> dict[str, Any]:
+        """Extract and type-convert path parameters."""
+        match = self._param_pattern.match(path)
+        if not match:
+            return {}
+
+        params: dict[str, Any] = {}
+        for name, value in match.groupdict().items():
+            target_type = self._type_hints.get(name, str)
+            try:
+                if target_type is int:
+                    params[name] = int(value)
+                elif target_type is float:
+                    params[name] = float(value)
+                elif target_type is bool:
+                    params[name] = value.lower() in ("true", "1", "yes")
+                else:
+                    params[name] = value
+            except (ValueError, TypeError):
+                params[name] = value
+
+        return params
+
+    async def call_handler(self, request: Any, params: dict[str, Any]) -> Any:
+        """Call the handler with request and explicit Titan parameters.
+
+        Args:
+            request: TitanRequest object (typed as Any to avoid circular imports).
+            params: Path parameters extracted from the URL.
+
+        Handler receives: (request, content, mime_type, token, **path_params)
+        """
+        # Add Titan-specific parameters
+        handler_params = {
+            "content": request.content,
+            "mime_type": request.mime_type,
+            "token": request.token,
+            **params,
+        }
+
+        if self._is_async:
+            return await self.handler(request, **handler_params)
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None, lambda: self.handler(request, **handler_params)
+        )
+
+    def __repr__(self) -> str:
+        return f"TitanRoute({self.path!r}, name={self.name!r})"
+
+
 class Router:
     """Collection of routes with matching logic.
 
@@ -293,6 +430,7 @@ class Router:
         self._routes: list[Route] = []
         self._routes_by_name: dict[str, Route] = {}
         self._mounted_routes: list[MountedRoute] = []
+        self._titan_routes: list[TitanRoute] = []
 
     def add_route(self, route: Route) -> None:
         """Add a route to the router.
@@ -351,6 +489,33 @@ class Router:
                 return route, params
         return None
 
+    def add_titan_route(self, route: TitanRoute) -> None:
+        """Add a Titan upload route to the router.
+
+        Args:
+            route: The Titan route to add.
+        """
+        self._titan_routes.append(route)
+
+    def match_titan(self, path: str) -> tuple[TitanRoute, dict[str, Any]] | None:
+        """Find a matching Titan route and extract parameters.
+
+        Args:
+            path: URL path to match.
+
+        Returns:
+            Tuple of (titan_route, params) if found, None otherwise.
+        """
+        for route in self._titan_routes:
+            if route.matches(path):
+                params = route.extract_params(path)
+                return route, params
+        return None
+
+    def has_titan_routes(self) -> bool:
+        """Check if any Titan routes are registered."""
+        return len(self._titan_routes) > 0
+
     def reverse(self, name: str, **params: Any) -> str:
         """Build URL for a named route.
 

{xitzin-0.3.0 → xitzin-0.5.0}/src/xitzin/scgi.py

@@ -49,7 +49,7 @@ class SCGIConfig:
     timeout: float = 30.0
     max_response_size: int | None = 1048576  # 1MB default
     buffer_size: int = 8192
-    inherit_environment: bool = True
+    inherit_environment: bool = False
     app_state_keys: list[str] = field(default_factory=list)
 
 

{xitzin-0.3.0 → xitzin-0.5.0}/src/xitzin/testing.py

@@ -13,6 +13,7 @@ from typing import TYPE_CHECKING, Generator
 from urllib.parse import quote_plus
 
 from nauyaca.protocol.request import GeminiRequest
+from nauyaca.protocol.request import TitanRequest as NauyacaTitanRequest
 from nauyaca.protocol.response import GeminiResponse
 
 if TYPE_CHECKING:
@@ -153,10 +154,15 @@ class TestClient:
         # Handle request through the app
         response = self._handle_sync(request)
 
+        # Convert bytes body to str for TestResponse
+        body = response.body
+        if isinstance(body, bytes):
+            body = body.decode("utf-8")
+
         return TestResponse(
             status=response.status,
             meta=response.meta,
-            body=response.body,
+            body=body,
         )
 
     def get_input(
@@ -210,6 +216,100 @@ class TestClient:
         new_client._default_fingerprint = fingerprint
         return new_client
 
+    def upload(
+        self,
+        path: str,
+        content: bytes | str,
+        *,
+        mime_type: str = "text/gemini",
+        token: str | None = None,
+        cert_fingerprint: str | None = None,
+    ) -> TestResponse:
+        """Make a Titan upload request.
+
+        Args:
+            path: The request path (e.g., "/upload/file.gmi").
+            content: Content to upload (str will be UTF-8 encoded).
+            mime_type: Content MIME type (default: text/gemini).
+            token: Authentication token (if required by route).
+            cert_fingerprint: Mock client certificate fingerprint.
+
+        Returns:
+            TestResponse with status, meta, and body.
+
+        Example:
+            response = client.upload(
+                "/files/test.gmi",
+                "# Hello World",
+                mime_type="text/gemini",
+                token="secret123"
+            )
+            assert response.is_success
+        """
+        # Convert str to bytes
+        if isinstance(content, str):
+            content_bytes = content.encode("utf-8")
+        else:
+            content_bytes = content
+
+        # Build Titan URL
+        size = len(content_bytes)
+        url = f"titan://testserver{path};size={size};mime={mime_type}"
+        if token:
+            url += f";token={token}"
+
+        # Create TitanRequest
+        request = NauyacaTitanRequest.from_line(url)
+        request.content = content_bytes
+
+        # Set certificate info
+        fingerprint = cert_fingerprint or self._default_fingerprint
+        if fingerprint:
+            request.client_cert_fingerprint = fingerprint
+
+        # Handle through app
+        response = self._handle_titan_sync(request)
+
+        # Convert bytes body to str for TestResponse
+        body = response.body
+        if isinstance(body, bytes):
+            body = body.decode("utf-8")
+
+        return TestResponse(
+            status=response.status,
+            meta=response.meta,
+            body=body,
+        )
+
+    def delete(
+        self,
+        path: str,
+        *,
+        token: str | None = None,
+        cert_fingerprint: str | None = None,
+    ) -> TestResponse:
+        """Make a Titan delete request (zero-byte upload).
+
+        Args:
+            path: The request path to delete.
+            token: Authentication token (if required by route).
+            cert_fingerprint: Mock client certificate fingerprint.
+
+        Returns:
+            TestResponse with status, meta, and body.
+
+        Example:
+            response = client.delete("/files/old.gmi", token="secret123")
+            assert response.is_success
+        """
+        return self.upload(
+            path,
+            b"",
+            mime_type="text/gemini",
+            token=token,
+            cert_fingerprint=cert_fingerprint,
+        )
+
     def _handle_sync(self, request: GeminiRequest) -> GeminiResponse:
         """Handle a request synchronously."""
         try:
@@ -220,6 +320,16 @@ class TestClient:
 
         return loop.run_until_complete(self._app._handle_request(request))
 
+    def _handle_titan_sync(self, request: NauyacaTitanRequest) -> GeminiResponse:
+        """Handle a Titan request synchronously."""
+        try:
+            loop = asyncio.get_event_loop()
+        except RuntimeError:
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+
+        return loop.run_until_complete(self._app._handle_titan_request(request))
+
 
 @contextmanager
 def test_app(app: "Xitzin") -> Generator[TestClient, None, None]: