f-layer 2.0.0__py3-none-any.whl

flayer/diagnostics/contracts.py

@@ -0,0 +1,167 @@
+"""Provider-independent diagnostic results and output safety contracts."""
+
+from __future__ import annotations
+
+import math
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from enum import Enum
+
+REDACTED = "[redacted]"
+SECRET_KEY = re.compile(
+    r"password|passwd|secret|token|credential|authorization|cookie|private.?key|api.?key|"
+    r"ssh.?key|client.?key|access.?key|refresh.?key",
+    re.IGNORECASE,
+)
+SECRET_VALUE = re.compile(
+    r"(?:bearer\s+\S+|-----BEGIN[^\n]*PRIVATE KEY-----[\s\S]*|"
+    r"(?:password|passwd|secret|token|api[_-]?key)\s*[=:][^\n]*|"
+    r"https?://[^\s]*|(?:\d{1,3}\.){3}\d{1,3})",
+    re.IGNORECASE,
+)
+SAFE_KEY = re.compile(r"[A-Za-z_][A-Za-z0-9_]{0,63}\Z")
+
+
+class DiagnosticStatus(str, Enum):
+    """Stable outcomes distinguish failure, expired evidence, and missing support."""
+
+    OK = "ok"
+    WARNING = "warning"
+    FAILED = "failed"
+    STALE = "stale"
+    UNSUPPORTED = "unsupported"
+
+
+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
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    """One diagnostic observation with details that are sanitized at serialization."""
+
+    name: str
+    status: DiagnosticStatus
+    message: str
+    details: Mapping[str, object] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        """Reject malformed adapter results before they can break report rendering."""
+
+        if (
+            not isinstance(self.name, str)
+            or not self.name
+            or not isinstance(self.status, DiagnosticStatus)
+            or not isinstance(self.message, str)
+            or not isinstance(self.details, Mapping)
+        ):
+            raise ValueError("Diagnostic check fields do not match the result contract")
+
+    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),
+        }
+
+
+STATUS_PRIORITY = {
+    DiagnosticStatus.OK: 0,
+    DiagnosticStatus.WARNING: 1,
+    DiagnosticStatus.UNSUPPORTED: 2,
+    DiagnosticStatus.STALE: 3,
+    DiagnosticStatus.FAILED: 4,
+}
+EXIT_CODES = {
+    DiagnosticStatus.OK: 0,
+    DiagnosticStatus.WARNING: 1,
+    DiagnosticStatus.FAILED: 1,
+    DiagnosticStatus.STALE: 3,
+    DiagnosticStatus.UNSUPPORTED: 4,
+}
+
+
+@dataclass(frozen=True)
+class DiagnosticReport:
+    """Versioned report whose aggregate outcome never hides failed checks."""
+
+    command: str
+    checks: tuple[CheckResult, ...]
+
+    def __post_init__(self) -> None:
+        """Keep report aggregation predictable and reject malformed public inputs."""
+
+        if (
+            not isinstance(self.command, str)
+            or not self.command
+            or not isinstance(self.checks, tuple)
+            or not all(isinstance(check, CheckResult) for check in self.checks)
+        ):
+            raise ValueError("Diagnostic report fields do not match the report contract")
+
+    @property
+    def Status(self) -> DiagnosticStatus:
+        """Return the most severe result, treating an empty report as unsupported."""
+
+        return max(
+            (check.status for check in self.checks),
+            key=STATUS_PRIORITY.__getitem__,
+            default=DiagnosticStatus.UNSUPPORTED,
+        )
+
+    def ExitCode(self) -> int:
+        """Return zero only when every requested observation succeeds."""
+
+        return EXIT_CODES[self.Status]
+
+    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],
+        }

flayer/diagnostics/health.py

