apsimo-hostworker 0.2.0__py3-none-any.whl

apsimo_hostworker/client.py

@@ -0,0 +1,292 @@
+"""Strict loopback client for the governed-action execution endpoint.
+
+The endpoint contract this client relies on is part of the safety boundary:
+
+* ``PUT /v1/host/actions/{action_id}`` durably reserves the immutable action
+  as ``executing`` before any effect is attempted.  That reservation permits
+  at most one mutation attempt and is never automatically replayed — so this
+  client NEVER retries a mutation.  A ``PUT`` that fails, times out, or
+  returns garbage leaves the outcome unknown, and the only permitted
+  follow-up is read-only observation.
+* ``GET /v1/host/actions/{action_id}`` is side-effect-free and returns the
+  endpoint's stable digest-bound projection of the action.
+
+The client is loopback-only (see :func:`apsimo_hostworker._private_io.\
+loopback_origin`), uses a redirect-refusing opener so the bearer credential
+can never be replayed to another origin, and decodes responses through the
+bounded strict JSON reader.  It validates only the request document's outer
+identity; semantic validation of responses belongs to the worker
+(:func:`apsimo_hostworker.worker.validate_execution_result`).
+"""
+
+from __future__ import annotations
+
+import math
+import re
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+from ._private_io import loopback_origin, read_private_json, strict_json_bytes
+from .contract import (
+    ACTION_ID_RE,
+    EXECUTION_REQUEST_FIELDS,
+    EXECUTION_REQUEST_MAX_BYTES,
+    EXECUTION_REQUEST_SCHEMA,
+    EXECUTION_RESULT_MAX_BYTES,
+    canonical_json_utf8,
+)
+
+
+class GovernedActionClientError(RuntimeError):
+    """The execution endpoint is unavailable or returned invalid data."""
+
+
+# The one principal the endpoint accepts for host-worker execution.  It is a
+# public wire string shared with the sidecar's independent validator
+# (``GOVERNED_ACTION_PRINCIPAL``); never rename it.
+WORKER_PRINCIPAL = "host-action-worker"
+
+CREDENTIAL_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$")
+
+_ACTIONS_PATH = "/v1/host/actions/"
+
+
+class NoRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """Refuse every redirect so credentials never leave the pinned origin.
+
+    Python's default redirect handler copies ordinary request headers —
+    including ``Authorization`` — to the redirect target.  A loopback service
+    boundary must instead surface the redirect to its caller as an error.
+    """
+
+    def redirect_request(self, request, file_pointer, code, message, headers, new_url):
+        del request, file_pointer, code, message, headers, new_url
+        return None
+
+
+def build_no_redirect_opener():
+    """Build a proxy-free, redirect-refusing ``urllib`` opener."""
+
+    return urllib.request.build_opener(
+        urllib.request.ProxyHandler({}), NoRedirectHandler()
+    )
+
+
+@dataclass(frozen=True)
+class ClientCredential:
+    """Dedicated client identity for only the governed-action endpoint.
+
+    Loaded exclusively from an owner-only mode-0600 regular file so a
+    world-readable secret, a symlink swap, or a group-readable deploy
+    artifact fails closed at startup instead of leaking authority.
+    """
+
+    principal: str
+    credential_id: str
+    secret: str = field(repr=False)
+
+    @classmethod
+    def load(cls, path: str) -> "ClientCredential":
+        _target, _raw, document = read_private_json(
+            path,
+            label="governed action credential",
+            error=GovernedActionClientError,
+        )
+        fields = {"version", "principal", "credential_id", "secret"}
+        if not isinstance(document, Mapping) or set(document) != fields:
+            raise GovernedActionClientError(
+                "governed action credential fields are invalid"
+            )
+        if (
+            isinstance(document.get("version"), bool)
+            or document.get("version") != 1
+            or document.get("principal") != WORKER_PRINCIPAL
+        ):
+            raise GovernedActionClientError(
+                "governed action credential principal is invalid"
+            )
+        credential_id = document.get("credential_id")
+        secret = document.get("secret")
+        if not isinstance(credential_id, str) or not CREDENTIAL_ID_RE.fullmatch(
+            credential_id
+        ):
+            raise GovernedActionClientError(
+                "governed action credential ID is invalid"
+            )
+        if (
+            not isinstance(secret, str)
+            or not 32 <= len(secret) <= 512
+            or any(
+                ord(character) < 0x21 or ord(character) > 0x7E
+                for character in secret
+            )
+        ):
+            raise GovernedActionClientError(
+                "governed action credential secret is invalid"
+            )
+        return cls(
+            principal=WORKER_PRINCIPAL,
+            credential_id=credential_id,
+            secret=secret,
+        )
+
+
+class GovernedActionClient:
+    """Credential-bound client for one loopback governed-action origin.
+
+    ``execute`` issues exactly one ``PUT`` per call and NEVER retries it —
+    the caller's state machine owns the one-mutation guarantee and must treat
+    any failure here as an unknown outcome to be resolved by ``observe``
+    only.  ``observe`` issues a side-effect-free ``GET``.
+    """
+
+    def __init__(
+        self,
+        origin: str,
+        credential: ClientCredential,
+        *,
+        opener=None,
+        timeout: float = 5.0,
+    ) -> None:
+        if not isinstance(credential, ClientCredential):
+            raise GovernedActionClientError(
+                "governed action credential is invalid"
+            )
+        if isinstance(timeout, bool):
+            raise GovernedActionClientError("governed action timeout is invalid")
+        try:
+            request_timeout = float(timeout)
+        except (TypeError, ValueError, OverflowError) as error:
+            raise GovernedActionClientError(
+                "governed action timeout is invalid"
+            ) from error
+        if not math.isfinite(request_timeout) or not 0.1 <= request_timeout <= 30.0:
+            raise GovernedActionClientError("governed action timeout is invalid")
+        candidate = build_no_redirect_opener() if opener is None else opener
+        if not hasattr(candidate, "open") or not callable(candidate.open):
+            raise GovernedActionClientError(
+                "governed action HTTP opener is invalid"
+            )
+        self.origin = loopback_origin(origin, error=GovernedActionClientError)
+        self.credential = credential
+        self.timeout = request_timeout
+        self.opener = candidate
+
+    @staticmethod
+    def _action_id(request: Mapping[str, Any]) -> str:
+        if (
+            not isinstance(request, Mapping)
+            or set(request) != EXECUTION_REQUEST_FIELDS
+            or request.get("schema") != EXECUTION_REQUEST_SCHEMA
+            or isinstance(request.get("version"), bool)
+            or request.get("version") != 1
+        ):
+            raise GovernedActionClientError(
+                "governed action request fields are invalid"
+            )
+        action_id = request.get("action_id")
+        if not isinstance(action_id, str) or not ACTION_ID_RE.fullmatch(action_id):
+            raise GovernedActionClientError("governed action ID is invalid")
+        return action_id
+
+    def _request(self, method: str, request: Mapping[str, Any]) -> Mapping[str, Any]:
+        action_id = self._action_id(request)
+        data = None
+        if method == "PUT":
+            try:
+                data = canonical_json_utf8(dict(request)).encode("utf-8")
+            except (
+                TypeError,
+                ValueError,
+                UnicodeError,
+                OverflowError,
+                RecursionError,
+            ) as error:
+                raise GovernedActionClientError(
+                    "governed action request is invalid"
+                ) from error
+            if len(data) > EXECUTION_REQUEST_MAX_BYTES:
+                raise GovernedActionClientError(
+                    "governed action request is too large"
+                )
+        elif method != "GET":
+            raise GovernedActionClientError(
+                "governed action HTTP method is invalid"
+            )
+        target = self.origin + _ACTIONS_PATH + urllib.parse.quote(
+            action_id, safe="-"
+        )
+        outbound = urllib.request.Request(
+            target,
+            data=data,
+            method=method,
+            headers={
+                "Authorization": "Bearer " + self.credential.secret,
+                "X-Colony-Principal": self.credential.principal,
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+            },
+        )
+        try:
+            with self.opener.open(outbound, timeout=self.timeout) as response:
+                status = getattr(response, "status", None)
+                if status is None and hasattr(response, "getcode"):
+                    status = response.getcode()
+                if isinstance(status, bool) or status != 200:
+                    raise GovernedActionClientError(
+                        "governed action response was rejected"
+                    )
+                raw = response.read(EXECUTION_RESULT_MAX_BYTES + 1)
+                if not isinstance(raw, bytes) or len(raw) > EXECUTION_RESULT_MAX_BYTES:
+                    raise GovernedActionClientError(
+                        "governed action response is too large"
+                    )
+        except GovernedActionClientError:
+            raise
+        except (
+            urllib.error.HTTPError,
+            urllib.error.URLError,
+            TimeoutError,
+            OSError,
+        ) as error:
+            raise GovernedActionClientError(
+                "governed action service is unavailable"
+            ) from error
+        except Exception as error:
+            raise GovernedActionClientError(
+                "governed action exchange failed"
+            ) from error
+        value = strict_json_bytes(
+            raw,
+            maximum=EXECUTION_RESULT_MAX_BYTES,
+            error=GovernedActionClientError,
+        )
+        if not isinstance(value, Mapping):
+            raise GovernedActionClientError(
+                "governed action response must be an object"
+            )
+        return value
+
+    def execute(self, request: Mapping[str, Any]) -> Mapping[str, Any]:
+        """Issue THE one mutation PUT for this request.  Never retried."""
+
+        return self._request("PUT", request)
+
+    def observe(self, request: Mapping[str, Any]) -> Mapping[str, Any]:
+        """Issue one side-effect-free reconciliation GET."""
+
+        return self._request("GET", request)
+
+
+__all__ = (
+    "CREDENTIAL_ID_RE",
+    "ClientCredential",
+    "GovernedActionClient",
+    "GovernedActionClientError",
+    "NoRedirectHandler",
+    "WORKER_PRINCIPAL",
+    "build_no_redirect_opener",
+)

