f-layer 2.0.0__py3-none-any.whl

flayer/providers/contracts.py

@@ -0,0 +1,207 @@
+"""Provider-neutral contracts for bounded, read-only infrastructure discovery."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Protocol, runtime_checkable
+
+IDENTIFIER_PATTERN = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.-]{0,127}\Z")
+
+
+class ResourceKind(StrEnum):
+    """Infrastructure resource kinds supported by the discovery contract."""
+
+    INSTANCE = "instance"
+    DISK = "disk"
+    NETWORK = "network"
+    SUBNET = "subnet"
+    ADDRESS = "address"
+    SECURITY_GROUP = "security_group"
+
+
+class ProviderCapability(StrEnum):
+    """Implemented operations advertised by a provider, independent of permissions."""
+
+    INVENTORY = "inventory"
+    RESOURCE_LOOKUP = "resource_lookup"
+    CREATE_RESOURCE = "create_resource"
+    DELETE_RESOURCE = "delete_resource"
+
+
+class ProviderErrorCode(StrEnum):
+    """Stable failure categories that never include vendor output or credentials."""
+
+    UNAVAILABLE = "unavailable"
+    AUTHENTICATION = "authentication"
+    PERMISSION_DENIED = "permission_denied"
+    NOT_FOUND = "not_found"
+    TIMEOUT = "timeout"
+    THROTTLED = "throttled"
+    CONFLICT = "conflict"
+    SCOPE_MISMATCH = "scope_mismatch"
+    INVALID_RESPONSE = "invalid_response"
+    UNSUPPORTED = "unsupported"
+    COMMAND_FAILED = "command_failed"
+    INCOMPLETE_INVENTORY = "incomplete_inventory"
+
+
+class ProviderError(RuntimeError):
+    """A sanitized provider failure with a stable code and retry recommendation."""
+
+    def __init__(self, code: ProviderErrorCode, operation: str) -> None:
+        """Build an error without retaining external command output or exceptions."""
+
+        self.code = code
+        self.operation = operation
+        self.retryable = code in {
+            ProviderErrorCode.TIMEOUT,
+            ProviderErrorCode.THROTTLED,
+        }
+        super().__init__(f"Provider operation {operation} failed: {code.value}")
+
+
+def ValidateIdentifier(value: str) -> None:
+    """Reject unsafe identifiers without including the rejected value in errors."""
+
+    if not isinstance(value, str) or IDENTIFIER_PATTERN.fullmatch(value) is None:
+        raise ValueError(
+            "Provider identifiers require 1-128 ASCII letters, digits, dots, underscores or dashes"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderIdentity:
+    """Non-secret provider and explicit scope identity; credentials remain external."""
+
+    provider_id: str
+    scope_id: str
+    authentication_source: str
+
+    def __post_init__(self) -> None:
+        """Validate immutable identity fields before they can define a resource scope."""
+
+        ValidateIdentifier(self.provider_id)
+        ValidateIdentifier(self.scope_id)
+        ValidateIdentifier(self.authentication_source)
+
+
+@dataclass(frozen=True, slots=True)
+class ResourceReference:
+    """A resource key bound to one provider, one scope and one resource kind."""
+
+    provider_id: str
+    scope_id: str
+    kind: ResourceKind
+    resource_id: str
+
+    def __post_init__(self) -> None:
+        """Reject malformed identities and unrecognized resource kinds."""
+
+        ValidateIdentifier(self.provider_id)
+        ValidateIdentifier(self.scope_id)
+        ValidateIdentifier(self.resource_id)
+
+        if not isinstance(self.kind, ResourceKind):
+            raise ValueError("Resource kind must be a ResourceKind member")
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderResource:
+    """A normalized observation, excluding raw vendor payloads and instance metadata."""
+
+    reference: ResourceReference
+    name: str
+    status: str = "UNKNOWN"
+    zone_id: str | None = None
+    labels: tuple[tuple[str, str], ...] = ()
+    public_addresses: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        """Require immutable labels and endpoint collections from provider adapters."""
+
+        if not isinstance(self.reference, ResourceReference):
+            raise ValueError("Provider resources require a validated resource reference")
+
+        if not isinstance(self.name, str) or not isinstance(self.status, str):
+            raise ValueError("Resource names and statuses must be strings")
+
+        if self.zone_id is not None:
+            ValidateIdentifier(self.zone_id)
+
+        if (
+            not isinstance(self.labels, tuple)
+            or any(
+                not isinstance(label, tuple)
+                or len(label) != 2
+                or not all(isinstance(value, str) for value in label)
+                for label in self.labels
+            )
+            or len({label[0] for label in self.labels}) != len(self.labels)
+        ):
+            raise ValueError("Resource labels must be immutable unique string pairs")
+
+        if not isinstance(self.public_addresses, tuple) or not all(
+            isinstance(address, str) for address in self.public_addresses
+        ):
+            raise ValueError("Public addresses must be an immutable string tuple")
+
+    def HasLabels(self, expected: tuple[tuple[str, str], ...]) -> bool:
+        """Check all required labels without treating a resource name as ownership."""
+
+        actual = dict(self.labels)
+
+        return bool(expected) and all(actual.get(key) == value for key, value in expected)
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderStatus:
+    """A sanitized probe result; unknown authentication differs from a failed probe."""
+
+    identity: ProviderIdentity
+    available: bool
+    authenticated: bool | None = None
+    error_code: ProviderErrorCode | None = None
+
+
+@runtime_checkable
+class CloudProvider(Protocol):
+    """Read-only provider boundary consumed by diagnostics and future orchestration."""
+
+    @property
+    def Identity(self) -> ProviderIdentity:
+        """Return the provider identity and explicit discovery scope."""
+
+        ...
+
+    @property
+    def Capabilities(self) -> frozenset[ProviderCapability]:
+        """Advertise implemented operations without promising account authorization."""
+
+        ...
+
+    def CheckAvailability(self) -> ProviderStatus:
+        """Probe the local provider adapter without accessing infrastructure."""
+
+        ...
+
+    def CheckAuthentication(self) -> ProviderStatus:
+        """Probe read permission to the selected scope without exposing credentials."""
+
+        ...
+
+    def ListResources(self, kind: ResourceKind) -> tuple[ProviderResource, ...]:
+        """List a complete resource kind within the provider's explicit scope."""
+
+        ...
+
+    def GetResource(self, reference: ResourceReference) -> ProviderResource:
+        """Read one resource and reject any reference or response outside the scope."""
+
+        ...
+
+    def DiscoverInventory(self) -> tuple[ProviderResource, ...]:
+        """Return all supported kinds or fail without returning partial inventory."""
+
+        ...

