cpkit 0.1.0__py3-none-any.whl

cpkit/bundle.py

@@ -0,0 +1,252 @@
+"""Standard cpkit capability bundle for FastAPI applications."""
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import APIRouter, Security
+from pydantic import BaseModel
+
+from .admin import create_cpkit_admin_router
+from .audit import (
+    AuditEventsService,
+    build_audit_log_record,
+    configure_audit_logging,
+    create_events_router,
+    log_event,
+)
+from .auth import ApiKeysService, AuthBundle, create_auth_bundle
+from .db import get_pool
+from .dependencies import configure_cpkit_dependencies
+from .errors import ServiceError, raise_http_from_service_error
+from .jobs import JobsService, QueueMessage, create_jobs_router, create_queue_worker
+from .jobs.worker import QueueHandler
+from .playbooks import PlaybooksService
+from .repository import get_repo
+from .settings import SettingsService
+
+AuditHook = Callable[[Any, str, str, dict[str, Any] | None], None]
+AuditRecordFactory = Callable[..., Any]
+PayloadParser = Callable[[Any, dict[str, Any]], Any]
+QueueMessageParser = Callable[[QueueMessage], Any]
+QueueHandlerResolver = Callable[[QueueMessage], QueueHandler | None]
+CommandModelMap = Mapping[Any, type[BaseModel]]
+
+
+@dataclass(frozen=True)
+class CpkitBundle:
+    """Standard cpkit routers, hooks, and auth dependencies."""
+
+    auth: AuthBundle
+    routers: tuple[APIRouter, ...]
+    startup_hooks: tuple[Callable[[], Any], ...]
+    background_tasks: tuple[Callable[[], Any], ...]
+
+    @property
+    def require_authenticated(self):
+        return self.auth.require_authenticated
+
+    @property
+    def require_user(self):
+        return self.auth.require_user
+
+    @property
+    def require_readonly(self):
+        return self.auth.require_readonly
+
+    @property
+    def require_admin(self):
+        return self.auth.require_admin
+
+    @property
+    def get_access_scope(self):
+        return self.auth.get_access_scope
+
+    @property
+    def get_audit_actor(self):
+        return self.auth.get_audit_actor
+
+
+def create_cpkit_bundle(
+    *,
+    command_models: CommandModelMap | None = None,
+    command_handlers: Mapping[Any, QueueHandler] | None = None,
+    parse_job_payload: PayloadParser | None = None,
+    reschedule_type_map: Mapping[Any, Any] | None = None,
+    resolve_queue_handler: QueueHandlerResolver | None = None,
+    parse_queue_message: QueueMessageParser | None = None,
+    audit_record_factory: AuditRecordFactory = build_audit_log_record,
+    audit_event_hook: AuditHook | None = None,
+) -> CpkitBundle:
+    """Create the standard cpkit capability bundle for an application."""
+    configure_audit_logging(audit_record_factory)
+    effective_audit_event_hook = audit_event_hook or log_event
+    normalized_command_models = _normalize_mapping(command_models)
+    effective_parse_job_payload = parse_job_payload or _command_model_parser(
+        normalized_command_models
+    )
+    effective_parse_queue_message = parse_queue_message or _queue_message_parser(
+        effective_parse_job_payload
+    )
+    normalized_command_handlers = _normalize_mapping(command_handlers)
+    effective_reschedule_type_map = {
+        _type_value(source): _type_value(target)
+        for source, target in (reschedule_type_map or {}).items()
+    }
+    auth = create_auth_bundle(
+        get_repo=get_repo,
+        audit_record_factory=audit_record_factory,
+    )
+
+    def validate_auth_config() -> None:
+        auth.oidc.validate_config(get_repo())
+
+    def get_api_keys_service():
+        return ApiKeysService(
+            get_repo(),
+            created_hook=effective_audit_event_hook,
+            deleted_hook=effective_audit_event_hook,
+        )
+
+    def get_events_service():
+        return AuditEventsService(get_repo())
+
+    def get_jobs_service():
+        return JobsService(
+            get_repo(),
+            parse_payload=effective_parse_job_payload,
+            reschedule_type_resolver=lambda job_type: effective_reschedule_type_map.get(
+                _type_value(job_type),
+                job_type,
+            ),
+            rescheduled_hook=effective_audit_event_hook,
+        )
+
+    def get_playbooks_service():
+        return PlaybooksService(
+            get_repo(),
+            version_created_hook=effective_audit_event_hook,
+            version_deleted_hook=effective_audit_event_hook,
+            default_set_hook=effective_audit_event_hook,
+        )
+
+    def get_settings_service():
+        return SettingsService(
+            get_repo(),
+            setting_updated_hook=_setting_updated_hook(effective_audit_event_hook),
+            setting_reset_hook=_setting_reset_hook(effective_audit_event_hook),
+        )
+
+    admin_router = create_cpkit_admin_router(
+        get_api_keys_service=get_api_keys_service,
+        get_settings_service=get_settings_service,
+        get_playbooks_service=get_playbooks_service,
+        get_audit_actor=auth.get_audit_actor,
+        handle_service_error=raise_http_from_service_error,
+        service_error_type=ServiceError,
+        dependencies=(Security(auth.require_admin),),
+    )
+    events_router = create_events_router(
+        get_service=get_events_service,
+        get_access_scope=auth.get_access_scope,
+        require_readonly=auth.require_readonly,
+        handle_service_error=raise_http_from_service_error,
+        service_error_type=ServiceError,
+    )
+    jobs_router = create_jobs_router(
+        get_service=get_jobs_service,
+        get_access_scope=auth.get_access_scope,
+        get_audit_actor=auth.get_audit_actor,
+        require_readonly=auth.require_readonly,
+        require_user=auth.require_user,
+        handle_service_error=raise_http_from_service_error,
+        service_error_type=ServiceError,
+    )
+    queue_worker = create_queue_worker(
+        get_pool=get_pool,
+        get_repo=get_repo,
+        handlers=normalized_command_handlers,
+        resolve_handler=resolve_queue_handler,
+        parse_message=effective_parse_queue_message,
+    )
+
+    bundle = CpkitBundle(
+        auth=auth,
+        routers=(
+            auth.router,
+            admin_router,
+            events_router,
+            jobs_router,
+        ),
+        startup_hooks=(validate_auth_config,),
+        background_tasks=(queue_worker,),
+    )
+    configure_cpkit_dependencies(bundle)
+    return bundle
+
+
+def _setting_updated_hook(
+    audit_event_hook: AuditHook | None,
+) -> Callable[[Any, str, str, str], None] | None:
+    if audit_event_hook is None:
+        return None
+
+    def log_setting_updated(
+        repo: Any,
+        setting_id: str,
+        value: str,
+        updated_by: str,
+    ) -> None:
+        audit_event_hook(
+            repo,
+            updated_by,
+            "SETTING_UPDATED",
+            {"ID": setting_id, "value": value},
+        )
+
+    return log_setting_updated
+
+
+def _setting_reset_hook(
+    audit_event_hook: AuditHook | None,
+) -> Callable[[Any, str, str], None] | None:
+    if audit_event_hook is None:
+        return None
+
+    def log_setting_reset(repo: Any, setting_id: str, updated_by: str) -> None:
+        audit_event_hook(
+            repo,
+            updated_by,
+            "SETTING_RESET",
+            {"ID": setting_id},
+        )
+
+    return log_setting_reset
+
+
+def _type_value(value: Any) -> Any:
+    return getattr(value, "value", value)
+
+
+def _normalize_mapping(mapping: Mapping[Any, Any] | None) -> dict[Any, Any] | None:
+    if mapping is None:
+        return None
+    return {_type_value(key): value for key, value in mapping.items()}
+
+
+def _command_model_parser(command_models: Mapping[Any, type[BaseModel]] | None):
+    if command_models is None:
+        raise ValueError("command_models or parse_job_payload is required.")
+
+    def parse(command_type: Any, payload: dict[str, Any] | None) -> BaseModel:
+        model_type = command_models[_type_value(command_type)]
+        return model_type.model_validate(payload or {})
+
+    return parse
+
+
+def _queue_message_parser(parse_payload: PayloadParser) -> QueueMessageParser:
+    def parse(message: QueueMessage) -> Any:
+        return parse_payload(message.msg_type, message.msg_data)
+
+    return parse