@@ -0,0 +1,154 @@
+"""Injected health probes and freshness validation without cloud access assumptions."""
+
+from __future__ import annotations
+
+import math
+import sys
+import time
+from collections.abc import Iterable, Mapping
+from typing import Protocol
+
+from .contracts import CheckResult, DiagnosticStatus
+
+
+class HealthProbe(Protocol):
+    """An adapter supplies read-only observations without transferring authorization."""
+
+    def __call__(self) -> CheckResult:
+        """Perform an adapter-bounded probe and return one structured observation."""
+
+        ...
+
+
+def RuntimeChecks() -> tuple[CheckResult, ...]:
+    """Check only supported Python execution; never imply remote infrastructure health."""
+
+    supported = sys.version_info >= (3, 11)
+
+    return (
+        CheckResult(
+            "python-runtime",
+            DiagnosticStatus.OK if supported else DiagnosticStatus.FAILED,
+            "Python runtime is supported" if supported else "Python 3.11 or newer is required",
+            {"version": ".".join(str(part) for part in sys.version_info[:3])},
+        ),
+    )
+
+
+def RunChecks(probes: Iterable[HealthProbe]) -> tuple[CheckResult, ...]:
+    """Collect injected observations and suppress raw exception text on probe failure."""
+
+    checks: list[CheckResult] = []
+
+    for probe in probes:
+        try:
+            result = probe()
+
+            if not isinstance(result, CheckResult):
+                raise TypeError("Probe must return CheckResult")
+
+            checks.append(result)
+
+        except Exception:
+            checks.append(CheckResult(
+                "probe", DiagnosticStatus.FAILED, "Probe failed without safe structured evidence"
+            ))
+
+    if not checks:
+        checks.append(CheckResult(
+            "probe", DiagnosticStatus.UNSUPPORTED, "No health probe was supplied"
+        ))
+
+    return tuple(checks)
+
+
+def ProviderStatus(observation: Mapping[str, object] | None = None) -> CheckResult:
+    """Interpret a supplied generic provider observation without discovering resources."""
+
+    if observation is None:
+        return CheckResult(
+            "provider-state", DiagnosticStatus.UNSUPPORTED, "No provider observation was supplied"
+        )
+
+    if not isinstance(observation, Mapping):
+        return CheckResult(
+            "provider-state", DiagnosticStatus.FAILED, "Provider observation must be a mapping"
+        )
+
+    state = observation.get("state")
+
+    if state not in ("ready", "pending", "failed", "absent"):
+        return CheckResult(
+            "provider-state", DiagnosticStatus.FAILED, "Provider observation has an invalid state"
+        )
+
+    status = {
+        "ready": DiagnosticStatus.OK,
+        "pending": DiagnosticStatus.WARNING,
+        "failed": DiagnosticStatus.FAILED,
+        "absent": DiagnosticStatus.FAILED,
+    }[str(state)]
+
+    return CheckResult("provider-state", status, "Provider state observed", {"state": state})
+
+
+def EvaluateHealthReport(
+    report: Mapping[str, object] | None,
+    max_age_seconds: float = 300,
+    current_time: float | None = None,
+) -> CheckResult:
+    """Validate versioned health evidence and separate stale evidence from failed health."""
+
+    now = time.time() if current_time is None else current_time
+
+    if (
+        isinstance(max_age_seconds, bool)
+        or not isinstance(max_age_seconds, (int, float))
+        or not math.isfinite(max_age_seconds)
+        or max_age_seconds <= 0
+        or isinstance(now, bool)
+        or not isinstance(now, (int, float))
+        or not math.isfinite(now)
+    ):
+        raise ValueError("Health freshness bounds must be finite and positive")
+
+    if report is None:
+        return CheckResult(
+            "health-report", DiagnosticStatus.UNSUPPORTED, "No health report was supplied"
+        )
+
+    if not isinstance(report, Mapping):
+        return CheckResult(
+            "health-report", DiagnosticStatus.FAILED, "Health report must be a mapping"
+        )
+
+    if type(report.get("schema_version")) is not int or report.get("schema_version") != 1:
+        return CheckResult(
+            "health-report", DiagnosticStatus.UNSUPPORTED, "Health report schema is unsupported"
+        )
+
+    timestamp = report.get("timestamp")
+    outcome = report.get("status")
+
+    if (
+        isinstance(timestamp, bool)
+        or not isinstance(timestamp, (int, float))
+        or not math.isfinite(timestamp)
+        or outcome not in ("ok", "warning", "failed")
+    ):
+        return CheckResult(
+            "health-report", DiagnosticStatus.FAILED, "Health report fields are invalid"
+        )
+
+    age = now - timestamp
+    details: dict[str, object] = {"age_seconds": age, "max_age_seconds": max_age_seconds}
+
+    if age < 0 or age > max_age_seconds:
+        return CheckResult(
+            "health-report", DiagnosticStatus.STALE,
+            "Health report is expired or dated in the future", details,
+        )
+
+    return CheckResult(
+        "health-report", DiagnosticStatus(str(outcome)), "Health report is current", details
+    )

