flayer.providers.contracts

Module source

flayer.providers.contracts

Provider-neutral contracts for bounded, read-only infrastructure discovery.

IDENTIFIER_PATTERN module-attribute

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

ResourceKind

Bases: StrEnum

Infrastructure resource kinds supported by the discovery contract.

INSTANCE class-attribute instance-attribute

INSTANCE = 'instance'

DISK class-attribute instance-attribute

DISK = 'disk'

NETWORK class-attribute instance-attribute

NETWORK = 'network'

SUBNET class-attribute instance-attribute

SUBNET = 'subnet'

ADDRESS class-attribute instance-attribute

ADDRESS = 'address'

SECURITY_GROUP class-attribute instance-attribute

SECURITY_GROUP = 'security_group'

ProviderCapability

Bases: StrEnum

Implemented operations advertised by a provider, independent of permissions.

INVENTORY class-attribute instance-attribute

INVENTORY = 'inventory'

RESOURCE_LOOKUP class-attribute instance-attribute

RESOURCE_LOOKUP = 'resource_lookup'

CREATE_RESOURCE class-attribute instance-attribute

CREATE_RESOURCE = 'create_resource'

DELETE_RESOURCE class-attribute instance-attribute

DELETE_RESOURCE = 'delete_resource'

ProviderErrorCode

Bases: StrEnum

Stable failure categories that never include vendor output or credentials.

UNAVAILABLE class-attribute instance-attribute

UNAVAILABLE = 'unavailable'

AUTHENTICATION class-attribute instance-attribute

AUTHENTICATION = 'authentication'

PERMISSION_DENIED class-attribute instance-attribute

PERMISSION_DENIED = 'permission_denied'

NOT_FOUND class-attribute instance-attribute

NOT_FOUND = 'not_found'

TIMEOUT class-attribute instance-attribute

TIMEOUT = 'timeout'

THROTTLED class-attribute instance-attribute

THROTTLED = 'throttled'

CONFLICT class-attribute instance-attribute

CONFLICT = 'conflict'

SCOPE_MISMATCH class-attribute instance-attribute

SCOPE_MISMATCH = 'scope_mismatch'

INVALID_RESPONSE class-attribute instance-attribute

INVALID_RESPONSE = 'invalid_response'

UNSUPPORTED class-attribute instance-attribute

UNSUPPORTED = 'unsupported'

COMMAND_FAILED class-attribute instance-attribute

COMMAND_FAILED = 'command_failed'

INCOMPLETE_INVENTORY class-attribute instance-attribute

INCOMPLETE_INVENTORY = 'incomplete_inventory'

ProviderError

ProviderError(code: ProviderErrorCode, operation: str)

Bases: RuntimeError

A sanitized provider failure with a stable code and retry recommendation.

Build an error without retaining external command output or exceptions.

Source code in installed/flayer/providers/contracts.py

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}")

code instance-attribute

code = code

operation instance-attribute

operation = operation

retryable instance-attribute

retryable = code in {ProviderErrorCode.TIMEOUT, ProviderErrorCode.THROTTLED}

ProviderIdentity dataclass

ProviderIdentity(provider_id: str, scope_id: str, authentication_source: str)

Non-secret provider and explicit scope identity; credentials remain external.

provider_id instance-attribute

provider_id: str

scope_id instance-attribute

scope_id: str

authentication_source instance-attribute

authentication_source: str

ResourceReference dataclass

ResourceReference(provider_id: str, scope_id: str, kind: ResourceKind, resource_id: str)

A resource key bound to one provider, one scope and one resource kind.

provider_id instance-attribute

provider_id: str

scope_id instance-attribute

scope_id: str

kind instance-attribute

kind: ResourceKind

resource_id instance-attribute

resource_id: str

ProviderResource dataclass

ProviderResource(reference: ResourceReference, name: str, status: str = 'UNKNOWN', zone_id: str | None = None, labels: tuple[tuple[str, str], ...] = (), public_addresses: tuple[str, ...] = ())

A normalized observation, excluding raw vendor payloads and instance metadata.

reference instance-attribute

reference: ResourceReference

name instance-attribute

name: str

status class-attribute instance-attribute

status: str = 'UNKNOWN'

zone_id class-attribute instance-attribute

zone_id: str | None = None

labels class-attribute instance-attribute

labels: tuple[tuple[str, str], ...] = ()

public_addresses class-attribute instance-attribute

public_addresses: tuple[str, ...] = ()

HasLabels

HasLabels(expected: tuple[tuple[str, str], ...]) -> bool

Check all required labels without treating a resource name as ownership.

Source code in installed/flayer/providers/contracts.py

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)

ProviderStatus dataclass

ProviderStatus(identity: ProviderIdentity, available: bool, authenticated: bool | None = None, error_code: ProviderErrorCode | None = None)

A sanitized probe result; unknown authentication differs from a failed probe.

identity instance-attribute

identity: ProviderIdentity

available instance-attribute

available: bool

authenticated class-attribute instance-attribute

authenticated: bool | None = None

error_code class-attribute instance-attribute

error_code: ProviderErrorCode | None = None

CloudProvider

Bases: Protocol

Read-only provider boundary consumed by diagnostics and future orchestration.

Identity property

Identity: ProviderIdentity

Return the provider identity and explicit discovery scope.

Capabilities property

Capabilities: frozenset[ProviderCapability]

Advertise implemented operations without promising account authorization.

CheckAvailability

CheckAvailability() -> ProviderStatus

Probe the local provider adapter without accessing infrastructure.

Source code in installed/flayer/providers/contracts.py

def CheckAvailability(self) -> ProviderStatus:
    """Probe the local provider adapter without accessing infrastructure."""

    ...

CheckAuthentication

CheckAuthentication() -> ProviderStatus

Probe read permission to the selected scope without exposing credentials.

Source code in installed/flayer/providers/contracts.py

def CheckAuthentication(self) -> ProviderStatus:
    """Probe read permission to the selected scope without exposing credentials."""

    ...

ListResources

ListResources(kind: ResourceKind) -> tuple[ProviderResource, ...]

List a complete resource kind within the provider's explicit scope.

Source code in installed/flayer/providers/contracts.py

def ListResources(self, kind: ResourceKind) -> tuple[ProviderResource, ...]:
    """List a complete resource kind within the provider's explicit scope."""

    ...

GetResource

GetResource(reference: ResourceReference) -> ProviderResource

Read one resource and reject any reference or response outside the scope.

Source code in installed/flayer/providers/contracts.py

def GetResource(self, reference: ResourceReference) -> ProviderResource:
    """Read one resource and reject any reference or response outside the scope."""

    ...

DiscoverInventory

DiscoverInventory() -> tuple[ProviderResource, ...]

Return all supported kinds or fail without returning partial inventory.

Source code in installed/flayer/providers/contracts.py

def DiscoverInventory(self) -> tuple[ProviderResource, ...]:
    """Return all supported kinds or fail without returning partial inventory."""

    ...

ValidateIdentifier

ValidateIdentifier(value: str) -> None

Reject unsafe identifiers without including the rejected value in errors.

Source code in installed/flayer/providers/contracts.py

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"
        )