cpkit/cli/README.md

@@ -0,0 +1,21 @@
+# CLI
+
+The CLI package gives cpkit-backed applications a small reusable command line
+interface. It is meant for app projects, not as a standalone cpkit server.
+
+## Files
+
+- `base.py`: `ApplicationCLI`, the main CLI implementation.
+- `schema.py`: SQL schema initialization and preflight helpers.
+- `server.py`: Uvicorn serving helper.
+- `__main__.py`: Allows running the package as a module when exposed by an app.
+
+## Runtime Flow
+
+`ApplicationCLI.from_project()` reads `pyproject.toml` and environment variables
+to discover the app import path, DDL files, schema checks, and DB URL variable.
+The app can then expose commands like:
+
+- `init`: initialize cpkit and app schemas from DDL files.
+- `check`: verify DB connectivity and required tables.
+- `serve`: run the configured FastAPI app with Uvicorn.

cpkit/cli/__init__.py

@@ -0,0 +1,14 @@
+"""Reusable command-line helpers for cpkit applications."""
+
+from .base import ApplicationCLI, main
+from .schema import apply_sql_file, check_database, check_table
+from .server import serve_uvicorn
+
+__all__ = [
+    "ApplicationCLI",
+    "apply_sql_file",
+    "check_database",
+    "check_table",
+    "main",
+    "serve_uvicorn",
+]