apsimo_hostworker/compat.py

@@ -0,0 +1,53 @@
+"""Legacy import names resolve to the canonical module, including its state."""
+from __future__ import annotations
+
+import importlib
+import importlib.abc
+import importlib.util
+import sys
+
+
+class _AliasLoader(importlib.abc.Loader):
+    def __init__(self, canonical, spec):
+        self.canonical = canonical
+        self.canonical_spec = spec
+
+    def create_module(self, spec):
+        return importlib.import_module(self.canonical)
+
+    def exec_module(self, module):
+        # module_from_spec assigns the alias spec to the returned module.
+        # Restore its real identity rather than executing its source again.
+        module.__spec__ = self.canonical_spec
+        module.__loader__ = self.canonical_spec.loader
+
+    def get_code(self, fullname):
+        # runpy uses get_code for `python -m legacy_package.entrypoint`.
+        return self.canonical_spec.loader.get_code(self.canonical)
+
+    def is_package(self, fullname):
+        return self.canonical_spec.submodule_search_locations is not None
+
+
+class _AliasFinder(importlib.abc.MetaPathFinder):
+    def __init__(self, legacy, canonical):
+        self.legacy, self.canonical = legacy, canonical
+
+    def find_spec(self, fullname, path=None, target=None):
+        if not fullname.startswith(self.legacy + '.'):
+            return None
+        canonical = self.canonical + fullname[len(self.legacy):]
+        spec = importlib.util.find_spec(canonical)
+        if spec is None:
+            return None
+        loader = _AliasLoader(canonical, spec)
+        return importlib.util.spec_from_loader(fullname, loader,
+            origin=spec.origin, is_package=spec.submodule_search_locations is not None)
+
+
+def register_module_alias(legacy: str, canonical: str) -> None:
+    """Install a lazy alias once, without eagerly importing optional subsystems."""
+    if not any(getattr(finder, 'legacy', None) == legacy
+               and getattr(finder, 'canonical', None) == canonical for finder in sys.meta_path):
+        sys.meta_path.insert(0, _AliasFinder(legacy, canonical))
+    sys.modules[legacy] = importlib.import_module(canonical)

