flayer.extensions.contracts

Module source

flayer.extensions.contracts

Typed, versioned extension identities and bounded credential-free contexts.

PROVIDER_GROUP module-attribute

PROVIDER_GROUP = 'flayer.providers.v1'

PROFILE_GROUP module-attribute

PROFILE_GROUP = 'flayer.profiles.v1'

VERSION_PATTERN module-attribute

VERSION_PATTERN = re.compile('(?:0|[1-9][0-9]*)\\.(?:0|[1-9][0-9]*)\\.(?:0|[1-9][0-9]*)\\Z')

DISTRIBUTION_PATTERN module-attribute

DISTRIBUTION_PATTERN = re.compile('[a-z0-9]+(?:-[a-z0-9]+)*\\Z')

TARGET_PATTERN module-attribute

TARGET_PATTERN = re.compile('[A-Za-z][A-Za-z0-9_]*(?:\\.[A-Za-z][A-Za-z0-9_]*)*:[A-Za-z][A-Za-z0-9_]*(?:\\.[A-Za-z][A-Za-z0-9_]*)*\\Z')

SHA256_PATTERN module-attribute

SHA256_PATTERN = re.compile('[a-f0-9]{64}\\Z')

ExtensionError

Bases: ContractError

An extension violates discovery, identity, compatibility, or loading policy.

ExtensionKind

Bases: StrEnum

The two implemented extension contracts; their ABI is encoded in the group.

PROVIDER class-attribute instance-attribute

PROVIDER = 'provider'

PROFILE class-attribute instance-attribute

PROFILE = 'profile'

ExtensionDescriptor dataclass

ExtensionDescriptor(kind: ExtensionKind, plugin_id: str, distribution: str, version: str, group: str, target: str, metadata_directory: Path | None = None, metadata_sha256: str | None = None)

A static identity; external metadata snapshots are not package authenticity proof.

kind instance-attribute

kind: ExtensionKind

plugin_id instance-attribute

plugin_id: str

distribution instance-attribute

distribution: str

version instance-attribute

version: str

group instance-attribute

group: str

target instance-attribute

target: str

metadata_directory class-attribute instance-attribute

metadata_directory: Path | None = field(default=None, repr=False)

metadata_sha256 class-attribute instance-attribute

metadata_sha256: str | None = field(default=None, repr=False)

ProviderContext dataclass

ProviderContext(scope_id: str, authentication_reference: str, command_timeout: float = 45.0, inventory_limit: int = 10000)

Explicit scope, external CLI authentication reference, and bounded execution limits.

scope_id instance-attribute

scope_id: str

authentication_reference instance-attribute

authentication_reference: str

command_timeout class-attribute instance-attribute

command_timeout: float = 45.0

inventory_limit class-attribute instance-attribute

inventory_limit: int = 10000

ProfileContext dataclass

ProfileContext(identity: StackIdentity)

Exact stack ownership context; profile configuration and artifacts stay separate.

identity instance-attribute

identity: StackIdentity

ProviderExtension

Bases: Protocol

Factory for the existing read-only provider contract, without mandatory mutation.

Descriptor property

Descriptor: ExtensionDescriptor

Return the exact static identity registered before factory loading.

CreateProvider

CreateProvider(context: ProviderContext) -> CloudProvider

Construct a scoped read-only adapter without probing or mutating infrastructure.

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

def CreateProvider(self, context: ProviderContext) -> CloudProvider:
    """Construct a scoped read-only adapter without probing or mutating infrastructure."""

    ...

LifecycleProviderExtension

Bases: ProviderExtension, Protocol

Optional separate factory for the existing owned resource lifecycle contract.

CreateLifecycleProvider

CreateLifecycleProvider(context: ProviderContext) -> LifecycleProvider

Construct a mutation-capable adapter without performing provider operations.

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

def CreateLifecycleProvider(self, context: ProviderContext) -> LifecycleProvider:
    """Construct a mutation-capable adapter without performing provider operations."""

    ...

CompiledProfile

Bases: Protocol

Validated profile adapter that preserves existing artifact and lifecycle boundaries.

Identity property

Identity: StackIdentity

Return the exact identity validated during profile compilation.

BuildServerBundle

BuildServerBundle() -> ArtifactBundle

Generate owned server initialization bytes without writing or deploying them.

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

def BuildServerBundle(self) -> ArtifactBundle:
    """Generate owned server initialization bytes without writing or deploying them."""

    ...

RenderPlan

RenderPlan(*, user_data_file: str | Path) -> str

Render lifecycle TOML after verifying the exact owned server artifact.

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

def RenderPlan(self, *, user_data_file: str | Path) -> str:
    """Render lifecycle TOML after verifying the exact owned server artifact."""

    ...

ProfileExtension

Bases: Protocol

Compile explicit profile configuration using its own strict versioned schema.

Descriptor property

Descriptor: ExtensionDescriptor

Return the exact static identity registered before factory loading.

CompileProfile

CompileProfile(configuration: Mapping[str, object], context: ProfileContext) -> CompiledProfile

Validate configuration and exact ownership without accessing infrastructure.

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

def CompileProfile(
    self, configuration: Mapping[str, object], context: ProfileContext,
) -> CompiledProfile:
    """Validate configuration and exact ownership without accessing infrastructure."""

    ...