cpkit 0.1.0__py3-none-any.whl

cpkit/db/postgres.py

@@ -0,0 +1,252 @@
+"""Low-level Postgres metadata database infrastructure."""
+
+import logging
+import os
+from typing import Any
+
+from psycopg import DatabaseError, InterfaceError, OperationalError
+from psycopg import errors as psycopg_errors
+from psycopg.abc import Dumper
+from psycopg.pq import Format
+from psycopg.rows import class_row
+from psycopg.types.array import ListDumper
+from psycopg.types.json import Jsonb, JsonbDumper
+from psycopg_pool import ConnectionPool
+
+from cpkit.errors import (
+    RepositoryConflictError,
+    RepositoryError,
+    RepositoryPermissionError,
+    RepositoryUnavailableError,
+    RepositoryValidationError,
+)
+
+CPKIT_DB_URL = os.getenv("CPKIT_DB_URL")
+pool: ConnectionPool | None = None
+logger = logging.getLogger(__name__)
+
+
+class Dict2JsonbDumper(JsonbDumper):
+    def dump(self, obj):
+        return super().dump(Jsonb(obj))
+
+
+class SelectorDumper(Dumper):
+    """Choose the correct dumper for list payloads."""
+
+    format = Format.BINARY
+    oid = None
+
+    _dict_dumper = Dict2JsonbDumper(list)
+    _list_dumper = ListDumper(list)
+
+    def upgrade(self, obj, format: Format) -> Dumper:
+        if obj and isinstance(obj[0], dict):
+            return self._dict_dumper
+        return self._list_dumper
+
+
+def execute_stmt(
+    stmt: str,
+    bind_args: tuple = (),
+    *,
+    operation: str | None = None,
+) -> None:
+    with get_pool().connection() as conn:
+        _register_dumpers(conn)
+
+        with conn.cursor() as cur:
+            try:
+                stmt = _normalize_stmt(stmt)
+                cur.execute(stmt, bind_args)
+            except Exception as err:
+                raise translate_database_error(err, operation) from err
+
+
+def fetch_all(
+    stmt: str,
+    bind_args: tuple,
+    row_type,
+    *,
+    operation: str | None = None,
+) -> list[Any]:
+    with get_pool().connection() as conn:
+        _register_dumpers(conn)
+
+        with conn.cursor(row_factory=class_row(row_type)) as cur:
+            try:
+                stmt = _normalize_stmt(stmt)
+                cur.execute(stmt, bind_args)
+                return cur.fetchall()
+            except Exception as err:
+                raise translate_database_error(err, operation) from err
+
+
+def fetch_one(
+    stmt: str,
+    bind_args: tuple,
+    row_type,
+    *,
+    operation: str | None = None,
+) -> Any | None:
+    with get_pool().connection() as conn:
+        _register_dumpers(conn)
+
+        with conn.cursor(row_factory=class_row(row_type)) as cur:
+            try:
+                stmt = _normalize_stmt(stmt)
+                cur.execute(stmt, bind_args)
+                return cur.fetchone()
+            except Exception as err:
+                raise translate_database_error(err, operation) from err
+
+
+def fetch_scalar(
+    stmt: str,
+    bind_args: tuple = (),
+    *,
+    operation: str | None = None,
+) -> Any | None:
+    with get_pool().connection() as conn:
+        _register_dumpers(conn)
+
+        with conn.cursor() as cur:
+            try:
+                stmt = _normalize_stmt(stmt)
+                cur.execute(stmt, bind_args)
+                row = cur.fetchone()
+                if row is None:
+                    return None
+                return row[0]
+            except Exception as err:
+                raise translate_database_error(err, operation) from err
+
+
+def _register_dumpers(conn) -> None:
+    conn.adapters.register_dumper(set, ListDumper)
+    conn.adapters.register_dumper(dict, Dict2JsonbDumper)
+    conn.adapters.register_dumper(list, SelectorDumper)
+
+
+def _normalize_stmt(stmt: str) -> str:
+    return " ".join([s.strip() for s in stmt.split("\n")])
+
+
+def initialize_postgres(db_url: str | None = None) -> None:
+    global pool
+
+    effective_db_url = db_url or CPKIT_DB_URL
+    if not effective_db_url:
+        raise EnvironmentError("CPKIT_DB_URL env variable not found!")
+
+    if pool is not None:
+        return
+
+    pool = ConnectionPool(
+        effective_db_url,
+        kwargs={"autocommit": True},
+        configure=_register_dumpers,
+    )
+
+
+def get_pool() -> ConnectionPool:
+    if pool is None:
+        raise RuntimeError("Database pool not initialized. Ensure lifespan ran.")
+    return pool
+
+
+def close_db() -> None:
+    global pool
+
+    if pool is not None:
+        pool.close()
+
+    pool = None
+
+
+def translate_database_error(
+    err: Exception,
+    operation: str | None,
+    *,
+    unavailable_error_types: tuple[type[Exception], ...] = (),
+) -> RepositoryError:
+    operation_name = operation or "database.statement"
+    sqlstate = getattr(err, "sqlstate", None)
+
+    if unavailable_error_types and isinstance(err, unavailable_error_types):
+        logger.warning(
+            "Database unavailable [operation=%s error=%s reason=%s]",
+            operation_name,
+            err.__class__.__name__,
+            getattr(err, "reason", str(err)),
+        )
+        return RepositoryUnavailableError(
+            "Database is temporarily unavailable.",
+            operation=operation_name,
+            retryable=True,
+        )
+
+    logger.exception(
+        "Database operation failed [operation=%s sqlstate=%s error=%s]",
+        operation_name,
+        sqlstate,
+        err.__class__.__name__,
+    )
+
+    if isinstance(
+        err,
+        (
+            OperationalError,
+            InterfaceError,
+            psycopg_errors.SerializationFailure,
+            psycopg_errors.DeadlockDetected,
+        ),
+    ):
+        return RepositoryUnavailableError(
+            "Database is temporarily unavailable.",
+            operation=operation_name,
+            retryable=True,
+        )
+
+    if isinstance(err, psycopg_errors.UniqueViolation):
+        return RepositoryConflictError(
+            "Database write conflicts with existing data.",
+            operation=operation_name,
+        )
+
+    if isinstance(err, psycopg_errors.DuplicateDatabase):
+        return RepositoryConflictError(
+            "Database already exists.",
+            operation=operation_name,
+        )
+
+    if isinstance(
+        err,
+        (
+            psycopg_errors.ForeignKeyViolation,
+            psycopg_errors.CheckViolation,
+            psycopg_errors.NotNullViolation,
+            psycopg_errors.InvalidTextRepresentation,
+        ),
+    ):
+        return RepositoryValidationError(
+            "Database rejected invalid data.",
+            operation=operation_name,
+        )
+
+    if isinstance(err, psycopg_errors.InsufficientPrivilege):
+        return RepositoryPermissionError(
+            "Database permission denied.",
+            operation=operation_name,
+        )
+
+    if isinstance(err, DatabaseError):
+        return RepositoryError(
+            "Database operation failed.",
+            operation=operation_name,
+        )
+
+    return RepositoryError(
+        "Repository operation failed.",
+        operation=operation_name,
+    )

