servicekit 0.6.0__py3-none-any.whl

servicekit/__init__.py

@@ -0,0 +1,88 @@
+"""Core framework components - generic interfaces and base classes."""
+
+# ruff: noqa: F401
+
+# Read version from package metadata - must be before internal imports
+try:
+    from importlib.metadata import version as _get_version
+
+    __version__ = _get_version("servicekit")
+except Exception:
+    __version__ = "unknown"
+
+# 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 InMemoryScheduler, Scheduler
+from .schemas import (
+    BulkOperationError,
+    BulkOperationResult,
+    EntityIn,
+    EntityOut,
+    JobRecord,
+    JobStatus,
+    PaginatedResponse,
+    ProblemDetail,
+)
+from .types import JsonSafe, ULIDType
+
+__all__ = [
+    # Version
+    "__version__",
+    # 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
+    "Scheduler",
+    "InMemoryScheduler",
+    # 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"
+}