cpkit 0.1.0__py3-none-any.whl

cpkit/README.md

@@ -0,0 +1,82 @@
+# cpkit Code Map
+
+cpkit is an application framework for FastAPI apps that want the same
+operational backbone: authentication, audit events, settings, jobs, playbooks,
+database helpers, and a shared webapp shell.
+
+The package is organized by capability. The directories look flat at first
+glance, but most capability packages use the same internal pattern:
+
+- `types.py`: Pydantic models, enums, and response shapes.
+- `repository.py` or `repositories.py`: database mixins for framework-owned
+  tables.
+- `service.py`: business rules and repository error translation.
+- `router.py`: FastAPI routes and dependency wiring.
+- `__init__.py`: public exports for that capability.
+
+The main app flow is:
+
+1. An app calls `create_cpkit_bundle()` from `bundle.py` to assemble cpkit
+   capabilities.
+2. The app calls `create_cpkit_app()` from `app.py` to create the FastAPI app,
+   configure the repository, run startup hooks, mount routers, and launch
+   background tasks.
+3. `repository.py` provides `CPKitRepo`, a mix of all framework repository
+   capabilities. Apps can subclass it and add their own repository methods.
+4. Capability services use `get_repo()` to work with the configured app repo.
+5. The shared webapp in `webapp/` talks to the framework API routes and can be
+   extended by app-owned web assets.
+
+## Architecture Review
+
+The current flat capability layout is reasonable for cpkit's size. It keeps
+imports readable and makes each framework feature easy to find. A deeper layout
+like `cpkit/core`, `cpkit/capabilities`, and `cpkit/integrations` might become
+useful later, but moving there now would mostly create import churn.
+
+The part that made the project feel like a black box was not the package shape;
+it was the lack of an orientation layer. These README files are intended to be
+that layer. They explain the module boundaries without changing runtime code.
+
+Good rules of thumb:
+
+- Start in `bundle.py` when asking "how does cpkit assemble itself?"
+- Start in `app.py` when asking "how does cpkit become a FastAPI app?"
+- Start in `repository.py` when asking "how do framework services reach the DB?"
+- Start in a capability package when asking about one feature area.
+- Start in `webapp/README.md` for frontend extension behavior.
+
+## Top-Level Modules
+
+- `app.py`: FastAPI app bootstrap, lifespan management, router mounting, static
+  webapp mounting, DB initialization, and background task startup.
+- `bundle.py`: The standard cpkit capability bundle. It wires auth, jobs,
+  events, admin routes, settings, playbooks, API keys, audit hooks, and the
+  queue worker.
+- `repository.py`: The framework repository composition point. `CPKitRepo`
+  combines all cpkit repository mixins; `configure_repository()` tells cpkit how
+  to create app repo instances.
+- `resources/`: Packaged framework resources such as `ddl.sql`. Use
+  `cpkit_ddl_path()` to locate them from installed wheels.
+- `admin.py`: Composes built-in admin routers under the admin API prefix.
+- `dependencies.py`: Global dependency accessors used by routers after a bundle
+  has been configured.
+- `time.py`: Shared timestamp formatting constants.
+
+## Capability Packages
+
+- `audit/`: audit event records, event reads, audit hooks, and the context used
+  to attach request/job identifiers.
+- `auth/`: OIDC login/logout, API key auth, role/group mapping, encrypted
+  secrets, and auth dependencies.
+- `cli/`: reusable app CLI for schema initialization, schema checks, and serving.
+- `config/`: small environment/config helpers.
+- `db/`: database pool, query helpers, Cockroach/Postgres compatibility, and
+  DB error translation.
+- `errors/`: repository/service/http exception layers.
+- `jobs/`: framework job table, queue table, queue worker, job APIs, and job
+  rescheduling.
+- `logging/`: request id context, middleware, and logging setup.
+- `playbooks/`: versioned playbook storage and Ansible runner integration.
+- `settings/`: framework settings table and admin settings API.
+- `webapp/`: static HTML/CSS/JS shell and extension contract for app UIs.

cpkit/__init__.py

