flayer.diagnostics.contracts

Module source

flayer.diagnostics.contracts

Provider-independent diagnostic results and output safety contracts.

REDACTED module-attribute

REDACTED = '[redacted]'

SECRET_KEY module-attribute

SECRET_KEY = re.compile('password|passwd|secret|token|credential|authorization|cookie|private.?key|api.?key|ssh.?key|client.?key|access.?key|refresh.?key', re.IGNORECASE)

SECRET_VALUE module-attribute

SECRET_VALUE = re.compile('(?:bearer\\s+\\S+|-----BEGIN[^\\n]*PRIVATE KEY-----[\\s\\S]*|(?:password|passwd|secret|token|api[_-]?key)\\s*[=:][^\\n]*|https?://[^\\s]*|(?:\\d{1,3}\\.){3}\\d{1,3})', re.IGNORECASE)

SAFE_KEY module-attribute

SAFE_KEY = re.compile('[A-Za-z_][A-Za-z0-9_]{0,63}\\Z')

STATUS_PRIORITY module-attribute

STATUS_PRIORITY = {DiagnosticStatus.OK: 0, DiagnosticStatus.WARNING: 1, DiagnosticStatus.UNSUPPORTED: 2, DiagnosticStatus.STALE: 3, DiagnosticStatus.FAILED: 4}

EXIT_CODES module-attribute

EXIT_CODES = {DiagnosticStatus.OK: 0, DiagnosticStatus.WARNING: 1, DiagnosticStatus.FAILED: 1, DiagnosticStatus.STALE: 3, DiagnosticStatus.UNSUPPORTED: 4}

DiagnosticStatus

Bases: str, Enum

Stable outcomes distinguish failure, expired evidence, and missing support.

OK class-attribute instance-attribute

OK = 'ok'

WARNING class-attribute instance-attribute

WARNING = 'warning'

FAILED class-attribute instance-attribute

FAILED = 'failed'

STALE class-attribute instance-attribute

STALE = 'stale'

UNSUPPORTED class-attribute instance-attribute

UNSUPPORTED = 'unsupported'

CheckResult dataclass

CheckResult(name: str, status: DiagnosticStatus, message: str, details: Mapping[str, object] = dict())

One diagnostic observation with details that are sanitized at serialization.

name instance-attribute

name: str

status instance-attribute

status: DiagnosticStatus

message instance-attribute

message: str

details class-attribute instance-attribute

details: Mapping[str, object] = field(default_factory=dict)

AsDict

AsDict() -> dict[str, object]

Return stable JSON-compatible fields without arbitrary raw provider output.

源代码位于： installed/flayer/diagnostics/contracts.py

def AsDict(self) -> dict[str, object]:
    """Return stable JSON-compatible fields without arbitrary raw provider output."""

    return {
        "name": Redact(self.name),
        "status": self.status.value,
        "message": Redact(self.message),
        "details": Redact(self.details),
    }

DiagnosticReport dataclass

DiagnosticReport(command: str, checks: tuple[CheckResult, ...])

Versioned report whose aggregate outcome never hides failed checks.

command instance-attribute

command: str

checks instance-attribute

checks: tuple[CheckResult, ...]

Status property

Status: DiagnosticStatus

Return the most severe result, treating an empty report as unsupported.

ExitCode

ExitCode() -> int

Return zero only when every requested observation succeeds.

源代码位于： installed/flayer/diagnostics/contracts.py

def ExitCode(self) -> int:
    """Return zero only when every requested observation succeeds."""

    return EXIT_CODES[self.Status]

AsDict

AsDict() -> dict[str, object]

Expose the report schema and sanitized observations in deterministic order.

源代码位于： installed/flayer/diagnostics/contracts.py

def AsDict(self) -> dict[str, object]:
    """Expose the report schema and sanitized observations in deterministic order."""

    return {
        "schema_version": 1,
        "command": Redact(self.command),
        "status": self.Status.value,
        "checks": [check.AsDict() for check in self.checks],
    }

Redact

Redact(value: object, _depth: int = 0) -> object

Recursively redact credential fields and common sensitive text before output.

源代码位于： installed/flayer/diagnostics/contracts.py

def Redact(value: object, _depth: int = 0) -> object:
    """Recursively redact credential fields and common sensitive text before output."""

    if _depth >= 16:
        return REDACTED

    if isinstance(value, Mapping):
        sanitized: dict[str, object] = {}

        for key, item in value.items():
            sensitive = not isinstance(key, str) or bool(SECRET_KEY.search(key))
            safe_key = key if isinstance(key, str) and SAFE_KEY.fullmatch(key) else REDACTED

            if sensitive:
                safe_key = REDACTED

            candidate = safe_key
            suffix = 2

            while candidate in sanitized:
                candidate = f"{safe_key}:{suffix}"
                suffix += 1

            sanitized[candidate] = REDACTED if sensitive else Redact(item, _depth + 1)

        return sanitized

    if isinstance(value, str):
        return SECRET_VALUE.sub(REDACTED, value)

    if isinstance(value, Sequence) and not isinstance(value, (bytes, bytearray)):
        return [Redact(item, _depth + 1) for item in value]

    if isinstance(value, bool) or value is None or isinstance(value, int):
        return value

    if isinstance(value, float):
        return value if math.isfinite(value) else None

    return REDACTED