servicekit 0.3.5__py3-none-any.whl

servicekit/__init__.py

@@ -0,0 +1,78 @@
+"""Core framework components - generic interfaces and base classes."""
+
+# ruff: noqa: F401
+
+# Base infrastructure (framework-agnostic)
+from .database import Database, SqliteDatabase, SqliteDatabaseBuilder
+from .exceptions import (
+    BadRequestError,
+    ConflictError,
+    ErrorType,
+    ForbiddenError,
+    InvalidULIDError,
+    NotFoundError,
+    ServicekitException,
+    UnauthorizedError,
+    ValidationError,
+)
+from .logging import add_request_context, clear_request_context, configure_logging, get_logger, reset_request_context
+from .manager import BaseManager, LifecycleHooks, Manager
+from .models import Base, Entity
+from .repository import BaseRepository, Repository
+from .scheduler import AIOJobScheduler, JobScheduler
+from .schemas import (
+    BulkOperationError,
+    BulkOperationResult,
+    EntityIn,
+    EntityOut,
+    JobRecord,
+    JobStatus,
+    PaginatedResponse,
+    ProblemDetail,
+)
+from .types import JsonSafe, ULIDType
+
+__all__ = [
+    # Base infrastructure
+    "Database",
+    "SqliteDatabase",
+    "SqliteDatabaseBuilder",
+    "Repository",
+    "BaseRepository",
+    "Manager",
+    "LifecycleHooks",
+    "BaseManager",
+    # ORM and types
+    "Base",
+    "Entity",
+    "ULIDType",
+    "JsonSafe",
+    # Schemas
+    "EntityIn",
+    "EntityOut",
+    "PaginatedResponse",
+    "BulkOperationResult",
+    "BulkOperationError",
+    "ProblemDetail",
+    "JobRecord",
+    "JobStatus",
+    # Job scheduling
+    "JobScheduler",
+    "AIOJobScheduler",
+    # Exceptions
+    "ErrorType",
+    "ServicekitException",
+    "NotFoundError",
+    "ValidationError",
+    "ConflictError",
+    "InvalidULIDError",
+    "BadRequestError",
+    "UnauthorizedError",
+    "ForbiddenError",
+    # Logging
+    "configure_logging",
+    "get_logger",
+    "add_request_context",
+    "clear_request_context",
+    "reset_request_context",
+]

servicekit/api/__init__.py

@@ -0,0 +1,72 @@
+"""FastAPI framework layer - routers, middleware, utilities."""
+
+from .app import App, AppInfo, AppLoader, AppManager, AppManifest
+from .auth import APIKeyMiddleware, load_api_keys_from_env, load_api_keys_from_file, validate_api_key_format
+from .crud import CrudPermissions, CrudRouter
+from .dependencies import (
+    get_app_manager,
+    get_database,
+    get_scheduler,
+    get_session,
+    set_app_manager,
+    set_database,
+    set_scheduler,
+)
+from .middleware import add_error_handlers, add_logging_middleware, database_error_handler, validation_error_handler
+from .pagination import PaginationParams, create_paginated_response
+from .router import Router
+from .routers import HealthRouter, HealthState, HealthStatus, JobRouter, SystemInfo, SystemRouter
+from .service_builder import BaseServiceBuilder, ServiceInfo
+from .sse import SSE_HEADERS, format_sse_event, format_sse_model_event
+from .utilities import build_location_url, run_app
+
+__all__ = [
+    # Base router classes
+    "Router",
+    "CrudRouter",
+    "CrudPermissions",
+    # Service builder
+    "BaseServiceBuilder",
+    "ServiceInfo",
+    # App system
+    "App",
+    "AppInfo",
+    "AppLoader",
+    "AppManifest",
+    "AppManager",
+    # Authentication
+    "APIKeyMiddleware",
+    "load_api_keys_from_env",
+    "load_api_keys_from_file",
+    "validate_api_key_format",
+    # Dependencies
+    "get_app_manager",
+    "set_app_manager",
+    "get_database",
+    "set_database",
+    "get_session",
+    "get_scheduler",
+    "set_scheduler",
+    # Middleware
+    "add_error_handlers",
+    "add_logging_middleware",
+    "database_error_handler",
+    "validation_error_handler",
+    # Pagination
+    "PaginationParams",
+    "create_paginated_response",
+    # System routers
+    "HealthRouter",
+    "HealthState",
+    "HealthStatus",
+    "JobRouter",
+    "SystemRouter",
+    "SystemInfo",
+    # SSE utilities
+    "SSE_HEADERS",
+    "format_sse_event",
+    "format_sse_model_event",
+    # Utilities
+    "build_location_url",
+    "run_app",
+]