cpkit/dependencies.py

@@ -0,0 +1,73 @@
+"""Application-scoped dependency callables exposed by cpkit."""
+
+from typing import Any
+
+from fastapi import Depends, Request, Security
+
+from .auth import access_key_scheme, signature_scheme, timestamp_scheme
+from .repository import get_repo
+
+_active_bundle: Any | None = None
+
+
+def configure_cpkit_dependencies(bundle: Any) -> None:
+    """Install the active cpkit bundle used by exported dependencies."""
+    global _active_bundle
+    _active_bundle = bundle
+
+
+async def require_authenticated(
+    request: Request,
+    repo: Any = Depends(get_repo),
+    access_key: str | None = Security(access_key_scheme),
+    signature: str | None = Security(signature_scheme),
+    timestamp: str | None = Security(timestamp_scheme),
+) -> dict[str, Any]:
+    """Return claims for the current caller."""
+    return await _bundle().require_authenticated(
+        request,
+        repo,
+        access_key,
+        signature,
+        timestamp,
+    )
+
+
+def require_user(
+    claims: dict[str, Any] = Security(require_authenticated),
+) -> dict[str, Any]:
+    """Require a role that permits mutating application operations."""
+    return _bundle().require_user(claims)
+
+
+def require_readonly(
+    request: Request,
+    claims: dict[str, Any] = Security(require_authenticated),
+) -> dict[str, Any]:
+    """Allow read-only roles on GET and require user roles on writes."""
+    return _bundle().require_readonly(request, claims)
+
+
+def require_admin(
+    claims: dict[str, Any] = Security(require_authenticated),
+) -> dict[str, Any]:
+    """Require an administrator role."""
+    return _bundle().require_admin(claims)
+
+
+def get_access_scope(claims: dict[str, Any]) -> tuple[list[str], bool]:
+    """Return normalized caller groups plus whether the caller is an admin."""
+    return _bundle().get_access_scope(claims)
+
+
+def get_audit_actor(
+    claims: dict[str, Any] = Security(require_authenticated),
+) -> str:
+    """Return the identifier that should be written into audit logs."""
+    return _bundle().get_audit_actor(claims)
+
+
+def _bundle() -> Any:
+    if _active_bundle is None:
+        raise RuntimeError("cpkit dependencies are not configured.")
+    return _active_bundle

