xitzin 0.1.3__py3-none-any.whl → 0.3.0__py3-none-any.whl

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,6 +39,7 @@ from .exceptions import (
     SensitiveInputRequired,
     ServerUnavailable,
     SlowDown,
+    TaskConfigurationError,
     TemporaryFailure,
 )
 from .requests import Request
@@ -56,6 +58,10 @@ __all__ = [
     "CGIConfig",
     "CGIHandler",
     "CGIScript",
+    # SCGI support
+    "SCGIApp",
+    "SCGIConfig",
+    "SCGIHandler",
     # Exceptions
     "GeminiException",
     "InputRequired",
@@ -73,6 +79,7 @@ __all__ = [
     "CertificateRequired",
     "CertificateNotAuthorized",
     "CertificateNotValid",
+    "TaskConfigurationError",
 ]
 
 __version__ = "0.1.0"

xitzin/application.py

@@ -14,12 +14,13 @@ from nauyaca.protocol.request import GeminiRequest
 from nauyaca.protocol.response import GeminiResponse
 from nauyaca.protocol.status import StatusCode
 
-from .exceptions import GeminiException, NotFound
+from .exceptions import GeminiException, NotFound, TaskConfigurationError
 from .requests import Request
 from .responses import Input, Redirect, convert_response
 from .routing import MountedRoute, Route, Router
 
 if TYPE_CHECKING:
+    from .tasks import BackgroundTask
     from .templating import TemplateEngine
 
 
@@ -84,6 +85,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))
@@ -288,6 +291,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 +402,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 +487,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.
 
@@ -462,6 +617,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:
@@ -523,6 +681,8 @@ class Xitzin:
                 await server.serve_forever()
 
         finally:
+            # Stop background tasks
+            await self._stop_tasks()
             await self._run_shutdown()
 
     def run(

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
+    """

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__(
@@ -217,3 +237,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)  # type: ignore[misc]
+
+        # 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/scgi.py

@@ -0,0 +1,447 @@
+"""SCGI support for Xitzin applications.
+
+This module provides SCGI (Simple Common Gateway Interface) client support
+for proxying requests to persistent backend processes. Unlike CGI which
+spawns a new process per request, SCGI connects to a running server process.
+
+Example:
+    from xitzin import Xitzin
+    from xitzin.scgi import SCGIHandler, SCGIConfig
+
+    app = Xitzin()
+
+    # Mount an SCGI backend via TCP
+    config = SCGIConfig(timeout=30)
+    app.mount("/dynamic", SCGIHandler("127.0.0.1", 4000, config=config))
+
+    # Or via Unix socket
+    app.mount("/api", SCGIApp("/tmp/scgi.sock", config=config))
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from nauyaca.protocol.response import GeminiResponse
+
+from .cgi import build_cgi_env, parse_cgi_output
+from .exceptions import CGIError, ProxyError
+
+if TYPE_CHECKING:
+    from .requests import Request
+
+
+@dataclass
+class SCGIConfig:
+    """Configuration for SCGI backend communication.
+
+    Attributes:
+        timeout: Maximum time to wait for SCGI response in seconds.
+        max_response_size: Maximum response size in bytes (None = unlimited).
+        buffer_size: Read buffer size for streaming responses.
+        inherit_environment: Whether to inherit parent environment variables.
+        app_state_keys: App state keys to pass as XITZIN_* env vars.
+    """
+
+    timeout: float = 30.0
+    max_response_size: int | None = 1048576  # 1MB default
+    buffer_size: int = 8192
+    inherit_environment: bool = True
+    app_state_keys: list[str] = field(default_factory=list)
+
+
+def encode_netstring(data: bytes) -> bytes:
+    """Encode data as a netstring.
+
+    Netstring format: <length>:<data>,
+
+    Args:
+        data: Bytes to encode.
+
+    Returns:
+        Netstring-encoded bytes.
+
+    Example:
+        >>> encode_netstring(b"hello")
+        b'5:hello,'
+    """
+    length = str(len(data)).encode("ascii")
+    return length + b":" + data + b","
+
+
+def encode_scgi_headers(env: dict[str, str]) -> bytes:
+    """Encode CGI environment as SCGI headers.
+
+    SCGI format is a netstring containing null-separated key-value pairs:
+    <key>\\0<value>\\0<key>\\0<value>\\0...
+
+    The CONTENT_LENGTH header must come first per SCGI spec.
+
+    Args:
+        env: CGI environment dictionary.
+
+    Returns:
+        Netstring-encoded headers ready for SCGI transmission.
+
+    Example:
+        >>> env = {"CONTENT_LENGTH": "0", "SCGI": "1", "PATH_INFO": "/test"}
+        >>> encode_scgi_headers(env)  # Returns netstring with headers
+    """
+    parts: list[bytes] = []
+
+    # CONTENT_LENGTH must be first per SCGI spec
+    content_length = env.get("CONTENT_LENGTH", "0")
+    parts.append(b"CONTENT_LENGTH\x00")
+    parts.append(content_length.encode("utf-8"))
+    parts.append(b"\x00")
+
+    # Add remaining headers
+    for key, value in env.items():
+        if key == "CONTENT_LENGTH":
+            continue  # Already added first
+        parts.append(key.encode("utf-8"))
+        parts.append(b"\x00")
+        parts.append(value.encode("utf-8"))
+        parts.append(b"\x00")
+
+    headers = b"".join(parts)
+    return encode_netstring(headers)
+
+
+class SCGIHandler:
+    """Proxy requests to an SCGI backend server via TCP socket.
+
+    This handler forwards requests to an SCGI application server
+    (like Python's flup, or custom SCGI servers) over a TCP connection.
+
+    Example:
+        from xitzin.scgi import SCGIHandler, SCGIConfig
+
+        config = SCGIConfig(timeout=30)
+        handler = SCGIHandler("127.0.0.1", 4000, config=config)
+        app.mount("/dynamic", handler)
+
+        # Requests to /dynamic/* are forwarded to 127.0.0.1:4000
+    """
+
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        *,
+        config: SCGIConfig | None = None,
+    ) -> None:
+        """Create an SCGI TCP handler.
+
+        Args:
+            host: SCGI server hostname or IP.
+            port: SCGI server port.
+            config: SCGI communication configuration.
+        """
+        self.host = host
+        self.port = port
+        self.config = config or SCGIConfig()
+
+    async def __call__(self, request: Request, path_info: str) -> GeminiResponse:
+        """Forward request to SCGI backend.
+
+        Args:
+            request: The Gemini request.
+            path_info: Path after the mount prefix.
+
+        Returns:
+            GeminiResponse from the SCGI backend.
+
+        Raises:
+            ProxyError: If connection or communication fails.
+        """
+        # Build CGI environment (reuse from cgi.py)
+        app_state_vars = self._get_app_state_vars(request)
+        env = build_cgi_env(
+            request,
+            script_name="",  # SCGI app handles routing internally
+            path_info=path_info,
+            app_state_vars=app_state_vars,
+            inherit_environment=self.config.inherit_environment,
+        )
+
+        # Add SCGI-specific variables
+        env["SCGI"] = "1"
+        env["CONTENT_LENGTH"] = "0"  # Gemini has no request body
+
+        # Connect to SCGI backend
+        try:
+            reader, writer = await asyncio.wait_for(
+                asyncio.open_connection(self.host, self.port),
+                timeout=self.config.timeout,
+            )
+        except asyncio.TimeoutError:
+            raise ProxyError(
+                f"SCGI connection timeout to {self.host}:{self.port}"
+            ) from None
+        except OSError as e:
+            raise ProxyError(
+                f"Failed to connect to SCGI backend at {self.host}:{self.port}: {e}"
+            ) from e
+
+        try:
+            # Send SCGI headers
+            headers = encode_scgi_headers(env)
+            writer.write(headers)
+            await writer.drain()
+
+            # Read response
+            response_data = await self._read_response(reader)
+
+            # Parse as CGI output (reuse from cgi.py)
+            cgi_response = parse_cgi_output(response_data, None)
+
+            return GeminiResponse(
+                status=cgi_response.status,
+                meta=cgi_response.meta,
+                body=cgi_response.body,
+            )
+
+        except asyncio.TimeoutError:
+            raise ProxyError(
+                f"SCGI backend timeout after {self.config.timeout}s"
+            ) from None
+        except CGIError as e:
+            # Re-raise as ProxyError (status 43 instead of 42)
+            raise ProxyError(f"SCGI backend error: {e.message}") from e
+        except ProxyError:
+            raise
+        except Exception as e:
+            raise ProxyError(f"SCGI communication error: {e}") from e
+        finally:
+            writer.close()
+            await writer.wait_closed()
+
+    async def _read_response(self, reader: asyncio.StreamReader) -> bytes:
+        """Read full response from SCGI backend.
+
+        Args:
+            reader: Stream reader connected to SCGI backend.
+
+        Returns:
+            Complete response bytes.
+
+        Raises:
+            ProxyError: If response exceeds max size or read fails.
+        """
+        chunks: list[bytes] = []
+        total_size = 0
+
+        while True:
+            try:
+                chunk = await asyncio.wait_for(
+                    reader.read(self.config.buffer_size),
+                    timeout=self.config.timeout,
+                )
+            except asyncio.TimeoutError:
+                raise ProxyError("SCGI backend read timeout") from None
+
+            if not chunk:
+                break
+
+            chunks.append(chunk)
+            total_size += len(chunk)
+
+            if (
+                self.config.max_response_size
+                and total_size > self.config.max_response_size
+            ):
+                raise ProxyError(
+                    f"SCGI response exceeds maximum size "
+                    f"({self.config.max_response_size} bytes)"
+                )
+
+        return b"".join(chunks)
+
+    def _get_app_state_vars(self, request: Request) -> dict[str, str]:
+        """Extract app state variables to pass to SCGI backend."""
+        if not self.config.app_state_keys:
+            return {}
+
+        result: dict[str, str] = {}
+        try:
+            app_state = request.app.state
+            for key in self.config.app_state_keys:
+                try:
+                    value = getattr(app_state, key)
+                    result[key] = str(value)
+                except AttributeError:
+                    pass
+        except RuntimeError:
+            # Request not bound to app
+            pass
+
+        return result
+
+
+class SCGIApp:
+    """Proxy requests to an SCGI backend server via Unix socket.
+
+    This handler forwards requests to an SCGI application server
+    over a Unix domain socket (more efficient for local communication).
+
+    Example:
+        from xitzin.scgi import SCGIApp, SCGIConfig
+
+        config = SCGIConfig(timeout=30)
+        handler = SCGIApp("/tmp/scgi.sock", config=config)
+        app.mount("/dynamic", handler)
+
+        # Requests to /dynamic/* are forwarded to /tmp/scgi.sock
+    """
+
+    def __init__(
+        self,
+        socket_path: Path | str,
+        *,
+        config: SCGIConfig | None = None,
+    ) -> None:
+        """Create an SCGI Unix socket handler.
+
+        Args:
+            socket_path: Path to the Unix socket.
+            config: SCGI communication configuration.
+        """
+        self.socket_path = Path(socket_path)
+        self.config = config or SCGIConfig()
+
+    async def __call__(self, request: Request, path_info: str) -> GeminiResponse:
+        """Forward request to SCGI backend via Unix socket.
+
+        Args:
+            request: The Gemini request.
+            path_info: Path after the mount prefix.
+
+        Returns:
+            GeminiResponse from the SCGI backend.
+
+        Raises:
+            ProxyError: If connection or communication fails.
+        """
+        # Build CGI environment (reuse from cgi.py)
+        app_state_vars = self._get_app_state_vars(request)
+        env = build_cgi_env(
+            request,
+            script_name="",
+            path_info=path_info,
+            app_state_vars=app_state_vars,
+            inherit_environment=self.config.inherit_environment,
+        )
+
+        # Add SCGI-specific variables
+        env["SCGI"] = "1"
+        env["CONTENT_LENGTH"] = "0"
+
+        # Connect via Unix socket
+        try:
+            reader, writer = await asyncio.wait_for(
+                asyncio.open_unix_connection(str(self.socket_path)),
+                timeout=self.config.timeout,
+            )
+        except FileNotFoundError:
+            raise ProxyError(f"SCGI socket not found: {self.socket_path}") from None
+        except asyncio.TimeoutError:
+            raise ProxyError(f"SCGI connection timeout to {self.socket_path}") from None
+        except OSError as e:
+            raise ProxyError(
+                f"Failed to connect to SCGI backend at {self.socket_path}: {e}"
+            ) from e
+
+        try:
+            # Send SCGI headers
+            headers = encode_scgi_headers(env)
+            writer.write(headers)
+            await writer.drain()
+
+            # Read response
+            response_data = await self._read_response(reader)
+
+            # Parse as CGI output (reuse from cgi.py)
+            cgi_response = parse_cgi_output(response_data, None)
+
+            return GeminiResponse(
+                status=cgi_response.status,
+                meta=cgi_response.meta,
+                body=cgi_response.body,
+            )
+
+        except asyncio.TimeoutError:
+            raise ProxyError(
+                f"SCGI backend timeout after {self.config.timeout}s"
+            ) from None
+        except CGIError as e:
+            raise ProxyError(f"SCGI backend error: {e.message}") from e
+        except ProxyError:
+            raise
+        except Exception as e:
+            raise ProxyError(f"SCGI communication error: {e}") from e
+        finally:
+            writer.close()
+            await writer.wait_closed()
+
+    async def _read_response(self, reader: asyncio.StreamReader) -> bytes:
+        """Read full response from SCGI backend."""
+        chunks: list[bytes] = []
+        total_size = 0
+
+        while True:
+            try:
+                chunk = await asyncio.wait_for(
+                    reader.read(self.config.buffer_size),
+                    timeout=self.config.timeout,
+                )
+            except asyncio.TimeoutError:
+                raise ProxyError("SCGI backend read timeout") from None
+
+            if not chunk:
+                break
+
+            chunks.append(chunk)
+            total_size += len(chunk)
+
+            if (
+                self.config.max_response_size
+                and total_size > self.config.max_response_size
+            ):
+                raise ProxyError(
+                    f"SCGI response exceeds maximum size "
+                    f"({self.config.max_response_size} bytes)"
+                )
+
+        return b"".join(chunks)
+
+    def _get_app_state_vars(self, request: Request) -> dict[str, str]:
+        """Extract app state variables to pass to SCGI backend."""
+        if not self.config.app_state_keys:
+            return {}
+
+        result: dict[str, str] = {}
+        try:
+            app_state = request.app.state
+            for key in self.config.app_state_keys:
+                try:
+                    value = getattr(app_state, key)
+                    result[key] = str(value)
+                except AttributeError:
+                    pass
+        except RuntimeError:
+            pass
+
+        return result
+
+
+__all__ = [
+    "SCGIApp",
+    "SCGIConfig",
+    "SCGIHandler",
+    "encode_netstring",
+    "encode_scgi_headers",
+]