@@ -0,0 +1,42 @@
+"""Reusable control-plane framework primitives."""
+
+from .admin import create_cpkit_admin_router
+from .app import create_cpkit_app
+from .bundle import CpkitBundle, create_cpkit_bundle
+from .cli import ApplicationCLI
+from .dependencies import (
+    configure_cpkit_dependencies,
+    get_access_scope,
+    get_audit_actor,
+    require_admin,
+    require_authenticated,
+    require_readonly,
+    require_user,
+)
+from .repository import CPKitRepo, configure_repository, get_repo
+from .resources import cpkit_ddl_path, cpkit_resources_directory
+from .time import STRFTIME, TS_FORMAT
+from .webapp import template_webapp_directory
+
+__all__ = [
+    "CPKitRepo",
+    "ApplicationCLI",
+    "CpkitBundle",
+    "STRFTIME",
+    "TS_FORMAT",
+    "configure_cpkit_dependencies",
+    "configure_repository",
+    "create_cpkit_bundle",
+    "create_cpkit_admin_router",
+    "create_cpkit_app",
+    "cpkit_ddl_path",
+    "cpkit_resources_directory",
+    "get_access_scope",
+    "get_audit_actor",
+    "get_repo",
+    "require_admin",
+    "require_authenticated",
+    "require_readonly",
+    "require_user",
+    "template_webapp_directory",
+]

cpkit/admin.py

@@ -0,0 +1,53 @@
+"""Admin router assembly for framework-owned capabilities."""
+
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from fastapi import APIRouter
+
+from .auth import create_api_keys_router
+from .playbooks import create_playbooks_router
+from .settings import create_settings_router
+
+
+def create_cpkit_admin_router(
+    *,
+    get_api_keys_service: Callable[..., Any],
+    get_settings_service: Callable[..., Any],
+    get_playbooks_service: Callable[..., Any],
+    get_audit_actor: Callable[..., Any],
+    handle_service_error: Callable[[Exception], None],
+    service_error_type: type[Exception] = Exception,
+    prefix: str = "/admin",
+    dependencies: Sequence[Any] | None = None,
+) -> APIRouter:
+    """Create the standard admin routes provided by cpkit."""
+    router = APIRouter(
+        prefix=prefix,
+        dependencies=list(dependencies or ()),
+    )
+    router.include_router(
+        create_settings_router(
+            get_service=get_settings_service,
+            get_audit_actor=get_audit_actor,
+            handle_service_error=handle_service_error,
+            service_error_type=service_error_type,
+        )
+    )
+    router.include_router(
+        create_playbooks_router(
+            get_service=get_playbooks_service,
+            get_audit_actor=get_audit_actor,
+            handle_service_error=handle_service_error,
+            service_error_type=service_error_type,
+        )
+    )
+    router.include_router(
+        create_api_keys_router(
+            get_service=get_api_keys_service,
+            get_audit_actor=get_audit_actor,
+            handle_service_error=handle_service_error,
+            service_error_type=service_error_type,
+        )
+    )
+    return router

cpkit/app.py