servicekit/api/app.py

@@ -0,0 +1,225 @@
+"""App system for hosting static web applications."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from servicekit.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class AppManifest(BaseModel):
+    """App manifest configuration."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(description="Human-readable app name")
+    version: str = Field(description="Semantic version")
+    prefix: str = Field(description="URL prefix for mounting")
+    description: str | None = Field(default=None, description="App description")
+    author: str | None = Field(default=None, description="Author name")
+    entry: str = Field(default="index.html", description="Entry point filename")
+
+    @field_validator("prefix")
+    @classmethod
+    def validate_prefix(cls, v: str) -> str:
+        """Validate mount prefix format."""
+        if not v.startswith("/"):
+            raise ValueError("prefix must start with '/'")
+        if ".." in v:
+            raise ValueError("prefix cannot contain '..'")
+        if v.startswith("/api/") or v == "/api":
+            raise ValueError("prefix cannot be '/api' or start with '/api/'")
+        return v
+
+    @field_validator("entry")
+    @classmethod
+    def validate_entry(cls, v: str) -> str:
+        """Validate entry file path for security."""
+        if ".." in v:
+            raise ValueError("entry cannot contain '..'")
+        if v.startswith("/"):
+            raise ValueError("entry must be a relative path")
+        # Normalize and check for path traversal
+        normalized = Path(v).as_posix()
+        if normalized.startswith("../") or "/../" in normalized:
+            raise ValueError("entry cannot contain path traversal")
+        return v
+
+
+@dataclass
+class App:
+    """Represents a loaded app with manifest and directory."""
+
+    manifest: AppManifest
+    directory: Path
+    prefix: str  # May differ from manifest if overridden
+    is_package: bool  # True if loaded from package resources
+
+
+class AppLoader:
+    """Loads and validates apps from filesystem or package resources."""
+
+    @staticmethod
+    def load(path: str | Path | tuple[str, str], prefix: str | None = None) -> App:
+        """Load and validate app from filesystem path or package resource tuple."""
+        # Detect source type and resolve to directory
+        if isinstance(path, tuple):
+            # Package resource
+            dir_path, is_package = AppLoader._resolve_package_path(path)
+        else:
+            # Filesystem path
+            dir_path = Path(path).resolve()
+            is_package = False
+
+            if not dir_path.exists():
+                raise FileNotFoundError(f"App directory not found: {dir_path}")
+            if not dir_path.is_dir():
+                raise NotADirectoryError(f"App path is not a directory: {dir_path}")
+
+        # Load and validate manifest
+        manifest_path = dir_path / "manifest.json"
+        if not manifest_path.exists():
+            raise FileNotFoundError(f"manifest.json not found in: {dir_path}")
+
+        try:
+            with manifest_path.open() as f:
+                manifest_data = json.load(f)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON in manifest.json: {e}") from e
+
+        manifest = AppManifest(**manifest_data)
+
+        # Validate entry file exists
+        entry_path = dir_path / manifest.entry
+        if not entry_path.exists():
+            raise FileNotFoundError(f"Entry file '{manifest.entry}' not found in: {dir_path}")
+
+        # Use override or manifest prefix
+        final_prefix = prefix if prefix is not None else manifest.prefix
+
+        # Re-validate prefix if overridden
+        if prefix is not None:
+            validated = AppManifest(
+                name=manifest.name,
+                version=manifest.version,
+                prefix=final_prefix,
+            )
+            final_prefix = validated.prefix
+
+        return App(
+            manifest=manifest,
+            directory=dir_path,
+            prefix=final_prefix,
+            is_package=is_package,
+        )
+
+    @staticmethod
+    def discover(path: str | Path | tuple[str, str]) -> list[App]:
+        """Discover all apps with manifest.json in directory."""
+        # Resolve directory
+        if isinstance(path, tuple):
+            dir_path, _ = AppLoader._resolve_package_path(path)
+        else:
+            dir_path = Path(path).resolve()
+
+            if not dir_path.exists():
+                raise FileNotFoundError(f"Apps directory not found: {dir_path}")
+            if not dir_path.is_dir():
+                raise NotADirectoryError(f"Apps path is not a directory: {dir_path}")
+
+        # Scan for subdirectories with manifest.json
+        apps: list[App] = []
+        for subdir in dir_path.iterdir():
+            if subdir.is_dir() and (subdir / "manifest.json").exists():
+                try:
+                    # Determine if we're in a package context
+                    if isinstance(path, tuple):
+                        # Build tuple path for subdirectory
+                        package_name: str = path[0]
+                        base_path: str = path[1]
+                        subdir_name = subdir.name
+                        subpath = f"{base_path}/{subdir_name}" if base_path else subdir_name
+                        app = AppLoader.load((package_name, subpath))
+                    else:
+                        app = AppLoader.load(subdir)
+                    apps.append(app)
+                except Exception as e:
+                    # Log but don't fail discovery for invalid apps
+                    logger.warning(
+                        "app.discovery.failed",
+                        directory=str(subdir),
+                        error=str(e),
+                    )
+
+        return apps
+
+    @staticmethod
+    def _resolve_package_path(package_tuple: tuple[str, str]) -> tuple[Path, bool]:
+        """Resolve package resource tuple to filesystem path."""
+        package_name, subpath = package_tuple
+
+        # Validate subpath for security
+        if ".." in subpath:
+            raise ValueError(f"subpath cannot contain '..' (got: {subpath})")
+        if subpath.startswith("/"):
+            raise ValueError(f"subpath must be relative (got: {subpath})")
+
+        try:
+            spec = importlib.util.find_spec(package_name)
+        except (ModuleNotFoundError, ValueError) as e:
+            raise ValueError(f"Package '{package_name}' could not be found") from e
+
+        if spec is None or spec.origin is None:
+            raise ValueError(f"Package '{package_name}' could not be found")
+
+        # Resolve to package directory
+        package_dir = Path(spec.origin).parent
+        app_dir = package_dir / subpath
+
+        # Verify resolved path is still within package directory
+        try:
+            app_dir.resolve().relative_to(package_dir.resolve())
+        except ValueError as e:
+            raise ValueError(f"App path '{subpath}' escapes package directory") from e
+
+        if not app_dir.exists():
+            raise FileNotFoundError(f"App path '{subpath}' not found in package '{package_name}'")
+        if not app_dir.is_dir():
+            raise NotADirectoryError(f"App path '{subpath}' in package '{package_name}' is not a directory")
+
+        return app_dir, True
+
+
+class AppInfo(BaseModel):
+    """App metadata for API responses."""
+
+    name: str = Field(description="Human-readable app name")
+    version: str = Field(description="Semantic version")
+    prefix: str = Field(description="URL prefix for mounting")
+    description: str | None = Field(default=None, description="App description")
+    author: str | None = Field(default=None, description="Author name")
+    entry: str = Field(description="Entry point filename")
+    is_package: bool = Field(description="Whether app is loaded from package resources")
+
+
+class AppManager:
+    """Lightweight manager for app metadata queries."""
+
+    def __init__(self, apps: list[App]):
+        """Initialize with loaded apps."""
+        self._apps = apps
+
+    def list(self) -> list[App]:
+        """Return all installed apps."""
+        return self._apps
+
+    def get(self, prefix: str) -> App | None:
+        """Get app by mount prefix."""
+        return next((app for app in self._apps if app.prefix == prefix), None)

