python-corekit 0.1.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

corekit/log_monitor/service.py

@@ -11,6 +11,7 @@ per container so a crash loop cannot become a restart loop.
 """
 
 import re
+import shlex
 import signal
 import subprocess
 import threading
@@ -51,7 +52,7 @@ class LogMonitor(Watchdog):
         config_path: str | None = None,
         config: LogMonitorConfig | None = None,
         notification_service: BaseNotificationService | None = None,
-        enforce_label: bool = False,
+        enforce_label: bool = True,
         max_workers: int | None = None,
         docker_host: str | None = None,
         handle_signals: bool = False,
@@ -61,6 +62,7 @@ class LogMonitor(Watchdog):
         :param config: an already-built configuration, instead of a path.
         :param notification_service: where notifications go; logs by default.
         :param enforce_label: only act on containers carrying the managed label.
+            On by default, matching Watchdog.
         :param handle_signals: install SIGTERM and SIGINT handlers. Off by
             default because installing them is process-global and only the
             program's entry point should decide that; ``run()`` turns it on.
@@ -117,12 +119,31 @@ class LogMonitor(Watchdog):
         }
         return mapping.get(severity, NotificationType.INFO)
 
-    def _send_notification(self, message: str, severity: Severity) -> None:
-        """Send notification using the notification service"""
+    def _send_notification(
+        self,
+        message: str,
+        severity: Severity,
+        container_name: str,
+        throttle: float = 0,
+    ) -> bool:
+        """
+        Send one notification for a container, honoring its throttle.
+
+        This is the only delivery path. A YAML notify action and a rule's
+        ``send_notification`` flag both come through here, so the throttle
+        cannot be recorded in one place and ignored in another.
+        """
+        last_notify = self.last_notify_times.get(container_name, 0.0)
+        if throttle and time.time() - last_notify < throttle:
+            self.debug(f"Notification throttled for {container_name}")
+            return False
+
+        self.last_notify_times[container_name] = time.time()
         notification = Notification(
             message=message, type=self._severity_to_notification_type(severity), meta={"source": "LogMonitor"}
         )
         self._notification_service.notify(notification)
+        return True
 
     def check_rate_limit(self, action_type: ActionType) -> bool:
         """Check if action is within rate limits"""
@@ -145,14 +166,17 @@ class LogMonitor(Watchdog):
         message = action.message.format(container=container_name, text=matched_text)
         self.info(f"[LogAction] {message}")
 
-    def _execute_notify_action(self, action: NotifyAction, container_name: str) -> None:
-        """Execute notify action - check throttle only (actual notification sent separately)"""
-        # Check throttle
-        last_notify = self.last_notify_times.get(container_name, 0.0)
-        if time.time() - last_notify < action.throttle:
-            self.debug(f"Notification throttled for {container_name}")
-            return
-        self.last_notify_times[container_name] = time.time()
+    def _execute_notify_action(
+        self,
+        action: NotifyAction,
+        container_name: str,
+        matched_text: str,
+        severity: Severity,
+        rule_name: str,
+    ) -> None:
+        """Deliver a notification, applying this action's throttle."""
+        message = f"*{rule_name}* in `{container_name}`\n```{matched_text.strip()}```"
+        self._send_notification(message, severity, container_name, throttle=action.throttle)
 
     def _execute_restart_action(self, action: RestartContainerAction, container_name: str) -> None:
         """Execute restart action - delegate to Watchdog parent"""
@@ -172,42 +196,51 @@ class LogMonitor(Watchdog):
             self.info(f"Waiting {action.delay}s before restarting {container_name}")
             time.sleep(action.delay)
 
-        try:
-            # Delegate to parent Watchdog method
-            container = self._client.containers.get(container_name)
-            container.restart()
+        if self.restart_container_by_name(container_name):
             self.restart_counts[container_name].append(time.time())
