f-layer 2.0.0__py3-none-any.whl

flayer/core/state.py

@@ -0,0 +1,351 @@
+"""Minimal owned-resource snapshots with strict reads and atomic local persistence."""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import tempfile
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import IO
+
+from .contracts import (
+    SCHEMA_VERSION,
+    ContractError,
+    ParseIdentity,
+    RequireTable,
+    StackIdentity,
+    ValidateFields,
+    ValidateIdentifier,
+    ValidateName,
+    ValidateSchemaVersion,
+)
+
+MAX_JSON_BYTES = 1024 * 1024
+
+
+class StateError(ContractError):
+    """Owned state is malformed, mismatched, busy, or cannot be persisted safely."""
+
+
+@dataclass(frozen=True)
+class ResourceState:
+    """Minimum provider locator for a resource recorded by one managed stack."""
+
+    logical_id: str
+    kind: str
+    resource_id: str
+
+    def __post_init__(self) -> None:
+        """Keep persisted locators explicit and free of arbitrary provider payloads."""
+
+        ValidateName(self.logical_id, "resources.logical_id")
+        ValidateName(self.kind, "resources.kind")
+        ValidateIdentifier(self.resource_id, "resources.resource_id")
+
+
+@dataclass(frozen=True)
+class StackState:
+    """Immutable resource inventory scoped to a complete ownership identity."""
+
+    identity: StackIdentity
+    resources: tuple[ResourceState, ...] = ()
+    schema_version: int = SCHEMA_VERSION
+
+    def __post_init__(self) -> None:
+        """Reject duplicate locators and invalid direct model construction."""
+
+        ValidateSchemaVersion(self.schema_version)
+
+        if not isinstance(self.identity, StackIdentity):
+            raise ContractError("identity must be a StackIdentity")
+
+        if not isinstance(self.resources, tuple) or any(
+            not isinstance(resource, ResourceState) for resource in self.resources
+        ):
+            raise ContractError("resources must be a tuple of ResourceState values")
+
+        if len({resource.logical_id for resource in self.resources}) != len(self.resources):
+            raise ContractError("resources.logical_id values must be unique")
+
+        if len({(resource.kind, resource.resource_id) for resource in self.resources}) != len(
+            self.resources
+        ):
+            raise ContractError("resources must not contain duplicate provider locators")
+
+
+def _RequireIdentity(actual: StackIdentity, expected: StackIdentity) -> None:
+    """Block all state operations when any ownership or provider-scope field differs."""
+
+    if not isinstance(expected, StackIdentity) or actual != expected:
+        raise StateError("State identity does not match the expected ownership boundary")
+
+
+def ParseState(data: Mapping[str, object], expected_identity: StackIdentity) -> StackState:
+    """Decode a versioned snapshot and require explicit caller ownership expectations."""
+
+    try:
+        ValidateFields(
+            data, frozenset({"schema_version", "identity", "resources"}), frozenset(), "state"
+        )
+        ValidateSchemaVersion(data["schema_version"])
+        identity = ParseIdentity(data["identity"])
+        _RequireIdentity(identity, expected_identity)
+        raw_resources = data["resources"]
+
+        if not isinstance(raw_resources, list):
+            raise ContractError("resources must be an array of tables")
+
+        resources: list[ResourceState] = []
+
+        for item in raw_resources:
+            table = RequireTable(item, "resources")
+            ValidateFields(
+                table,
+                frozenset({"logical_id", "kind", "resource_id"}),
+                frozenset(),
+                "resources",
+            )
+            resources.append(
+                ResourceState(
+                    logical_id=ValidateName(table["logical_id"], "resources.logical_id"),
+                    kind=ValidateName(table["kind"], "resources.kind"),
+                    resource_id=ValidateIdentifier(table["resource_id"], "resources.resource_id"),
+                )
+            )
+
+        return StackState(identity=identity, resources=tuple(resources))
+
+    except ContractError as error:
+        raise StateError(str(error)) from error
+
+
+def _UniqueObject(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    """Reject duplicate JSON fields instead of silently accepting the last value."""
+
+    result: dict[str, object] = {}
+
+    for key, value in pairs:
+        if key in result:
+            raise StateError("State JSON contains duplicate fields")
+
+        result[key] = value
+
+    return result
+
+
+def _ValidatePath(path: Path) -> None:
+    """Reject traversal, symlinks, and nonregular targets within caller-owned storage."""
+
+    if not path.name or ".." in path.parts:
+        raise StateError("State path must name a file without parent traversal")
+
+    for candidate in (path, *path.parents):
+        if candidate.is_symlink():
+            raise StateError("State path must not contain symlinks")
+
+    if path.exists() and not path.is_file():
+        raise StateError("State path must refer to a regular file")
+
+
+def _OpenTextStream(descriptor: int, mode: str) -> IO[str]:
+    """Transfer descriptor ownership to a stream or close it when the transfer fails."""
+
+    try:
+        return os.fdopen(descriptor, mode, encoding="utf-8")
+
+    except BaseException:
+        os.close(descriptor)
+
+        raise
+
+
+def _ReadOwnedJson(path: Path) -> object:
+    """Read bounded regular JSON without blocking on a post-validation FIFO substitution."""
+
+    opened_descriptor = os.open(
+        path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
+    )
+    descriptor: int | None = opened_descriptor
+
+    try:
+        opened = os.fstat(opened_descriptor)
+
+        if not stat.S_ISREG(opened.st_mode) or opened.st_size > MAX_JSON_BYTES:
+            raise StateError("Owned JSON must be a bounded regular file")
+
+        stream_descriptor = opened_descriptor
+        descriptor = None
+
+        with _OpenTextStream(stream_descriptor, "r") as stream:
+            text = stream.read(MAX_JSON_BYTES + 1)
+
+        if len(text.encode("utf-8")) > MAX_JSON_BYTES:
+            raise StateError("Owned JSON exceeds its bounded read limit")
+
+        return json.loads(text, object_pairs_hook=_UniqueObject)
+
+    except FileNotFoundError as error:
+        raise StateError("Unable to read an opened owned JSON file") from error
+
+    finally:
+        if descriptor is not None:
+            os.close(descriptor)
+
+
+def LoadState(path: str | Path, expected_identity: StackIdentity) -> StackState | None:
+    """Return a strictly owned snapshot, or None only when the file is absent."""
+
+    state_path = Path(path)
+
+    if not isinstance(expected_identity, StackIdentity):
+        raise StateError("expected_identity must be a StackIdentity")
+
+    try:
+        _ValidatePath(state_path)
+        data = _ReadOwnedJson(state_path)
+
+    except FileNotFoundError:
+        return None
+
+    except StateError:
+        raise
+
+    except (OSError, ValueError, RecursionError) as error:
+        raise StateError("Unable to read a valid state snapshot") from error
+
+    try:
+        return ParseState(RequireTable(data, "state"), expected_identity)
+
+    except ContractError as error:
+        raise StateError(str(error)) from error
+
+
+@contextmanager
+def _StateLock(path: Path) -> Iterator[None]:
+    """Serialize cooperating writers and leave crash locks for explicit operator recovery."""
+
+    descriptor: int | None = None
+
+    try:
+        _ValidatePath(path)
+        lock_path = path.with_name(f".{path.name}.lock")
+        path.parent.mkdir(parents=True, exist_ok=True)
+        descriptor = os.open(lock_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+        os.close(descriptor)
+        descriptor = None
+
+    except OSError as error:
+        if descriptor is not None:
+            try:
+                os.close(descriptor)
+
+            except OSError:
+                pass
+
+        raise StateError("State storage is unavailable or another writer holds its lock") from error
+
+    try:
+        yield
+
+    finally:
+        try:
+            lock_path.unlink()
+
+        except OSError as error:
+            raise StateError("Unable to release the state writer lock") from error
+
+
+def _SyncDirectory(path: Path) -> None:
+    """Persist directory updates on platforms with a usable directory fsync operation."""
+
+    if os.name != "posix":
+        return
+
+    descriptor = os.open(path, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0))
+
+    try:
+        os.fsync(descriptor)
+
+    finally:
+        os.close(descriptor)
+
+
+def SaveState(path: str | Path, state: StackState, expected_identity: StackIdentity) -> None:
+    """Atomically save owned state; never replace a foreign or malformed existing snapshot."""
+
+    if not isinstance(state, StackState):
+        raise StateError("state must be a StackState")
+
+    _RequireIdentity(state.identity, expected_identity)
+    serialized = json.dumps(asdict(state), indent=2, sort_keys=True) + "\n"
+
+    if len(serialized.encode("utf-8")) > MAX_JSON_BYTES:
+        raise StateError("Owned state snapshot exceeds its bounded JSON storage limit")
+
+    state_path = Path(path)
+    temporary_path: Path | None = None
+
+    with _StateLock(state_path):
+        LoadState(state_path, expected_identity)
+
+        try:
+            descriptor, temporary_name = tempfile.mkstemp(
+                prefix=f".{state_path.name}.", suffix=".tmp", dir=state_path.parent
+            )
+            temporary_path = Path(temporary_name)
+
+            with _OpenTextStream(descriptor, "w") as stream:
+                stream.write(serialized)
+                stream.flush()
+                os.fsync(stream.fileno())
+
+            os.replace(temporary_path, state_path)
+            temporary_path = None
+            _SyncDirectory(state_path.parent)
+
+        except OSError as error:
+            raise StateError(
+                "Unable to persist state; a completed replacement may be visible"
+            ) from error
+
+        finally:
+            if temporary_path is not None:
+                try:
+                    temporary_path.unlink(missing_ok=True)
+
+                except OSError as error:
+                    raise StateError(
+                        "Unable to clean temporary state; "
+                        "incomplete local cleanup requires recovery"
+                    ) from error
+
+
+def RemoveState(path: str | Path, expected_identity: StackIdentity) -> bool:
+    """Remove only a matching local snapshot; never delete infrastructure resources."""
+
+    state_path = Path(path)
+
+    if not isinstance(expected_identity, StackIdentity):
+        raise StateError("expected_identity must be a StackIdentity")
+
+    try:
+        _ValidatePath(state_path)
+
+        if not state_path.parent.exists():
+            return False
+
+        with _StateLock(state_path):
+            if LoadState(state_path, expected_identity) is None:
+                return False
+
+            state_path.unlink()
+            _SyncDirectory(state_path.parent)
+
+    except OSError as error:
+        raise StateError("Unable to remove the owned state snapshot") from error
+
+    return True

flayer/diagnostics/__init__.py

@@ -0,0 +1,20 @@
+"""Safe diagnostic contracts with explicit provider and endpoint boundaries."""
+
+from .benchmark import (
+    BenchmarkLimits,
+    EndpointMeasurement,
+    EndpointTransport,
+    MeasureEndpoint,
+    ProbeEndpoint,
+    RunBenchmark,
+)
+from .contracts import CheckResult, DiagnosticReport, DiagnosticStatus, Redact
+from .health import EvaluateHealthReport, HealthProbe, ProviderStatus, RunChecks, RuntimeChecks
+from .reporting import RenderJson, RenderText
+
+__all__ = [
+    "BenchmarkLimits", "CheckResult", "DiagnosticReport", "DiagnosticStatus",
+    "EndpointMeasurement", "EndpointTransport", "EvaluateHealthReport", "HealthProbe",
+    "MeasureEndpoint", "ProbeEndpoint", "ProviderStatus", "Redact", "RenderJson", "RenderText",
+    "RunBenchmark", "RunChecks", "RuntimeChecks",
+]

flayer/diagnostics/benchmark.py

@@ -0,0 +1,272 @@
+"""Bounded HTTP measurements against an explicitly authorized endpoint."""
+
+from __future__ import annotations
+
+import http.client
+import math
+import multiprocessing
+import time
+from dataclasses import dataclass
+from multiprocessing.connection import Connection
+from typing import Protocol
+from urllib.parse import SplitResult, urlsplit
+
+from .contracts import CheckResult, DiagnosticStatus
+
+MAX_TIMEOUT_SECONDS = 30.0
+MAX_REQUEST_COUNT = 10
+MAX_BYTE_LIMIT = 1024 * 1024
+
+
+@dataclass(frozen=True)
+class BenchmarkLimits:
+    """Hard per-request deadline, request count, and response payload limits."""
+
+    timeout_seconds: float = 3.0
+    count: int = 3
+    byte_limit: int = 64 * 1024
+
+    def __post_init__(self) -> None:
+        """Reject invalid or unbounded work before starting a transport."""
+
+        if (
+            isinstance(self.timeout_seconds, bool)
+            or not math.isfinite(self.timeout_seconds)
+            or not 0 < self.timeout_seconds <= MAX_TIMEOUT_SECONDS
+            or isinstance(self.count, bool)
+            or not isinstance(self.count, int)
+            or not 1 <= self.count <= MAX_REQUEST_COUNT
+            or isinstance(self.byte_limit, bool)
+            or not isinstance(self.byte_limit, int)
+            or not 1 <= self.byte_limit <= MAX_BYTE_LIMIT
+        ):
+            raise ValueError("Benchmark limits exceed the supported bounds")
+
+
+@dataclass(frozen=True)
+class EndpointMeasurement:
+    """Safe metrics exclude response content, credentials, and target identifiers."""
+
+    status: DiagnosticStatus
+    duration_seconds: float
+    received_bytes: int = 0
+    http_status: int | None = None
+
+
+class EndpointTransport(Protocol):
+    """A measurement implementation enforces supplied limits without emitting raw data."""
+
+    def __call__(
+        self, endpoint: str, timeout_seconds: float, byte_limit: int
+    ) -> EndpointMeasurement:
+        """Return one bounded HTTP measurement without exposing response payloads."""
+
+        ...
+
+
+def ValidateEndpoint(endpoint: str) -> SplitResult:
+    """Allow explicit HTTP(S) URLs without credentials, query strings, or fragments."""
+
+    try:
+        parsed = urlsplit(endpoint)
+        port = parsed.port
+
+        if (
+            parsed.scheme not in ("http", "https")
+            or not parsed.hostname
+            or parsed.username is not None
+            or parsed.password is not None
+            or parsed.query
+            or parsed.fragment
+            or any(character.isspace() or ord(character) < 32 for character in endpoint)
+            or (port is not None and port < 1)
+        ):
+            raise ValueError("Invalid endpoint")
+
+    except ValueError:
+        raise ValueError("Endpoint must be an HTTP(S) URL without credentials, query or fragment") \
+            from None
+
+    return parsed
+
+
+def HttpMeasurement(endpoint: str, timeout_seconds: float, byte_limit: int) -> EndpointMeasurement:
+    """Read a limited payload with TLS verification and no redirects or proxy discovery."""
+
+    parsed = ValidateEndpoint(endpoint)
+    connection_type = (
+        http.client.HTTPSConnection if parsed.scheme == "https" else http.client.HTTPConnection
+    )
+    connection = connection_type(str(parsed.hostname), port=parsed.port, timeout=timeout_seconds)
+    started = time.monotonic()
+
+    try:
+        connection.request(
+            "GET", parsed.path or "/",
+            headers={"Range": f"bytes=0-{byte_limit - 1}", "Connection": "close"},
+        )
+        response = connection.getresponse()
+        received_bytes = len(response.read(byte_limit))
+        status = DiagnosticStatus.OK if 200 <= response.status < 300 else DiagnosticStatus.FAILED
+
+        return EndpointMeasurement(status, time.monotonic() - started, received_bytes, response.status)
+
+    finally:
+        connection.close()
+
+
+def EndpointWorker(
+    sender: Connection, endpoint: str, timeout_seconds: float, byte_limit: int
+) -> None:
+    """Isolate network work so DNS, TLS, connect, and response reads share a hard deadline."""
+
+    try:
+        measurement = HttpMeasurement(endpoint, timeout_seconds, byte_limit)
+
+    except Exception:
+        measurement = EndpointMeasurement(DiagnosticStatus.FAILED, 0.0)
+
+    try:
+        sender.send(measurement)
+
+    finally:
+        sender.close()
+
+
+def MeasureEndpoint(endpoint: str, timeout_seconds: float, byte_limit: int) -> EndpointMeasurement:
+    """Terminate isolated network work at the deadline, including a stalled DNS resolver."""
+
+    ValidateEndpoint(endpoint)
+    BenchmarkLimits(timeout_seconds=timeout_seconds, count=1, byte_limit=byte_limit)
+    context = multiprocessing.get_context("spawn")
+    receiver, sender = context.Pipe(duplex=False)
+    process = context.Process(
+        target=EndpointWorker, args=(sender, endpoint, timeout_seconds, byte_limit), daemon=True
+    )
+    started = time.monotonic()
+    launched = False
+
+    try:
+        process.start()
+        launched = True
+        sender.close()
+        remaining = max(0.0, timeout_seconds - (time.monotonic() - started))
+
+        if receiver.poll(remaining):
+            measurement: EndpointMeasurement = receiver.recv()
+
+            return measurement
+
+        return EndpointMeasurement(DiagnosticStatus.FAILED, timeout_seconds)
+
+    except (OSError, EOFError, RuntimeError):
+        return EndpointMeasurement(DiagnosticStatus.FAILED, time.monotonic() - started)
+
+    finally:
+        sender.close()
+        receiver.close()
+
+        if launched:
+            if process.is_alive():
+                process.terminate()
+
+            process.join(timeout=1.0)
+
+            if process.is_alive():
+                process.kill()
+                process.join(timeout=1.0)
+
+        process.close()
+
+
+def SafeMeasurement(
+    endpoint: str, limits: BenchmarkLimits, transport: EndpointTransport
+) -> EndpointMeasurement:
+    """Reject invalid adapter metrics and suppress all unstructured exception output."""
+
+    try:
+        measurement = transport(endpoint, limits.timeout_seconds, limits.byte_limit)
+
+        if (
+            not isinstance(measurement, EndpointMeasurement)
+            or not isinstance(measurement.status, DiagnosticStatus)
+            or isinstance(measurement.duration_seconds, bool)
+            or not math.isfinite(measurement.duration_seconds)
+            or not 0 <= measurement.duration_seconds <= limits.timeout_seconds
+            or isinstance(measurement.received_bytes, bool)
+            or not isinstance(measurement.received_bytes, int)
+            or not 0 <= measurement.received_bytes <= limits.byte_limit
+            or (
+                measurement.http_status is not None
+                and (
+                    isinstance(measurement.http_status, bool)
+                    or not isinstance(measurement.http_status, int)
+                    or not 100 <= measurement.http_status <= 599
+                )
+            )
+            or (
+                measurement.status is DiagnosticStatus.OK
+                and (measurement.http_status is None or not 200 <= measurement.http_status < 300)
+            )
+        ):
+            raise ValueError("Adapter returned invalid metrics")
+
+        return measurement
+
+    except Exception:
+        return EndpointMeasurement(DiagnosticStatus.FAILED, 0.0)
+
+
+def ProbeEndpoint(
+    endpoint: str, timeout_seconds: float = 3.0,
+    transport: EndpointTransport = MeasureEndpoint,
+) -> CheckResult:
+    """Check explicit HTTP reachability without pretending it validates guest hardening."""
+
+    ValidateEndpoint(endpoint)
+    limits = BenchmarkLimits(timeout_seconds=timeout_seconds, count=1, byte_limit=1)
+    measurement = SafeMeasurement(endpoint, limits, transport)
+
+    return CheckResult(
+        "endpoint", measurement.status,
+        "Endpoint answered successfully" if measurement.status is DiagnosticStatus.OK
+        else "Endpoint probe did not succeed",
+        {"duration_seconds": measurement.duration_seconds, "http_status": measurement.http_status},
+    )
+
+
+def RunBenchmark(
+    endpoint: str, limits: BenchmarkLimits | None = None,
+    transport: EndpointTransport = MeasureEndpoint,
+) -> tuple[CheckResult, ...]:
+    """Measure a fixed count of bounded downloads without inferring upload or tunnel speed."""
+
+    ValidateEndpoint(endpoint)
+    resolved_limits = limits or BenchmarkLimits()
+    checks: list[CheckResult] = []
+
+    for index in range(resolved_limits.count):
+        measurement = SafeMeasurement(endpoint, resolved_limits, transport)
+        status = measurement.status
+
+        if status is DiagnosticStatus.OK and measurement.received_bytes == 0:
+            status = DiagnosticStatus.FAILED
+
+        throughput = (
+            measurement.received_bytes * 8 / measurement.duration_seconds / 1_000_000
+            if measurement.duration_seconds > 0 else None
+        )
+        checks.append(CheckResult(
+            f"http-download-{index + 1}", status,
+            "Bounded HTTP download measured" if status is DiagnosticStatus.OK
+            else "Bounded HTTP download did not succeed",
+            {
+                "received_bytes": measurement.received_bytes,
+                "duration_seconds": measurement.duration_seconds,
+                "throughput_mbps": throughput,
+                "http_status": measurement.http_status,
+                "byte_limit": resolved_limits.byte_limit,
+            },
+        ))
+
+    return tuple(checks)