xitzin/sqlmodel.py

@@ -0,0 +1,172 @@
+"""SQLModel integration for Xitzin.
+
+This module provides database session management through middleware
+and helper functions. Requires the 'sqlmodel' optional dependency.
+
+Install with: pip install xitzin[sqlmodel]
+
+Example:
+    from sqlmodel import Field, select
+    from xitzin import Xitzin, Request
+    from xitzin.sqlmodel import (
+        SQLModel,
+        create_engine,
+        SessionMiddleware,
+        get_session,
+        init_db,
+    )
+
+    # Define models
+    class Entry(SQLModel, table=True):
+        id: int | None = Field(default=None, primary_key=True)
+        content: str
+
+    # Setup app
+    app = Xitzin()
+    engine = create_engine("sqlite:///./database.db")
+
+    # Initialize database and add middleware
+    init_db(app, engine)
+    app.middleware(SessionMiddleware(engine))
+
+    # Use in routes
+    @app.gemini("/entries")
+    def list_entries(request: Request):
+        session = get_session(request)
+        entries = session.exec(select(Entry)).all()
+        return render_entries(entries)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Awaitable, Callable
+
+from sqlalchemy import Engine
+from sqlmodel import Session, SQLModel, create_engine
+
+if TYPE_CHECKING:
+    from nauyaca.protocol.response import GeminiResponse
+
+    from xitzin.application import Xitzin
+    from xitzin.requests import Request
+
+__all__ = [
+    "SQLModel",
+    "Session",
+    "create_engine",
+    "SessionMiddleware",
+    "get_session",
+    "init_db",
+]
+
+
+def SessionMiddleware(
+    engine: Engine,
+    *,
+    autoflush: bool = True,
+) -> Callable[
+    ["Request", Callable[["Request"], Awaitable["GeminiResponse"]]],
+    Awaitable["GeminiResponse"],
+]:
+    """Create a middleware that manages database sessions per request.
+
+    The session is stored in request.state.db and automatically committed
+    on success or rolled back on error.
+
+    Args:
+        engine: SQLAlchemy engine instance.
+        autoflush: If True, flush before queries. Defaults to True.
+
+    Returns:
+        Middleware function compatible with @app.middleware.
+
+    Example:
+        engine = create_engine("sqlite:///./database.db")
+        app.middleware(SessionMiddleware(engine))
+    """
+
+    async def middleware(
+        request: "Request",
+        call_next: Callable[["Request"], Awaitable["GeminiResponse"]],
+    ) -> "GeminiResponse":
+        session = Session(engine, autoflush=autoflush)
+        request.state.db = session
+
+        try:
+            response = await call_next(request)
+            session.commit()
+            return response
+        except Exception:
+            session.rollback()
+            raise
+        finally:
+            session.close()
+
+    return middleware
+
+
+def get_session(request: "Request") -> Session:
+    """Get the database session from the current request.
+
+    This helper retrieves the session created by SessionMiddleware.
+
+    Args:
+        request: The current Xitzin request object.
+
+    Returns:
+        SQLModel Session instance.
+
+    Raises:
+        AttributeError: If SessionMiddleware is not configured.
+
+    Example:
+        @app.gemini("/users/{user_id}")
+        def get_user(request: Request, user_id: int):
+            session = get_session(request)
+            user = session.get(User, user_id)
+            return f"# {user.name}"
+    """
+    if not hasattr(request.state, "db"):
+        raise AttributeError(
+            "No database session found. Did you add SessionMiddleware?"
+        )
+    return request.state.db
+
+
+def init_db(
+    app: "Xitzin",
+    engine: Engine,
+    *,
+    create_tables: bool = True,
+    drop_all: bool = False,
+) -> None:
+    """Initialize database with lifecycle hooks.
+
+    This helper registers startup/shutdown hooks to manage table creation
+    and engine cleanup.
+
+    Args:
+        app: Xitzin application instance.
+        engine: SQLAlchemy engine instance.
+        create_tables: Create all tables on startup. Defaults to True.
+        drop_all: Drop all tables before creating. Defaults to False.
+
+    Warning:
+        Setting drop_all=True will DELETE ALL DATA on startup!
+
+    Example:
+        app = Xitzin()
+        engine = create_engine("sqlite:///./database.db")
+        init_db(app, engine)
+    """
+
+    @app.on_startup
+    def create_db_tables() -> None:
+        if drop_all:
+            SQLModel.metadata.drop_all(engine)
+        if create_tables:
+            SQLModel.metadata.create_all(engine)
+
+    @app.on_shutdown
+    def dispose_engine() -> None:
+        engine.dispose()

xitzin/tasks.py

@@ -0,0 +1,176 @@
+"""Background task scheduling for Xitzin.
+
+This module provides background task execution with interval-based
+and cron-based scheduling.
+
+Example:
+    from xitzin import Xitzin
+
+    app = Xitzin()
+
+    @app.task(interval="1h")
+    async def hourly_cleanup():
+        await cleanup_old_records()
+
+    @app.task(cron="0 2 * * *")  # 2 AM daily
+    def daily_backup():
+        backup_database()
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Callable
+
+import structlog
+
+logger = structlog.get_logger("xitzin.tasks")
+
+
+async def _execute_handler(handler: Callable[[], Any]) -> None:
+    """Execute a task handler, wrapping sync handlers in executor.
+
+    Args:
+        handler: The handler function to execute.
+    """
+    if asyncio.iscoroutinefunction(handler):
+        await handler()
+    else:
+        loop = asyncio.get_running_loop()
+        await loop.run_in_executor(None, handler)
+
+
+@dataclass
+class BackgroundTask:
+    """Configuration for a background task."""
+
+    handler: Callable[[], Any]
+    interval: float | None  # Seconds
+    cron: str | None
+    name: str
+
+
+def parse_interval(interval: str | int | float) -> float:
+    """Parse interval string or int to seconds.
+
+    Args:
+        interval: Either an integer/float (seconds) or string like "1h", "30m", "1d"
+
+    Returns:
+        Interval in seconds
+
+    Raises:
+        ValueError: If format is invalid
+    """
+    if isinstance(interval, (int, float)):
+        if interval <= 0:
+            raise ValueError("Interval must be positive")
+        return float(interval)
+
+    # Parse duration strings
+    pattern = r"^(\d+)([smhd])$"
+    match = re.match(pattern, interval.lower().strip())
+    if not match:
+        raise ValueError(
+            f"Invalid interval format: {interval!r}. "
+            "Use integer seconds or format like '1h', '30m', '1d'"
+        )
+
+    value, unit = match.groups()
+    value = int(value)
+
+    multipliers = {
+        "s": 1,
+        "m": 60,
+        "h": 3600,
+        "d": 86400,
+    }
+
+    return float(value * multipliers[unit])
+
+
+async def run_interval_task(task: BackgroundTask) -> None:
+    """Run a task on a fixed interval.
+
+    Args:
+        task: The task to run
+    """
+    task_logger = logger.bind(task=task.name)
+    task_logger.info("task_started", interval=task.interval)
+
+    while True:
+        try:
+            # Wait first (standard behavior)
+            await asyncio.sleep(task.interval)  # type: ignore[arg-type]
+
+            # Execute handler
+            await _execute_handler(task.handler)
+            task_logger.debug("task_executed")
+
+        except asyncio.CancelledError:
+            task_logger.info("task_cancelled")
+            raise
+        except Exception as e:
+            task_logger.error(
+                "task_failed",
+                error=str(e),
+                error_type=type(e).__name__,
+            )
+            # Continue running despite errors
+
+
+async def run_cron_task(task: BackgroundTask) -> None:
+    """Run a task on a cron schedule.
+
+    Args:
+        task: The task to run
+    """
+    from croniter import croniter
+
+    task_logger = logger.bind(task=task.name)
+    task_logger.info("task_started", cron=task.cron)
+
+    try:
+        cron_iter = croniter(task.cron, datetime.now(timezone.utc))
+    except Exception as e:
+        task_logger.error(
+            "task_cron_invalid",
+            cron=task.cron,
+            error=str(e),
+            error_type=type(e).__name__,
+        )
+        raise
+
+    while True:
+        try:
+            # Calculate next run time
+            next_run = cron_iter.get_next(datetime)
+            now = datetime.now(timezone.utc)
+
+            # Handle timezone-naive datetime from croniter
+            if next_run.tzinfo is None:
+                next_run = next_run.replace(tzinfo=timezone.utc)
+
+            sleep_seconds = (next_run - now).total_seconds()
+
+            if sleep_seconds > 0:
+                task_logger.debug("task_waiting", next_run=next_run.isoformat())
+                await asyncio.sleep(sleep_seconds)
+
+            # Execute handler
+            await _execute_handler(task.handler)
+            task_logger.debug("task_executed")
+
+        except asyncio.CancelledError:
+            task_logger.info("task_cancelled")
+            raise
+        except Exception as e:
+            task_logger.error(
+                "task_failed",
+                error=str(e),
+                error_type=type(e).__name__,
+            )
+            # Continue running despite errors