-            self.info(f"Restarted container: {container_name}")
-        except NotFound:
-            self.error(f"Container '{container_name}' not found")
-        except APIError as e:
-            self.error(f"Failed to restart {container_name}: {e}")
 
     def _execute_pause_action(self, action: PauseContainerAction, container_name: str) -> None:
         """Execute pause action - delegate to Watchdog parent"""
         self.pause_container_by_name(container_name)
 
     def _execute_command_action(self, action: ExecuteCommandAction, container_name: str) -> None:
-        """Execute shell command action"""
-        command = action.command.format(container=container_name)
+        """
+        Run a command as an argument list. The config string is not a shell.
+        """
+        try:
+            argv = [part.format(container=container_name) for part in shlex.split(action.command)]
+        except ValueError as exc:
+            self.error(f"Invalid command for {container_name}: {exc}")
+            return
+        if not argv:
+            self.error(f"Empty command for {container_name}")
+            return
         try:
             result = subprocess.run(
-                command,
-                shell=True,
+                argv,
+                shell=False,
                 capture_output=True,
                 text=True,
-                timeout=30,  # 30 second timeout for safety
+                timeout=30,
             )
+            rendered = " ".join(argv)
             if result.returncode == 0:
-                self.info(f"Executed: {command}\nOutput: {result.stdout}")
+                self.info(f"Executed: {rendered}\nOutput: {result.stdout}")
             else:
-                self.error(f"Command failed: {command}\nError: {result.stderr}")
+                self.error(f"Command failed: {rendered}\nError: {result.stderr}")
         except subprocess.TimeoutExpired:
-            self.error(f"Command timed out: {command}")
+            self.error(f"Command timed out: {action.command}")
         except Exception as e:
             self.error(f"Failed to execute command: {e}")
 
-    def execute_action(self, action: Action, container_name: str, matched_text: str = "") -> None:
+    def execute_action(
+        self,
+        action: Action,
+        container_name: str,
+        matched_text: str = "",
+        severity: Severity = Severity.INFO,
+        rule_name: str = "",
+    ) -> None:
         """Execute configured actions by delegating to specific action handlers"""
         action_type = action.type
 
@@ -221,7 +254,7 @@ class LogMonitor(Watchdog):
         if action_type is ActionType.LOG:
             self._execute_log_action(action, container_name, matched_text)
         elif action_type is ActionType.NOTIFY:
-            self._execute_notify_action(action, container_name)
+            self._execute_notify_action(action, container_name, matched_text, severity, rule_name)
         elif action_type is ActionType.RESTART_CONTAINER:
             self._execute_restart_action(action, container_name)
         elif action_type is ActionType.PAUSE_CONTAINER:
@@ -246,14 +279,20 @@ class LogMonitor(Watchdog):
                 else:
                     self.info(log_message)
 
-                # Execute actions
-                for action in rule.actions:
-                    self.execute_action(action, container_name, line)
-
-                # Send notification if configured
-                if rule.send_notification:
-                    message = f"*{rule.name}* in `{container_name}`\n```{line.strip()}```"
-                    self._send_notification(message, rule.severity)
+                # A notify flag is the same delivery path as a notify action.
+                # Do not send beside it: that path used to ignore the throttle.
+                actions = list(rule.actions)
+                if rule.send_notification and not any(action.type is ActionType.NOTIFY for action in actions):
+                    actions.append(NotifyAction())
+
+                for action in actions:
+                    self.execute_action(
+                        action,
+                        container_name,
+                        line,
+                        severity=rule.severity,
+                        rule_name=rule.name,
+                    )
 
     # FIXME: does this actually make more sense being part of watchdog?
     def monitor_container(self, container_name: str, rules: list[Rule]) -> None:

corekit/notifications/base.py