servicekit/api/apps/landing/index.html

@@ -0,0 +1,146 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Service Information</title>
+    <style>
+        body {
+            font-family: system-ui, -apple-system, sans-serif;
+            max-width: 800px;
+            margin: 2rem auto;
+            padding: 0 1rem;
+            background: #f5f5f5;
+        }
+        .container {
+            background: white;
+            border-radius: 8px;
+            box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+            padding: 2rem;
+        }
+        h1 {
+            margin: 0 0 0.5rem 0;
+            color: #333;
+        }
+        .nav-links {
+            display: flex;
+            gap: 1rem;
+            margin-bottom: 1.5rem;
+            padding-bottom: 1rem;
+            border-bottom: 1px solid #e5e5e5;
+        }
+        .nav-links a {
+            color: #2563eb;
+            text-decoration: none;
+            font-size: 0.875rem;
+        }
+        .nav-links a:hover {
+            text-decoration: underline;
+        }
+        .info-grid {
+            display: grid;
+            gap: 1rem;
+            margin-top: 1.5rem;
+        }
+        .info-item {
+            display: grid;
+            gap: 0.25rem;
+        }
+        .info-label {
+            font-size: 0.75rem;
+            text-transform: uppercase;
+            color: #666;
+            font-weight: 600;
+            letter-spacing: 0.05em;
+        }
+        .info-value {
+            color: #333;
+            font-size: 1rem;
+        }
+        pre {
+            background: #f5f5f5;
+            padding: 1rem;
+            border-radius: 4px;
+            overflow-x: auto;
+            margin: 0;
+            font-size: 0.875rem;
+        }
+        .loading {
+            text-align: center;
+            color: #666;
+            padding: 2rem;
+        }
+        .error {
+            color: #dc2626;
+            padding: 1rem;
+            background: #fee;
+            border-radius: 4px;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div id="content" class="loading">Loading service information...</div>
+    </div>
+    <script>
+        fetch('/api/v1/info')
+            .then(res => res.json())
+            .then(info => {
+                const items = [];
+
+                items.push(`<h1>${info.display_name}</h1>`);
+                items.push(`<div class="nav-links">
+                    <a href="/docs">📚 API Documentation</a>
+                    <a href="/redoc">📖 ReDoc</a>
+                </div>`);
+                items.push(`<div class="info-grid">`);
+
+                items.push(`<div class="info-item">
+                    <div class="info-label">Version</div>
+                    <div class="info-value">${info.version}</div>
+                </div>`);
+
+                if (info.summary) {
+                    items.push(`<div class="info-item">
+                        <div class="info-label">Summary</div>
+                        <div class="info-value">${info.summary}</div>
+                    </div>`);
+                }
+
+                if (info.description) {
+                    items.push(`<div class="info-item">
+                        <div class="info-label">Description</div>
+                        <div class="info-value">${info.description}</div>
+                    </div>`);
+                }
+
+                if (info.contact) {
+                    const contactJson = JSON.stringify(info.contact, null, 2);
+                    items.push(`<div class="info-item">
+                        <div class="info-label">Contact</div>
+                        <div class="info-value"><pre>${contactJson}</pre></div>
+                    </div>`);
+                }
+
+                if (info.license_info) {
+                    const licenseJson = JSON.stringify(info.license_info, null, 2);
+                    items.push(`<div class="info-item">
+                        <div class="info-label">License</div>
+                        <div class="info-value"><pre>${licenseJson}</pre></div>
+                    </div>`);
+                }
+
+                items.push(`</div>`);
+                const contentEl = document.getElementById('content');
+                contentEl.className = '';
+                contentEl.innerHTML = items.join('');
+            })
+            .catch(err => {
+                const errorMsg = 'Failed to load service information: ' + err.message;
+                const contentEl = document.getElementById('content');
+                contentEl.className = '';
+                contentEl.innerHTML = `<div class="error">${errorMsg}</div>`;
+            });
+    </script>
+</body>
+</html>

servicekit/api/apps/landing/manifest.json

@@ -0,0 +1,8 @@
+{
+  "name": "Chapkit Landing Page",
+  "version": "1.0.0",
+  "prefix": "/",
+  "description": "Default landing page showing service information",
+  "author": "Chapkit Team",
+  "entry": "index.html"
+}

servicekit/api/auth.py

@@ -0,0 +1,162 @@
+"""API key authentication middleware and utilities."""
+
+import os
+from pathlib import Path
+from typing import Any, Set
+
+from fastapi import Request, Response, status
+from fastapi.responses import JSONResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from servicekit.logging import get_logger
+from servicekit.schemas import ProblemDetail
+
+from .middleware import MiddlewareCallNext
+
+logger = get_logger(__name__)
+
+
+class APIKeyMiddleware(BaseHTTPMiddleware):
+    """Middleware for API key authentication via X-API-Key header."""
+
+    def __init__(
+        self,
+        app: Any,
+        *,
+        api_keys: Set[str],
+        header_name: str = "X-API-Key",
+        unauthenticated_paths: Set[str],
+    ) -> None:
+        """Initialize API key middleware.
+
+        Args:
+            app: ASGI application
+            api_keys: Set of valid API keys
+            header_name: HTTP header name for API key
+            unauthenticated_paths: Paths that don't require authentication
+        """
+        super().__init__(app)
+        self.api_keys = api_keys
+        self.header_name = header_name
+        self.unauthenticated_paths = unauthenticated_paths
+
+    async def dispatch(self, request: Request, call_next: MiddlewareCallNext) -> Response:
+        """Process request with API key authentication."""
+        # Allow unauthenticated access to specific paths
+        if request.url.path in self.unauthenticated_paths:
+            return await call_next(request)
+
+        # Extract API key from header
+        api_key = request.headers.get(self.header_name)
+
+        if not api_key:
+            logger.warning(
+                "auth.missing_key",
+                path=request.url.path,
+                method=request.method,
+            )
+            problem = ProblemDetail(
+                type="urn:servicekit:error:unauthorized",
+                title="Unauthorized",
+                status=status.HTTP_401_UNAUTHORIZED,
+                detail=f"Missing authentication header: {self.header_name}",
+                instance=str(request.url.path),
+            )
+            return JSONResponse(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                content=problem.model_dump(exclude_none=True),
+                media_type="application/problem+json",
+            )
+
+        # Validate API key
+        if api_key not in self.api_keys:
+            # Log only prefix for security
+            key_prefix = api_key[:7] if len(api_key) >= 7 else "***"
+            logger.warning(
+                "auth.invalid_key",
+                key_prefix=key_prefix,
+                path=request.url.path,
+                method=request.method,
+            )
+            problem = ProblemDetail(
+                type="urn:servicekit:error:unauthorized",
+                title="Unauthorized",
+                status=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid API key",
+                instance=str(request.url.path),
+            )
+            return JSONResponse(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                content=problem.model_dump(exclude_none=True),
+                media_type="application/problem+json",
+            )
+
+        # Attach key prefix to request state for logging
+        request.state.api_key_prefix = api_key[:7] if len(api_key) >= 7 else "***"
+
+        logger.info(
+            "auth.success",
+            key_prefix=request.state.api_key_prefix,
+            path=request.url.path,
+        )
+
+        return await call_next(request)
+
+
+def load_api_keys_from_env(env_var: str = "SERVICEKIT_API_KEYS") -> Set[str]:
+    """Load API keys from environment variable (comma-separated).
+
+    Args:
+        env_var: Environment variable name
+
+    Returns:
+        Set of API keys
+    """
+    env_value = os.getenv(env_var, "")
+    if not env_value:
+        return set()
+    return {key.strip() for key in env_value.split(",") if key.strip()}
+
+
+def load_api_keys_from_file(file_path: str | Path) -> Set[str]:
+    """Load API keys from file (one key per line).
+
+    Args:
+        file_path: Path to file containing API keys
+
+    Returns:
+        Set of API keys
+
+    Raises:
+        FileNotFoundError: If file doesn't exist
+    """
+    path = Path(file_path)
+    if not path.exists():
+        raise FileNotFoundError(f"API key file not found: {file_path}")
+
+    keys = set()
+    with path.open("r") as f:
+        for line in f:
+            line = line.strip()
+            if line and not line.startswith("#"):  # Skip empty lines and comments
+                keys.add(line)
+
+    return keys
+
+
+def validate_api_key_format(key: str) -> bool:
+    """Validate API key format.
+
+    Args:
+        key: API key to validate
+
+    Returns:
+        True if key format is valid
+    """
+    # Basic validation: minimum length
+    if len(key) < 16:
+        return False
+    # Optional: Check for prefix pattern like sk_env_random
+    # if not key.startswith("sk_"):
+    #     return False
+    return True