cpkit/cli/__main__.py

@@ -0,0 +1,5 @@
+"""Module entry point for cpkit CLI helpers."""
+
+from .base import main
+
+raise SystemExit(main())

cpkit/cli/base.py

@@ -0,0 +1,200 @@
+"""Base application CLI for cpkit apps."""
+
+import argparse
+import os
+import sys
+import tomllib
+from collections.abc import Sequence
+from pathlib import Path
+
+from cpkit.resources import cpkit_ddl_path
+
+from .schema import apply_sql_file, check_database, check_table
+from .server import serve_uvicorn
+
+
+class ApplicationCLI:
+    """Standard command-line interface for a cpkit-backed application."""
+
+    def __init__(
+        self,
+        *,
+        app_name: str,
+        app_import: str,
+        app_ddl_paths: Sequence[str | Path] = (),
+        app_schema_checks: Sequence[str] = (),
+        db_url_env: str = "CPKIT_DB_URL",
+        cpkit_ddl_path: str | Path | None = None,
+        project_root: str | Path | None = None,
+    ) -> None:
+        self.app_name = app_name
+        self.app_import = app_import
+        self.app_ddl_paths = tuple(Path(path) for path in app_ddl_paths)
+        self.app_schema_checks = tuple(app_schema_checks)
+        self.db_url_env = db_url_env
+        self.cpkit_ddl_path = Path(cpkit_ddl_path) if cpkit_ddl_path else None
+        self.project_root = Path(project_root).resolve() if project_root else None
+
+    @classmethod
+    def from_project(
+        cls,
+        *,
+        project_root: str | Path | None = None,
+        app_name: str | None = None,
+    ) -> "ApplicationCLI":
+        """Create an app CLI from pyproject.toml metadata."""
+        root = Path(project_root or os.getcwd()).resolve()
+        pyproject = _load_pyproject(root)
+        project = pyproject.get("project", {})
+        cpkit_config = pyproject.get("tool", {}).get("cpkit", {})
+        effective_app_name = (
+            app_name
+            or os.getenv("CPKIT_APP_NAME")
+            or cpkit_config.get("app_name")
+            or project.get("name")
+            or Path(sys.argv[0]).name
+        )
+        app_import = (
+            os.getenv("CPKIT_APP_IMPORT")
+            or cpkit_config.get("app_import")
+            or f"{effective_app_name}.main:app"
+        )
+        ddl_paths = _configured_paths(
+            root,
+            os.getenv("CPKIT_APP_DDL"),
+            cpkit_config.get("ddl"),
+        )
+        schema_checks = _configured_values(
+            os.getenv("CPKIT_SCHEMA_CHECKS"),
+            cpkit_config.get("schema_checks"),
+        )
+        db_url_env = (
+            os.getenv("CPKIT_DB_URL_ENV")
+            or cpkit_config.get("db_url_env")
+            or "CPKIT_DB_URL"
+        )
+        cpkit_ddl = cpkit_config.get("cpkit_ddl")
+        return cls(
+            app_name=effective_app_name,
+            app_import=app_import,
+            app_ddl_paths=ddl_paths,
+            app_schema_checks=schema_checks,
+            db_url_env=db_url_env,
+            cpkit_ddl_path=(root / cpkit_ddl) if cpkit_ddl else None,
+            project_root=root,
+        )
+
+    def main(self, argv: Sequence[str] | None = None) -> int:
+        """Run the application CLI."""
+        args = self._parser().parse_args(argv)
+        return int(args.handler(args) or 0)
+
+    def init(self, _args: argparse.Namespace) -> int:
+        """Initialize cpkit and application schemas from DDL files."""
+        db_url = self._db_url()
+        cpkit_ddl = self._cpkit_ddl_path()
+        if cpkit_ddl is not None:
+            print(f"Applying cpkit schema: {cpkit_ddl}")
+            apply_sql_file(db_url, cpkit_ddl)
+
+        for path in self._app_ddl_paths():
+            print(f"Applying {self.app_name} schema: {path}")
+            apply_sql_file(db_url, path)
+
+        self._check_schemas(db_url)
+        print("Initialization complete.")
+        return 0
+
+    def serve(self, args: argparse.Namespace) -> int:
+        """Serve the FastAPI app."""
+        serve_uvicorn(
+            self.app_import,
+            host=args.host,
+            port=args.port,
+            reload=args.reload,
+            log_level=args.log_level,
+        )
+        return 0
+
+    def _parser(self) -> argparse.ArgumentParser:
+        parser = argparse.ArgumentParser(prog=self.app_name)
+        subparsers = parser.add_subparsers(dest="command", required=True)
+
+        init = subparsers.add_parser("init", help="Initialize database schemas.")
+        init.set_defaults(handler=self.init)
+
+        server = subparsers.add_parser("serve", help="Run the FastAPI application.")
+        server.add_argument("--host", default="0.0.0.0")
+        server.add_argument("--port", type=int, default=8000)
+        server.add_argument("--reload", action="store_true")
+        server.add_argument("--log-level", default="info")
+        server.set_defaults(handler=self.serve)
+
+        return parser
+
+    def _db_url(self) -> str:
+        db_url = os.getenv(self.db_url_env, "").strip()
+        if not db_url:
+            raise RuntimeError(f"{self.db_url_env} is not set.")
+        return db_url
+
+    def _check_schemas(self, db_url: str) -> None:
+        print("Checking database connectivity.")
+        check_database(db_url)
+        print("Checking cpkit schema.")
+        check_table(db_url, "cpkit.settings")
+        for table_name in self.app_schema_checks:
+            print(f"Checking application table: {table_name}")
+            check_table(db_url, table_name)
+
+    def _cpkit_ddl_path(self) -> Path | None:
+        if self.cpkit_ddl_path is not None:
+            return self.cpkit_ddl_path
+
+        candidate = cpkit_ddl_path()
+        if candidate.exists():
+            return candidate
+        return None
+
+    def _app_ddl_paths(self) -> tuple[Path, ...]:
+        if self.app_ddl_paths:
+            return self.app_ddl_paths
+        root = self.project_root or Path(os.getcwd()).resolve()
+        return tuple(path for path in _default_ddl_paths(root) if path.exists())
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the current project's cpkit application CLI."""
+    return ApplicationCLI.from_project().main(argv)
+
+
+def _load_pyproject(root: Path) -> dict:
+    path = root / "pyproject.toml"
+    if not path.exists():
+        return {}
+    return tomllib.loads(path.read_text())
+
+
+def _configured_paths(
+    root: Path,
+    env_value: str | None,
+    config_value,
+) -> tuple[Path, ...]:
+    values = _configured_values(env_value, config_value)
+    return tuple(root / value for value in values)
+
+
+def _configured_values(env_value: str | None, config_value) -> tuple[str, ...]:
+    if env_value:
+        return tuple(item.strip() for item in env_value.split(",") if item.strip())
+    if config_value:
+        return tuple(str(item) for item in config_value)
+    return ()
+
+
+def _default_ddl_paths(root: Path) -> tuple[Path, ...]:
+    return (
+        root / "resources" / "ddl.sql",
+        root / "resources" / "post_schema.sql",
+        root / "resources" / "database" / "ddl.sql",
+    )