flayer/diagnostics/reporting.py

@@ -0,0 +1,24 @@
+"""Stable JSON and concise text representations of sanitized diagnostic reports."""
+
+import json
+
+from .contracts import DiagnosticReport
+
+
+def RenderJson(report: DiagnosticReport) -> str:
+    """Serialize only the versioned public report with deterministic JSON keys."""
+
+    return json.dumps(report.AsDict(), sort_keys=True, allow_nan=False)
+
+
+def RenderText(report: DiagnosticReport) -> str:
+    """Render one safe single-line observation per check without raw details."""
+
+    public = report.AsDict()
+    lines = [f"{public['command']}: {public['status']}"]
+
+    for check in report.checks:
+        safe = check.AsDict()
+        lines.append(f"[{safe['status']}] {safe['name']}: {safe['message']}")
+
+    return "\n".join(" ".join(line.split()) for line in lines)

flayer/extensions/__init__.py

@@ -0,0 +1,25 @@
+"""Additive typed extension contracts, static metadata discovery, and explicit loading."""
+
+from .builtins import BuiltinDescriptors
+from .contracts import (
+    PROFILE_GROUP,
+    PROVIDER_GROUP,
+    CompiledProfile,
+    ExtensionDescriptor,
+    ExtensionError,
+    ExtensionKind,
+    LifecycleProviderExtension,
+    ProfileContext,
+    ProfileExtension,
+    ProviderContext,
+    ProviderExtension,
+)
+from .discovery import DiscoverExtensions
+from .registry import ExtensionRegistry
+
+__all__ = [
+    "PROFILE_GROUP", "PROVIDER_GROUP", "BuiltinDescriptors", "CompiledProfile",
+    "DiscoverExtensions", "ExtensionDescriptor", "ExtensionError", "ExtensionKind",
+    "ExtensionRegistry", "LifecycleProviderExtension", "ProfileContext", "ProfileExtension",
+    "ProviderContext", "ProviderExtension",
+]

flayer/extensions/builtins.py