@@ -0,0 +1,130 @@
+"""FastAPI application bootstrap helpers."""
+
+import asyncio
+import inspect
+from collections.abc import Awaitable, Callable, Iterable
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+
+from fastapi import APIRouter, FastAPI, Request
+from fastapi.staticfiles import StaticFiles
+
+from cpkit.bundle import CpkitBundle
+from cpkit.db import close_db, initialize_postgres
+from cpkit.logging import configure_logging, request_logging_middleware
+from cpkit.repository import configure_repository
+from cpkit.repository import get_repo as get_configured_repo
+
+StartupHook = Callable[[], Any]
+BackgroundTaskFactory = Callable[[], Awaitable[Any]]
+RepoClass = Callable[[Any], Any]
+
+
+def create_cpkit_app(
+    *,
+    title: str,
+    version: str,
+    repo_class: RepoClass | None = None,
+    get_repo: Callable[[], Any] | None = None,
+    db_url: str | None,
+    capabilities: Iterable[CpkitBundle] | None = None,
+    bundles: Iterable[CpkitBundle] = (),
+    routers: Iterable[APIRouter] = (),
+    startup_hooks: Iterable[StartupHook] = (),
+    background_tasks: Iterable[BackgroundTaskFactory] = (),
+    static_directory: str | Path | None = None,
+    app_static_directory: str | Path | None = None,
+    api_prefix: str = "/api",
+    default_journald_identifier: str = "cp",
+) -> FastAPI:
+    """Create a cpkit-managed FastAPI app with an application API subapp."""
+    capability_tuple = tuple(capabilities if capabilities is not None else bundles)
+
+    @asynccontextmanager
+    async def lifespan(_app: FastAPI):
+        running_tasks: list[asyncio.Task[Any]] = []
+
+        initialize_postgres(db_url)
+        if repo_class is not None:
+            configure_repository(repo_class=repo_class)
+        elif get_repo is not None:
+            configure_repository(repo_factory=get_repo)
+        else:
+            raise ValueError("repo_class or get_repo is required.")
+
+        repo = get_configured_repo()
+        configure_logging(
+            repo,
+            force=True,
+            default_journald_identifier=default_journald_identifier,
+        )
+        effective_startup_hooks = (
+            *(
+                hook
+                for capability in capability_tuple
+                for hook in capability.startup_hooks
+            ),
+            *startup_hooks,
+        )
+        for hook in effective_startup_hooks:
+            result = hook()
+            if inspect.isawaitable(result):
+                await result
+
+        effective_background_tasks = (
+            *(
+                task
+                for capability in capability_tuple
+                for task in capability.background_tasks
+            ),
+            *background_tasks,
+        )
+        running_tasks = [
+            asyncio.create_task(task_factory())
+            for task_factory in effective_background_tasks
+        ]
+
+        yield
+
+        for task in running_tasks:
+            task.cancel()
+        for task in running_tasks:
+            try:
+                await task
+            except asyncio.CancelledError:
+                pass
+
+        close_db()
+
+    app = FastAPI(lifespan=lifespan)
+    api = FastAPI(title=title, version=version)
+
+    effective_routers = (
+        *(router for capability in capability_tuple for router in capability.routers),
+        *routers,
+    )
+    for router in effective_routers:
+        api.include_router(router)
+
+    app.mount(api_prefix, api)
+
+    if app_static_directory is not None:
+        app.mount(
+            "/app",
+            StaticFiles(directory=Path(app_static_directory), html=True),
+            name="app_webapp",
+        )
+
+    if static_directory is not None:
+        app.mount(
+            "/",
+            StaticFiles(directory=Path(static_directory), html=True),
+            name="webapp",
+        )
+
+    @app.middleware("http")
+    async def dispatch(request: Request, call_next):
+        return await request_logging_middleware(request, call_next)
+
+    return app

cpkit/audit/README.md

@@ -0,0 +1,33 @@
+# Audit
+
+The audit package records and exposes framework/application events such as
+logins, settings changes, API key changes, reschedules, and app-defined actions.
+
+The important idea is that audit records are app-owned objects built through a
+record factory, then written through the configured repository. cpkit provides a
+default `AuditLogRecord`, but apps can provide their own factory if their audit
+schema differs.
+
+## Files
+
+- `types.py`: Default audit models, including `AuditLogRecord`.
+- `recorder.py`: The common audit recorder and hooks. This is where request ids
+  and job ids are resolved before calling the record factory.
+- `repository.py`: Repository mixin for reading and writing `cpkit.event_log`.
+- `events_service.py`: Service used by the Events page/API to list events.
+- `router.py`: Read-only API routes for audit events.
+- `service.py`: Generic audit emission service for app code that wants a small
+  service wrapper.
+
+## Runtime Flow
+
+1. A service calls `log_event()` or a hook created by `create_audit_event_hook()`.
+2. `AuditRecorder` resolves contextual values, currently `request_id` and
+   `job_id`, through provider functions.
+3. The configured record factory receives `actor_id`, `event_type`, `metadata`,
+   `request_id`, and `job_id`.
+4. The resulting record is written through the repository's `log_event()` method.
+
+Best-effort audit logging should not break the user workflow. If an audit record
+cannot be built or written, cpkit logs the exception and returns `False`.
+

cpkit/audit/__init__.py

