conseqa 0.1.0__py3-none-any.whl

conseqa/__init__.py

@@ -0,0 +1,67 @@
+"""Conseqa for Python: verify what your agent actually changed.
+
+    from conseqa import Conseqa, load_contract_package
+
+    package = load_contract_package("dist/conseqa")
+    refund = package.contract(
+        "refund.processed", 1,
+        bind_result=lambda reply: {"refundId": reply["id"]},
+    )
+    conseqa = Conseqa(package, sidecar_token=os.environ["CONSEQA_SIDECAR_TOKEN"])
+    reply = conseqa.protect(
+        refund,
+        action_key="ticket-8042-refund",
+        intent={"paymentId": "pay_1001", "amountMinor": 2500, "currency": "USD"},
+        execute=lambda call: create_refund(reference=call.provider_correlation_key),
+    )
+"""
+
+from ._canonical import canonical_json, payload_digest
+from ._client import Conseqa, ExecuteContext
+from ._package import (
+    Classification,
+    Contract,
+    ContractPackage,
+    IntentContext,
+    ambiguous,
+    calculate_build_hash,
+    load_contract_package,
+    not_executed,
+    rejected,
+)
+from ._runner import HttpRunnerTransport
+from ._version import __version__
+from .errors import (
+    ConseqaError,
+    ContractPackageIntegrityError,
+    DuplicateActionError,
+    ProtectionUnavailableError,
+    RunnerRejectedError,
+    RunnerUnavailableError,
+    UnregisteredContractError,
+)
+
+__all__ = [
+    "Classification",
+    "Conseqa",
+    "ConseqaError",
+    "Contract",
+    "ContractPackage",
+    "ContractPackageIntegrityError",
+    "DuplicateActionError",
+    "ExecuteContext",
+    "HttpRunnerTransport",
+    "IntentContext",
+    "ProtectionUnavailableError",
+    "RunnerRejectedError",
+    "RunnerUnavailableError",
+    "UnregisteredContractError",
+    "__version__",
+    "ambiguous",
+    "calculate_build_hash",
+    "canonical_json",
+    "load_contract_package",
+    "not_executed",
+    "payload_digest",
+    "rejected",
+]

conseqa/_canonical.py