cpkit/errors/README.md

@@ -0,0 +1,22 @@
+# Errors
+
+The errors package defines cpkit's exception layers. The layers are deliberately
+separate so low-level DB details do not leak directly into API responses.
+
+## Files
+
+- `repository.py`: Errors raised by repository/database operations.
+- `service.py`: User-facing service errors and repository-to-service
+  translation.
+- `http.py`: Service-to-FastAPI HTTP response translation.
+
+## Error Flow
+
+1. DB helpers raise `RepositoryError` subclasses.
+2. Services catch repository errors and call `from_repository_error()`.
+3. Routers catch `ServiceError` and call `raise_http_from_service_error()`.
+
+This keeps SQL and driver details out of routers while still letting the UI show
+clear messages such as "not found", "not authorized", or "temporarily
+unavailable".
+

cpkit/errors/__init__.py

@@ -0,0 +1,35 @@
+"""Shared framework exception types."""
+
+from .http import raise_http_from_service_error
+from .repository import (
+    RepositoryConflictError,
+    RepositoryError,
+    RepositoryPermissionError,
+    RepositoryUnavailableError,
+    RepositoryValidationError,
+)
+from .service import (
+    ServiceAuthorizationError,
+    ServiceConflictError,
+    ServiceError,
+    ServiceNotFoundError,
+    ServiceUnavailableError,
+    ServiceValidationError,
+    from_repository_error,
+)
+
+__all__ = [
+    "RepositoryConflictError",
+    "RepositoryError",
+    "RepositoryPermissionError",
+    "RepositoryUnavailableError",
+    "RepositoryValidationError",
+    "ServiceAuthorizationError",
+    "ServiceConflictError",
+    "ServiceError",
+    "ServiceNotFoundError",
+    "ServiceUnavailableError",
+    "ServiceValidationError",
+    "from_repository_error",
+    "raise_http_from_service_error",
+]

cpkit/errors/http.py

