xitzin 0.2.0__tar.gz → 0.4.0__tar.gz

{xitzin-0.2.0 → xitzin-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: xitzin
-Version: 0.2.0
+Version: 0.4.0
 Summary: A Gemini Application Framework
 Keywords: gemini,protocol,framework,async,geminispace
 Author: Alan Velasco
@@ -20,15 +20,18 @@ Classifier: Typing :: Typed
 Requires-Dist: jinja2>=3.1.0
 Requires-Dist: nauyaca>=0.3.2
 Requires-Dist: rich>=14.2.0
+Requires-Dist: structlog>=25.5.0
 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

{xitzin-0.2.0 → xitzin-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xitzin"
-version = "0.2.0"
+version = "0.4.0"
 description = "A Gemini Application Framework"
 readme = "README.md"
 license = { text = "MIT" }
@@ -26,6 +26,7 @@ dependencies = [
     "jinja2>=3.1.0",
     "nauyaca>=0.3.2",
     "rich>=14.2.0",
+    "structlog>=25.5.0",
     "typing-extensions>=4.15.0",
 ]
 
@@ -33,6 +34,9 @@ dependencies = [
 sqlmodel = [
     "sqlmodel>=0.0.22",
 ]
+tasks = [
+    "croniter>=1.0.0",
+]
 
 [project.urls]
 Homepage = "https://github.com/alanbato/xitzin"
@@ -47,6 +51,7 @@ build-backend = "uv_build"
 
 [dependency-groups]
 dev = [
+    "croniter>=1.0.0",
     "pre-commit>=4.5.1",
     "pytest>=9.0.2",
     "pytest-asyncio>=0.24.0",

{xitzin-0.2.0 → xitzin-0.4.0}/src/xitzin/__init__.py

@@ -22,6 +22,7 @@ Example:
 
 from .application import Xitzin
 from .cgi import CGIConfig, CGIHandler, CGIScript
+from .scgi import SCGIApp, SCGIConfig, SCGIHandler
 from .exceptions import (
     BadRequest,
     CertificateNotAuthorized,
@@ -38,9 +39,10 @@ from .exceptions import (
     SensitiveInputRequired,
     ServerUnavailable,
     SlowDown,
+    TaskConfigurationError,
     TemporaryFailure,
 )
-from .requests import Request
+from .requests import Request, TitanRequest
 from .responses import Input, Link, Redirect, Response
 
 __all__ = [
@@ -48,6 +50,7 @@ __all__ = [
     "Xitzin",
     # Request/Response
     "Request",
+    "TitanRequest",
     "Response",
     "Input",
     "Redirect",
@@ -56,6 +59,10 @@ __all__ = [
     "CGIConfig",
     "CGIHandler",
     "CGIScript",
+    # SCGI support
+    "SCGIApp",
+    "SCGIConfig",
+    "SCGIHandler",
     # Exceptions
     "GeminiException",
     "InputRequired",
@@ -73,6 +80,7 @@ __all__ = [
     "CertificateRequired",
     "CertificateNotAuthorized",
     "CertificateNotValid",
+    "TaskConfigurationError",
 ]
 
 __version__ = "0.1.0"

{xitzin-0.2.0 → xitzin-0.4.0}/src/xitzin/application.py

@@ -11,15 +11,22 @@ 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
-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
     from .templating import TemplateEngine
 
 
@@ -84,6 +91,8 @@ class Xitzin:
         self._startup_handlers: list[Callable[[], Any]] = []
         self._shutdown_handlers: list[Callable[[], Any]] = []
         self._middleware: list[Callable[..., Any]] = []
+        self._tasks: list[BackgroundTask] = []
+        self._task_handles: list[asyncio.Task[Any]] = []
 
         if templates_dir:
             self._init_templates(Path(templates_dir))
@@ -224,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,
@@ -288,6 +336,69 @@ class Xitzin:
         handler = CGIHandler(script_dir, config=config)
         self.mount(path, handler, name=name)
 
+    def scgi(
+        self,
+        path: str,
+        host: str | None = None,
+        port: int | None = None,
+        socket_path: Path | str | None = None,
+        *,
+        name: str | None = None,
+        timeout: float = 30.0,
+        app_state_keys: list[str] | None = None,
+    ) -> None:
+        """Mount an SCGI backend at a path prefix.
+
+        This is a convenience method that creates an SCGIHandler or SCGIApp
+        and mounts it. Exactly one of (host+port) or socket_path must be provided.
+
+        Args:
+            path: Mount point prefix (e.g., "/dynamic").
+            host: SCGI server hostname (for TCP connection).
+            port: SCGI server port (for TCP connection).
+            socket_path: Path to Unix socket (for local connection).
+            name: Optional name for the mount.
+            timeout: Maximum response wait time in seconds.
+            app_state_keys: App state keys to pass as XITZIN_* env vars.
+
+        Raises:
+            ValueError: If neither or both connection types are specified.
+
+        Example:
+            # TCP connection
+            app.scgi("/dynamic", host="127.0.0.1", port=4000, timeout=30)
+
+            # Unix socket connection
+            app.scgi("/dynamic", socket_path="/tmp/scgi.sock", timeout=30)
+        """
+        from .scgi import SCGIApp, SCGIConfig, SCGIHandler
+
+        # Validate parameters
+        tcp_specified = host is not None or port is not None
+        unix_specified = socket_path is not None
+
+        if tcp_specified and unix_specified:
+            msg = "Cannot specify both TCP (host/port) and Unix socket (socket_path)"
+            raise ValueError(msg)
+        if not tcp_specified and not unix_specified:
+            msg = "Must specify either TCP (host and port) or Unix socket (socket_path)"
+            raise ValueError(msg)
+        if tcp_specified and (host is None or port is None):
+            msg = "Both host and port must be specified for TCP connection"
+            raise ValueError(msg)
+
+        config = SCGIConfig(
+            timeout=timeout,
+            app_state_keys=app_state_keys or [],
+        )
+
+        if tcp_specified:
+            handler = SCGIHandler(host, port, config=config)  # type: ignore[arg-type]
+        else:
+            handler = SCGIApp(socket_path, config=config)  # type: ignore[arg-type]
+
+        self.mount(path, handler, name=name)
+
     def on_startup(self, handler: Callable[[], Any]) -> Callable[[], Any]:
         """Register a startup event handler.
 
@@ -336,6 +447,75 @@ class Xitzin:
         self._middleware.append(handler)
         return handler
 
+    def task(
+        self,
+        *,
+        interval: str | int | float | None = None,
+        cron: str | None = None,
+    ) -> Callable[[Callable[[], Any]], Callable[[], Any]]:
+        """Register a background task.
+
+        Tasks run continuously while the server is running. They are started
+        after startup handlers and stopped before shutdown handlers.
+
+        Args:
+            interval: Run every N seconds (int) or duration string ("1h", "30m", "1d").
+            cron: Cron expression string ("0 * * * *" runs hourly).
+                Requires croniter: pip install 'xitzin[tasks]'
+
+        Exactly one of interval or cron must be provided.
+
+        Returns:
+            Decorator function.
+
+        Raises:
+            TaskConfigurationError: If neither or both parameters provided,
+                or if cron is used but croniter is not installed.
+
+        Example:
+            @app.task(interval="1h")
+            async def cleanup():
+                await app.state.db.cleanup_old_records()
+
+            @app.task(cron="0 2 * * *")  # 2 AM daily
+            def backup():
+                backup_database()
+        """
+        from .tasks import BackgroundTask, parse_interval
+
+        # Validate parameters
+        if interval is None and cron is None:
+            raise TaskConfigurationError("Either 'interval' or 'cron' must be provided")
+        if interval is not None and cron is not None:
+            raise TaskConfigurationError(
+                "Only one of 'interval' or 'cron' can be provided, not both"
+            )
+
+        # Check croniter availability
+        if cron is not None:
+            try:
+                from croniter import croniter as _  # noqa: F401
+            except ImportError:
+                raise TaskConfigurationError(
+                    "croniter is required for cron tasks. "
+                    "Install with: pip install 'xitzin[tasks]'"
+                ) from None
+
+        def decorator(handler: Callable[[], Any]) -> Callable[[], Any]:
+            # Parse interval if provided
+            parsed_interval = parse_interval(interval) if interval else None
+
+            task = BackgroundTask(
+                handler=handler,
+                interval=parsed_interval,
+                cron=cron,
+                name=getattr(handler, "__name__", "<anonymous>"),
+            )
+            self._tasks.append(task)
+            return handler
+
+        return decorator
+
     async def _run_startup(self) -> None:
         """Run all startup handlers."""
         for handler in self._startup_handlers:
@@ -352,6 +532,26 @@ class Xitzin:
             else:
                 handler()
 
+    async def _run_tasks(self) -> None:
+        """Start all registered background tasks."""
+        from .tasks import run_cron_task, run_interval_task
+
+        for task in self._tasks:
+            if task.interval is not None:
+                handle = asyncio.create_task(run_interval_task(task))
+            else:  # task.cron is not None
+                handle = asyncio.create_task(run_cron_task(task))
+            self._task_handles.append(handle)
+
+    async def _stop_tasks(self) -> None:
+        """Stop all running background tasks."""
+        for handle in self._task_handles:
+            handle.cancel()
+        # Wait for all tasks to finish cancelling
+        if self._task_handles:
+            await asyncio.gather(*self._task_handles, return_exceptions=True)
+        self._task_handles.clear()
+
     async def _handle_request(self, raw_request: GeminiRequest) -> GeminiResponse:
         """Handle an incoming request.
 
@@ -408,24 +608,69 @@ class Xitzin:
 
         except GeminiException as e:
             return GeminiResponse(status=e.status_code, meta=e.message)
-        except Exception as e:
+        except Exception:
             # Log the error and return a generic failure
             import traceback
 
             traceback.print_exc()
             return GeminiResponse(
                 status=StatusCode.TEMPORARY_FAILURE,
-                meta=f"Internal error: {type(e).__name__}",
+                meta="Internal server error",
+            )
+
+    async def _handle_titan_request(
+        self, raw_request: NauyacaTitanRequest
+    ) -> GeminiResponse:
+        """Handle an incoming Titan upload request.
+
+        This is the Titan request processing logic, separate from Gemini.
+        """
+        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}")
+
+            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")
+
+            # Build middleware chain
+            async def call_handler(req: TitanRequest) -> GeminiResponse:
+                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)
+
+            return await handler(request)
+
+        except GeminiException as e:
+            return GeminiResponse(status=e.status_code, meta=e.message)
+        except Exception:
+            import traceback
+
+            traceback.print_exc()
+            return GeminiResponse(
+                status=StatusCode.TEMPORARY_FAILURE,
+                meta="Internal server error",
             )
 
     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)
@@ -462,6 +707,9 @@ class Xitzin:
         # Run startup handlers
         await self._run_startup()
 
+        # Start background tasks
+        await self._run_tasks()
+
         try:
             # Create PyOpenSSL context (accepts any self-signed client cert)
             if certfile and keyfile:
@@ -501,11 +749,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,
                 )
 
@@ -523,6 +790,8 @@ class Xitzin:
                 await server.serve_forever()
 
         finally:
+            # Stop background tasks
+            await self._stop_tasks()
             await self._run_shutdown()
 
     def run(

{xitzin-0.2.0 → xitzin-0.4.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.2.0 → xitzin-0.4.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.2.0 → xitzin-0.4.0}/src/xitzin/exceptions.py

@@ -136,3 +136,21 @@ class CertificateNotValid(GeminiException):
 
     status_code = 62
     default_message = "Certificate not valid"
+
+
+# Application configuration errors
+class TaskConfigurationError(Exception):
+    """Raised when a background task is misconfigured.
+
+    This typically indicates mutually exclusive parameters were provided,
+    or a required optional dependency is missing.
+
+    Example:
+        @app.task()  # Error: neither interval nor cron provided
+        def my_task():
+            pass
+
+        @app.task(interval="1h", cron="* * * * *")  # Error: both provided
+        def my_task():
+            pass
+    """