@@ -0,0 +1,119 @@
+"""Canonical JSON and hashing, byte for byte what the JavaScript packages produce.
+
+The runner and the hosted service compare digests made by either SDK, so the same value
+must give the same text here as `canonicalJson` gives in `@conseqa/contracts`: keys sorted
+by UTF-16 code unit, no whitespace, strings escaped as `JSON.stringify` escapes them, and
+numbers written as JavaScript writes them.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from decimal import Decimal
+from typing import Any, Union
+
+#: The largest whole number JavaScript carries exactly. A larger one would be rounded on
+#: its way through the runner, so the digest made here would describe a different value.
+MAX_SAFE_INTEGER = 2**53 - 1
+
+
+def _utf16_units(key: str) -> bytes:
+    return key.encode("utf-16-be", "surrogatepass")
+
+
+def _string(value: str, path: str) -> str:
+    for character in value:
+        if 0xD800 <= ord(character) <= 0xDFFF:
+            raise TypeError(f"Text with an unpaired surrogate at {path}")
+    # json.dumps escapes exactly what JSON.stringify escapes: the quote, the backslash and
+    # the control characters below U+0020, with the same short forms and lowercase hex.
+    return json.dumps(value, ensure_ascii=False)
+
+
+def _number(value: float, path: str) -> str:
+    """A double the way ECMAScript's Number::toString writes it."""
+    if math.isnan(value) or math.isinf(value):
+        raise TypeError(f"Canonical JSON cannot contain NaN or Infinity (at {path})")
+    if value == 0:
+        return "0"
+    # repr() gives the shortest digits that read back as the same double, as JavaScript does.
+    sign, digits, exponent = Decimal(repr(value)).as_tuple()
+    text = "".join(str(digit) for digit in digits).lstrip("0") or "0"
+    stripped = text.rstrip("0")
+    exponent = int(exponent) + (len(text) - len(stripped))
+    text = stripped
+    count = len(text)
+    point = count + exponent  # how many digits stand before the decimal point
+    if count <= point <= 21:
+        body = text + "0" * (point - count)
+    elif 0 < point <= 21:
+        body = f"{text[:point]}.{text[point:]}"
+    elif -6 < point <= 0:
+        body = "0." + "0" * (-point) + text
+    else:
+        power = point - 1
+        mantissa = text if count == 1 else f"{text[0]}.{text[1:]}"
+        body = f"{mantissa}e{'+' if power >= 0 else '-'}{abs(power)}"
+    return f"-{body}" if sign else body
+
+
+def canonical_json(value: Any) -> str:
+    """Stable JSON text for a JSON value. Anything that is not plain JSON is refused."""
+    seen: set[int] = set()
+
+    def visit(candidate: Any, path: str) -> str:
+        if candidate is None:
+            return "null"
+        if candidate is True:
+            return "true"
+        if candidate is False:
+            return "false"
+        if isinstance(candidate, str):
+            return _string(candidate, path)
+        if isinstance(candidate, int):
+            if abs(candidate) > MAX_SAFE_INTEGER:
+                raise TypeError(
+                    f"Whole number at {path} is too large to carry exactly; send it as text"
+                )
+            return str(candidate)
+        if isinstance(candidate, float):
+            return _number(candidate, path)
+        if isinstance(candidate, (list, tuple, dict)):
+            if id(candidate) in seen:
+                raise TypeError(f"Circular value at {path}")
+            seen.add(id(candidate))
+            try:
+                if isinstance(candidate, dict):
+                    for key in candidate:
+                        if not isinstance(key, str):
+                            raise TypeError(f"Key that is not text at {path}")
+                    return (
+                        "{"
+                        + ",".join(
+                            f"{_string(key, path)}:{visit(candidate[key], f'{path}.{key}')}"
+                            for key in sorted(candidate, key=_utf16_units)
+                        )
+                        + "}"
+                    )
+                return (
+                    "["
+                    + ",".join(visit(item, f"{path}[{index}]") for index, item in enumerate(candidate))
+                    + "]"
+                )
+            finally:
+                seen.discard(id(candidate))
+        raise TypeError(f"Value that is not JSON at {path}: {type(candidate).__name__}")
+
+    return visit(value, "$")
+
+
+def sha256_hex(value: Union[str, bytes]) -> str:
+    data = value.encode("utf-8") if isinstance(value, str) else value
+    return hashlib.sha256(data).hexdigest()
+
+
+def payload_digest(intent: Any) -> str:
+    """The digest of an intent, as every SDK and the runner compute it."""
+    return sha256_hex(canonical_json(intent))

conseqa/_client.py