flayer/providers/lifecycle.py

@@ -0,0 +1,177 @@
+"""Immutable lifecycle requests and explicit, ownership-bound mutation contracts."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Protocol, TypeAlias, runtime_checkable
+
+from flayer.core.contracts import StackIdentity, ValidateName
+
+from .contracts import (
+    ProviderCapability,
+    ProviderError,
+    ProviderErrorCode,
+    ProviderIdentity,
+    ProviderResource,
+    ResourceKind,
+    ResourceReference,
+)
+
+JsonValue: TypeAlias = str | int | bool | None | tuple["JsonValue", ...]
+MAX_PARAMETER_DEPTH = 10
+MAX_PARAMETER_VALUES = 2048
+LOGICAL_ID_LABEL = "flayer-resource"
+SPEC_DIGEST_LABEL = "flayer-spec"
+OPERATION_ID_LABEL = "flayer-operation"
+
+
+def _ValidateValue(value: JsonValue, depth: int, remaining: list[int]) -> None:
+    """Bound recursively immutable values before hashing or translating requests."""
+
+    remaining[0] -= 1
+
+    if depth > MAX_PARAMETER_DEPTH or remaining[0] < 0:
+        raise ValueError("Resource parameters exceed their structural bounds")
+
+    if isinstance(value, tuple):
+        for item in value:
+            _ValidateValue(item, depth + 1, remaining)
+
+    elif isinstance(value, str):
+        if len(value) > 16384 or "\x00" in value:
+            raise ValueError("Resource parameter strings exceed their bounds")
+
+    elif value is not None and type(value) not in {int, bool}:
+        raise ValueError("Resource parameters require immutable JSON-compatible values")
+
+    elif type(value) is int and not -(2 ** 63) <= value < 2 ** 63:
+        raise ValueError("Resource integer parameters exceed signed 64-bit bounds")
+
+
+@dataclass(frozen=True, slots=True)
+class ResourceSpec:
+    """A desired logical resource with immutable options and explicit dependencies."""
+
+    logical_id: str
+    kind: ResourceKind
+    name: str
+    parameters: tuple[tuple[str, JsonValue], ...] = field(default=(), repr=False)
+    dependencies: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        """Reject malformed, mutable, duplicate or cyclic direct request fields."""
+
+        ValidateName(self.logical_id, "resource.logical_id")
+        ValidateName(self.name, "resource.name")
+
+        if not isinstance(self.kind, ResourceKind):
+            raise ValueError("Lifecycle kind requires a ResourceKind member")
+
+        if (
+            not isinstance(self.parameters, tuple)
+            or len(self.parameters) > 128
+            or any(
+                not isinstance(pair, tuple) or len(pair) != 2
+                or not isinstance(pair[0], str) or not pair[0].isidentifier()
+                for pair in self.parameters
+            )
+            or len({pair[0] for pair in self.parameters}) != len(self.parameters)
+        ):
+            raise ValueError("Resource parameters require unique immutable named pairs")
+
+        remaining = [MAX_PARAMETER_VALUES]
+
+        for _, value in self.parameters:
+            _ValidateValue(value, 0, remaining)
+
+        if (
+            not isinstance(self.dependencies, tuple)
+            or len(self.dependencies) > 128
+            or any(not isinstance(value, str) for value in self.dependencies)
+            or len(set(self.dependencies)) != len(self.dependencies)
+            or self.logical_id in self.dependencies
+        ):
+            raise ValueError("Resource dependencies require unique immutable logical IDs")
+
+        for logical_id in self.dependencies:
+            ValidateName(logical_id, "resource.dependency")
+
+    def OwnershipLabels(self, identity: StackIdentity) -> tuple[tuple[str, str], ...]:
+        """Bind one logical resource to the complete stack ownership boundary."""
+
+        labels = identity.OwnershipLabels()
+        labels[LOGICAL_ID_LABEL] = self.logical_id
+        content = (self.logical_id, self.kind.value, self.name, self.parameters, self.dependencies)
+        digest = hashlib.sha256(json.dumps(content, sort_keys=True).encode("utf-8")).hexdigest()
+        labels[SPEC_DIGEST_LABEL] = digest[:40]
+
+        return tuple(sorted(labels.items()))
+
+
+class MutationError(ProviderError):
+    """A sanitized mutation failure that distinguishes an uncertain remote outcome."""
+
+    def __init__(
+        self, code: ProviderErrorCode, operation: str, outcome_unknown: bool
+    ) -> None:
+        """Retain only a stable failure category and whether submission may have occurred."""
+
+        if type(outcome_unknown) is not bool:
+            raise ValueError("Mutation outcome uncertainty requires a boolean")
+
+        self.outcome_unknown = outcome_unknown
+        super().__init__(code, operation)
+        self.retryable = self.retryable and not outcome_unknown
+
+
+@runtime_checkable
+class LifecycleProvider(Protocol):
+    """Mutation boundary with exact scope, stable reconciliation and owned deletion."""
+
+    @property
+    def Identity(self) -> ProviderIdentity:
+        """Return the provider and explicit scope used by every observation and command."""
+
+        ...
+
+    @property
+    def Capabilities(self) -> frozenset[ProviderCapability]:
+        """Advertise implemented mutation operations independently of account permissions."""
+
+        ...
+
+    def ValidateSpec(self, spec: ResourceSpec) -> None:
+        """Reject unsupported resource options without accessing infrastructure."""
+
+        ...
+
+    def FindResource(
+        self, spec: ResourceSpec, identity: StackIdentity
+    ) -> ProviderResource | None:
+        """Find the unique complete ownership-label match or reject ambiguous inventory."""
+
+        ...
+
+    def GetResource(self, reference: ResourceReference) -> ProviderResource:
+        """Observe an exact reference with scope validation and sanitized failures."""
+
+        ...
+
+    def CreateResource(
+        self, spec: ResourceSpec, identity: StackIdentity,
+        dependencies: Mapping[str, ProviderResource], operation_id: str,
+    ) -> ProviderResource:
+        """Create once from validated owned dependencies; never retry uncertain creation."""
+
+        ...
+
+    def DeleteResource(
+        self, reference: ResourceReference, identity: StackIdentity, logical_id: str,
+        operation_id: str | None = None,
+    ) -> None:
+        """Re-read exact scope and complete ownership immediately before deleting by ID."""
+
+        ...