crackerjack 0.37.9__py3-none-any.whl → 0.45.2__py3-none-any.whl

crackerjack/errors.py

@@ -3,7 +3,7 @@ import typing as t
 from enum import Enum
 from pathlib import Path
 
-from rich.console import Console
+from acb.console import Console
 from rich.panel import Panel
 
 

crackerjack/events/README.md

@@ -0,0 +1,11 @@
+> Crackerjack Docs: [Main](<../../README.md>) | [Crackerjack Package](<../README.md>) | [Events](<./README.md>)
+
+# Events
+
+Event types, signals, and dispatch-related helpers.
+
+## Related
+
+- [Crackerjack Package](<../README.md>) - Parent package
+- [Monitoring](<../monitoring/README.md>) - Observability and metrics
+- [Coordinators](../coordinators/README.md) - Event coordination and orchestration

crackerjack/events/__init__.py

@@ -0,0 +1,16 @@
+"""Event bus utilities for Crackerjack."""
+
+from .telemetry import WorkflowEventTelemetry, register_default_subscribers
+from .workflow_bus import (
+    WorkflowEvent,
+    WorkflowEventBus,
+    WorkflowEventDispatchResult,
+)
+
+__all__ = [
+    "WorkflowEvent",
+    "WorkflowEventBus",
+    "WorkflowEventDispatchResult",
+    "WorkflowEventTelemetry",
+    "register_default_subscribers",
+]

crackerjack/events/telemetry.py