@@ -0,0 +1,44 @@
+"""Generic audit record types and service helpers."""
+
+from .events_service import AuditEventsService
+from .recorder import (
+    AuditRecorder,
+    AuditRecordWriter,
+    build_audit_log_record,
+    configure_audit_logging,
+    create_audit_event_hook,
+    job_id_ctx,
+    log_event,
+    write_audit_record,
+    write_audit_record_best_effort,
+)
+from .repository import EVENT_LOG_TABLE, AuditEventsRepositoryMixin
+from .router import create_events_router
+from .service import AuditService
+from .types import (
+    AuditEventCountResponse,
+    AuditLogRecord,
+    AuditOutcome,
+    AuditRecordCreate,
+)
+
+__all__ = [
+    "AuditEventCountResponse",
+    "AuditEventsRepositoryMixin",
+    "AuditEventsService",
+    "AuditLogRecord",
+    "AuditOutcome",
+    "AuditRecorder",
+    "AuditRecordCreate",
+    "AuditRecordWriter",
+    "AuditService",
+    "EVENT_LOG_TABLE",
+    "build_audit_log_record",
+    "configure_audit_logging",
+    "create_events_router",
+    "create_audit_event_hook",
+    "job_id_ctx",
+    "log_event",
+    "write_audit_record",
+    "write_audit_record_best_effort",
+]

cpkit/audit/events_service.py

@@ -0,0 +1,36 @@
+"""Service helpers for framework audit event reads."""
+
+from cpkit.errors import RepositoryError, from_repository_error
+
+from .types import AuditLogRecord
+
+
+class AuditEventsService:
+    def __init__(self, repo) -> None:
+        self.repo = repo
+
+    def list_visible_events(
+        self,
+        limit: int,
+        offset: int,
+        groups: list[str],
+        is_admin: bool,
+    ) -> list[AuditLogRecord]:
+        try:
+            return self.repo.list_events(limit, offset, groups, is_admin)
+        except RepositoryError as err:
+            raise from_repository_error(
+                err,
+                unavailable_message="Events are temporarily unavailable.",
+                fallback_message="Unable to load events.",
+            ) from err
+
+    def get_event_total(self) -> int:
+        try:
+            return self.repo.get_event_count()
+        except RepositoryError as err:
+            raise from_repository_error(
+                err,
+                unavailable_message="Event totals are temporarily unavailable.",
+                fallback_message="Unable to load the event count.",
+            ) from err

cpkit/audit/recorder.py