@@ -0,0 +1,45 @@
+"""FastAPI translation helpers for framework service errors."""
+
+from fastapi import HTTPException, status
+
+from .service import (
+    ServiceAuthorizationError,
+    ServiceConflictError,
+    ServiceError,
+    ServiceNotFoundError,
+    ServiceUnavailableError,
+    ServiceValidationError,
+)
+
+
+def raise_http_from_service_error(err: ServiceError) -> None:
+    """Raise an HTTPException that matches a service-layer error."""
+    if isinstance(err, ServiceNotFoundError):
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=err.user_message,
+        )
+    if isinstance(err, ServiceValidationError):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=err.user_message,
+        )
+    if isinstance(err, ServiceConflictError):
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=err.user_message,
+        )
+    if isinstance(err, ServiceAuthorizationError):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=err.user_message,
+        )
+    if isinstance(err, ServiceUnavailableError):
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=err.user_message,
+        )
+    raise HTTPException(
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        detail=err.user_message,
+    )

cpkit/errors/repository.py

@@ -0,0 +1,32 @@
+"""Repository-layer exception types."""
+
+
+class RepositoryError(Exception):
+    """Base exception for repository and infrastructure failures."""
+
+    def __init__(
+        self,
+        message: str = "Repository operation failed.",
+        *,
+        operation: str | None = None,
+        retryable: bool = False,
+    ) -> None:
+        super().__init__(message)
+        self.operation = operation
+        self.retryable = retryable
+
+
+class RepositoryUnavailableError(RepositoryError):
+    """Raised when the database is temporarily unavailable."""
+
+
+class RepositoryConflictError(RepositoryError):
+    """Raised when a write conflicts with existing data."""
+
+
+class RepositoryValidationError(RepositoryError):
+    """Raised when the database rejects invalid data."""
+
+
+class RepositoryPermissionError(RepositoryError):
+    """Raised when the database denies access to an operation."""

cpkit/errors/service.py

@@ -0,0 +1,74 @@
+"""Service-layer exception types and repository error translation."""
+
+from .repository import (
+    RepositoryConflictError,
+    RepositoryError,
+    RepositoryPermissionError,
+    RepositoryUnavailableError,
+    RepositoryValidationError,
+)
+
+
+class ServiceError(Exception):
+    """Base exception for errors that may be shown in a UI or API response."""
+
+    default_title = "Error"
+    default_message = "Something went wrong. Please try again."
+
+    def __init__(
+        self,
+        message: str | None = None,
+        *,
+        title: str | None = None,
+    ) -> None:
+        self.user_title = title or self.default_title
+        self.user_message = message or self.default_message
+        super().__init__(self.user_message)
+
+
+class ServiceUnavailableError(ServiceError):
+    default_title = "Temporarily Unavailable"
+    default_message = "The service is temporarily unavailable. Please try again."
+
+
+class ServiceConflictError(ServiceError):
+    default_title = "Conflict"
+    default_message = "The requested change conflicts with existing data."
+
+
+class ServiceValidationError(ServiceError):
+    default_title = "Invalid Request"
+    default_message = "The submitted data is invalid."
+
+
+class ServiceAuthorizationError(ServiceError):
+    default_title = "Not Authorized"
+    default_message = "You are not authorized to perform this action."
+
+
+class ServiceNotFoundError(ServiceError):
+    default_title = "Not Found"
+    default_message = "The requested item could not be found."
+
+
+def from_repository_error(
+    err: RepositoryError,
+    *,
+    unavailable_message: str | None = None,
+    conflict_message: str | None = None,
+    validation_message: str | None = None,
+    permission_message: str | None = None,
+    fallback_message: str | None = None,
+    fallback_title: str | None = None,
+) -> ServiceError:
+    """Translate a repository exception into a service exception."""
+
+    if isinstance(err, RepositoryUnavailableError):
+        return ServiceUnavailableError(unavailable_message)
+    if isinstance(err, RepositoryConflictError):
+        return ServiceConflictError(conflict_message)
+    if isinstance(err, RepositoryValidationError):
+        return ServiceValidationError(validation_message)
+    if isinstance(err, RepositoryPermissionError):
+        return ServiceAuthorizationError(permission_message)
+    return ServiceError(fallback_message, title=fallback_title)