@@ -0,0 +1,175 @@
+"""Telemetry collection for workflow events."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import typing as t
+from collections import Counter, deque
+from contextlib import suppress
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from acb.events import Event, EventHandlerResult
+
+from .workflow_bus import WorkflowEvent
+
+if TYPE_CHECKING:  # pragma: no cover - typing helper
+    from .workflow_bus import WorkflowEventBus
+
+HistoryEntry = dict[str, t.Any]
+
+
+@dataclass
+class WorkflowEventTelemetry:
+    """Collects lightweight metrics about workflow events."""
+
+    max_history: int = 100
+    state_file: Path | None = None
+    rollup_interval_seconds: float = 3600.0
+    rollup_file: Path | None = None
+    _lock: asyncio.Lock = field(default_factory=asyncio.Lock, init=False)
+    _counts: Counter[str] = field(default_factory=Counter, init=False)
+    _history: deque[HistoryEntry] = field(init=False)
+    _last_error: HistoryEntry | None = field(default=None, init=False)
+    _persist_task: asyncio.Task[None] | None = field(
+        default=None, init=False, repr=False
+    )
+    _rollup_task: asyncio.Task[None] | None = field(
+        default=None, init=False, repr=False
+    )
+
+    def __post_init__(self) -> None:
+        self._history = deque(maxlen=self.max_history)
+        if self.rollup_file is None and self.state_file is not None:
+            self.rollup_file = self.state_file.with_name(
+                f"{self.state_file.stem}_rollups.jsonl"
+            )
+
+    async def handle_event(self, event: Event) -> EventHandlerResult:
+        """Event bus subscriber that records event metadata."""
+        entry: HistoryEntry = {
+            "event_type": event.metadata.event_type,
+            "timestamp": event.metadata.timestamp.isoformat(),
+            "source": event.metadata.source,
+            "payload": event.payload,
+        }
+
+        async with self._lock:
+            self._counts[event.metadata.event_type] += 1
+            self._history.append(entry)
+            if event.metadata.event_type == WorkflowEvent.WORKFLOW_FAILED.value:
+                self._last_error = entry
+
+        if self.state_file is not None:
+            await self._schedule_persist()
+        await self._ensure_rollup_task()
+
+        return EventHandlerResult(success=True)
+
+    async def snapshot(self) -> dict[str, t.Any]:
+        """Return a snapshot of the telemetry counters and history."""
+        async with self._lock:
+            return {
+                "counts": dict(self._counts),
+                "recent_events": list(self._history),
+                "last_error": self._last_error,
+            }
+
+    async def reset(self) -> None:
+        """Reset telemetry counters."""
+        async with self._lock:
+            self._counts.clear()
+            self._history.clear()
+            self._last_error = None
+        if self.state_file and self.state_file.exists():
+            with suppress(Exception):
+                self.state_file.unlink()
+
+    async def shutdown(self) -> None:
+        """Shutdown background persistence tasks."""
+        if self._persist_task and not self._persist_task.done():
+            self._persist_task.cancel()
+            with suppress(asyncio.CancelledError):
+                await self._persist_task
+        if self._rollup_task and not self._rollup_task.done():
+            self._rollup_task.cancel()
+            with suppress(asyncio.CancelledError):
+                await self._rollup_task
+
+    async def _schedule_persist(self) -> None:
+        if self.state_file is None:
+            return
+
+        if self._persist_task and not self._persist_task.done():
+            return
+
+        async def _persist() -> None:
+            snapshot = await self.snapshot()
+            state_file = self.state_file
+            if state_file is None:
+                return
+            with suppress(Exception):
+                state_file.parent.mkdir(parents=True, exist_ok=True)
+                await asyncio.to_thread(
+                    state_file.write_text,
+                    json.dumps(snapshot, indent=2),
+                )
+
+        self._persist_task = asyncio.create_task(_persist())
+
+    async def _ensure_rollup_task(self) -> None:
+        if self.rollup_file is None or self.rollup_interval_seconds <= 0:
+            return
+        loop = asyncio.get_running_loop()
+        if self._rollup_task and not self._rollup_task.done():
+            return
+
+        async def _rollup_loop() -> None:
+            try:
+                while True:
+                    await asyncio.sleep(self.rollup_interval_seconds)
+                    await self._persist_rollup()
+            except asyncio.CancelledError:  # pragma: no cover - loop cancellation
+                raise
+
+        self._rollup_task = loop.create_task(_rollup_loop())
+
+    async def _persist_rollup(self) -> None:
+        if self.rollup_file is None:
+            return
+        snapshot = await self.snapshot()
+        rollup_entry = {
+            "timestamp": datetime.now().isoformat(),
+            "counts": snapshot["counts"],
+            "total_events": sum(snapshot["counts"].values()),
+            "last_error": snapshot["last_error"],
+        }
+
+        rollup_file = self.rollup_file
+
+        def _write() -> None:
+            if rollup_file is None:
+                return
+            rollup_file.parent.mkdir(parents=True, exist_ok=True)
+            with rollup_file.open("a", encoding="utf-8") as fh:
+                fh.write(json.dumps(rollup_entry))
+                fh.write("\n")
+
+        await asyncio.to_thread(_write)
+
+
+def register_default_subscribers(
+    event_bus: WorkflowEventBus,
+    telemetry: WorkflowEventTelemetry,
+) -> None:
+    """Attach default subscribers to the workflow event bus."""
+    event_bus.register_logging_handler()
+    event_bus.subscribe(
+        event_type=None,
+        handler=telemetry.handle_event,
+        description="workflow.telemetry",
+        max_concurrent=1,
+    )

crackerjack/events/workflow_bus.py

@@ -0,0 +1,346 @@
+"""Workflow event bus built on top of ACB event primitives.
+
+Provides a lightweight in-process event bus that uses ``acb.events`` data
+structures so the rest of the codebase can adopt the forthcoming ACB EventBus
+without waiting on external messaging infrastructure. Subscribers register
+handlers for workflow event types and publishers emit events that are dispatched
+asynchronously.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import threading
+import typing as t
+from dataclasses import dataclass, field
+from enum import Enum
+
+from acb.events import (
+    Event,
+    EventHandlerResult,
+    FunctionalEventHandler,
+    create_event,
+)
+from acb.events._base import EventSubscription
+
+logger = logging.getLogger(__name__)
+
+HandlerCallable = t.Callable[
+    [Event], t.Awaitable[EventHandlerResult] | EventHandlerResult
+]
+
+
+class WorkflowEvent(str, Enum):
+    """Standard workflow events emitted inside Crackerjack."""
+
+    WORKFLOW_STARTED = "workflow.started"
+    WORKFLOW_SESSION_INITIALIZING = "workflow.session.initializing"
+    WORKFLOW_SESSION_READY = "workflow.session.ready"
+    CONFIG_PHASE_STARTED = "workflow.config.started"
+    CONFIG_PHASE_COMPLETED = "workflow.config.completed"
+    WORKFLOW_COMPLETED = "workflow.completed"
+    WORKFLOW_FAILED = "workflow.failed"
+    WORKFLOW_INTERRUPTED = "workflow.interrupted"
+
+    QUALITY_PHASE_STARTED = "workflow.quality.started"
+    QUALITY_PHASE_COMPLETED = "workflow.quality.completed"
+
+    PUBLISH_PHASE_STARTED = "workflow.publish.started"
+    PUBLISH_PHASE_COMPLETED = "workflow.publish.completed"
+
+    COMMIT_PHASE_STARTED = "workflow.commit.started"
+    COMMIT_PHASE_COMPLETED = "workflow.commit.completed"
+
+    HOOK_STRATEGY_STARTED = "hooks.strategy.started"
+    HOOK_STRATEGY_COMPLETED = "hooks.strategy.completed"
+    HOOK_STRATEGY_FAILED = "hooks.strategy.failed"
+
+    HOOK_EXECUTION_STARTED = "hooks.execution.started"
+    HOOK_EXECUTION_COMPLETED = "hooks.execution.completed"
+    HOOK_EXECUTION_FAILED = "hooks.execution.failed"
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return str(self.value)
+
+
+@dataclass
+class WorkflowEventDispatchResult:
+    """Result returned from publishing an event."""
+
+    event: Event
+    results: list[EventHandlerResult] = field(default_factory=list)
+
+
+@dataclass
+class _SubscriptionEntry:
+    """Internal representation of a subscription with concurrency control."""
+
+    subscription: EventSubscription
+    description: str | None = None
+    semaphore: asyncio.Semaphore = field(default_factory=lambda: asyncio.Semaphore(1))
+    max_retries: int = 0
+    retry_backoff: float = 0.5
+
+    def __post_init__(self) -> None:
+        max_concurrent = self.subscription.max_concurrent or 1
+        self.semaphore = asyncio.Semaphore(max_concurrent)
+
+
+class WorkflowEventBus:
+    """In-process event bus compatible with ACB event handlers."""
+
+    def __init__(self) -> None:
+        self._subscriptions: dict[str | None, dict[str, _SubscriptionEntry]] = {}
+        self._lock = threading.RLock()
+        self._default_handlers_registered = False
+
+    def subscribe(
+        self,
+        event_type: WorkflowEvent | str | None,
+        handler: HandlerCallable,
+        *,
+        predicate: t.Callable[[Event], bool] | None = None,
+        max_concurrent: int | None = None,
+        description: str | None = None,
+        max_retries: int = 0,
+        retry_backoff: float = 0.5,
+    ) -> str:
+        """Register a handler for an event type.
+
+        Args:
+            event_type: WorkflowEvent enum value, string, or ``None`` for wildcard.
+            handler: Callable invoked when the event is published.
+            predicate: Optional additional filter predicate.
+            max_concurrent: Maximum concurrent invocations for this handler.
+            description: Optional human readable identifier.
+            max_retries: Number of retry attempts when a handler raises.
+            retry_backoff: Initial backoff delay (seconds) between retries; doubles each attempt.
+
+        Returns:
+            Subscription ID string.
+        """
+        event_type_value = (
+            event_type.value if isinstance(event_type, WorkflowEvent) else event_type
+        )
+
+        event_handler = FunctionalEventHandler(
+            handler,
+            event_type=event_type_value,
+            predicate=predicate,
+        )
+        subscription = EventSubscription(
+            handler=event_handler,
+            event_type=event_type_value,
+            predicate=predicate,
+            max_concurrent=max_concurrent or 1,
+        )
+        entry = _SubscriptionEntry(
+            subscription=subscription,
+            description=description,
+            max_retries=max_retries,
+            retry_backoff=retry_backoff,
+        )
+
+        key = event_type_value
+
+        with self._lock:
+            bucket = self._subscriptions.setdefault(key, {})
+            bucket[str(subscription.subscription_id)] = entry
+
+        logger.debug(
+            "Registered workflow event subscription",
+            extra={
+                "event_type": event_type_value or "*",
+                "subscription_id": str(subscription.subscription_id),
+                "description": description,
+                "max_concurrent": max_concurrent or 1,
+                "max_retries": max_retries,
+                "retry_backoff": retry_backoff,
+            },
+        )
+
+        return str(subscription.subscription_id)
+
+    def unsubscribe(self, subscription_id: str) -> bool:
+        """Remove a subscription by ID."""
+        with self._lock:
+            for bucket in self._subscriptions.values():
+                if subscription_id in bucket:
+                    del bucket[subscription_id]
+                    logger.debug(
+                        "Removed workflow event subscription",
+                        extra={"subscription_id": subscription_id},
+                    )
+                    return True
+        return False
+
+    def list_subscriptions(self) -> list[dict[str, t.Any]]:
+        """Return summary information for registered subscriptions."""
+        data: list[dict[str, t.Any]] = []
+        with self._lock:
+            for event_type, bucket in self._subscriptions.items():
+                for subscription_id, entry in bucket.items():
+                    data.append(
+                        {
+                            "subscription_id": subscription_id,
+                            "event_type": event_type or "*",
+                            "description": entry.description,
+                            "max_concurrent": entry.subscription.max_concurrent,
+                        }
+                    )
+        return data
+
+    async def publish(
+        self,
+        event_type: WorkflowEvent | str,
+        payload: dict[str, t.Any] | None = None,
+        *,
+        source: str = "crackerjack.workflow",
+        **metadata: t.Any,
+    ) -> WorkflowEventDispatchResult:
+        """Publish an event to subscribed handlers."""
+        event_type_value = (
+            event_type.value if isinstance(event_type, WorkflowEvent) else event_type
+        )
+        payload = payload or {}
+        event = create_event(event_type_value, source, payload, **metadata)
+
+        entries = self._collect_subscriptions(event)
+        if not entries:
+            logger.debug(
+                "Workflow event published with no subscribers",
+                extra={"event_type": event_type_value},
+            )
+            return WorkflowEventDispatchResult(event=event, results=[])
+
+        tasks = [self._invoke_subscription(entry, event) for entry in entries]
+        raw_results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        results: list[EventHandlerResult] = []
+        for entry, result in zip(entries, raw_results, strict=False):
+            if isinstance(result, EventHandlerResult):
+                results.append(result)
+                continue
+
+            if isinstance(result, Exception):
+                logger.exception(
+                    "Workflow event handler raised an exception",
+                    extra={
+                        "event_type": event_type_value,
+                        "subscription_id": entry.subscription.subscription_id,
+                        "description": entry.description,
+                    },
+                    exc_info=result,
+                )
+                results.append(
+                    EventHandlerResult(
+                        success=False,
+                        error_message=str(result),
+                        metadata={
+                            "subscription_id": str(entry.subscription.subscription_id)
+                        },
+                    )
+                )
+                continue
+
+            # Allow handlers to return truthy values instead of EventHandlerResult
+            success = True if result is None else bool(result)
+            results.append(
+                EventHandlerResult(
+                    success=success,
+                    metadata={
+                        "subscription_id": str(entry.subscription.subscription_id)
+                    },
+                )
+            )
+
+        return WorkflowEventDispatchResult(event=event, results=results)
+
+    def register_logging_handler(self) -> None:
+        """Install a default debug logging handler (idempotent)."""
+        if self._default_handlers_registered:
+            return
+
+        async def _log_event(event: Event) -> EventHandlerResult:
+            logger.debug(
+                "Workflow event dispatched",
+                extra={
+                    "event_type": event.metadata.event_type,
+                    "source": event.metadata.source,
+                    "payload": event.payload,
+                },
+            )
+            return EventHandlerResult(success=True)
+
+        self.subscribe(
+            event_type=None,
+            handler=_log_event,
+            description="workflow.logging",
+        )
+        self._default_handlers_registered = True
+
+    def _collect_subscriptions(self, event: Event) -> list[_SubscriptionEntry]:
+        with self._lock:
+            specific = list(
+                self._subscriptions.get(event.metadata.event_type, {}).values()
+            )
+            wildcard = list(self._subscriptions.get(None, {}).values())
+        return specific + wildcard
+
+    async def _invoke_subscription(
+        self,
+        entry: _SubscriptionEntry,
+        event: Event,
+    ) -> EventHandlerResult:
+        handler = entry.subscription.handler
+        if not handler.can_handle(event):
+            return EventHandlerResult(
+                success=True,
+                metadata={
+                    "subscription_id": str(entry.subscription.subscription_id),
+                    "skipped": True,
+                },
+            )
+
+        async with entry.semaphore:
+            attempt = 0
+            delay = max(entry.retry_backoff, 0.0)
+            while True:
+                try:
+                    return await handler.handle(event)
+                except Exception as exc:
+                    attempt += 1
+                    if attempt > entry.max_retries:
+                        logger.exception(
+                            "Workflow event handler failed after retries",
+                            extra={
+                                "subscription_id": str(
+                                    entry.subscription.subscription_id
+                                ),
+                                "description": entry.description,
+                                "event_type": event.metadata.event_type,
+                                "attempts": attempt,
+                            },
+                            exc_info=exc,
+                        )
+                        raise
+
+                    logger.warning(
+                        "Workflow event handler raised; retrying",
+                        extra={
+                            "subscription_id": str(entry.subscription.subscription_id),
+                            "description": entry.description,
+                            "event_type": event.metadata.event_type,
+                            "attempt": attempt,
+                            "max_retries": entry.max_retries,
+                            "retry_delay": delay,
+                        },
+                        exc_info=exc,
+                    )
+                    if delay > 0:
+                        await asyncio.sleep(delay)
+                        delay *= 2
+
+
+__all__ = ["WorkflowEventBus", "WorkflowEvent", "WorkflowEventDispatchResult"]