taskferry 0.2.0__py3-none-any.whl

taskferry/config.py

@@ -0,0 +1,360 @@
+"""Typed configuration — one shape, several sources.
+
+```mermaid
+flowchart TD
+    ENV["Environment<br/>TASKFERRY_*"]
+    PY["Python<br/>TaskferryConfig(...)"]
+    MAP["Mapping<br/>from_mapping(...)"]
+    DJ["Django settings<br/>(taskferry_django)"]
+    FILE["TOML / YAML<br/>(application's job)"]
+
+    CONFIG["TaskferryConfig"]
+    RUNTIME["Taskferry runtime"]
+
+    ENV --> CONFIG
+    PY --> CONFIG
+    MAP --> CONFIG
+    DJ --> CONFIG
+    FILE --> CONFIG
+    CONFIG --> RUNTIME
+```
+
+Environment variables are an important *source* — they are how a Twelve-Factor
+deployment configures anything — but they are never the internal model. The
+internal model is :class:`TaskferryConfig`: typed, immutable, validated once at
+construction, and inspectable. Everything else is a loader that produces one.
+
+The core never reads ``django.conf.settings``, a config file path, or a
+framework's registry. ``taskferry_django.config_from_settings()`` builds a
+``TaskferryConfig`` from ``settings.TASKFERRY`` and hands it over — the dependency
+points inward, always.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field, replace
+from types import MappingProxyType
+from typing import Any
+
+from .core.errors import ConfigurationError
+from .execution import ExecutionKind
+from .router import Route, Router
+
+ENV_PREFIX = "TASKFERRY_"
+
+DEFAULT_BACKENDS: Mapping[str, str] = MappingProxyType(
+    {
+        "inline": "taskferry.backends.inline:InlineExecutionBackend",
+        "thread": "taskferry.backends.thread:ThreadTaskBackend",
+        "process": "taskferry.backends.process:ProcessTaskBackend",
+        "subprocess": "taskferry.backends.subprocess:SubprocessJobBackend",
+    }
+)
+"""The built-in backends, always available without any plugin installed."""
+
+
+@dataclass(frozen=True, slots=True)
+class BackendConfig:
+    """How to build one backend.
+
+    Attributes:
+        factory: Either a plugin name registered under the ``taskferry.backends``
+            entry-point group (``"procrastinate"``, ``"cloudrun"``), or an
+            explicit ``"module.path:callable"`` import string. Names are tried as
+            plugins first, then as the built-in aliases.
+        options: Keyword arguments handed to the factory. Provider-specific by
+            nature — this is the one place provider vocabulary is expected.
+    """
+
+    factory: str
+    options: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.factory:
+            raise ConfigurationError("BackendConfig.factory must not be empty")
+        object.__setattr__(self, "options", MappingProxyType(dict(self.options)))
+
+    @classmethod
+    def from_mapping(cls, data: Mapping[str, Any]) -> BackendConfig:
+        payload = dict(data)
+        factory = payload.pop("factory", None) or payload.pop("backend", None)
+        if not isinstance(factory, str):
+            raise ConfigurationError(
+                "backend configuration needs a 'factory' (plugin name or 'module:callable')"
+            )
+        options = payload.pop("options", None)
+        if options is None:
+            options = payload  # allow flat form: {"factory": ..., "project": ...}
+        elif payload:
+            raise ConfigurationError(
+                f"backend configuration mixes 'options' with extra keys: {sorted(payload)}"
+            )
+        if not isinstance(options, Mapping):
+            raise ConfigurationError("backend 'options' must be a mapping")
+        return cls(factory=factory, options=dict(options))
+
+
+@dataclass(frozen=True, slots=True)
+class TaskferryConfig:
+    """Everything the runtime needs, resolved and validated.
+
+    Attributes:
+        backends: Named backend definitions. Instantiated lazily, so configuring
+            a Cloud Run backend costs nothing until a job is actually routed to
+            it, and importing the Google SDK never happens in a web process that
+            only enqueues tasks.
+        routes: Ordered routing rules. See :class:`~taskferry.router.Route`.
+        defaults: Fallback backend per execution kind.
+        allow_import: Whether unregistered task names may be imported dynamically.
+        allowed_modules: Import allowlist for task names. Empty means "any
+            module" and is only appropriate when task names are trusted.
+        max_tracked_executions: How many ``id -> backend`` pairs the runtime
+            remembers so ``runtime.get(id)`` can find the right backend without
+            being told. Bounded on purpose — a long-lived producer must not grow
+            a map forever.
+    """
+
+    backends: Mapping[str, BackendConfig] = field(default_factory=dict)
+    routes: Sequence[Route] = ()
+    defaults: Mapping[ExecutionKind, str] = field(default_factory=dict)
+    allow_import: bool = True
+    allowed_modules: Sequence[str] = ()
+    max_tracked_executions: int = 10_000
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "backends", MappingProxyType(dict(self.backends)))
+        object.__setattr__(self, "routes", tuple(self.routes))
+        object.__setattr__(self, "defaults", MappingProxyType(dict(self.defaults)))
+        object.__setattr__(self, "allowed_modules", tuple(self.allowed_modules))
+        if self.max_tracked_executions < 0:
+            raise ConfigurationError("max_tracked_executions must be >= 0")
+        self._validate_references()
+
+    def _validate_references(self) -> None:
+        """Fail at construction when a route names a backend that is not defined.
+
+        Catching this here means a typo in a route surfaces at startup rather
+        than the first time that queue happens to be used in production.
+        """
+        known = set(self.backends)
+        for route in self.routes:
+            if route.backend not in known:
+                raise ConfigurationError(
+                    f"route {route.describe()!r} names unknown backend {route.backend!r} "
+                    f"(defined: {', '.join(sorted(known)) or '<none>'})"
+                )
+        for kind, backend in self.defaults.items():
+            if backend not in known:
+                raise ConfigurationError(
+                    f"default backend for {kind.value!r} is {backend!r}, which is not defined "
+                    f"(defined: {', '.join(sorted(known)) or '<none>'})"
+                )
+
+    # -- derived ------------------------------------------------------------ #
+    def router(self) -> Router:
+        """Build the :class:`~taskferry.router.Router` this configuration describes."""
+        return Router(self.routes, defaults=self.defaults)
+
+    def evolve(self, **changes: Any) -> TaskferryConfig:
+        """Return a modified copy. Configs are immutable."""
+        return replace(self, **changes)
+
+    def with_backend(self, name: str, config: BackendConfig) -> TaskferryConfig:
+        """Return a copy with one more backend defined."""
+        return self.evolve(backends={**self.backends, name: config})
+
+    # -- loaders ------------------------------------------------------------ #
+    @classmethod
+    def local(cls) -> TaskferryConfig:
+        """The zero-infrastructure configuration.
+
+        Inline runs in this process, tasks run on a thread pool, jobs run as
+        subprocesses. No queue, no database, no cloud, no worker. This is what
+        :meth:`taskferry.Taskferry.local` uses, and it is a genuinely useful
+        production configuration for a CLI or a single-process tool.
+        """
+        return cls(
+            backends={
+                "inline": BackendConfig(factory="inline"),
+                "thread": BackendConfig(factory="thread"),
+                "subprocess": BackendConfig(factory="subprocess"),
+            },
+            defaults={
+                ExecutionKind.INLINE: "inline",
+                ExecutionKind.TASK: "thread",
+                ExecutionKind.JOB: "subprocess",
+            },
+        )
+
+    @classmethod
+    def from_mapping(cls, data: Mapping[str, Any]) -> TaskferryConfig:
+        """Build from a plain mapping — the shape a TOML/YAML/settings loader produces.
+
+        ::
+
+            {
+              "backends": {
+                "metadata": {"factory": "procrastinate", "app": "myapp.tasks:app"},
+                "heavy":    {"factory": "cloudrun", "project": "p", "location": "eu"},
+              },
+              "routes": [
+                {"kind": "task", "queue": "metadata", "backend": "metadata"},
+                {"kind": "job",  "profile": "heavy",  "backend": "heavy"},
+              ],
+              "defaults": {"inline": "inline", "task": "metadata", "job": "heavy"},
+            }
+        """
+        backends_raw = data.get("backends") or {}
+        if not isinstance(backends_raw, Mapping):
+            raise ConfigurationError("'backends' must be a mapping of name -> configuration")
+        backends = {
+            str(name): BackendConfig.from_mapping(entry)
+            if isinstance(entry, Mapping)
+            else BackendConfig(factory=str(entry))
+            for name, entry in backends_raw.items()
+        }
+
+        routes_raw = data.get("routes") or ()
+        if isinstance(routes_raw, Mapping):
+            raise ConfigurationError("'routes' must be an ordered sequence, not a mapping")
+        routes = tuple(_route_from_mapping(entry) for entry in routes_raw)
+
+        defaults_raw = data.get("defaults") or {}
+        if not isinstance(defaults_raw, Mapping):
+            raise ConfigurationError("'defaults' must be a mapping of kind -> backend name")
+        defaults = {_parse_kind(key): str(value) for key, value in defaults_raw.items()}
+
+        return cls(
+            backends=backends,
+            routes=routes,
+            defaults=defaults,
+            allow_import=bool(data.get("allow_import", True)),
+            allowed_modules=tuple(str(m) for m in (data.get("allowed_modules") or ())),
+            max_tracked_executions=int(data.get("max_tracked_executions", 10_000)),
+        )
+
+    @classmethod
+    def from_env(cls, environ: Mapping[str, str] | None = None) -> TaskferryConfig:
+        """Build from ``TASKFERRY_*`` environment variables.
+
+        Two variables carry the structure, both JSON so that nested provider
+        options survive intact:
+
+        ``TASKFERRY_BACKENDS``
+            ``{"metadata": {"factory": "procrastinate", "app": "myapp:app"}}``
+
+        ``TASKFERRY_ROUTES``
+            ``[{"kind": "task", "queue": "metadata", "backend": "metadata"}]``
+
+        And the scalars:
+
+        ``TASKFERRY_DEFAULT_INLINE`` · ``TASKFERRY_DEFAULT_TASK`` ·
+        ``TASKFERRY_DEFAULT_JOB`` · ``TASKFERRY_ALLOW_IMPORT`` ·
+        ``TASKFERRY_ALLOWED_MODULES`` (comma-separated).
+
+        With nothing set at all this returns :meth:`local`, so a container that
+        forgot to configure Taskferry still starts and still runs work — locally,
+        visibly, and without pretending to have reached a queue.
+        """
+        source = environ if environ is not None else os.environ
+        raw_backends = source.get(f"{ENV_PREFIX}BACKENDS")
+        raw_routes = source.get(f"{ENV_PREFIX}ROUTES")
+
+        payload: dict[str, Any] = {}
+        if raw_backends:
+            payload["backends"] = _json_env(f"{ENV_PREFIX}BACKENDS", raw_backends, Mapping)
+        if raw_routes:
+            payload["routes"] = _json_env(f"{ENV_PREFIX}ROUTES", raw_routes, list)
+
+        defaults = {
+            kind.value: source[f"{ENV_PREFIX}DEFAULT_{kind.value.upper()}"]
+            for kind in ExecutionKind
+            if source.get(f"{ENV_PREFIX}DEFAULT_{kind.value.upper()}")
+        }
+        if defaults:
+            payload["defaults"] = defaults
+
+        if not payload:
+            return cls.local()
+
+        allow_import = source.get(f"{ENV_PREFIX}ALLOW_IMPORT")
+        if allow_import is not None:
+            falsey = {"0", "false", "no", "off"}
+            payload["allow_import"] = allow_import.strip().lower() not in falsey
+        allowed = source.get(f"{ENV_PREFIX}ALLOWED_MODULES")
+        if allowed:
+            payload["allowed_modules"] = [m.strip() for m in allowed.split(",") if m.strip()]
+        tracked = source.get(f"{ENV_PREFIX}MAX_TRACKED_EXECUTIONS")
+        if tracked:
+            payload["max_tracked_executions"] = _int_env(
+                f"{ENV_PREFIX}MAX_TRACKED_EXECUTIONS", tracked
+            )
+        return cls.from_mapping(payload)
+
+
+def _json_env(key: str, raw: str, expected: type) -> Any:
+    try:
+        value = json.loads(raw)
+    except ValueError as exc:
+        raise ConfigurationError(f"{key} must contain valid JSON: {exc}") from exc
+    if not isinstance(value, expected):
+        raise ConfigurationError(f"{key} must be a JSON {expected.__name__.lower()}")
+    return value
+
+
+def _int_env(key: str, raw: str) -> int:
+    try:
+        return int(raw)
+    except ValueError as exc:
+        raise ConfigurationError(f"{key} must be an integer, got {raw!r}") from exc
+
+
+def _parse_kind(value: object) -> ExecutionKind:
+    if isinstance(value, ExecutionKind):
+        return value
+    try:
+        return ExecutionKind(str(value))
+    except ValueError as exc:
+        known = ", ".join(k.value for k in ExecutionKind)
+        raise ConfigurationError(f"unknown execution kind {value!r} (known: {known})") from exc
+
+
+def _route_from_mapping(entry: object) -> Route:
+    if isinstance(entry, Route):
+        return entry
+    if not isinstance(entry, Mapping):
+        raise ConfigurationError(f"route entries must be mappings, got {type(entry).__name__}")
+    data = dict(entry)
+    backend = data.pop("backend", None)
+    if not isinstance(backend, str):
+        raise ConfigurationError("each route needs a 'backend' name")
+    kind = data.pop("kind", None)
+    labels = data.pop("labels", None) or {}
+    if not isinstance(labels, Mapping):
+        raise ConfigurationError("route 'labels' must be a mapping")
+    unknown = set(data) - {"queue", "profile", "name"}
+    if unknown:
+        raise ConfigurationError(f"unknown route keys: {', '.join(sorted(unknown))}")
+    return Route(
+        backend=backend,
+        kind=_parse_kind(kind) if kind is not None else None,
+        queue=_opt_str(data.get("queue")),
+        profile=_opt_str(data.get("profile")),
+        name=_opt_str(data.get("name")),
+        labels={str(k): str(v) for k, v in labels.items()},
+    )
+
+
+def _opt_str(value: object) -> str | None:
+    return None if value is None else str(value)
+
+
+__all__ = [
+    "DEFAULT_BACKENDS",
+    "ENV_PREFIX",
+    "BackendConfig",
+    "TaskferryConfig",
+]

taskferry/contract/__init__.py

@@ -0,0 +1,56 @@
+"""Reusable contract suites every adapter must pass.
+
+An adapter's job is to be *interchangeable*. That is only true if every adapter
+behaves the same way at the port, so the port ships its own test suite and each
+adapter runs it:
+
+```mermaid
+flowchart TD
+    SUITE["taskferry.contract<br/>TaskBackendContract · JobBackendContract"]
+
+    PRO["taskferry-procrastinate tests"]
+    CT["taskferry-cloudtasks tests"]
+    CR["taskferry-cloudrun tests"]
+    LOCAL["built-in backend tests"]
+
+    SUITE --> PRO
+    SUITE --> CT
+    SUITE --> CR
+    SUITE --> LOCAL
+```
+
+The suites are **capability-driven**. A backend that does not advertise ``CANCEL``
+is not skipped — it is asserted to *reject* cancellation with
+:class:`~taskferry.errors.UnsupportedCapability`. That is the assertion that
+matters, because the failure mode this design exists to prevent is a backend
+quietly pretending.
+
+Usage in an adapter's test module::
+
+    from taskferry.contract import TaskBackendContract
+
+    class TestMyBackend(TaskBackendContract):
+        def make_backend(self):
+            return MyTaskBackend(client=FakeClient())
+
+        def success_spec(self):
+            return TaskSpec(task="tests.tasks:ok")
+
+This module imports :mod:`pytest`, so it belongs in test environments. It is
+shipped inside the ``taskferry`` distribution anyway: an adapter released
+separately must be able to import the suite it is required to pass.
+"""
+
+from __future__ import annotations
+
+from .base import ExecutionBackendContract
+from .inline import InlineBackendContract
+from .job import JobBackendContract
+from .task import TaskBackendContract
+
+__all__ = [
+    "ExecutionBackendContract",
+    "InlineBackendContract",
+    "JobBackendContract",
+    "TaskBackendContract",
+]

taskferry/contract/base.py

@@ -0,0 +1,179 @@
+"""Invariants that hold for every backend, of every kind.
+
+Subclassed by the per-kind suites; adapters normally use those rather than this
+one directly.
+"""
+
+from __future__ import annotations
+
+import time
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+
+import pytest
+
+from ..capabilities import Capability, CapabilitySet
+from ..errors import ExecutionNotFound, UnsupportedCapability
+from ..execution import Execution, ExecutionId, ExecutionState
+from ..ports import ExecutionBackend
+from ..specs import AnySpec
+
+WAIT_TIMEOUT = 30.0
+"""How long the shared helpers wait for a real backend to reach a terminal state."""
+
+
+class ExecutionBackendContract(ABC):
+    """Assertions every :class:`~taskferry.ports.ExecutionBackend` must satisfy."""
+
+    #: Set True when the backend really executes work, so the suite can drive a
+    #: full submit → poll → terminal lifecycle. Leave False for adapters tested
+    #: against a fake provider client that never completes anything.
+    reaches_terminal_state: bool = False
+
+    @abstractmethod
+    def make_backend(self) -> ExecutionBackend:
+        """Return a fresh backend under test. Called once per test."""
+
+    @abstractmethod
+    def success_spec(self) -> AnySpec:
+        """Return a spec this backend should accept and (if it executes) succeed on."""
+
+    # -- identity ------------------------------------------------------------- #
+    def test_declares_a_name_a_kind_and_capabilities(self) -> None:
+        backend = self.make_backend()
+        assert isinstance(backend.name, str) and backend.name, "a backend needs a stable name"
+        caps = backend.capabilities
+        assert isinstance(caps, CapabilitySet)
+        assert caps.provider == backend.name, "capabilities must be attributed to the backend"
+        assert Capability.SUBMIT in caps, "every backend can submit; say so explicitly"
+
+    def test_kind_matches_the_specs_it_accepts(self) -> None:
+        backend = self.make_backend()
+        assert backend.kind is self.success_spec().kind
+
+    # -- submission ------------------------------------------------------------ #
+    def test_submit_returns_a_well_formed_execution(self) -> None:
+        backend = self.make_backend()
+        execution = backend.submit(self.success_spec())
+        assert isinstance(execution, Execution)
+        assert execution.id, "an execution must carry a Taskferry-owned id"
+        assert execution.id.startswith(f"{backend.kind.value}_"), (
+            "execution ids are minted by taskferry and prefixed with the kind"
+        )
+        assert execution.backend == backend.name
+        assert execution.kind is backend.kind
+        assert isinstance(execution.state, ExecutionState)
+
+    def test_submit_rejects_a_spec_of_the_wrong_kind(self) -> None:
+        backend = self.make_backend()
+        wrong = _spec_of_another_kind(self.success_spec())
+        with pytest.raises(TypeError):
+            backend.submit(wrong)
+
+    def test_provider_id_is_not_reused_as_the_taskferry_id(self) -> None:
+        """A Taskferry id is Taskferry's; the engine's id lives in ``external_id``."""
+        backend = self.make_backend()
+        execution = backend.submit(self.success_spec())
+        if execution.external_id is not None:
+            assert execution.external_id != execution.id
+
+    # -- capabilities are honest ------------------------------------------------ #
+    def test_state_capability_matches_get(self) -> None:
+        backend = self.make_backend()
+        execution = backend.submit(self.success_spec())
+        if Capability.STATE in backend.capabilities:
+            fetched = backend.get(execution.id)
+            assert fetched.id == execution.id
+            assert execution.transitions_to(fetched.state), (
+                f"{execution.state} -> {fetched.state} is not a legal transition"
+            )
+        else:
+            with pytest.raises(UnsupportedCapability):
+                backend.get(execution.id)
+
+    def test_cancel_capability_matches_cancel(self) -> None:
+        backend = self.make_backend()
+        execution = backend.submit(self.success_spec())
+        if Capability.CANCEL in backend.capabilities:
+            cancelled = backend.cancel(execution.id)
+            assert cancelled.id == execution.id
+        else:
+            with pytest.raises(UnsupportedCapability):
+                backend.cancel(execution.id)
+
+    def test_result_capability_matches_result(self) -> None:
+        backend = self.make_backend()
+        execution = backend.submit(self.success_spec())
+        if Capability.RESULT not in backend.capabilities:
+            with pytest.raises(UnsupportedCapability):
+                backend.result(execution.id)
+        elif self.reaches_terminal_state:
+            assert backend.result(execution.id, timeout=WAIT_TIMEOUT) is not None
+
+    def test_unknown_id_raises_execution_not_found(self) -> None:
+        backend = self.make_backend()
+        if Capability.STATE not in backend.capabilities:
+            pytest.skip("backend cannot report state, so there is nothing to look up")
+        with pytest.raises(ExecutionNotFound):
+            backend.get(ExecutionId("task_does_not_exist_0000"))
+
+    # -- lifecycle (only where work really runs) -------------------------------- #
+    def test_reaches_a_terminal_state(self) -> None:
+        if not self.reaches_terminal_state:
+            pytest.skip("backend does not execute work in this test environment")
+        backend = self.make_backend()
+        execution = backend.submit(self.success_spec())
+        final = self.wait_for_terminal(backend, execution)
+        assert final.is_terminal
+        assert final.state is ExecutionState.SUCCEEDED, (
+            f"success_spec() should succeed, got {final.state}: "
+            f"{final.result.error if final.result else '<no result>'}"
+        )
+        assert final.finished_at is not None, "a terminal execution should report when it finished"
+
+    def test_terminal_state_is_stable(self) -> None:
+        """Re-reading a finished execution must not change it."""
+        if not self.reaches_terminal_state:
+            pytest.skip("backend does not execute work in this test environment")
+        backend = self.make_backend()
+        execution = backend.submit(self.success_spec())
+        final = self.wait_for_terminal(backend, execution)
+        again = backend.get(final.id)
+        assert again.state is final.state
+
+    # -- helper ------------------------------------------------------------------ #
+    def wait_for_terminal(
+        self, backend: ExecutionBackend, execution: Execution, timeout: float = WAIT_TIMEOUT
+    ) -> Execution:
+        """Poll until terminal, failing the test rather than hanging."""
+        if execution.is_terminal:
+            return execution
+        deadline = time.monotonic() + timeout
+        current = execution
+        while time.monotonic() < deadline:
+            current = backend.get(execution.id)
+            if current.is_terminal:
+                return current
+            time.sleep(0.02)
+        pytest.fail(f"{execution.id} never reached a terminal state (last: {current.state})")
+
+
+def _spec_of_another_kind(spec: AnySpec) -> AnySpec:
+    """Build a spec of a different kind, to prove the backend rejects it."""
+    from ..execution import ExecutionKind
+    from ..specs import InlineSpec, JobSpec, TaskSpec
+
+    others: dict[ExecutionKind, Callable[[], AnySpec]] = {
+        ExecutionKind.INLINE: lambda: InlineSpec(func=_noop),
+        ExecutionKind.TASK: lambda: TaskSpec(task="taskferry.contract.base:_noop"),
+        ExecutionKind.JOB: lambda: JobSpec(job="wrong-kind", command=["true"]),
+    }
+    wrong_kind = next(kind for kind in others if kind is not spec.kind)
+    return others[wrong_kind]()
+
+
+def _noop() -> None:
+    """Referenced by :func:`_spec_of_another_kind` so the reference resolves."""
+
+
+__all__ = ["WAIT_TIMEOUT", "ExecutionBackendContract"]

taskferry/contract/inline.py

@@ -0,0 +1,89 @@
+"""The contract every :class:`~taskferry.ports.InlineBackend` must satisfy.
+
+Inline is the strictest port: it runs in the caller's process, so there is
+nowhere to hide. By the time ``submit`` returns, the work is finished.
+"""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+
+import pytest
+
+from ..capabilities import Capability
+from ..execution import ExecutionKind, ExecutionState
+from ..ports import ExecutionBackend
+from ..specs import InlineSpec
+from .base import ExecutionBackendContract
+
+
+def _echo(value: object = "ok") -> object:
+    return value
+
+
+def _explode() -> None:
+    raise ValueError("contract failure probe")
+
+
+class InlineBackendContract(ExecutionBackendContract):
+    """Subclass in a test module and implement :meth:`make_backend`."""
+
+    reaches_terminal_state = True
+
+    @abstractmethod
+    def make_backend(self) -> ExecutionBackend: ...
+
+    def success_spec(self) -> InlineSpec:
+        return InlineSpec(func=_echo, args=("ok",))
+
+    def test_is_an_inline_backend(self) -> None:
+        assert self.make_backend().kind is ExecutionKind.INLINE
+
+    def test_submit_is_already_terminal(self) -> None:
+        """Inline has no queue: submission and completion are the same moment."""
+        backend = self.make_backend()
+        execution = backend.submit(self.success_spec())
+        assert execution.is_terminal
+        assert execution.state is ExecutionState.SUCCEEDED
+
+    def test_the_value_comes_back(self) -> None:
+        backend = self.make_backend()
+        execution = backend.submit(InlineSpec(func=_echo, args=(42,)))
+        assert execution.result is not None
+        assert execution.result.value == 42
+
+    def test_a_failure_is_recorded_not_raised(self) -> None:
+        """A failed execution is data, not an exception at the submit call site.
+
+        The exception surfaces from ``handle.result()``, so callers choose when
+        to care — the same as for a task that fails on a worker.
+        """
+        backend = self.make_backend()
+        execution = backend.submit(InlineSpec(func=_explode))
+        assert execution.state is ExecutionState.FAILED
+        assert execution.result is not None
+        assert execution.result.error_type == "ValueError"
+        assert execution.result.traceback
+
+    def test_closures_and_lambdas_are_accepted(self) -> None:
+        """The point of inline: no importable name is required."""
+        backend = self.make_backend()
+        offset = 5
+        execution = backend.submit(InlineSpec(func=lambda x: x + offset, args=(1,)))
+        assert execution.result is not None
+        assert execution.result.value == 6
+
+    async def test_async_callables_are_awaited(self) -> None:
+        backend = self.make_backend()
+        if Capability.ASYNC_CALLABLE not in backend.capabilities:
+            pytest.skip("backend does not claim to run async callables")
+
+        async def coro(value: int) -> int:
+            return value * 2
+
+        execution = backend.submit(InlineSpec(func=coro, args=(21,)))
+        assert execution.result is not None
+        assert execution.result.value == 42
+
+
+__all__ = ["InlineBackendContract"]