@@ -0,0 +1,240 @@
+"""Audit recording helpers for application-owned audit record models."""
+
+import logging
+from collections.abc import Callable
+from contextvars import ContextVar
+from enum import StrEnum
+from typing import Any, Protocol
+
+from cpkit.logging import request_id_ctx
+
+from .types import AuditLogRecord
+
+logger = logging.getLogger(__name__)
+_audit_record_factory: Callable[..., Any] | None = None
+job_id_ctx: ContextVar[int | None] = ContextVar("job_id", default=None)
+
+
+class AuditRecordWriter(Protocol):
+    """Repository-like object that can persist an application audit record."""
+
+    def log_event(self, record: Any) -> Any: ...
+
+
+def write_audit_record(
+    writer: Any,
+    record: Any,
+    *,
+    method_name: str = "log_event",
+) -> Any:
+    """Write an application-owned audit record through a repository-like writer."""
+    return getattr(writer, method_name)(record)
+
+
+def write_audit_record_best_effort(
+    writer: Any,
+    record: Any,
+    *,
+    event_type: str | None = None,
+    method_name: str = "log_event",
+    event_logger: logging.Logger | None = None,
+) -> bool:
+    """Write an audit record without letting audit failures fail the caller."""
+    active_logger = event_logger or logger
+
+    try:
+        write_audit_record(writer, record, method_name=method_name)
+    except Exception:
+        active_logger.exception("Failed to write audit event %s", event_type or record)
+        return False
+
+    return True
+
+
+class AuditRecorder:
+    """Build and persist application-owned audit records with common mechanics."""
+
+    def __init__(
+        self,
+        writer: AuditRecordWriter,
+        record_factory: Callable[..., Any],
+        *,
+        request_id_provider: Callable[[], str | None] | None = None,
+        job_id_provider: Callable[[], int | None] | None = None,
+        method_name: str = "log_event",
+        event_logger: logging.Logger | None = None,
+    ) -> None:
+        self.writer = writer
+        self.record_factory = record_factory
+        self.request_id_provider = request_id_provider
+        self.job_id_provider = job_id_provider
+        self.method_name = method_name
+        self.logger = event_logger or logger
+
+    def emit(
+        self,
+        event_type: str | StrEnum,
+        *,
+        actor_id: str,
+        metadata: dict[str, Any] | None = None,
+        request_id: str | None = None,
+        job_id: int | None = None,
+    ) -> Any:
+        """Create and write an application-owned audit record."""
+        record = self._build_record(
+            event_type,
+            actor_id=actor_id,
+            metadata=metadata,
+            request_id=request_id,
+            job_id=job_id,
+        )
+        return write_audit_record(
+            self.writer,
+            record,
+            method_name=self.method_name,
+        )
+
+    def emit_best_effort(
+        self,
+        event_type: str | StrEnum,
+        *,
+        actor_id: str,
+        metadata: dict[str, Any] | None = None,
+        request_id: str | None = None,
+        job_id: int | None = None,
+    ) -> bool:
+        """Create and write an audit record without failing the caller."""
+        try:
+            record = self._build_record(
+                event_type,
+                actor_id=actor_id,
+                metadata=metadata,
+                request_id=request_id,
+                job_id=job_id,
+            )
+            return write_audit_record_best_effort(
+                self.writer,
+                record,
+                event_type=str(event_type),
+                method_name=self.method_name,
+                event_logger=self.logger,
+            )
+        except Exception:
+            self.logger.exception("Failed to build audit event %s", event_type)
+            return False
+
+    def _build_record(
+        self,
+        event_type: str | StrEnum,
+        *,
+        actor_id: str,
+        metadata: dict[str, Any] | None,
+        request_id: str | None,
+        job_id: int | None,
+    ) -> Any:
+        effective_request_id = request_id
+        if effective_request_id is None and self.request_id_provider is not None:
+            effective_request_id = self.request_id_provider()
+
+        effective_job_id = job_id
+        if effective_job_id is None and self.job_id_provider is not None:
+            effective_job_id = self.job_id_provider()
+
+        return self.record_factory(
+            actor_id=actor_id,
+            event_type=str(event_type),
+            metadata=metadata,
+            request_id=effective_request_id,
+            job_id=effective_job_id,
+        )
+
+
+def build_audit_log_record(
+    *,
+    actor_id: str,
+    event_type: str,
+    metadata: dict[str, Any] | None,
+    request_id: str | None,
+    job_id: int | None,
+    default_metadata: dict[str, Any] | None = None,
+) -> AuditLogRecord:
+    """Build the standard cpkit audit log record."""
+    effective_metadata = metadata if metadata is not None else default_metadata
+    return AuditLogRecord(
+        user_id=actor_id,
+        action=event_type,
+        job_id=job_id,
+        details=effective_metadata,
+        request_id=_normalize_request_id(request_id),
+    )
+
+
+def _normalize_request_id(request_id: str | None) -> str | None:
+    return (str(request_id).strip() or None) if request_id else None
+
+
+def configure_audit_logging(record_factory: Callable[..., Any]) -> None:
+    """Configure the default audit record factory for framework logging APIs."""
+    global _audit_record_factory
+    _audit_record_factory = record_factory
+
+
+def create_audit_event_hook(
+    record_factory: Callable[..., Any],
+    *,
+    request_id_provider: Callable[[], str | None] = request_id_ctx.get,
+    job_id_provider: Callable[[], int | None] = job_id_ctx.get,
+    best_effort: bool = True,
+    event_logger: logging.Logger | None = None,
+) -> Callable[[Any, str, str | StrEnum, dict[str, Any] | None], None]:
+    """Create a reusable audit hook backed by an application record factory."""
+
+    def emit_audit_event(
+        repo: Any,
+        actor_id: str,
+        action: str | StrEnum,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        recorder = AuditRecorder(
+            repo,
+            record_factory,
+            request_id_provider=request_id_provider,
+            job_id_provider=job_id_provider,
+            event_logger=event_logger,
+        )
+        if best_effort:
+            recorder.emit_best_effort(
+                action,
+                actor_id=actor_id,
+                metadata=details,
+            )
+            return
+
+        recorder.emit(
+            action,
+            actor_id=actor_id,
+            metadata=details,
+        )
+
+    return emit_audit_event
+
+
+def log_event(
+    repo: Any,
+    actor_id: str,
+    action: str | StrEnum,
+    details: dict[str, Any] | None = None,
+) -> None:
+    """Best-effort audit logging for cpkit-backed service actions."""
+    if _audit_record_factory is None:
+        raise RuntimeError("cpkit audit logging has not been configured.")
+
+    create_audit_event_hook(
+        _audit_record_factory,
+        event_logger=logger,
+    )(
+        repo,
+        actor_id,
+        action,
+        details,
+    )