flayer.core.config

Module source

flayer.core.config

Strict TOML desired-state loading without provider defaults or secret material.

ConfigError

Bases: ContractError

Desired configuration cannot be safely parsed or read.

SecretReference dataclass

SecretReference(name: str, source: str, reference: str)

A named credential source; resolution belongs to an authentication adapter.

name instance-attribute

name: str

source instance-attribute

source: str

reference instance-attribute

reference: str

DesiredResource dataclass

DesiredResource(logical_id: str, kind: str, name: str)

Provider-independent logical resource identity before an external resource exists.

logical_id instance-attribute

logical_id: str

kind instance-attribute

kind: str

name instance-attribute

name: str

DesiredConfig dataclass

DesiredConfig(identity: StackIdentity, profile: str, resources: tuple[DesiredResource, ...] = (), credentials: tuple[SecretReference, ...] = (), schema_version: int = SCHEMA_VERSION)

Immutable, validated desired intent without observed identifiers or credentials.

identity instance-attribute

identity: StackIdentity

profile instance-attribute

profile: str

resources class-attribute instance-attribute

resources: tuple[DesiredResource, ...] = ()

credentials class-attribute instance-attribute

credentials: tuple[SecretReference, ...] = ()

schema_version class-attribute instance-attribute

schema_version: int = SCHEMA_VERSION

ParseConfig

ParseConfig(data: Mapping[str, object]) -> DesiredConfig

Validate decoded TOML; unknown fields and schema versions always fail closed.

Source code in installed/flayer/core/config.py

def ParseConfig(data: Mapping[str, object]) -> DesiredConfig:
    """Validate decoded TOML; unknown fields and schema versions always fail closed."""

    try:
        ValidateFields(
            data,
            frozenset({"schema_version", "identity", "profile"}),
            frozenset({"resources", "credentials"}),
            "configuration",
        )
        ValidateSchemaVersion(data["schema_version"])

        return DesiredConfig(
            identity=ParseIdentity(data["identity"]),
            profile=ValidateName(data["profile"], "profile"),
            resources=_ParseResources(data.get("resources", [])),
            credentials=_ParseCredentials(data.get("credentials", [])),
        )

    except ContractError as error:
        raise ConfigError(str(error)) from error

LoadConfig

LoadConfig(path: str | Path) -> DesiredConfig

Load an explicit TOML path with no implicit local defaults or environment overrides.

Source code in installed/flayer/core/config.py

def LoadConfig(path: str | Path) -> DesiredConfig:
    """Load an explicit TOML path with no implicit local defaults or environment overrides."""

    try:
        with Path(path).open("rb") as stream:
            data = tomllib.load(stream)

    except (OSError, ValueError, RecursionError) as error:
        raise ConfigError("Unable to read a valid TOML configuration") from error

    return ParseConfig(data)