@@ -0,0 +1,165 @@
+"""Usable extension adapters for the existing Yandex providers and secure gateway."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from flayer import __version__
+from flayer.core.contracts import StackIdentity
+from flayer.profiles.artifacts import ArtifactBundle
+from flayer.providers.contracts import CloudProvider
+from flayer.providers.lifecycle import LifecycleProvider
+
+from .contracts import (
+    PROFILE_GROUP,
+    PROVIDER_GROUP,
+    CompiledProfile,
+    ExtensionDescriptor,
+    ExtensionError,
+    ExtensionKind,
+    ProfileContext,
+    ProfileExtension,
+    ProviderContext,
+    ProviderExtension,
+)
+
+if TYPE_CHECKING:
+    from flayer.profiles.gateway import GatewayPlan
+
+YANDEX_READ_ONLY = ExtensionDescriptor(
+    ExtensionKind.PROVIDER, "yandex-read-only", "f-layer", __version__, PROVIDER_GROUP,
+    "flayer.extensions.builtins:YandexReadOnlyExtension",
+)
+YANDEX_LIFECYCLE = ExtensionDescriptor(
+    ExtensionKind.PROVIDER, "yandex-lifecycle", "f-layer", __version__, PROVIDER_GROUP,
+    "flayer.extensions.builtins:YandexLifecycleExtension",
+)
+SECURE_GATEWAY = ExtensionDescriptor(
+    ExtensionKind.PROFILE, "secure-gateway", "f-layer", __version__, PROFILE_GROUP,
+    "flayer.extensions.builtins:SecureGatewayExtension",
+)
+
+
+def BuiltinDescriptors() -> tuple[ExtensionDescriptor, ...]:
+    """Return static descriptors without importing provider or profile implementations."""
+
+    return (YANDEX_READ_ONLY, YANDEX_LIFECYCLE, SECURE_GATEWAY)
+
+
+class YandexReadOnlyExtension:
+    """Build the real read-only Yandex adapter with an external CLI profile reference."""
+
+    @property
+    def Descriptor(self) -> ExtensionDescriptor:
+        """Return the immutable built-in identity used by registry lookup."""
+
+        return YANDEX_READ_ONLY
+
+    def CreateProvider(self, context: ProviderContext) -> CloudProvider:
+        """Construct a real adapter without running CLI commands or reading credentials."""
+
+        from flayer.providers.yandex import YandexCloudProvider, YandexCloudSettings
+
+        if not isinstance(context, ProviderContext):
+            raise ExtensionError("Provider construction requires a validated ProviderContext")
+
+        return YandexCloudProvider(YandexCloudSettings(
+            folder_id=context.scope_id, profile=context.authentication_reference,
+            command_timeout=context.command_timeout, inventory_limit=context.inventory_limit,
+        ))
+
+
+class YandexLifecycleExtension(YandexReadOnlyExtension):
+    """Opt in separately to the existing exact-scope owned resource mutation contract."""
+
+    @property
+    def Descriptor(self) -> ExtensionDescriptor:
+        """Return the distinct identity that explicitly advertises lifecycle construction."""
+
+        return YANDEX_LIFECYCLE
+
+    def CreateLifecycleProvider(self, context: ProviderContext) -> LifecycleProvider:
+        """Construct the real lifecycle adapter without performing provider operations."""
+
+        from flayer.providers.yandex import YandexCloudSettings
+        from flayer.providers.yandex_lifecycle import YandexLifecycleProvider
+
+        if not isinstance(context, ProviderContext):
+            raise ExtensionError("Provider construction requires a validated ProviderContext")
+
+        return YandexLifecycleProvider(YandexCloudSettings(
+            folder_id=context.scope_id, profile=context.authentication_reference,
+            command_timeout=context.command_timeout, inventory_limit=context.inventory_limit,
+        ))
+
+
+@dataclass(frozen=True, slots=True)
+class _CompiledGateway:
+    """Adapt a real compiled gateway while retaining its artifact verification contract."""
+
+    plan: GatewayPlan
+
+    @property
+    def Identity(self) -> StackIdentity:
+        """Return the exact ownership identity already validated by profile compilation."""
+
+        return self.plan.profile.identity
+
+    def BuildServerBundle(self) -> ArtifactBundle:
+        """Generate the real gateway server bundle in memory without storing it."""
+
+        from flayer.profiles.gateway import BuildServerBundle
+
+        return BuildServerBundle(self.plan.profile)
+
+    def RenderPlan(self, *, user_data_file: str | Path) -> str:
+        """Preserve gateway verification of the exact exported server artifact."""
+
+        from flayer.profiles.gateway import RenderPlan
+
+        return RenderPlan(self.plan, user_data_file=user_data_file)
+
+
+class SecureGatewayExtension:
+    """Compile the real strict gateway schema through the additive extension boundary."""
+
+    @property
+    def Descriptor(self) -> ExtensionDescriptor:
+        """Return the immutable built-in profile identity."""
+
+        return SECURE_GATEWAY
+
+    def CompileProfile(
+        self, configuration: Mapping[str, object], context: ProfileContext,
+    ) -> CompiledProfile:
+        """Reject identity disagreement before constructing a real gateway plan."""
+
+        from flayer.profiles.gateway import CompileGateway, ParseGatewayProfile
+
+        if not isinstance(context, ProfileContext):
+            raise ExtensionError("Profile compilation requires a validated ProfileContext")
+
+        profile = ParseGatewayProfile(configuration)
+
+        if profile.identity != context.identity:
+            raise ExtensionError("Profile configuration does not match its exact ownership context")
+
+        return _CompiledGateway(CompileGateway(profile))
+
+
+def LoadBuiltin(descriptor: ExtensionDescriptor) -> ProviderExtension | ProfileExtension:
+    """Load only an exact known built-in descriptor, rejecting invented built-in targets."""
+
+    if descriptor == YANDEX_READ_ONLY:
+        return YandexReadOnlyExtension()
+
+    if descriptor == YANDEX_LIFECYCLE:
+        return YandexLifecycleExtension()
+
+    if descriptor == SECURE_GATEWAY:
+        return SecureGatewayExtension()
+
+    raise ExtensionError("Extension is not an exact registered F-Layer built-in")