@@ -8,13 +8,15 @@ Subclass ``BaseNotificationService`` and implement ``_send``::
         Sends notifications by email.
         '''
 
-        def _send(self, message: str) -> None:
-            smtp.send(message)
+        def _send(self, notification: Notification) -> None:
+            smtp.send(notification.message, extra=notification.meta)
 
     service.notify(Notification(message="disk full", type=NotificationType.ERROR))
 
-Override ``_send``, not ``send``: ``notify`` formats the message and calls
-``_send``, so an override with any other name silently does nothing.
+Override ``_send``, not ``notify``, if you only want to replace the transport.
+``notify`` hands the whole ``Notification`` to ``_send``, including ``meta``.
+Events are a different job: they fan a payload out over Redis, they do not
+alert a person.
 """
 
 from corekit.notifications.models import Notification
@@ -36,16 +38,22 @@ class BaseNotificationService(Loggable):
         """
         Render a notification as the text a transport will send.
         """
-        return f"[{notification.type} Notification]: {notification.message}"
+        text = f"[{notification.type} Notification]: {notification.message}"
+        if notification.meta:
+            return f"{text} {notification.meta}"
+        return text
 
-    def _send(self, message: str) -> None:
+    def _send(self, notification: Notification) -> None:
         """
-        Deliver formatted text. Override this in a subclass.
+        Deliver a notification. Override this in a subclass.
+
+        The argument is the notification, not a preformatted string, so a
+        transport can use ``message``, ``type``, and ``meta``.
         """
-        self.warning(message)
+        self.warning(self._format(notification))
 
     def notify(self, notification: Notification) -> None:
         """
-        Format a notification and deliver it.
+        Hand a notification to the transport, including its meta.
         """
-        self._send(self._format(notification))
+        self._send(notification)

corekit/observability/__init__.py

@@ -2,8 +2,9 @@
 Logging and performance measurement.
 
 ``Loggable`` gives a class a logger named after itself; ``Benchmarkable`` adds
-split timing on top. They live together because they are the same concern --
-knowing what a running system is doing.
+split timing on top. ``BaseRequestContext`` carries per-request metadata so a
+log line can say which request it belongs to. They live together because they
+are the same concern -- knowing what a running system is doing.
 
     class Importer(Benchmarkable):
         def run(self) -> None:
@@ -15,7 +16,15 @@ knowing what a running system is doing.
 
 from corekit.observability.benchmarkable import Benchmarkable
 from corekit.observability.loggable import Loggable
+from corekit.observability.request_context import BaseRequestContext, RequestContextFilter
 from corekit.observability.timing.split import Split
 from corekit.observability.timing.timer import Timer
 
-__all__ = ["Benchmarkable", "Loggable", "Split", "Timer"]
+__all__ = [
+    "BaseRequestContext",
+    "Benchmarkable",
+    "Loggable",
+    "RequestContextFilter",
+    "Split",
+    "Timer",
+]

corekit/observability/benchmarkable.py

@@ -1,12 +1,30 @@
+from typing import Any
+
 from corekit.observability.loggable import Loggable
+from corekit.observability.timing.split import Split
 from corekit.observability.timing.timer import Timer
 
 
 class Benchmarkable(Loggable):
-    def __init__(self) -> None:
-        super().__init__()
+    """
+    ``Loggable`` plus split timing.
+
+    ``__init__`` forwards ``*args``/``**kwargs`` the same way ``Loggable``
+    does, so a service can sit in a cooperative ``super()`` chain without
+    this class swallowing the arguments the next base expects.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
         self._timing = Timer()
 
-    def timing(self, split_name: str | None = None) -> None:
-        split_message = str(self._timing.split(split_name=split_name))
-        self.info(split_message)
+    def timing(self, split_name: str | None = None) -> Split:
+        """
+        Log the time since the last split and return it.
+
+        The log line is unchanged. The return value is for a caller that
+        wants the numbers without parsing that line.
+        """
+        split = self._timing.split(split_name=split_name)
+        self.info(str(split))
+        return split

corekit/observability/loggable.py

@@ -1,6 +1,8 @@
 import logging
 from typing import Any
 
+from corekit.observability.request_context import RequestContextFilter
+
 
 class Loggable:
     """
@@ -8,10 +10,16 @@ class Loggable:
 
     Accepts and ignores ``*args``/``**kwargs`` so it can sit anywhere in a
     cooperative ``super().__init__()`` chain.
+
+    The logger name is the class name, not ``module.Class``. Consuming
+    projects filter on that name; renaming it is a log-config change, not a
+    local cleanup. Request context is attached as record attributes instead,
+    so a formatter can include it without renaming the logger.
     """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         self.logger = logging.getLogger(self.__class__.__name__)
+        _attach_request_context(self.logger)
 
     def debug(self, message: str, **kwargs: Any) -> None:
         self.logger.debug(message, **kwargs)
@@ -27,3 +35,16 @@ class Loggable:
 
     def exception(self, message: str, **kwargs: Any) -> None:
         self.logger.exception(message, **kwargs)
+
+
+def _attach_request_context(logger: logging.Logger) -> None:
+    """
+    Attach the request-context filter once per logger name.
+
+    Loggers are process-global and keyed by name, so every instance of a
+    class shares one. Adding the filter again would stamp the same fields
+    twice.
+    """
+    if any(isinstance(existing, RequestContextFilter) for existing in logger.filters):
+        return
+    logger.addFilter(RequestContextFilter())

corekit/observability/request_context.py

@@ -0,0 +1,188 @@
+"""
+Request-scoped metadata.
+
+Small values that belong to one request -- which surface initiated it, a request
+id, a correlation id -- carried in a ``ContextVar`` so they follow the work
+rather than being threaded through every call signature.
+
+A ``ContextVar`` rather than ``threading.local``: coroutines that ``await``
+may resume on a different thread, and several tasks may share one, so
+thread-local state either leaks between requests or vanishes mid-request.
+Context variables follow the logical task instead.
+
+This is not for connections or anything that must be closed. It holds
+immutable-per-request facts; see ``ThreadLocalRegistry`` for resources with a
+lifecycle.
+
+Subclass it with the fields an application actually wants::
+
+    class RequestContext(BaseRequestContext):
+        surface: Surface
+        request_id: str | None = None
+
+    with RequestContext(surface=Surface.API).active():
+        ...                                  # RequestContext.current() sees it
+
+Each subclass gets its own storage, so one application's context cannot be read
+through another's class.
+"""
+
+import logging
+from contextlib import contextmanager
+from contextvars import ContextVar, Token
+from typing import Any, ClassVar, Iterator, Self
+
+from pydantic import BaseModel
+
+__all__ = ["BaseRequestContext", "RequestContextFilter"]
+
+
+class BaseRequestContext(BaseModel):
+    """
+    Base for request-scoped metadata carried in a ``ContextVar``.
+
+    Prefer ``active()`` or ``active_if_absent()`` over the manual
+    ``activate``/``deactivate`` pair: an early return or a raised exception
+    between them leaks the context into whatever runs next on that task.
+    """
+
+    #: Subclasses that own storage. The logging filter walks this rather than
+    #: guessing which application's context class is in use.
+    _known_subclasses: ClassVar[list[type["BaseRequestContext"]]] = []
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        """
+        Give every subclass its own ContextVar.
+        """
+        super().__init_subclass__(**kwargs)
+        cls._context_var = ContextVar(f"{cls.__module__}.{cls.__name__}", default=None)
+        if cls not in BaseRequestContext._known_subclasses:
+            BaseRequestContext._known_subclasses.append(cls)
+
+    @classmethod
+    def _var(cls) -> ContextVar[Any]:
+        """
+        This class's context variable.
+
+        Raises:
+            TypeError: If called on ``BaseRequestContext`` itself, which holds
+                no storage -- subclass it with the fields you need.
+        """
+        # Set by __init_subclass__, so each subclass reads and writes its own
+        # variable rather than sharing one with its siblings.
+        var = cls.__dict__.get("_context_var") or getattr(cls, "_context_var", None)
+        if not isinstance(var, ContextVar):
+            raise TypeError(
+                f"{cls.__name__} has no context storage. Subclass BaseRequestContext "
+                f"with the fields your application needs rather than using it directly."
+            )
+        return var
+
+    @classmethod
+    def current(cls) -> Self | None:
+        """
+        The active context, or ``None`` if nothing is active.
+        """
+        return cls._var().get()
+
+    def activate(self) -> Token:
+        """
+        Make this the active context, returning a token for ``deactivate``.
+
+        Prefer ``active()``, which cannot leak.
+        """
+        return self._var().set(self)
+
+    def activate_if_absent(self) -> Token | None:
+        """
+        Activate only if nothing is active yet, else return ``None``.
+
+        Lets an inner call establish a default without overriding the surface an
+        outer caller already set. The result, ``None`` included, goes to
+        ``deactivate``.
+        """
+        if self._var().get() is not None:
+            return None
+        return self._var().set(self)
+
+    @classmethod
+    def deactivate(cls, token: Token | None) -> None:
+        """
+        Restore whatever was active before. ``None`` is a no-op.
+        """
+        if token is not None:
+            cls._var().reset(token)
+
+    @contextmanager
+    def active(self) -> Iterator[Self]:
+        """
+        Activate for the duration of the block, restoring on the way out.
+
+        Restores even when the block raises, which the manual pair does not do
+        unless every caller remembers the ``finally``.
+        """
+        token = self.activate()
+        try:
+            yield self
+        finally:
+            type(self).deactivate(token)
+
+    @contextmanager
+    def active_if_absent(self) -> Iterator[Self | None]:
+        """
+        Activate for the block only if nothing is active yet.
+
+        Yields the context that ends up active -- this one, or the one that was
+        already there -- so a caller can read it either way.
+        """
+        token = self.activate_if_absent()
+        try:
+            yield type(self).current()
+        finally:
+            type(self).deactivate(token)
+
+
+class RequestContextFilter(logging.Filter):
+    """
+    Stamp the active request context onto each log record.
+
+    The message is left alone, so existing log lines and anything that
+    matches them stay stable. Fields land on the record for a formatter
+    that opts in: ``%(request_context)s`` is a compact summary, and
+    ``request_context_fields`` is the dumped model. Both are always set,
+    to an empty string and an empty dict when nothing is active, so a
+    format string that names them does not raise.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        fields: dict[str, Any] = {}
+        parts: list[str] = []
+        for cls in BaseRequestContext._known_subclasses:
+            current = cls.current()
+            if current is None:
+                continue
+            dumped = _dump_context(current)
+            if not dumped:
+                continue
+            fields[cls.__name__] = dumped
+            rendered = ", ".join(f"{key}={value}" for key, value in dumped.items())
+            parts.append(f"{cls.__name__}({rendered})")
+
+        record.request_context = " ".join(parts)
+        record.request_context_fields = fields
+        return True
+
+
+def _dump_context(context: BaseRequestContext) -> dict[str, Any]:
+    """
+    JSON-safe fields, or stringified values if a field will not dump.
+    """
+    try:
+        dumped = context.model_dump(mode="json")
+    except Exception:
+        dumped = {key: getattr(context, key, None) for key in type(context).model_fields}
+    return {key: value if _is_log_safe(value) else str(value) for key, value in dumped.items()}
+
+
+def _is_log_safe(value: Any) -> bool:
+    return value is None or isinstance(value, (str, int, float, bool))

corekit/observability/timing/timer.py

@@ -6,7 +6,9 @@ from corekit.observability.timing.split import Split
 
 class Timer:
     def __init__(self, precision: int = DEFAULT_PRECISION) -> None:
-        _time = time.time()
+        # perf_counter is monotonic. time.time() can step backwards, which
+        # makes a split look negative for no reason the caller can act on.
+        _time = time.perf_counter()
         self.start = _time
         self.latest = _time
         self.num = 0
@@ -17,7 +19,7 @@ class Timer:
         return round(value, self.precision)
 
     def split(self, split_name: str | None = None) -> Split:
-        _time = time.time()
+        _time = time.perf_counter()
         self.num += 1
         split = Split(
             num=self.num,

corekit/registry/__init__.py

@@ -1,12 +1,17 @@
 """
-Key-normalizing registry.
+Registries.
 
-``SmartRegistry`` folds case, trims whitespace and treats spaces and underscores
-as hyphens, so ``"AI Conversation Handler"``, ``"ai_conversation_handler"`` and
-``"ai-conversation-handler"`` all address the same entry. That forgiveness
-matters wherever a human -- or a language model -- supplies the key.
+``SmartRegistry`` is keyed and forgiving: it folds case, trims whitespace and
+treats spaces and underscores as hyphens, so ``"AI Conversation Handler"``,
+``"ai_conversation_handler"`` and ``"ai-conversation-handler"`` all address the
+same entry. That matters wherever a human -- or a language model -- supplies
+the key.
+
+``OrderedRegistry`` is unkeyed: it preserves registration order and allows
+duplicates. Reach for it when position is what matters and no name is needed.
 """
 
-from corekit.registry.registry import SmartRegistry
+from corekit.registry.ordered import OrderedRegistry
+from corekit.registry.registry import SmartRegistry, normalize_key
 
-__all__ = ["SmartRegistry"]
+__all__ = ["OrderedRegistry", "SmartRegistry", "normalize_key"]

corekit/registry/ordered.py

@@ -0,0 +1,86 @@
+"""
+Insertion-ordered registry.
+
+Where ``SmartRegistry`` is a dict keyed by a forgiving name, ``OrderedRegistry``
+is a list: it keeps what was registered, in the order it was registered, and
+lets callers filter it. Use it when order is the point and names are not --
+mount order, execution order, pipeline stages -- and when two entries may
+legitimately share a name.
+"""
+
+from typing import Callable, Generic, Iterator, TypeVar
+
+__all__ = ["OrderedRegistry"]
+
+T = TypeVar("T")
+
+
+class OrderedRegistry(Generic[T]):
+    """
+    Everything registered in this process, in construction order.
+
+    Deliberately not keyed. A keyed registry silently evicts a collision, which
+    for order-sensitive collections means an entry vanishing with no error --
+    so duplicates are kept, and callers select with ``where`` instead.
+    """
+
+    __slots__ = ("_entries",)
+
+    def __init__(self) -> None:
+        """
+        Initialize an empty registry.
+        """
+        self._entries: list[T] = []
+
+    def register(self, entry: T) -> T:
+        """
+        Append an entry, returning it so this can be used inline.
+        """
+        self._entries.append(entry)
+        return entry
+
+    def where(self, predicate: Callable[[T], bool]) -> list[T]:
+        """
+        Return the entries matching ``predicate``, in registration order.
+        """
+        return [entry for entry in self._entries if predicate(entry)]
+
+    def clear(self) -> None:
+        """
+        Forget every entry. For tests that build more than one of whatever this holds.
+        """
+        self._entries.clear()
+
+    @property
+    def entries(self) -> list[T]:
+        """
+        A copy of the entries, in registration order.
+
+        A copy, so a caller iterating the result cannot be tripped up by
+        something registering mid-loop.
+        """
+        return list(self._entries)
+
+    def __len__(self) -> int:
+        """
+        Return the number of registered entries.
+        """
+        return len(self._entries)
+
+    def __iter__(self) -> Iterator[T]:
+        """
+        Iterate the entries in registration order.
+        """
+        return iter(self._entries)
+
+    def __contains__(self, entry: object) -> bool:
+        """
+        Check whether an entry has been registered, by identity or equality.
+        """
+        return entry in self._entries
+
+    def __repr__(self) -> str:
+        """
+        Return a formal representation of the registry.
+        """
+        return f"{type(self).__name__}({self._entries!r})"