base.py 1.5 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455
  1. """Resolver protocols and the results of the two non-passive tiers.
  2. `locate` reads file metadata only. `inspect` may open files and call OS APIs in-process.
  3. `probe` is fresh, never cached, and the only tier that may open a socket or spawn.
  4. """
  5. from __future__ import annotations
  6. from dataclasses import dataclass
  7. from enum import Enum
  8. from typing import Protocol, runtime_checkable
  9. from hermes_platform.resolver.core import LookupContext, Observation, Resolution
  10. class Effort(Enum):
  11. """What `probe` may do. `NETWORK` never implies subprocess; `DIAGNOSTIC` alone may spawn."""
  12. LOCAL = "local"
  13. NETWORK = "network"
  14. DIAGNOSTIC = "diagnostic"
  15. @dataclass(frozen=True)
  16. class Inspection:
  17. version: Observation[str]
  18. signer: Observation[str]
  19. @property
  20. def ok(self) -> bool:
  21. return self.version.state.value != "error" and self.signer.state.value != "error"
  22. @dataclass(frozen=True)
  23. class Probe:
  24. running: Observation[bool]
  25. answering: Observation[bool]
  26. endpoint: Observation[str]
  27. def __bool__(self) -> bool: # pragma: no cover - the raise is the behavior
  28. raise TypeError("Probe is not a boolean; read .running/.answering")
  29. @runtime_checkable
  30. class Resolver(Protocol):
  31. name: str
  32. def locate(self, ctx: LookupContext | None = None) -> Resolution: ...
  33. def inspect(self, res: Resolution, ctx: LookupContext | None = None) -> Inspection: ...
  34. @runtime_checkable
  35. class Probeable(Resolver, Protocol):
  36. def probe(self, res: Resolution, *, effort: Effort, deadline_s: float = 3.0) -> Probe: ...