cpkit/cli/schema.py

@@ -0,0 +1,30 @@
+"""Database schema initialization and preflight helpers for cpkit applications."""
+
+from pathlib import Path
+
+import psycopg
+
+
+def apply_sql_file(db_url: str, path: str | Path) -> None:
+    """Execute a SQL file against the configured database."""
+    sql_path = Path(path)
+    sql = sql_path.read_text()
+    with psycopg.connect(db_url, autocommit=True) as conn:
+        with conn.cursor() as cur:
+            cur.execute(sql)
+
+
+def check_database(db_url: str) -> None:
+    """Verify the database can be reached."""
+    with psycopg.connect(db_url, autocommit=True) as conn:
+        with conn.cursor() as cur:
+            cur.execute("SELECT 1")
+            cur.fetchone()
+
+
+def check_table(db_url: str, table_name: str) -> None:
+    """Verify a required table can be queried."""
+    with psycopg.connect(db_url, autocommit=True) as conn:
+        with conn.cursor() as cur:
+            cur.execute(f"SELECT 1 FROM {table_name} LIMIT 1")
+            cur.fetchone()

cpkit/cli/server.py

@@ -0,0 +1,22 @@
+"""ASGI server helpers for cpkit application CLIs."""
+
+import uvicorn
+
+
+def serve_uvicorn(
+    app_import: str,
+    *,
+    host: str,
+    port: int,
+    reload: bool,
+    log_level: str,
+) -> None:
+    """Run an ASGI app through Uvicorn."""
+    uvicorn.run(
+        app_import,
+        host=host,
+        port=port,
+        reload=reload,
+        log_level=log_level,
+        log_config=None,
+    )

