xitzin 0.1.2__py3-none-any.whl

xitzin/exceptions.py

@@ -0,0 +1,138 @@
+"""Gemini exception classes for error responses.
+
+These exceptions can be raised in handlers to return specific Gemini status codes.
+"""
+
+from __future__ import annotations
+
+
+class GeminiException(Exception):
+    """Base exception for Gemini error responses.
+
+    Subclasses define specific status codes for different error types.
+    Raise these in handlers to return the appropriate Gemini status.
+
+    Example:
+        @app.gemini("/page/{page_id}")
+        def get_page(request: Request, page_id: int):
+            page = db.get(page_id)
+            if not page:
+                raise NotFound(f"Page {page_id} not found")
+            return page.content
+    """
+
+    status_code: int = 50
+    default_message: str = "Permanent failure"
+
+    def __init__(self, message: str | None = None) -> None:
+        self.message = message or self.default_message
+        super().__init__(self.message)
+
+
+# Input required (1x)
+class InputRequired(GeminiException):
+    """Request requires user input (status 10)."""
+
+    status_code = 10
+    default_message = "Input required"
+
+
+class SensitiveInputRequired(GeminiException):
+    """Request requires sensitive user input (status 11)."""
+
+    status_code = 11
+    default_message = "Sensitive input required"
+
+
+# Temporary failures (4x)
+class TemporaryFailure(GeminiException):
+    """Temporary failure - client may retry (status 40)."""
+
+    status_code = 40
+    default_message = "Temporary failure"
+
+
+class ServerUnavailable(GeminiException):
+    """Server unavailable due to maintenance or overload (status 41)."""
+
+    status_code = 41
+    default_message = "Server unavailable"
+
+
+class CGIError(GeminiException):
+    """CGI or similar process error (status 42)."""
+
+    status_code = 42
+    default_message = "CGI error"
+
+
+class ProxyError(GeminiException):
+    """Proxy request failed (status 43)."""
+
+    status_code = 43
+    default_message = "Proxy error"
+
+
+class SlowDown(GeminiException):
+    """Rate limiting - client should slow down (status 44)."""
+
+    status_code = 44
+    default_message = "Slow down"
+
+
+# Permanent failures (5x)
+class PermanentFailure(GeminiException):
+    """Permanent failure - client should not retry (status 50)."""
+
+    status_code = 50
+    default_message = "Permanent failure"
+
+
+class NotFound(GeminiException):
+    """Resource not found (status 51)."""
+
+    status_code = 51
+    default_message = "Not found"
+
+
+class Gone(GeminiException):
+    """Resource permanently removed (status 52)."""
+
+    status_code = 52
+    default_message = "Gone"
+
+
+class ProxyRequestRefused(GeminiException):
+    """Proxy request refused (status 53)."""
+
+    status_code = 53
+    default_message = "Proxy request refused"
+
+
+class BadRequest(GeminiException):
+    """Malformed request (status 59)."""
+
+    status_code = 59
+    default_message = "Bad request"
+
+
+# Client certificate errors (6x)
+class CertificateRequired(GeminiException):
+    """Client certificate required (status 60)."""
+
+    status_code = 60
+    default_message = "Client certificate required"
+
+
+class CertificateNotAuthorized(GeminiException):
+    """Certificate not authorized for this resource (status 61)."""
+
+    status_code = 61
+    default_message = "Certificate not authorized"
+
+
+class CertificateNotValid(GeminiException):
+    """Certificate is not valid (status 62)."""
+
+    status_code = 62
+    default_message = "Certificate not valid"

xitzin/middleware.py