cpkit/jobs/README.md

@@ -0,0 +1,29 @@
+# Jobs
+
+The jobs package owns cpkit's framework job history and queue mechanics. A job
+is represented by a row in `cpkit.jobs`; queued work is represented by a row in
+`cpkit.mq`, where the queue message id doubles as the job id for normal app
+jobs.
+
+## Files
+
+- `types.py`: Job, task, queue, stats, and detail response models.
+- `repository.py`: Repository mixins for jobs, tasks, linked resources, and the
+  queue table.
+- `service.py`: Job listing, detail loading, stats, and rescheduling rules.
+- `router.py`: Jobs API routes.
+- `worker.py`: Background queue poller and handler dispatch.
+- `maintenance.py`: Framework maintenance queue handlers, such as zombie job
+  cleanup.
+
+## Runtime Flow
+
+1. App code enqueues work through the repository/service.
+2. The queue worker claims due messages from `cpkit.mq`.
+3. The worker resolves a handler and calls it with `(job_id, payload, created_by)`.
+4. Handlers update `cpkit.jobs` and write task rows as work progresses.
+5. The Jobs page reads job rows, task rows, and stats through the Jobs API.
+
+When a normal queue message is being processed, the worker sets the current
+audit job context so audit records can store the job id separately from details.
+

cpkit/jobs/__init__.py

@@ -0,0 +1,49 @@
+"""Framework-owned job queue primitives."""
+
+from .maintenance import FAIL_ZOMBIE_JOBS_MESSAGE_TYPE, create_fail_zombie_jobs_handler
+from .repository import (
+    JOBS_TABLE,
+    QUEUE_TABLE,
+    TASKS_TABLE,
+    JobsRepositoryMixin,
+    QueueJobRepositoryMixin,
+    QueueRepositoryMixin,
+)
+from .router import create_jobs_router
+from .service import JobsService
+from .types import (
+    IntID,
+    Job,
+    JobDetailsResponse,
+    JobID,
+    JobRescheduleResponse,
+    JobStatsResponse,
+    LinkedResourceRef,
+    QueueMessage,
+    Task,
+)
+from .worker import create_queue_worker, run_queue_worker
+
+__all__ = [
+    "FAIL_ZOMBIE_JOBS_MESSAGE_TYPE",
+    "IntID",
+    "JOBS_TABLE",
+    "Job",
+    "JobDetailsResponse",
+    "JobID",
+    "JobRescheduleResponse",
+    "JobStatsResponse",
+    "JobsRepositoryMixin",
+    "JobsService",
+    "LinkedResourceRef",
+    "QUEUE_TABLE",
+    "QueueMessage",
+    "QueueJobRepositoryMixin",
+    "QueueRepositoryMixin",
+    "TASKS_TABLE",
+    "Task",
+    "create_fail_zombie_jobs_handler",
+    "create_queue_worker",
+    "create_jobs_router",
+    "run_queue_worker",
+]

cpkit/jobs/maintenance.py

@@ -0,0 +1,15 @@
+"""Framework job maintenance handlers."""
+
+from collections.abc import Callable
+from typing import Any
+
+FAIL_ZOMBIE_JOBS_MESSAGE_TYPE = "FAIL_ZOMBIE_JOBS"
+
+
+def create_fail_zombie_jobs_handler(get_repo: Callable[[], Any]):
+    """Create a queue handler that marks stale framework jobs as failed."""
+
+    def fail_zombie_jobs(_job_id: int, _command: Any, _requested_by: str) -> None:
+        get_repo().fail_zombie_jobs()
+
+    return fail_zombie_jobs