inspector

inspector

Runtime-neutral container introspection abstraction.

Clearance renders notifications for every container the firewall touches, regardless of which runtime created it (podman today; a future krun / docker / containerd backend tomorrow). The translation from container id to ContainerInfo is therefore expressed here as a pure ContainerInspector protocol; the concrete backend that knows how to talk to a specific runtime lives in terok-sandbox, where runtime selection is owned.

NullInspector ships as a safe default: deployments without any runtime-aware package installed (clearance standalone, test rigs) still boot; notifications just carry raw container ids.

ContainerInspector

Bases: Protocol

Callable that maps a container id to a ContainerInfo.

The protocol intentionally covers only the notification-rendering use case — name + OCI annotations + lifecycle state. Broader runtime operations (exec, mount, signals) live on terok_sandbox.runtime.ContainerRuntime and are not part of this contract.

Implementations MUST soft-fail: an unreachable runtime / missing container / malformed metadata returns an empty ContainerInfo rather than raising, so notification pipelines keep their fallback label instead of crashing on a lookup hiccup.

__call__(container_id)

Return the best-effort ContainerInfo for container_id.

Source code in src/terok_clearance/domain/inspector.py

def __call__(self, container_id: str) -> ContainerInfo:
    """Return the best-effort [`ContainerInfo`][terok_clearance.ContainerInfo] for *container_id*."""
    ...

NullInspector

Always-empty ContainerInspector — the graceful-degradation default.

Installed when no runtime-aware package provides a concrete backend. Every lookup returns ContainerInfo() so the notifier still renders (raw container id, no enrichment).

__call__(_container_id)

Return the universal empty ContainerInfo.

Source code in src/terok_clearance/domain/inspector.py

def __call__(self, _container_id: str) -> ContainerInfo:
    """Return the universal empty [`ContainerInfo`][terok_clearance.ContainerInfo]."""
    return ContainerInfo()