{xitzin-0.1.3.dist-info → xitzin-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: xitzin
-Version: 0.1.3
+Version: 0.3.0
 Summary: A Gemini Application Framework
 Keywords: gemini,protocol,framework,async,geminispace
 Author: Alan Velasco
@@ -20,13 +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: Repository, https://github.com/alanbato/xitzin.git
+Provides-Extra: sqlmodel
+Provides-Extra: tasks
 Description-Content-Type: text/markdown
 
 # Xitzin

xitzin-0.3.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+xitzin/__init__.py,sha256=NwOPmRS4lfOkkUyG1_RNjveqPL2p7pvQvnNyTPTWvdo,1817
+xitzin/application.py,sha256=cHKfrGWPsbMHd445YIsXV6BBTtyK7-MnM2PD7JUNXqg,23834
+xitzin/auth.py,sha256=KT1WprT4qF1u03T8lAGO_UzQBLQcg-OegIFubay7VlA,4511
+xitzin/cgi.py,sha256=nmKaeLwYfk3esRnxQnn1Rx-6EHKq2zL-Xvpw5hdI-rk,17627
+xitzin/exceptions.py,sha256=82z-CjyC0FwFbo9hGTjjmurlL_Vd4rTVdgkmQoFLXT0,3883
+xitzin/middleware.py,sha256=q19ePBvIMgbR97qNud8NJj94yhZuwnJfwsR5PakQY0M,12499
+xitzin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xitzin/requests.py,sha256=EeDqh0roz7eTItqarEDj53iFxMZlVsEIcimybKdqAHI,4612
+xitzin/responses.py,sha256=N4HeP9Yy2PIHY0zsGa2pj8xvX2OFHAjtqR5nogNh8UQ,6545
+xitzin/routing.py,sha256=SiT9J617GfQR_rPDD3Ivw0_N4CTh8-Jb_AZjWJnT5sw,12409
+xitzin/scgi.py,sha256=PKpbIAsHs0iw998AwMvSPlHyoNjDDlxIHi5drOafiqo,13664
+xitzin/sqlmodel.py,sha256=lZvDzYAgnG8S2K-EYnx6PkO7D68pjM06uQLSKUZ9yY4,4500
+xitzin/tasks.py,sha256=_smEXy-THge8wmQqWDtX3iUmAmoHniw_qqZBlKjCdqA,4597
+xitzin/templating.py,sha256=spjxb05wgwKA4txOMbWJuwEVMaoLovo13_ukbXAcBDY,6040
+xitzin/testing.py,sha256=JO41TeIJeb1CqHVqBOjCVAvv9BOlvDJYzAeG83ZofdE,7572
+xitzin-0.3.0.dist-info/WHEEL,sha256=RRVLqVugUmFOqBedBFAmA4bsgFcROUBiSUKlERi0Hcg,79
+xitzin-0.3.0.dist-info/METADATA,sha256=S1yYzsGTGQOtg-FdeEcpllwiUGA5Wqt_XiXpcpu6sJU,3456
+xitzin-0.3.0.dist-info/RECORD,,

xitzin-0.1.3.dist-info/RECORD

@@ -1,15 +0,0 @@
-xitzin/__init__.py,sha256=9zCk_h4rI-QGLE3q95NSgPha-dtvSOEdwiZuTQmbBR4,1637
-xitzin/application.py,sha256=GWcL-u1C6xiUwYwMxg60kQxprJ_KaLcJFPcIBf8xCzU,17909
-xitzin/auth.py,sha256=KT1WprT4qF1u03T8lAGO_UzQBLQcg-OegIFubay7VlA,4511
-xitzin/cgi.py,sha256=nmKaeLwYfk3esRnxQnn1Rx-6EHKq2zL-Xvpw5hdI-rk,17627
-xitzin/exceptions.py,sha256=JdxAXHtnXMf6joXeFQMfxlcdbv_R5odb-qYPMbgRTZY,3382
-xitzin/middleware.py,sha256=z2QJJjMEinz5e4NeZvjsCeyMLt8ZD2a3Ox2V2vuTnk8,6748
-xitzin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-xitzin/requests.py,sha256=EeDqh0roz7eTItqarEDj53iFxMZlVsEIcimybKdqAHI,4612
-xitzin/responses.py,sha256=N4HeP9Yy2PIHY0zsGa2pj8xvX2OFHAjtqR5nogNh8UQ,6545
-xitzin/routing.py,sha256=SiT9J617GfQR_rPDD3Ivw0_N4CTh8-Jb_AZjWJnT5sw,12409
-xitzin/templating.py,sha256=spjxb05wgwKA4txOMbWJuwEVMaoLovo13_ukbXAcBDY,6040
-xitzin/testing.py,sha256=JO41TeIJeb1CqHVqBOjCVAvv9BOlvDJYzAeG83ZofdE,7572
-xitzin-0.1.3.dist-info/WHEEL,sha256=RRVLqVugUmFOqBedBFAmA4bsgFcROUBiSUKlERi0Hcg,79
-xitzin-0.1.3.dist-info/METADATA,sha256=0K_lXt3a_Vy_itxhTC7hbbQPLEZ4dqMUhNhg3UqIDjs,3272
-xitzin-0.1.3.dist-info/RECORD,,