@@ -0,0 +1,219 @@
+"""Middleware system for Xitzin.
+
+Middleware functions can intercept requests before they reach handlers
+and modify responses before they are sent to clients.
+"""
+
+from __future__ import annotations
+
+import time
+from abc import ABC
+from typing import TYPE_CHECKING, Awaitable, Callable
+
+from nauyaca.protocol.response import GeminiResponse
+from nauyaca.protocol.status import StatusCode
+
+if TYPE_CHECKING:
+    from .requests import Request
+
+# Type alias for middleware call_next function
+CallNext = Callable[["Request"], Awaitable[GeminiResponse]]
+
+
+class BaseMiddleware(ABC):
+    """Base class for class-based middleware.
+
+    Subclass this and implement before_request and/or after_response
+    for a cleaner interface than writing raw middleware functions.
+
+    Example:
+        class LoggingMiddleware(BaseMiddleware):
+            async def before_request(
+                self, request: Request
+            ) -> Request | GeminiResponse | None:
+                print(f"Request: {request.path}")
+                return None  # Continue processing
+
+            async def after_response(
+                self, request: Request, response: GeminiResponse
+            ) -> GeminiResponse:
+                print(f"Response: {response.status}")
+                return response
+
+        app.add_middleware(LoggingMiddleware())
+    """
+
+    async def before_request(
+        self, request: "Request"
+    ) -> "Request | GeminiResponse | None":
+        """Called before the handler.
+
+        Args:
+            request: The incoming request.
+
+        Returns:
+            - None: Continue to next middleware/handler
+            - Request: Use this modified request
+            - GeminiResponse: Short-circuit and return this response immediately
+        """
+        return None
+
+    async def after_response(
+        self, request: "Request", response: GeminiResponse
+    ) -> GeminiResponse:
+        """Called after the handler.
+
+        Args:
+            request: The original request.
+            response: The response from the handler.
+
+        Returns:
+            The response to send (can be modified).
+        """
+        return response
+
+    async def __call__(self, request: "Request", call_next: CallNext) -> GeminiResponse:
+        """Process the request through this middleware.
+
+        This implements the middleware protocol by calling before_request,
+        then call_next, then after_response.
+        """
+        # Before request
+        result = await self.before_request(request)
+        if isinstance(result, GeminiResponse):
+            return result  # Short-circuit
+        if result is not None:
+            request = result  # Use modified request
+
+        # Call next handler
+        response = await call_next(request)
+
+        # After response
+        return await self.after_response(request, response)
+
+
+class TimingMiddleware(BaseMiddleware):
+    """Middleware that tracks request processing time.
+
+    Stores the elapsed time in request.state.elapsed_time.
+
+    Example:
+        app.add_middleware(TimingMiddleware())
+
+        @app.gemini("/")
+        def home(request: Request):
+            elapsed = getattr(request.state, 'elapsed_time', 0)
+            return f"# Response generated in {elapsed:.3f}s"
+    """
+
+    async def before_request(
+        self, request: "Request"
+    ) -> "Request | GeminiResponse | None":
+        request.state.start_time = time.perf_counter()
+        return None
+
+    async def after_response(
+        self, request: "Request", response: GeminiResponse
+    ) -> GeminiResponse:
+        elapsed = time.perf_counter() - request.state.start_time
+        request.state.elapsed_time = elapsed
+        return response
+
+
+class LoggingMiddleware(BaseMiddleware):
+    """Middleware that logs requests and responses.
+
+    Example:
+        app.add_middleware(LoggingMiddleware())
+    """
+
+    def __init__(self, logger: Callable[[str], None] | None = None) -> None:
+        """Create logging middleware.
+
+        Args:
+            logger: Custom logging function. Defaults to print.
+        """
+        self._log = logger or print
+
+    async def before_request(
+        self, request: "Request"
+    ) -> "Request | GeminiResponse | None":
+        cert_info = ""
+        if request.client_cert_fingerprint:
+            cert_info = f" [cert:{request.client_cert_fingerprint[:8]}]"
+        self._log(f"[Xitzin] Request: {request.path}{cert_info}")
+        return None
+
+    async def after_response(
+        self, request: "Request", response: GeminiResponse
+    ) -> GeminiResponse:
+        self._log(f"[Xitzin] Response: {response.status} {response.meta}")
+        return response
+
+
+class RateLimitMiddleware(BaseMiddleware):
+    """Simple in-memory rate limiting middleware.
+
+    Limits requests per client based on certificate fingerprint or IP.
+
+    Example:
+        app.add_middleware(RateLimitMiddleware(max_requests=10, window_seconds=60))
+    """
+
+    def __init__(
+        self,
+        max_requests: int = 10,
+        window_seconds: float = 60.0,
+        retry_after: int = 30,
+    ) -> None:
+        """Create rate limit middleware.
+
+        Args:
+            max_requests: Maximum requests allowed per window.
+            window_seconds: Time window in seconds.
+            retry_after: Seconds to tell client to wait.
+        """
+        self.max_requests = max_requests
+        self.window_seconds = window_seconds
+        self.retry_after = retry_after
+        self._requests: dict[str, list[float]] = {}
+
+    def _get_client_id(self, request: "Request") -> str:
+        """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)
+        return "unknown"
+
+    def _is_rate_limited(self, client_id: str) -> bool:
+        """Check if a client is rate limited."""
+        now = time.time()
+        cutoff = now - self.window_seconds
+
+        # Get request timestamps for this client
+        timestamps = self._requests.get(client_id, [])
+
+        # Filter to only recent requests
+        recent = [t for t in timestamps if t > cutoff]
+        self._requests[client_id] = recent
+
+        # Check if over limit
+        if len(recent) >= self.max_requests:
+            return True
+
+        # Record this request
+        recent.append(now)
+        return False
+
+    async def before_request(
+        self, request: "Request"
+    ) -> "Request | GeminiResponse | None":
+        client_id = self._get_client_id(request)
+
+        if self._is_rate_limited(client_id):
+            return GeminiResponse(
+                status=StatusCode.SLOW_DOWN,
+                meta=str(self.retry_after),
+            )
+
+        return None

xitzin/requests.py

@@ -0,0 +1,150 @@
+"""Request wrapper for Xitzin handlers.
+
+Provides a convenient interface to the underlying Nauyaca GeminiRequest.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+from urllib.parse import unquote_plus
+
+from nauyaca.protocol.request import GeminiRequest
+
+if TYPE_CHECKING:
+    from cryptography.x509 import Certificate
+
+    from .application import Xitzin
+
+
+class RequestState:
+    """Arbitrary state storage for a request.
+
+    Middleware and handlers can store arbitrary data here.
+
+    Example:
+        request.state.user = get_current_user()
+        request.state.start_time = time.time()
+    """
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        self.__dict__[name] = value
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return self.__dict__[name]
+        except KeyError:
+            raise AttributeError(f"'RequestState' has no attribute '{name}'") from None
+
+    def __delattr__(self, name: str) -> None:
+        try:
+            del self.__dict__[name]
+        except KeyError:
+            raise AttributeError(f"'RequestState' has no attribute '{name}'") from None
+
+
+class Request:
+    """Wraps a Nauyaca GeminiRequest with convenient accessors.
+
+    Handlers receive this object as their first argument.
+
+    Example:
+        @app.gemini("/user/{username}")
+        def profile(request: Request, username: str):
+            cert_id = request.client_cert_fingerprint
+            viewer = cert_id[:16] if cert_id else 'anonymous'
+            return f"# {username}'s Profile\\n\\nViewing as: {viewer}"
+
+    Attributes:
+        app: The Xitzin application instance.
+        state: Arbitrary state storage for this request.
+        path: The URL path component.
+        query: The decoded query string (user input).
+        raw_query: The raw (URL-encoded) query string.
+        client_cert: The client's TLS certificate, if provided.
+        client_cert_fingerprint: SHA-256 fingerprint of client certificate.
+    """
+
+    def __init__(self, raw_request: GeminiRequest, 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 raw_query(self) -> str:
+        """The raw (URL-encoded) query string."""
+        return self._raw_request.query
+
+    @property
+    def query(self) -> str:
+        """The decoded query string.
+
+        Gemini uses URL query strings for user input (status 10/11 flow).
+        This property decodes the query string for convenient access.
+        """
+        if not self._raw_request.query:
+            return ""
+        return unquote_plus(self._raw_request.query)
+
+    @property
+    def url(self) -> str:
+        """The full normalized URL."""
+        return self._raw_request.normalized_url
+
+    @property
+    def raw_url(self) -> str:
+        """The original URL from the request."""
+        return self._raw_request.raw_url
+
+    @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 remote_addr(self) -> str | None:
+        """The client's IP address, if available.
+
+        Note: This property returns the client IP address if it was set
+        by the server or middleware. In CGI context, this is passed to
+        scripts via the REMOTE_ADDR environment variable.
+
+        Returns:
+            The client IP address string, or None if not available.
+        """
+        return getattr(self._raw_request, "remote_addr", None)
+
+    def __repr__(self) -> str:
+        return f"Request({self._raw_request.raw_url!r})"