cpkit 0.1.0__py3-none-any.whl

cpkit/jobs/worker.py

@@ -0,0 +1,200 @@
+"""Generic queue worker loop."""
+
+import asyncio
+import logging
+import random
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from psycopg.rows import class_row
+
+from cpkit.audit import job_id_ctx
+
+from .maintenance import FAIL_ZOMBIE_JOBS_MESSAGE_TYPE, create_fail_zombie_jobs_handler
+from .repository import QUEUE_TABLE
+from .types import QueueMessage
+
+logger = logging.getLogger(__name__)
+
+QueueHandler = Callable[[int, Any, str], None]
+ResolveHandler = Callable[[QueueMessage], QueueHandler | None]
+ParseMessage = Callable[[QueueMessage], Any]
+FailureHandler = Callable[[QueueMessage, Exception], None]
+
+
+def create_queue_worker(
+    *,
+    get_pool: Callable[[], Any],
+    get_repo: Callable[[], Any],
+    handlers: Mapping[Any, QueueHandler] | None = None,
+    resolve_handler: ResolveHandler | None = None,
+    parse_message: ParseMessage | None = None,
+    handle_failure: FailureHandler | None = None,
+    failed_status: str = "FAILED",
+) -> Callable[[], Any]:
+    """Create a background task that polls the framework queue."""
+    maintenance_handlers = {
+        FAIL_ZOMBIE_JOBS_MESSAGE_TYPE: create_fail_zombie_jobs_handler(get_repo),
+    }
+
+    def record_failure(message: QueueMessage, err: Exception) -> None:
+        try:
+            get_repo().update_job(message.msg_id, failed_status)
+        except Exception:
+            logger.exception("Unable to mark job %s as failed", message.msg_id)
+        if handle_failure is not None:
+            handle_failure(message, err)
+
+    async def pull_from_mq() -> None:
+        await run_queue_worker(
+            get_pool=get_pool,
+            resolve_handler=_resolve_worker_handler(
+                maintenance_handlers,
+                handlers,
+                resolve_handler,
+            ),
+            parse_message=_parse_worker_message(
+                maintenance_handlers,
+                parse_message,
+            ),
+            handle_failure=record_failure,
+        )
+
+    return pull_from_mq
+
+
+def _resolve_worker_handler(
+    maintenance_handlers: Mapping[str, QueueHandler],
+    handlers: Mapping[Any, QueueHandler] | None,
+    resolve_handler: ResolveHandler | None,
+) -> ResolveHandler:
+    def resolve(message: QueueMessage) -> QueueHandler | None:
+        handler = maintenance_handlers.get(message.msg_type)
+        if handler is not None:
+            return handler
+        if handlers is not None:
+            handler = handlers.get(message.msg_type)
+            if handler is not None:
+                return handler
+        if resolve_handler is None:
+            return None
+        return resolve_handler(message)
+
+    return resolve
+
+
+def _parse_worker_message(
+    maintenance_handlers: Mapping[str, QueueHandler],
+    parse_message: ParseMessage | None,
+) -> ParseMessage:
+    def parse(message: QueueMessage) -> Any:
+        if message.msg_type in maintenance_handlers:
+            return message.msg_data
+        if parse_message is None:
+            return message.msg_data
+        return parse_message(message)
+
+    return parse
+
+
+async def run_queue_worker(
+    *,
+    get_pool: Callable[[], Any],
+    handlers: Mapping[Any, QueueHandler] | None = None,
+    resolve_handler: ResolveHandler | None = None,
+    parse_message: ParseMessage | None = None,
+    handle_failure: FailureHandler | None = None,
+    poll_seconds: float = 5,
+    jitter_min: float = 0.7,
+    jitter_max: float = 1.3,
+) -> None:
+    """Continuously claim due queue messages and dispatch them to handlers."""
+    try:
+        while True:
+            await asyncio.sleep(poll_seconds * random.uniform(jitter_min, jitter_max))
+            try:
+                with get_pool().connection() as conn:
+                    with conn.cursor(row_factory=class_row(QueueMessage)) as cur:
+                        with conn.transaction():
+                            message = _claim_due_message(cur)
+                            if message is None:
+                                continue
+
+                            logger.info(
+                                "Processing queue message %s of type %s",
+                                message.msg_id,
+                                message.msg_type,
+                            )
+
+                            job_id_token = _set_current_job_id(message)
+                            try:
+                                handler = _resolve_handler(
+                                    message,
+                                    handlers=handlers,
+                                    resolve_handler=resolve_handler,
+                                )
+                                payload = (
+                                    parse_message(message)
+                                    if parse_message is not None
+                                    else message.msg_data
+                                )
+                                handler(message.msg_id, payload, message.created_by)
+                            except Exception as err:
+                                logger.exception(
+                                    "Queue message %s failed during dispatch",
+                                    message.msg_id,
+                                )
+                                if handle_failure is not None:
+                                    try:
+                                        handle_failure(message, err)
+                                    except Exception:
+                                        logger.exception(
+                                            "Queue message %s failure hook failed",
+                                            message.msg_id,
+                                        )
+                            finally:
+                                if job_id_token is not None:
+                                    job_id_ctx.reset(job_id_token)
+                                cur.execute(
+                                    f"DELETE FROM {QUEUE_TABLE} WHERE msg_id = %s;",
+                                    (message.msg_id,),
+                                )
+            except Exception:
+                logger.exception("Unexpected failure while polling the message queue")
+
+    except asyncio.CancelledError:
+        logger.info("Queue worker was stopped")
+
+
+def _claim_due_message(cur) -> QueueMessage | None:
+    return cur.execute(f"""
+        SELECT *
+        FROM {QUEUE_TABLE}
+        WHERE now() > start_after
+        LIMIT 1
+        FOR UPDATE SKIP LOCKED
+        """).fetchone()
+
+
+def _set_current_job_id(message: QueueMessage):
+    if message.msg_type == FAIL_ZOMBIE_JOBS_MESSAGE_TYPE:
+        return None
+    return job_id_ctx.set(message.msg_id)
+
+
+def _resolve_handler(
+    message: QueueMessage,
+    *,
+    handlers: Mapping[Any, QueueHandler] | None,
+    resolve_handler: ResolveHandler | None,
+) -> QueueHandler:
+    if resolve_handler is not None:
+        handler = resolve_handler(message)
+    elif handlers is not None:
+        handler = handlers.get(message.msg_type)
+    else:
+        handler = None
+
+    if handler is None:
+        raise ValueError(f"Unknown task type requested: {message.msg_type}")
+    return handler

