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

xitzin/middleware.py

@@ -6,9 +6,13 @@ and modify responses before they are sent to clients.
 
 from __future__ import annotations
 
+import asyncio
 import time
 from abc import ABC
-from typing import TYPE_CHECKING, Awaitable, Callable
+from collections import OrderedDict
+from functools import lru_cache
+from inspect import iscoroutinefunction
+from typing import TYPE_CHECKING, Any, Awaitable, Callable
 
 from nauyaca.protocol.response import GeminiResponse
 from nauyaca.protocol.status import StatusCode
@@ -40,7 +44,11 @@ class BaseMiddleware(ABC):
                 print(f"Response: {response.status}")
                 return response
 
-        app.add_middleware(LoggingMiddleware())
+        logging_mw = LoggingMiddleware()
+
+        @app.middleware
+        async def logging(request, call_next):
+            return await logging_mw(request, call_next)
     """
 
     async def before_request(
@@ -98,7 +106,11 @@ class TimingMiddleware(BaseMiddleware):
     Stores the elapsed time in request.state.elapsed_time.
 
     Example:
-        app.add_middleware(TimingMiddleware())
+        timing_mw = TimingMiddleware()
+
+        @app.middleware
+        async def timing(request, call_next):
+            return await timing_mw(request, call_next)
 
         @app.gemini("/")
         def home(request: Request):
@@ -124,7 +136,11 @@ class LoggingMiddleware(BaseMiddleware):
     """Middleware that logs requests and responses.
 
     Example:
-        app.add_middleware(LoggingMiddleware())
+        logging_mw = LoggingMiddleware()
+
+        @app.middleware
+        async def logging(request, call_next):
+            return await logging_mw(request, call_next)
     """
 
     def __init__(self, logger: Callable[[str], None] | None = None) -> None:
@@ -157,7 +173,11 @@ class RateLimitMiddleware(BaseMiddleware):
     Limits requests per client based on certificate fingerprint or IP.
 
     Example:
-        app.add_middleware(RateLimitMiddleware(max_requests=10, window_seconds=60))
+        rate_limit_mw = RateLimitMiddleware(max_requests=10, window_seconds=60)
+
+        @app.middleware
+        async def rate_limit(request, call_next):
+            return await rate_limit_mw(request, call_next)
     """
 
     def __init__(
@@ -182,7 +202,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:
@@ -217,3 +239,146 @@ class RateLimitMiddleware(BaseMiddleware):
             )
 
         return None
+
+
+class UserSessionMiddleware(BaseMiddleware):
+    """Middleware that loads and caches user data from certificate fingerprints.
+
+    Stores the loaded user in request.state.user. Uses an LRU cache to avoid
+    repeated database lookups for the same user across requests.
+
+    Supports both sync and async user_loader functions. Sync loaders are
+    executed in a thread pool to avoid blocking the event loop.
+
+    Example with sync loader:
+        from xitzin.middleware import UserSessionMiddleware
+
+        def load_user(fingerprint: str) -> User | None:
+            with Session(engine) as session:
+                return session.exec(
+                    select(User).where(User.fingerprint == fingerprint)
+                ).first()
+
+        user_mw = UserSessionMiddleware(load_user)
+
+        @app.middleware
+        async def user_session(request, call_next):
+            return await user_mw(request, call_next)
+
+    Example with async loader:
+        async def load_user(fingerprint: str) -> User | None:
+            async with async_session() as session:
+                result = await session.execute(
+                    select(User).where(User.fingerprint == fingerprint)
+                )
+                return result.scalar_one_or_none()
+
+        user_mw = UserSessionMiddleware(load_user)
+    """
+
+    def __init__(
+        self,
+        user_loader: Callable[[str], Any] | Callable[[str], Awaitable[Any]],
+        cache_size: int = 100,
+    ) -> None:
+        """Create user session middleware.
+
+        Args:
+            user_loader: Function that takes a fingerprint and returns a user
+                object (or None if not found). Can be sync or async. Sync
+                loaders are executed in a thread pool to avoid blocking.
+            cache_size: Maximum number of users to cache. Defaults to 100.
+        """
+        self._user_loader = user_loader
+        self._cache_size = cache_size
+        self._is_async = iscoroutinefunction(user_loader)
+
+        # For sync loaders, use lru_cache
+        # For async loaders, use a simple OrderedDict-based LRU cache
+        if self._is_async:
+            self._async_cache: OrderedDict[str, Any] = OrderedDict()
+            self._cache_hits = 0
+            self._cache_misses = 0
+        else:
+            self._sync_cached_loader = lru_cache(maxsize=cache_size)(user_loader)
+
+    async def _get_user_async(self, fingerprint: str) -> Any:
+        """Get user with async loader and caching."""
+        if fingerprint in self._async_cache:
+            self._cache_hits += 1
+            # Move to end (most recently used)
+            self._async_cache.move_to_end(fingerprint)
+            return self._async_cache[fingerprint]
+
+        self._cache_misses += 1
+        user = await self._user_loader(fingerprint)
+
+        # Add to cache
+        self._async_cache[fingerprint] = user
+        self._async_cache.move_to_end(fingerprint)
+
+        # Evict oldest if over capacity
+        while len(self._async_cache) > self._cache_size:
+            self._async_cache.popitem(last=False)
+
+        return user
+
+    async def _get_user_sync(self, fingerprint: str) -> Any:
+        """Get user with sync loader, running in executor."""
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(None, self._sync_cached_loader, fingerprint)
+
+    async def before_request(
+        self, request: "Request"
+    ) -> "Request | GeminiResponse | None":
+        fingerprint = request.client_cert_fingerprint
+        if fingerprint:
+            if self._is_async:
+                request.state.user = await self._get_user_async(fingerprint)
+            else:
+                request.state.user = await self._get_user_sync(fingerprint)
+        else:
+            request.state.user = None
+        return None
+
+    def clear_cache(self) -> None:
+        """Clear all cached users.
+
+        Call this after updating user data to ensure fresh lookups.
+
+        Example:
+            def update_user(user: User):
+                with Session(engine) as session:
+                    session.add(user)
+                    session.commit()
+                user_middleware.clear_cache()
+        """
+        if self._is_async:
+            self._async_cache.clear()
+            self._cache_hits = 0
+            self._cache_misses = 0
+        else:
+            self._sync_cached_loader.cache_clear()
+
+    def cache_info(self) -> Any:
+        """Return cache statistics.
+
+        Returns information about cache hits, misses, and size.
+
+        Example:
+            info = user_middleware.cache_info()
+            print(f"Cache hits: {info.hits}, misses: {info.misses}")
+        """
+        if self._is_async:
+            from collections import namedtuple
+
+            CacheInfo = namedtuple(
+                "CacheInfo", ["hits", "misses", "maxsize", "currsize"]
+            )
+            return CacheInfo(
+                hits=self._cache_hits,
+                misses=self._cache_misses,
+                maxsize=self._cache_size,
+                currsize=len(self._async_cache),
+            )
+        return self._sync_cached_loader.cache_info()

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/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/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.