taskferry 0.2.0__py3-none-any.whl

taskferry/hooks.py

@@ -0,0 +1,238 @@
+"""Observability hooks — composable, explicit, never global.
+
+Taskferry deliberately has no global signal bus. A bus makes it impossible to
+know which listeners will run, listeners registered by a library leak into every
+consumer, and tests have to remember to tear down. Instead a :class:`Hook` is an
+ordinary object you pass to the runtime::
+
+    runtime = Taskferry(config=config, hooks=[LoggingHook(), MetricsHook()])
+
+```mermaid
+sequenceDiagram
+    participant App
+    participant TP as Taskferry
+    participant H as Hooks
+    participant B as Backend
+    participant E as Engine
+
+    App->>TP: submit(spec)
+    TP->>H: before_submit(spec, backend)
+    TP->>B: submit(spec)
+    B->>E: enqueue
+    E-->>B: execution
+    B-->>TP: Execution
+    TP->>H: after_submit(spec, execution)
+    TP-->>App: ExecutionHandle
+```
+
+Every method has a no-op default, so a hook implements only what it cares about.
+A hook that raises is *never* allowed to break the submission it observes — the
+chain catches, reports through :func:`hook_error_handler`, and carries on. A
+telemetry outage must not take the application down with it.
+
+Ordering, precisely
+-------------------
+
+Hooks come in two families, and the guarantee is *per family*:
+
+* **submit-side** — ``before_submit`` always precedes ``after_submit``;
+* **execute-side** — ``before_execute`` precedes ``on_success``/``on_failure``,
+  with ``on_retry`` in between for each re-attempt.
+
+Across the two families there is **no ordering guarantee** whenever execution is
+concurrent. A thread-pool worker can start before ``after_submit`` returns; a
+Procrastinate worker runs in a different process, where ordering is not even a
+meaningful question. The one exception is inline execution, where the work
+happens inside ``submit`` and every execute-side hook therefore fires before
+``after_submit``. A hook that needs to distinguish "submitted" from "finished"
+should read :attr:`~taskferry.execution.Execution.state`, not infer it from
+arrival order.
+
+Trace context propagation is separate: it rides on
+:class:`~taskferry.core.correlation.Correlation`, which adapters copy into engine
+metadata. Hooks observe; correlation travels.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable, Iterable, Sequence
+from typing import Protocol, runtime_checkable
+
+from .execution import Execution, ExecutionResult
+from .specs import ExecutionSpec
+
+logger = logging.getLogger("taskferry.hooks")
+
+HookErrorHandler = Callable[[str, "Hook", BaseException], None]
+"""Called when a hook method raises: ``(method_name, hook, exception)``."""
+
+
+def _log_hook_error(method: str, hook: Hook, exc: BaseException) -> None:
+    logger.warning("taskferry hook %r failed in %s(): %s", type(hook).__name__, method, exc)
+
+
+hook_error_handler: HookErrorHandler = _log_hook_error
+"""Module-level policy for hook failures. Replace to re-raise in tests."""
+
+
+@runtime_checkable
+class Hook(Protocol):
+    """Observe the lifecycle of executions. Every method is optional."""
+
+    def before_submit(self, spec: ExecutionSpec, backend: str) -> None: ...
+
+    def after_submit(self, spec: ExecutionSpec, execution: Execution) -> None: ...
+
+    def on_submit_error(self, spec: ExecutionSpec, backend: str, exc: BaseException) -> None: ...
+
+    def before_execute(self, execution: Execution) -> None: ...
+
+    def after_execute(self, execution: Execution, result: ExecutionResult) -> None: ...
+
+    def on_success(self, execution: Execution, result: ExecutionResult) -> None: ...
+
+    def on_failure(self, execution: Execution, exc: BaseException) -> None: ...
+
+    def on_cancel(self, execution: Execution) -> None: ...
+
+    def on_retry(self, execution: Execution, attempt: int, exc: BaseException) -> None: ...
+
+
+class BaseHook:
+    """No-op implementation of every :class:`Hook` method. Subclass and override."""
+
+    def before_submit(self, spec: ExecutionSpec, backend: str) -> None:
+        """Called before a spec is handed to ``backend``."""
+
+    def after_submit(self, spec: ExecutionSpec, execution: Execution) -> None:
+        """Called once the backend has accepted the spec."""
+
+    def on_submit_error(self, spec: ExecutionSpec, backend: str, exc: BaseException) -> None:
+        """Called when submission itself failed. Nothing was enqueued."""
+
+    def before_execute(self, execution: Execution) -> None:
+        """Called by in-process backends immediately before running the work."""
+
+    def after_execute(self, execution: Execution, result: ExecutionResult) -> None:
+        """Called by in-process backends once the work finished, success or not."""
+
+    def on_success(self, execution: Execution, result: ExecutionResult) -> None:
+        """Called when an execution reached ``SUCCEEDED``."""
+
+    def on_failure(self, execution: Execution, exc: BaseException) -> None:
+        """Called when an execution failed with ``exc``."""
+
+    def on_cancel(self, execution: Execution) -> None:
+        """Called when an execution was cancelled through Taskferry."""
+
+    def on_retry(self, execution: Execution, attempt: int, exc: BaseException) -> None:
+        """Called by in-process backends before re-attempting after ``exc``."""
+
+
+class HookChain:
+    """Fans one lifecycle event out to several hooks, in registration order.
+
+    Immutable and safe to share across threads. A failing hook is reported and
+    skipped; the remaining hooks still run.
+    """
+
+    __slots__ = ("_hooks",)
+
+    def __init__(self, hooks: Iterable[Hook] = ()) -> None:
+        self._hooks: tuple[Hook, ...] = tuple(hooks)
+
+    @property
+    def hooks(self) -> Sequence[Hook]:
+        return self._hooks
+
+    def __len__(self) -> int:
+        return len(self._hooks)
+
+    def __bool__(self) -> bool:
+        return bool(self._hooks)
+
+    def __repr__(self) -> str:
+        names = ", ".join(type(h).__name__ for h in self._hooks)
+        return f"HookChain({names})"
+
+    def with_hook(self, hook: Hook) -> HookChain:
+        """Return a new chain with ``hook`` appended. The original is unchanged."""
+        return HookChain((*self._hooks, hook))
+
+    def _dispatch(self, method: str, *args: object) -> None:
+        for hook in self._hooks:
+            handler = getattr(hook, method, None)
+            if handler is None:
+                continue
+            try:
+                handler(*args)
+            except Exception as exc:  # never let telemetry break the workload
+                hook_error_handler(method, hook, exc)
+
+    def before_submit(self, spec: ExecutionSpec, backend: str) -> None:
+        self._dispatch("before_submit", spec, backend)
+
+    def after_submit(self, spec: ExecutionSpec, execution: Execution) -> None:
+        self._dispatch("after_submit", spec, execution)
+
+    def on_submit_error(self, spec: ExecutionSpec, backend: str, exc: BaseException) -> None:
+        self._dispatch("on_submit_error", spec, backend, exc)
+
+    def before_execute(self, execution: Execution) -> None:
+        self._dispatch("before_execute", execution)
+
+    def after_execute(self, execution: Execution, result: ExecutionResult) -> None:
+        self._dispatch("after_execute", execution, result)
+
+    def on_success(self, execution: Execution, result: ExecutionResult) -> None:
+        self._dispatch("on_success", execution, result)
+
+    def on_failure(self, execution: Execution, exc: BaseException) -> None:
+        self._dispatch("on_failure", execution, exc)
+
+    def on_cancel(self, execution: Execution) -> None:
+        self._dispatch("on_cancel", execution)
+
+    def on_retry(self, execution: Execution, attempt: int, exc: BaseException) -> None:
+        self._dispatch("on_retry", execution, attempt, exc)
+
+
+class LoggingHook(BaseHook):
+    """Logs every lifecycle event. Useful on its own and as a worked example."""
+
+    def __init__(self, logger_name: str = "taskferry", level: int = logging.INFO) -> None:
+        self._log = logging.getLogger(logger_name)
+        self._level = level
+
+    def after_submit(self, spec: ExecutionSpec, execution: Execution) -> None:
+        self._log.log(
+            self._level,
+            "submitted %s %s to %s (%s)",
+            execution.kind.value,
+            execution.name,
+            execution.backend,
+            execution.id,
+        )
+
+    def on_submit_error(self, spec: ExecutionSpec, backend: str, exc: BaseException) -> None:
+        self._log.warning("submission of %s to %s failed: %s", spec.name, backend, exc)
+
+    def on_failure(self, execution: Execution, exc: BaseException) -> None:
+        self._log.warning("%s %s failed: %s", execution.kind.value, execution.id, exc)
+
+    def on_retry(self, execution: Execution, attempt: int, exc: BaseException) -> None:
+        self._log.info("retrying %s (attempt %d) after %s", execution.id, attempt, exc)
+
+    def on_cancel(self, execution: Execution) -> None:
+        self._log.info("cancelled %s %s", execution.kind.value, execution.id)
+
+
+__all__ = [
+    "BaseHook",
+    "Hook",
+    "HookChain",
+    "HookErrorHandler",
+    "LoggingHook",
+    "hook_error_handler",
+]

taskferry/plugins.py

@@ -0,0 +1,183 @@
+"""Backend discovery — entry points, not import-time magic.
+
+An adapter distribution advertises its backends in its own ``pyproject.toml``::
+
+    [project.entry-points."taskferry.backends"]
+    procrastinate = "taskferry_procrastinate:make_backend"
+
+which lets a deployment write ``{"factory": "procrastinate", ...}`` in config and
+have it work the moment the package is installed — without `taskferry` importing,
+knowing about, or depending on that package.
+
+```mermaid
+flowchart BT
+    PRO["taskferry-procrastinate<br/>entry point: procrastinate"]
+    CR["taskferry-cloudrun<br/>entry point: cloudrun"]
+    CT["taskferry-cloudtasks<br/>entry point: cloudtasks"]
+    EP["taskferry.backends<br/>entry-point group"]
+    TP["taskferry<br/>load_backend()"]
+
+    PRO --> EP
+    CR --> EP
+    CT --> EP
+    EP --> TP
+```
+
+Two things this deliberately does *not* do. It does not scan installed packages
+looking for anything importable, and it does not import every registered plugin
+at startup: an entry point is only loaded when a backend that names it is
+actually built. A process that enqueues tasks but never runs jobs never imports
+the Google SDK.
+"""
+
+from __future__ import annotations
+
+import importlib
+from collections.abc import Callable, Mapping
+from functools import cache
+from typing import Any, cast
+
+from .config import DEFAULT_BACKENDS
+from .core.errors import ConfigurationError
+from .ports import ExecutionBackend
+
+ENTRY_POINT_GROUP = "taskferry.backends"
+
+BackendFactory = Callable[..., ExecutionBackend]
+"""A callable taking the configured options as keyword arguments."""
+
+_manual: dict[str, BackendFactory] = {}
+
+
+def register_backend(name: str, factory: BackendFactory, *, replace: bool = False) -> None:
+    """Register a factory in-process, bypassing entry points.
+
+    For tests, notebooks, and applications that build backends in Python rather
+    than through installed distributions. Takes precedence over entry points, so
+    a test can shadow ``"procrastinate"`` with a fake without touching the
+    installed package.
+    """
+    if name in _manual and not replace:
+        raise ConfigurationError(f"backend factory {name!r} is already registered")
+    _manual[name] = factory
+
+
+def unregister_backend(name: str) -> None:
+    """Remove a manually registered factory. Silent when it was not registered."""
+    _manual.pop(name, None)
+
+
+def registered_backends() -> Mapping[str, BackendFactory]:
+    """The manually registered factories, for introspection and test teardown."""
+    return dict(_manual)
+
+
+@cache
+def _entry_points() -> Mapping[str, Any]:
+    from importlib.metadata import entry_points
+
+    return {ep.name: ep for ep in entry_points(group=ENTRY_POINT_GROUP)}
+
+
+def available_backends() -> tuple[str, ...]:
+    """Every backend name this process could build, from all three sources."""
+    return tuple(sorted({*DEFAULT_BACKENDS, *_entry_points(), *_manual}))
+
+
+def resolve_factory(spec: str) -> BackendFactory:
+    """Resolve a factory from a plugin name, a built-in alias, or an import string.
+
+    Resolution order, most specific first:
+
+    1. a factory registered with :func:`register_backend`;
+    2. an installed ``taskferry.backends`` entry point;
+    3. a built-in alias (``"inline"``, ``"thread"``, ``"process"``, ``"subprocess"``);
+    4. an explicit ``"module.path:callable"`` import string.
+
+    Raises:
+        ConfigurationError: when nothing matches, listing what is available so
+            the fix is usually visible in the error itself.
+    """
+    manual = _manual.get(spec)
+    if manual is not None:
+        return manual
+
+    entry_point = _entry_points().get(spec)
+    if entry_point is not None:
+        try:
+            loaded = entry_point.load()
+        except Exception as exc:
+            raise ConfigurationError(
+                f"the {spec!r} backend plugin failed to load: {exc}. "
+                f"Is its distribution installed correctly?"
+            ) from exc
+        return _as_factory(loaded, spec)
+
+    builtin = DEFAULT_BACKENDS.get(spec)
+    if builtin is not None:
+        return _import_factory(builtin)
+
+    if ":" in spec or "." in spec:
+        return _import_factory(spec)
+
+    known = ", ".join(available_backends())
+    raise ConfigurationError(
+        f"unknown backend {spec!r}; install the adapter that provides it, register it with "
+        f"taskferry.register_backend(), or use a 'module:callable' import string "
+        f"(available: {known})"
+    )
+
+
+def _import_factory(spec: str) -> BackendFactory:
+    module_path, sep, attr = spec.partition(":")
+    if not sep:
+        module_path, _, attr = spec.rpartition(".")
+    if not module_path or not attr:
+        raise ConfigurationError(f"invalid factory {spec!r}; expected 'package.module:callable'")
+    try:
+        module = importlib.import_module(module_path)
+    except ImportError as exc:
+        raise ConfigurationError(
+            f"cannot import {module_path!r} for backend factory {spec!r}: {exc}. "
+            f"The adapter distribution providing it is probably not installed."
+        ) from exc
+    try:
+        target = getattr(module, attr)
+    except AttributeError as exc:
+        raise ConfigurationError(f"{module_path!r} has no attribute {attr!r}") from exc
+    return _as_factory(target, spec)
+
+
+def _as_factory(target: object, spec: str) -> BackendFactory:
+    if not callable(target):
+        raise ConfigurationError(f"backend factory {spec!r} is not callable")
+    return cast(BackendFactory, target)
+
+
+def build_backend(factory_spec: str, options: Mapping[str, Any]) -> ExecutionBackend:
+    """Resolve ``factory_spec`` and call it with ``options`` as keyword arguments.
+
+    A ``TypeError`` from the factory is translated into a
+    :class:`~taskferry.core.errors.ConfigurationError`, because "you passed an
+    option this backend does not accept" is a configuration problem and should
+    read like one.
+    """
+    factory = resolve_factory(factory_spec)
+    try:
+        return factory(**dict(options))
+    except TypeError as exc:
+        raise ConfigurationError(
+            f"backend {factory_spec!r} rejected its options {sorted(options)}: {exc}"
+        ) from exc
+
+
+__all__ = [
+    "ENTRY_POINT_GROUP",
+    "BackendFactory",
+    "available_backends",
+    "build_backend",
+    "register_backend",
+    "registered_backends",
+    "resolve_factory",
+    "unregister_backend",
+]