apsimo_hostworker/conformance/__init__.py

@@ -0,0 +1,52 @@
+"""Executable store-adapter conformance suite for governed host workers.
+
+Any host must pass this suite with its own :class:`StoreHarness` before
+running its store live::
+
+    from apsimo_hostworker.conformance import assert_store_conformance
+    assert_store_conformance(my_harness_factory)
+
+The bundled reference store can be checked from the command line::
+
+    python -m apsimo_hostworker.conformance
+"""
+
+from __future__ import annotations
+
+from .harness import (
+    HarnessFactory,
+    ManualClock,
+    SqliteStoreHarness,
+    StoreHarness,
+    approval_id,
+    build_envelope,
+    build_intent,
+    delivery_gate_evidence,
+    grant_gate_evidence,
+    sqlite_harness,
+)
+from .suite import (
+    CASES,
+    ConformanceFailure,
+    ConformanceResult,
+    assert_store_conformance,
+    run_store_conformance,
+)
+
+__all__ = (
+    "CASES",
+    "ConformanceFailure",
+    "ConformanceResult",
+    "HarnessFactory",
+    "ManualClock",
+    "SqliteStoreHarness",
+    "StoreHarness",
+    "approval_id",
+    "assert_store_conformance",
+    "build_envelope",
+    "build_intent",
+    "delivery_gate_evidence",
+    "grant_gate_evidence",
+    "run_store_conformance",
+    "sqlite_harness",
+)