cpkit/logging/README.md

@@ -0,0 +1,19 @@
+# Logging
+
+The logging package configures operational logs and carries per-request context.
+
+## Files
+
+- `context.py`: `request_id_ctx`, a logging filter, and compact formatter.
+- `middleware.py`: FastAPI middleware that assigns/request-propagates
+  `X-Request-ID` and logs inbound/outbound requests.
+- `setup.py`: Root logger setup, log levels, and journald-friendly formatting.
+
+## Runtime Flow
+
+1. `create_cpkit_app()` configures logging during startup.
+2. Request middleware sets `request_id_ctx` for each HTTP request.
+3. Audit recording uses `request_id_ctx.get` as the default request id provider.
+4. Log formatters include the request id so API logs and audit records can be
+   correlated.
+

cpkit/logging/__init__.py

@@ -0,0 +1,13 @@
+"""Logging setup and request context helpers."""
+
+from .context import RequestIDFilter, ShorthandFormatter, request_id_ctx
+from .middleware import request_logging_middleware
+from .setup import configure_logging
+
+__all__ = [
+    "RequestIDFilter",
+    "ShorthandFormatter",
+    "configure_logging",
+    "request_logging_middleware",
+    "request_id_ctx",
+]

cpkit/logging/context.py

@@ -0,0 +1,29 @@
+"""Request-aware logging context."""
+
+import logging
+from contextvars import ContextVar
+
+request_id_ctx: ContextVar[str | None] = ContextVar("request_id", default=None)
+
+
+class RequestIDFilter(logging.Filter):
+    def filter(self, record):
+        record.request_id = request_id_ctx.get() or "-"
+        return True
+
+
+class ShorthandFormatter(logging.Formatter):
+    LEVEL_MAP = {
+        "DEBUG": "D",
+        "INFO": "I",
+        "WARNING": "W",
+        "ERROR": "E",
+        "CRITICAL": "C",
+    }
+
+    def format(self, record):
+        original_levelname = record.levelname
+        record.levelname = self.LEVEL_MAP.get(original_levelname, original_levelname)
+        result = super().format(record)
+        record.levelname = original_levelname
+        return result

cpkit/logging/middleware.py

@@ -0,0 +1,55 @@
+"""FastAPI request logging middleware helpers."""
+
+import logging
+import time
+import uuid
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from fastapi import Request, Response
+
+from .context import request_id_ctx
+
+
+async def request_logging_middleware(
+    request: Request,
+    call_next: Callable[[Request], Awaitable[Response]],
+) -> Response:
+    """Attach a request id and log inbound/outbound request details."""
+    request_id = _request_id(request.headers.get("X-Request-ID"))
+    request_id_ctx.set(request_id)
+
+    start_time = time.perf_counter()
+
+    client = _client_address(request)
+    logging.debug(f'<- {client} - "{request.method} {request.url.path}"')
+
+    response = await call_next(request)
+
+    process_time_ms = (time.perf_counter() - start_time) * 1000
+    logging.info(
+        f'-> {client} - "{request.method} {request.url.path}" '
+        f"{response.status_code} | {process_time_ms:.2f}"
+    )
+
+    response.headers["X-Request-ID"] = request_id
+    response.headers["X-Process-Time-ms"] = f"{process_time_ms:.2f}"
+
+    return response
+
+
+def _client_address(request: Request) -> str:
+    client: Any = request.client
+    if client is None:
+        return "-"
+    return f"{client.host}:{client.port}"
+
+
+def _request_id(value: str | None) -> str:
+    normalized = (str(value).strip() or None) if value else None
+    if normalized is not None:
+        try:
+            return str(uuid.UUID(normalized))
+        except ValueError:
+            pass
+    return str(uuid.uuid4())