@@ -0,0 +1,512 @@
+"""`Conseqa.protect`: record what a call is meant to do, make the call, report how it ended.
+
+This follows the JavaScript SDK step for step, and sends the runner the same requests:
+
+1. Register the intent. A required action that cannot be registered is not made.
+2. Record that the call is about to start.
+3. Make the call. Whatever it returns or raises is what `protect` returns or raises.
+4. Report how it ended: what it returned and what identifies the result, or what the
+   exception proves.
+
+The runner does the rest: it reads the system of record and decides the verdict.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import threading
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, Mapping, Optional, Union
+
+from ._canonical import canonical_json, payload_digest
+from ._package import Classification, Contract, ContractPackage, IntentContext
+from ._runner import HttpRunnerTransport
+from ._telemetry import OperationTelemetry, SignalHandler
+from ._version import __version__
+from .errors import (
+    DuplicateActionError,
+    ProtectionUnavailableError,
+    RunnerRejectedError,
+    UnregisteredContractError,
+)
+
+JsonObject = Dict[str, Any]
+SDK_NAME = "conseqa-python"
+
+
+@dataclass(frozen=True)
+class ExecuteContext:
+    """What the protected call is given."""
+
+    #: The reference to send with the call, so its record can be found by it afterwards.
+    provider_correlation_key: str
+
+
+def _iso(moment: datetime) -> str:
+    if moment.tzinfo is None:
+        raise ValueError("A time without a zone is ambiguous; use a timezone-aware datetime")
+    text = moment.astimezone(timezone.utc).isoformat(timespec="milliseconds")
+    return text.replace("+00:00", "Z")
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _new_id() -> str:
+    return str(uuid.uuid4())
+
+
+@dataclass
+class _Run:
+    contract: Contract
+    mode: str
+    action_key: str
+    intent_id: str
+    registration: JsonObject
+    context: ExecuteContext
+    telemetry: OperationTelemetry
+
+
+class Conseqa:
+    """The client an application keeps for as long as it runs."""
+
+    def __init__(
+        self,
+        package: ContractPackage,
+        *,
+        runner_url: str = "http://127.0.0.1:4319",
+        sidecar_token: Optional[str] = None,
+        runner: Any = None,
+        runtime_heartbeat_interval: float = 30.0,
+        instance_id: Optional[str] = None,
+        on_signal: Optional[SignalHandler] = None,
+        clock: Optional[Callable[[], datetime]] = None,
+        id_factory: Optional[Callable[[], str]] = None,
+    ) -> None:
+        """
+        `package` comes from `load_contract_package`. `runner_url` and `sidecar_token` say
+        where the runner listens and what it expects; `runner` replaces them with a
+        transport of your own. `runtime_heartbeat_interval` is how often, in seconds, the
+        application tells the runner which contract build it runs; 0 switches that off.
+        """
+        if not isinstance(package, ContractPackage):
+            raise TypeError("package must come from load_contract_package")
+        if runner is not None and sidecar_token is not None:
+            raise TypeError("sidecar_token cannot be used with a runner transport of your own")
+        if instance_id is not None:
+            try:
+                instance_id = str(uuid.UUID(instance_id))
+            except (ValueError, AttributeError, TypeError) as error:
+                raise TypeError(
+                    "instance_id must be an opaque UUID, not a host name or a person"
+                ) from error
+        if runtime_heartbeat_interval < 0:
+            raise TypeError("runtime_heartbeat_interval must be zero or positive")
+        self._package = package
+        self._runner = runner or HttpRunnerTransport(runner_url, sidecar_token=sidecar_token)
+        self._on_signal = on_signal
+        self._clock = clock or _now
+        self._new_id = id_factory or _new_id
+        self.instance_id = instance_id or _new_id()
+        self._heartbeat_interval = float(runtime_heartbeat_interval)
+        self._closed = threading.Event()
+        self._heartbeat_thread: Optional[threading.Thread] = None
+        if self._heartbeat_interval > 0 and hasattr(self._runner, "report_runtime_instance"):
+            self._heartbeat_thread = threading.Thread(
+                target=self._heartbeats, name="conseqa-heartbeat", daemon=True
+            )
+            self._heartbeat_thread.start()
+
+    # ---------------------------------------------------------------- lifecycle of the client
+
+    def close(self) -> None:
+        """Stops the background report of which build this application runs."""
+        self._closed.set()
+
+    def __enter__(self) -> "Conseqa":
+        return self
+
+    def __exit__(self, *_exc: Any) -> None:
+        self.close()
+
+    def _heartbeats(self) -> None:
+        while not self._closed.is_set():
+            try:
+                self._runner.report_runtime_instance(
+                    {
+                        "instanceId": self.instance_id,
+                        "buildHash": self._package.build_hash,
+                        "packageName": self._package.package_name,
+                        "packageVersion": self._package.package_version,
+                        "observedAt": _iso(self._clock()),
+                    }
+                )
+            except Exception:
+                pass  # a diagnostic report must never get in the way of the application
+            self._closed.wait(self._heartbeat_interval)
+
+    # ------------------------------------------------------------------------------- protect
+
+    def protect(
+        self,
+        contract: Contract,
+        *,
+        action_key: str,
+        intent: Mapping[str, Any],
+        execute: Callable[[ExecuteContext], Any],
+        mode: str = "required",
+        deadline_at: Union[datetime, str, None] = None,
+    ) -> Any:
+        """Makes one protected call and returns what it returned.
+
+        `action_key` is one stable key for the business operation, such as the ticket or
+        order it belongs to. `intent` is what the call is meant to do, in the shape of the
+        contract's intent schema. `execute` is the call you already make; it is given the
+        reference to send with it. With `mode="required"` the call is not made unless the
+        intent was recorded first; with `"best_effort"` it goes ahead anyway and shows as
+        an unprotected gap.
+        """
+        if inspect.iscoroutinefunction(execute):
+            raise TypeError("execute is a coroutine function; use protect_async")
+        run = self._begin(contract, action_key, intent, mode, deadline_at)
+        with run.telemetry.active():
+            if not (self._register(run) and self._authorize(run)):
+                return self._unprotected(run, lambda: execute(run.context))
+            try:
+                result = execute(run.context)
+            except BaseException as error:
+                self._after_exception(run, error)
+                raise
+            if inspect.isawaitable(result):
+                # The call was never made: what came back is a promise to make it.
+                closer = getattr(result, "close", None)
+                if callable(closer):
+                    closer()
+                self._report(
+                    run,
+                    self._event(
+                        run,
+                        2,
+                        "action.exception",
+                        classification=Classification(
+                            "not_executed", False, "awaitable_in_protect"
+                        ).as_json(),
+                    ),
+                )
+                run.telemetry.fail()
+                run.telemetry.end()
+                raise TypeError("execute returned an awaitable; use protect_async")
+            self._after_return(run, result)
+            return result
+
+    async def protect_async(
+        self,
+        contract: Contract,
+        *,
+        action_key: str,
+        intent: Mapping[str, Any],
+        execute: Callable[[ExecuteContext], Any],
+        mode: str = "required",
+        deadline_at: Union[datetime, str, None] = None,
+    ) -> Any:
+        """`protect` for an application that runs on asyncio. `execute` may be a coroutine."""
+        run = self._begin(contract, action_key, intent, mode, deadline_at)
+        with run.telemetry.active():
+            registered = await asyncio.to_thread(self._register, run)
+            if not (registered and await asyncio.to_thread(self._authorize, run)):
+
+                async def unprotected() -> Any:
+                    outcome = execute(run.context)
+                    return await outcome if inspect.isawaitable(outcome) else outcome
+
+                try:
+                    result = await unprotected()
+                except BaseException:
+                    run.telemetry.fail()
+                    run.telemetry.end()
+                    raise
+                run.telemetry.end()
+                return result
+            try:
+                result = execute(run.context)
+                if inspect.isawaitable(result):
+                    result = await result
+            except BaseException as error:
+                # Shielded: a task cancelled in the middle of a call must still say so.
+                await asyncio.shield(asyncio.to_thread(self._after_exception, run, error))
+                raise
+            await asyncio.to_thread(self._after_return, run, result)
+            return result
+
+    # ------------------------------------------------------------------------------- observe
+
+    def observe(
+        self, operation: str, execute: Callable[[], Any], *, action_key: Optional[str] = None
+    ) -> Any:
+        """Runs a call without protecting it, and marks it as one that could have been.
+
+        Coverage is the share of an operation's runs that were protected. This is how the
+        runs that were not get counted. It needs the application to have OpenTelemetry.
+        """
+        del action_key  # accepted for parity with the JavaScript SDK; never sent anywhere
+        telemetry = OperationTelemetry(operation, self._on_signal)
+        telemetry.emit(
+            "conseqa.unprotected.observed",
+            protection_level="NONE",
+            attributes={"explicitly_eligible": True},
+        )
+        with telemetry.active():
+            try:
+                result = execute()
+            except BaseException:
+                telemetry.fail()
+                telemetry.end()
+                raise
+        telemetry.end()
+        return result
+
+    # ----------------------------------------------------------------------------- the steps
+
+    def _begin(
+        self,
+        contract: Contract,
+        action_key: str,
+        intent: Mapping[str, Any],
+        mode: str,
+        deadline_at: Union[datetime, str, None],
+    ) -> _Run:
+        if not isinstance(contract, Contract) or contract._package is not self._package:
+            raise UnregisteredContractError(
+                "The contract did not come from the package this client was given"
+            )
+        if mode not in ("required", "best_effort"):
+            raise ValueError('mode must be "required" or "best_effort"')
+        if not isinstance(action_key, str) or not 1 <= len(action_key) <= 512:
+            raise ValueError("action_key must be text of 1 to 512 characters")
+        if not isinstance(intent, Mapping):
+            raise TypeError("intent must be a JSON object")
+        intent_body: JsonObject = dict(intent)
+        digest = payload_digest(intent_body)  # also refuses anything that is not JSON
+        intent_id = self._new_id()
+        correlation = contract.correlation_key(
+            IntentContext(action_key=action_key, intent_id=intent_id, intent=intent_body)
+        )
+        if not isinstance(correlation, str) or not 1 <= len(correlation) <= 256:
+            raise ValueError("The correlation key must be text of 1 to 256 characters")
+        telemetry = OperationTelemetry(contract.operation, self._on_signal)
+        registration: JsonObject = {
+            "intentId": intent_id,
+            "actionKey": action_key,
+            "operation": contract.operation,
+            "protectionMode": mode,
+            "protectionLevel": contract.protection_level,
+            "contract": {
+                "name": contract.name,
+                "version": contract.version,
+                "buildHash": contract.build_hash,
+            },
+            "providerCorrelationKey": correlation,
+            "intent": intent_body,
+            "payloadDigest": digest,
+            "registeredAt": _iso(self._clock()),
+            "sdk": {"name": SDK_NAME, "version": __version__, "instanceId": self.instance_id},
+        }
+        if deadline_at is not None:
+            registration["deadlineAt"] = (
+                _iso(deadline_at)
+                if isinstance(deadline_at, datetime)
+                else _iso(datetime.fromisoformat(deadline_at.replace("Z", "+00:00")))
+            )
+        trace_context = telemetry.trace_context
+        if trace_context:
+            registration["traceContext"] = trace_context
+        return _Run(
+            contract=contract,
+            mode=mode,
+            action_key=action_key,
+            intent_id=intent_id,
+            registration=registration,
+            context=ExecuteContext(provider_correlation_key=correlation),
+            telemetry=telemetry,
+        )
+
+    def _event(self, run: _Run, sequence: int, kind: str, **fields: Any) -> JsonObject:
+        return {
+            "eventId": self._new_id(),
+            "intentId": run.intent_id,
+            "sequence": sequence,
+            "occurredAt": _iso(self._clock()),
+            "type": kind,
+            **fields,
+        }
+
+    def _send(self, run: _Run, event: JsonObject) -> Optional[BaseException]:
+        """Sends one event. Returns what went wrong, or None."""
+        try:
+            self._runner.append_event(event)
+            return None
+        except Exception as error:
+            return error
+
+    def _register(self, run: _Run) -> bool:
+        """True when the intent is recorded. False when the call may go ahead unprotected."""
+        telemetry = run.telemetry
+        level = run.contract.protection_level
+        failure: Optional[BaseException] = None
+        acknowledged: Optional[JsonObject] = None
+        try:
+            acknowledged = self._runner.register_intent(run.registration)
+            if not acknowledged["contractHashValidated"]:
+                failure = RunnerRejectedError(
+                    "Runner did not validate the exact contract build hash", 409
+                )
+        except Exception as error:
+            failure = error
+
+        if acknowledged and acknowledged["status"] == "duplicate":
+            telemetry.emit(
+                "conseqa.intent.duplicate", intent_id=acknowledged["intentId"], protection_level=level
+            )
+            telemetry.fail()
+            telemetry.end()
+            raise DuplicateActionError(
+                f"Action key {run.action_key} is already registered; "
+                "execution stopped before dispatch",
+                acknowledged["intentId"],
+                acknowledged["providerCorrelationKey"],
+            )
+        if acknowledged and failure is None and (
+            acknowledged["intentId"] != run.intent_id
+            or acknowledged["providerCorrelationKey"] != run.context.provider_correlation_key
+        ):
+            telemetry.fail()
+            telemetry.end()
+            raise ProtectionUnavailableError(
+                "Runner acknowledgement did not match the newly registered intent; execution stopped"
+            )
+        if failure is not None:
+            telemetry.emit(
+                "conseqa.protection.gap",
+                intent_id=run.intent_id,
+                protection_level="NONE",
+                attributes={"phase": "intent_registration", "mode": run.mode},
+            )
+            if run.mode == "required":
+                telemetry.fail()
+                telemetry.end()
+                raise ProtectionUnavailableError(
+                    "Required Conseqa intent could not be durably registered"
+                ) from failure
+            return False
+        telemetry.emit(
+            "conseqa.intent.registered",
+            intent_id=run.intent_id,
+            protection_level=level,
+            attributes={"durable_via": "runner"},
+        )
+        return True
+
+    def _authorize(self, run: _Run) -> bool:
+        """Records that the call is about to start. False: go ahead unprotected."""
+        telemetry = run.telemetry
+        failure = self._send(run, self._event(run, 1, "dispatch.authorized"))
+        if failure is None:
+            telemetry.emit(
+                "conseqa.dispatch.authorized",
+                intent_id=run.intent_id,
+                protection_level=run.contract.protection_level,
+                attributes={"durable_via": "runner"},
+            )
+            return True
+        telemetry.emit(
+            "conseqa.protection.gap",
+            intent_id=run.intent_id,
+            protection_level="NONE",
+            attributes={"phase": "dispatch_authorization", "mode": run.mode},
+        )
+        if run.mode == "required":
+            self._send(
+                run,
+                self._event(
+                    run,
+                    2,
+                    "action.abandoned",
+                    reason="Required dispatch authorization could not be durably recorded",
+                ),
+            )
+            telemetry.fail()
+            telemetry.end()
+            raise ProtectionUnavailableError(
+                "Required Conseqa dispatch could not be durably authorized"
+            ) from failure
+        return False
+
+    def _unprotected(self, run: _Run, call: Callable[[], Any]) -> Any:
+        try:
+            result = call()
+        except BaseException:
+            run.telemetry.fail()
+            run.telemetry.end()
+            raise
+        run.telemetry.end()
+        return result
+
+    def _report(self, run: _Run, event: JsonObject) -> None:
+        if self._send(run, event) is not None:
+            run.telemetry.emit(
+                "conseqa.lifecycle.persistence_failed",
+                protection_level="PARTIAL",
+                attributes={"phase": event["type"]},
+            )
+
+    def _after_exception(self, run: _Run, error: BaseException) -> None:
+        try:
+            classification = run.contract.classify_exception(error)
+            if not isinstance(classification, Classification):
+                raise TypeError("classify_exception must return a Classification")
+        except Exception:
+            # A classifier that fails has told us nothing, which is what ambiguous means.
+            classification = Classification(
+                "ambiguous",
+                False,
+                "classification_failed",
+                "The contract exception classifier failed",
+            )
+        self._report(
+            run, self._event(run, 2, "action.exception", classification=classification.as_json())
+        )
+        run.telemetry.fail()
+        run.telemetry.end()
+
+    def _after_return(self, run: _Run, result: Any) -> None:
+        binding: Optional[JsonObject] = None
+        binding_failure: Optional[str] = None
+        try:
+            candidate = run.contract.bind_result(result)
+            if candidate is None:
+                binding_failure = "The provider result did not contain a usable binding"
+            else:
+                binding = dict(candidate)
+                canonical_json(binding)  # a binding is a JSON object or it is nothing
+        except Exception:
+            binding = None
+            binding_failure = "The contract could not bind the provider result"
+
+        returned = self._event(run, 2, "action.returned", disposition="success")
+        if binding is not None:
+            returned["binding"] = binding
+        self._report(run, returned)
+        if binding_failure:
+            self._report(run, self._event(run, 3, "binding.failed", reason=binding_failure))
+        elif binding is not None:
+            run.telemetry.emit(
+                "conseqa.result.bound",
+                intent_id=run.intent_id,
+                protection_level=run.contract.protection_level,
+            )
+        run.telemetry.end()
+