apsimo_hostworker/conformance/__main__.py

@@ -0,0 +1,29 @@
+"""Run the store conformance suite against the bundled reference store."""
+
+from __future__ import annotations
+
+import sys
+
+from .harness import sqlite_harness
+from .suite import run_store_conformance
+
+
+def main() -> int:
+    results = run_store_conformance(sqlite_harness)
+    failures = 0
+    for result in results:
+        marker = "PASS" if result.passed else "FAIL"
+        line = "%s %s" % (marker, result.name)
+        if result.detail:
+            line += " — " + result.detail
+        print(line)
+        if not result.passed:
+            failures += 1
+    print(
+        "%d/%d conformance cases passed" % (len(results) - failures, len(results))
+    )
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

apsimo_hostworker/conformance/harness.py

@@ -0,0 +1,278 @@
+"""Harness contract and fixtures for the store conformance suite.
+
+A host proves its :class:`~apsimo_hostworker.store.ActionStore` adapter by
+implementing :class:`StoreHarness` — the store under test plus the two
+ingress operations the suite needs (proposing an action, attaching a gate
+receipt) and a controllable clock — and passing a factory for it to
+:func:`apsimo_hostworker.conformance.run_store_conformance`.
+
+The clock MUST be the same clock the store judges time with (invariant
+I11): several cases advance it to prove point-of-use expiry, lease theft,
+and observation deadlines.
+
+Everything here is stdlib-only; the suite runs without pytest so it can be
+executed inside a host's own deployment checks
+(``python -m apsimo_hostworker.conformance``).
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+import uuid
+from typing import Any, Callable, Mapping, Protocol, runtime_checkable
+
+from ..contract import INTENT_ENVELOPE_SCHEMA
+from ..gate import GRANT_BINDING_METHOD, GRANT_UNLIMITED_SENTINEL
+from ..intent import HermesToolActionIntentV1
+from ..sqlite_store import SqliteActionStore
+
+
+class ManualClock:
+    """Deterministic, explicitly advanced clock for conformance runs."""
+
+    def __init__(self, start: float = 1_700_000_000.0) -> None:
+        self._now = float(start)
+
+    def now(self) -> float:
+        return self._now
+
+    def advance(self, seconds: float) -> float:
+        self._now += float(seconds)
+        return self._now
+
+    def __call__(self) -> float:
+        return self._now
+
+
+@runtime_checkable
+class StoreHarness(Protocol):
+    """One store under test plus the ingress the suite drives it with.
+
+    ``store`` must implement :class:`~apsimo_hostworker.store.ActionStore`.
+    ``propose`` and ``add_gate`` are the host's ingress equivalents (however
+    they are implemented in production); ``add_gate`` returns
+    ``(action, gate_receipt)``.  ``now``/``advance`` control the SAME clock
+    the store reads.  ``close`` releases resources.
+    """
+
+    store: Any
+
+    def now(self) -> float:
+        ...
+
+    def advance(self, seconds: float) -> float:
+        ...
+
+    def propose(
+        self,
+        *,
+        idempotency_key: str,
+        source: str,
+        source_ref: str,
+        action_type: str,
+        payload: Any,
+    ) -> Mapping[str, Any]:
+        ...
+
+    def add_gate(
+        self,
+        action_id: str,
+        evidence: Mapping[str, Any],
+        *,
+        receipt_key: str = "owner-gate",
+        external_id: str | None = None,
+    ) -> tuple[Mapping[str, Any], Mapping[str, Any]]:
+        ...
+
+    def close(self) -> None:
+        ...
+
+
+HarnessFactory = Callable[[], StoreHarness]
+
+
+class SqliteStoreHarness:
+    """Reference harness: :class:`SqliteActionStore` on a throwaway path.
+
+    ``store_class`` exists so the suite's own tests can prove the suite
+    CATCHES deliberately broken stores; hosts testing a different store
+    write their own harness instead.
+    """
+
+    def __init__(
+        self,
+        directory: str | None = None,
+        *,
+        store_class: type[SqliteActionStore] = SqliteActionStore,
+    ) -> None:
+        self._temp = (
+            tempfile.mkdtemp(prefix="colony-hostworker-conformance-")
+            if directory is None
+            else None
+        )
+        base = self._temp if directory is None else directory
+        self.clock = ManualClock()
+        self.store = store_class(
+            os.path.join(base, "governed-actions.sqlite3"), clock=self.clock
+        )
+
+    def now(self) -> float:
+        return self.clock.now()
+
+    def advance(self, seconds: float) -> float:
+        return self.clock.advance(seconds)
+
+    def propose(self, *, idempotency_key, source, source_ref, action_type, payload):
+        return self.store.propose(
+            idempotency_key,
+            source,
+            action_type,
+            payload,
+            source_ref=source_ref,
+        )
+
+    def add_gate(self, action_id, evidence, *, receipt_key="owner-gate", external_id=None):
+        return self.store.gate(
+            action_id,
+            evidence,
+            receipt_key=receipt_key,
+            external_id=external_id,
+        )
+
+    def close(self) -> None:
+        self.store.close()
+        if self._temp:
+            shutil.rmtree(self._temp, ignore_errors=True)
+
+
+def sqlite_harness() -> SqliteStoreHarness:
+    """Factory for the reference harness (used by the module runner)."""
+
+    return SqliteStoreHarness()
+
+
+# --------------------------------------------------------------- fixtures
+
+
+def build_intent(
+    *,
+    tool_name: str = "colony_create_commitment",
+    args: Mapping[str, Any] | None = None,
+    seed: str | None = None,
+) -> HermesToolActionIntentV1:
+    """One valid governed intent with a unique call identity per ``seed``."""
+
+    seed = seed or uuid.uuid4().hex[:12]
+    if args is None:
+        args = {"description": "conformance fixture commitment %s" % seed}
+    context = {
+        "api_request_id": "req-%s" % seed,
+        "authority_lane": "owner",
+        "contact_id": "contact-conformance",
+        "platform": "conformance",
+        "sender_id": "owner:conformance",
+        "session_id": "sess-%s" % seed,
+        "task_id": "",
+        "tool_call_id": "call-%s" % seed,
+        "turn_id": "turn-%s" % seed,
+    }
+    return HermesToolActionIntentV1.build(
+        tool_name=tool_name, args=args, context=context
+    )
+
+
+def build_envelope(intent: HermesToolActionIntentV1) -> dict[str, Any]:
+    return {
+        "schema": INTENT_ENVELOPE_SCHEMA,
+        "version": 1,
+        "intent": intent.to_dict(),
+    }
+
+
+def approval_id(seed: str | None = None) -> str:
+    return "APR-" + (seed or uuid.uuid4().hex[:12]).upper()[:12].rjust(12, "0")
+
+
+def delivery_gate_evidence(
+    action: Mapping[str, Any],
+    *,
+    decided_at: float,
+    expires_at: float,
+    approval: str | None = None,
+    decision_id: str | None = None,
+    action_digest: str | None = None,
+) -> dict[str, Any]:
+    """Message-delivery-shaped owner approval evidence bound to ``action``."""
+
+    seed = uuid.uuid4().hex[:8]
+    return {
+        "decision": "approved",
+        "authority": "owner",
+        "decision_id": decision_id or ("decision-%s" % seed),
+        "approval_id": approval or approval_id(),
+        "action_id": action["action_id"],
+        "action_digest": (
+            action["payload_sha256"] if action_digest is None else action_digest
+        ),
+        "revision": 1,
+        "principal": "owner:conformance",
+        "channel": "conformance-channel",
+        "thread_id": "thread-%s" % seed,
+        "event_id": "event-%s" % seed,
+        "event_key": "event-key-%s" % seed,
+        "delivery_id": "delivery-%s" % seed,
+        "delivery_message_id": "message-%s" % seed,
+        "binding_method": "delivered_reply",
+        "decided_at_epoch": float(decided_at),
+        "expires_at_epoch": float(expires_at),
+    }
+
+
+def grant_gate_evidence(
+    action: Mapping[str, Any],
+    *,
+    decided_at: float,
+    expires_at: float,
+    grant_expires_at: float | str,
+    approval: str | None = None,
+    decision_id: str | None = None,
+) -> dict[str, Any]:
+    """Bounded-grant-shaped owner approval evidence bound to ``action``."""
+
+    seed = uuid.uuid4().hex[:8]
+    return {
+        "decision": "approved",
+        "authority": "owner",
+        "decision_id": decision_id or ("decision-%s" % seed),
+        "approval_id": approval or approval_id(),
+        "action_id": action["action_id"],
+        "action_digest": action["payload_sha256"],
+        "revision": 1,
+        "principal": "owner:conformance",
+        "bounded_grant_id": "grant-%s" % seed,
+        "approval_source_request_id": "request-%s" % seed,
+        "bounded_grant_expires_at_epoch": (
+            GRANT_UNLIMITED_SENTINEL
+            if grant_expires_at == GRANT_UNLIMITED_SENTINEL
+            else float(grant_expires_at)
+        ),
+        "binding_method": GRANT_BINDING_METHOD,
+        "decided_at_epoch": float(decided_at),
+        "expires_at_epoch": float(expires_at),
+    }
+
+
+__all__ = (
+    "HarnessFactory",
+    "ManualClock",
+    "SqliteStoreHarness",
+    "StoreHarness",
+    "approval_id",
+    "build_envelope",
+    "build_intent",
+    "delivery_gate_evidence",
+    "grant_gate_evidence",
+    "sqlite_harness",
+)