cpkit/config/README.md

@@ -0,0 +1,13 @@
+# Config
+
+The config package contains small helpers for reading environment-backed
+configuration.
+
+At the moment this package is intentionally tiny:
+
+- `env.py`: Environment lookup helpers.
+
+Keep broad framework wiring in `bundle.py` or capability-specific config modules
+such as `auth/config.py`. Use this package for generic configuration helpers
+that do not belong to a single capability.
+

cpkit/config/__init__.py

@@ -0,0 +1,9 @@
+"""Configuration helpers."""
+
+from .env import as_bool, safe_csv_set, safe_json_string_dict
+
+__all__ = [
+    "as_bool",
+    "safe_csv_set",
+    "safe_json_string_dict",
+]

cpkit/config/env.py

@@ -0,0 +1,31 @@
+"""Helpers for parsing environment-style configuration values."""
+
+import json
+
+
+def as_bool(value: str | None, default: bool = False) -> bool:
+    """Parse common truthy environment-style values into a boolean."""
+    if value is None:
+        return default
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def safe_csv_set(raw_value: str | None) -> set[str]:
+    """Split a comma-delimited string into a trimmed set of values."""
+    if not raw_value:
+        return set()
+    return {part.strip() for part in raw_value.split(",") if part and part.strip()}
+
+
+def safe_json_string_dict(
+    value: str | None, *, default: dict[str, str] | None = None
+) -> dict[str, str]:
+    """Parse a JSON object and coerce its keys and values to strings."""
+    if not value:
+        return default or {}
+
+    parsed = json.loads(value)
+    if not isinstance(parsed, dict):
+        raise ValueError("Expected a JSON object.")
+
+    return {str(k): str(v) for k, v in parsed.items()}

cpkit/db/README.md

@@ -0,0 +1,24 @@
+# DB
+
+The DB package owns the shared database connection pool and low-level query
+helpers used by repository mixins.
+
+cpkit currently targets Cockroach/Postgres-style SQL. The helper functions hide
+some repetitive details: pool access, cursor row mapping, JSON/list dumpers,
+statement normalization, and translation from database exceptions into
+repository exceptions.
+
+## Files
+
+- `postgres.py`: Pool lifecycle, query helpers, custom dumpers, and database
+  error translation.
+- `__init__.py`: Public exports.
+
+## Runtime Flow
+
+1. `create_cpkit_app()` calls `initialize_postgres(db_url)` during app startup.
+2. Repository mixins call helpers such as `fetch_one()`, `fetch_all()`,
+   `fetch_scalar()`, and `execute_stmt()`.
+3. Database exceptions are translated into `cpkit.errors.repository` types.
+4. Service layers translate repository errors into user-facing service errors.
+

cpkit/db/__init__.py

@@ -0,0 +1,23 @@
+"""Database infrastructure helpers."""
+
+from .postgres import (
+    close_db,
+    execute_stmt,
+    fetch_all,
+    fetch_one,
+    fetch_scalar,
+    get_pool,
+    initialize_postgres,
+    translate_database_error,
+)
+
+__all__ = [
+    "close_db",
+    "execute_stmt",
+    "fetch_all",
+    "fetch_one",
+    "fetch_scalar",
+    "get_pool",
+    "initialize_postgres",
+    "translate_database_error",
+]