cpkit/logging/setup.py

@@ -0,0 +1,81 @@
+"""Logging configuration for operational messages."""
+
+import logging
+import sys
+import time
+from typing import Any
+
+from cpkit.settings import FrameworkSettingKey
+
+from .context import RequestIDFilter, ShorthandFormatter
+
+
+def configure_logging(
+    settings_provider=None,
+    *,
+    force: bool = False,
+    default_level: str = "INFO",
+    default_journald_identifier: str = "app",
+    level_key: Any = FrameworkSettingKey.logging_level,
+    journald_identifier_key: Any = FrameworkSettingKey.logging_journald_identifier,
+) -> None:
+    """Configure root logging with journald when available."""
+
+    if getattr(configure_logging, "_configured", False) and not force:
+        return
+
+    level_name = _setting_value(settings_provider, level_key, default_level).upper()
+    journald_identifier = _setting_value(
+        settings_provider,
+        journald_identifier_key,
+        default_journald_identifier,
+    )
+    level = getattr(logging, level_name, logging.INFO)
+    root_logger = logging.getLogger()
+    root_logger.setLevel(level)
+    logging.getLogger("uvicorn").setLevel(logging.ERROR)
+    logging.getLogger("uvicorn.access").setLevel(logging.ERROR)
+
+    if force:
+        for handler in list(root_logger.handlers):
+            root_logger.removeHandler(handler)
+            try:
+                handler.close()
+            except Exception:
+                pass
+    elif root_logger.handlers:
+        configure_logging._configured = True
+        return
+
+    formatter = ShorthandFormatter(
+        "%(asctime)s [%(levelname)s] [%(request_id)s] %(message)s"
+    )
+    formatter.converter = time.gmtime
+    formatter.default_msec_format = "%s.%03d"
+
+    handler: logging.Handler
+    try:
+        if sys.platform != "linux":
+            raise RuntimeError("journald unavailable")
+
+        from systemd.journal import JournalHandler
+
+        handler = JournalHandler(SYSLOG_IDENTIFIER=journald_identifier)
+    except Exception:
+        handler = logging.StreamHandler()
+
+    handler.addFilter(RequestIDFilter())
+    handler.setFormatter(formatter)
+    root_logger.addHandler(handler)
+    configure_logging._configured = True
+
+
+def _setting_value(settings_provider, key: Any, default: str) -> str:
+    if settings_provider is None:
+        return default
+
+    setting = settings_provider.get_setting(key)
+    value = getattr(setting, "value", setting)
+    if value in (None, ""):
+        return default
+    return str(value)

cpkit/playbooks/README.md

@@ -0,0 +1,25 @@
+# Playbooks
+
+The playbooks package owns versioned playbook storage and Ansible execution.
+It lets apps store playbook versions in the database, choose a default version,
+edit playbooks from the admin webapp, and run the selected playbook as part of a
+job.
+
+## Files
+
+- `types.py`: Playbook records, list/version responses, and save requests.
+- `repository.py`: Repository mixin for playbook version storage and defaults.
+- `service.py`: Version listing, loading, saving, deleting, and default-setting
+  rules.
+- `router.py`: Admin playbook API routes.
+- `ansible.py`: Ansible runner wrappers that load stored playbooks, update jobs,
+  and record task output.
+
+## Runtime Flow
+
+1. Admin APIs manage compressed playbook content and default versions.
+2. A job handler calls `run_playbook()` or `run_playbook_lite()`.
+3. The runner loads the default playbook version from the database.
+4. The runner records the selected version on the job and writes task output as
+   Ansible events arrive.
+

cpkit/playbooks/__init__.py

@@ -0,0 +1,40 @@
+"""Versioned playbook models and repository helpers."""
+
+from .ansible import (
+    AnsibleRunner,
+    LiteAnsibleRunner,
+    LiteRunnerResult,
+    RunnerResult,
+    run_playbook,
+    run_playbook_lite,
+)
+from .repository import PLAYBOOKS_TABLE, PlaybooksRepositoryMixin
+from .router import create_playbooks_router
+from .service import PlaybooksService
+from .types import (
+    Playbook,
+    PlaybookListResponse,
+    PlaybookOverview,
+    PlaybookResponse,
+    PlaybookSaveRequest,
+    PlaybookVersionResponse,
+)
+
+__all__ = [
+    "PLAYBOOKS_TABLE",
+    "AnsibleRunner",
+    "LiteAnsibleRunner",
+    "LiteRunnerResult",
+    "Playbook",
+    "PlaybookListResponse",
+    "PlaybookOverview",
+    "PlaybookResponse",
+    "PlaybookSaveRequest",
+    "PlaybookVersionResponse",
+    "PlaybooksRepositoryMixin",
+    "PlaybooksService",
+    "RunnerResult",
+    "create_playbooks_router",
+    "run_playbook",
+    "run_playbook_lite",
+]