paas-charm 2.0.dev3__tar.gz → 2.0.dev4__tar.gz

{paas_charm-2.0.dev3 → paas_charm-2.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paas-charm
-Version: 2.0.dev3
+Version: 2.0.dev4
 Summary: Companion library for 12-factor app support in Charmcraft & Rockcraft.
 Author-email: Canonical IS DevOps team <is-devops-team@canonical.com>
 Project-URL: Repository, https://github.com/canonical/paas-charm

{paas_charm-2.0.dev3 → paas_charm-2.0.dev4}/pyproject.toml

@@ -2,7 +2,7 @@
 # See LICENSE file for licensing details.
 [project]
 name = "paas-charm"
-version = "2.0.dev3"
+version = "2.0.dev4"
 description = "Companion library for 12-factor app support in Charmcraft & Rockcraft."
 readme = "README.md"
 authors = [
@@ -40,7 +40,7 @@ where = ["src"]
 
 [tool.uv.sources]
 # opcli is published only from the charm-ci git repository, not PyPI.
-opcli = { git = "https://github.com/canonical/charm-ci.git", tag = "v1.0.1" }
+opcli = { git = "https://github.com/canonical/charm-ci.git", tag = "v1.0.2" }
 
 [tool.setuptools.package-data]
 paas_charm = ["**/cos/**", "**/cos/**/.**", "**/*.j2", "**/templates/**/*.py", "**/templates/**/*.json"]

{paas_charm-2.0.dev3 → paas_charm-2.0.dev4}/src/paas_charm/app.py

@@ -16,7 +16,8 @@ from dpcharmlibs.interfaces import ValkeyResponseModel
 
 from paas_charm.charm_state import CharmState
 from paas_charm.database_migration import DatabaseMigration
-from paas_charm.paas_config import LoggingFormat
+from paas_charm.exceptions import PaasConfigError
+from paas_charm.paas_config import EnvVarConfig, LoggingFormat, SecretEnvVarsConfig
 
 logger = logging.getLogger(__name__)
 
@@ -442,38 +443,198 @@ class App:  # pylint: disable=too-many-instance-attributes
         self._run_migrations()
         self._container.replan()
 
-    # 2024/04/25 - we're refactoring this method which will get rid of map_integrations_to_env
-    # wrapper function. Ignore too-complex error from flake8 for now.
-    # pylint: disable=too-many-branches
-    def gen_environment(self) -> dict[str, str]:  # noqa: too-complex
-        """Generate a environment dictionary from the charm configurations.
-
-        The environment generation follows these rules:
-             1. User-defined configuration cannot overwrite built-in framework configurations,
-                even if the built-in framework application configuration value is None (undefined).
-             2. Boolean and integer-typed configuration values will be JSON encoded before
-                being passed to application.
-             3. String-typed configuration values will be passed to the application as environment
-                variables directly.
-             4. Different prefixes can be set to the environment variable names depending on the
-                framework.
+    def gen_environment(self) -> dict[str, str]:
+        """Generate the final workload environment in precedence order.
+
+        Explicit config mappings override integrations, which override library-generated
+        variables. The config/framework layer comes from ``_framework_environment``.
+
+        Returns:
+            The final environment with string-encoded values.
+        """
+        framework_sources = self._framework_config_mapping_sources()
+        env = self._framework_environment()
+        for name, value in self._generate_integration_environments(
+            prefix=self.integrations_prefix
+        ).items():
+            if name in env:
+                logger.warning(
+                    "Environment variable %r for a relation or Prometheus metrics overwrites an "
+                    "environment variable from charm configuration or framework settings",
+                    name,
+                )
+            env[name] = value
+        for name, (source, value) in self._mapped_config_environment(framework_sources).items():
+            if name in env:
+                logger.warning(
+                    "Explicit config.options mapping from %r overwrites environment variable %r",
+                    source,
+                    name,
+                )
+            env[name] = value
+        return env
+
+    def _mapped_framework_config_fields(self) -> set[str]:
+        """Get framework fields whose default outputs are explicitly renamed.
+
+        Returns:
+            Framework field names, excluding unmapped secret-key entries.
+        """
+        mappings = self._charm_state.config_options.options
+        return {
+            field
+            for option, field in self._charm_state.framework_config_fields.items()
+            if (mapping := mappings.get(option)) is not None
+            and (
+                isinstance(mapping, EnvVarConfig)
+                or (
+                    field in ("secret_key", "app_secret_key")
+                    and "value" in mapping.secret_env_vars
+                    and not isinstance(self._charm_state.framework_config.get(field), dict)
+                )
+            )
+        }
+
+    def _framework_config_mapping_sources(self) -> dict[str, str | dict[str, str]]:
+        """Read resolved framework values without borrowing unrelated generated outputs.
+
+        Returns:
+            Values keyed by exact option names, using the existing encoding and key fallback.
+        """
+        sources: dict[str, str | dict[str, str]] = {}
+        for option, mapping in self._charm_state.config_options.options.items():
+            field = self._charm_state.framework_config_fields.get(option)
+            if field is None:
+                continue
+            value = self._charm_state.framework_config.get(field)
+            if value is None and field in ("secret_key", "app_secret_key"):
+                value = self._charm_state.secret_key
+            if value is None:
+                continue
+            if isinstance(mapping, SecretEnvVarsConfig):
+                if isinstance(value, dict):
+                    sources[option] = value
+                elif field in ("secret_key", "app_secret_key"):
+                    sources[option] = {"value": encode_env(value)}
+                else:
+                    sources[option] = encode_env(value)
+            else:
+                sources[option] = encode_env(value)
+        return sources
+
+    def _mapped_config_environment(
+        self, framework_sources: dict[str, str | dict[str, str]]
+    ) -> dict[str, tuple[str, str]]:
+        """Generate explicit config destinations from their original source values.
+
+        Args:
+            framework_sources: Resolved framework outputs keyed by exact option names,
+                including secret-key fallbacks.
+
+        Returns:
+            Destinations mapped to source names and encoded values, omitting absent values.
+
+        Raises:
+            PaasConfigError: If a secret mapping receives non-secret content.
+        """
+        env: dict[str, tuple[str, str]] = {}
+        for option, mapping in self._charm_state.config_options.options.items():
+            value = (
+                framework_sources.get(option)
+                if option in self._charm_state.framework_config_fields
+                else self._charm_state.user_defined_config.get(option.replace("-", "_"))
+            )
+            if value is None:
+                continue
+            if isinstance(mapping, SecretEnvVarsConfig):
+                if not isinstance(value, collections.abc.Mapping):
+                    raise PaasConfigError(
+                        f"config.options.{option}.secret-env-vars requires secret content"
+                    )
+                for key, destination in mapping.secret_env_vars.items():
+                    if key not in value:
+                        logger.warning(
+                            "Charm configuration option %r has no secret content key %r; "
+                            "skipping mapped environment variable %r",
+                            option,
+                            key,
+                            destination,
+                        )
+                        continue
+                    env[destination] = (f"{option}.{key}", encode_env(value[key]))
+            else:
+                env[mapping.env_var] = (option, encode_env(value))
+        return env
+
+    def _unmapped_framework_config(self) -> dict[str, str | int | bool | dict[str, str]]:
+        """Keep framework defaults and secret entries that have not been renamed.
 
         Returns:
-            A dictionary representing the application environment variables.
+            Resolved framework configuration with mapped fields or secret entries omitted.
+        """
+        mapped_fields = self._mapped_framework_config_fields()
+        config = {
+            field: value
+            for field, value in self._charm_state.framework_config.items()
+            if field not in mapped_fields
+        }
+        for option, field in self._charm_state.framework_config_fields.items():
+            mapping = self._charm_state.config_options.options.get(option)
+            value = config.get(field)
+            if (
+                isinstance(mapping, SecretEnvVarsConfig)
+                and isinstance(value, dict)
+                and value.keys() & mapping.secret_env_vars.keys()
+            ):
+                remaining = {
+                    key: val for key, val in value.items() if key not in mapping.secret_env_vars
+                }
+                if remaining:
+                    config[field] = remaining
+                else:
+                    config.pop(field)
+        return config
+
+    def _framework_environment(self) -> dict[str, str]:  # noqa: too-complex
+        """Build config and library-owned variables before higher-priority overrides.
+
+        Explicitly mapped sources are omitted from their default names. Unmapped config
+        retains its existing prefixes and value encoding. Framework subclasses extend
+        this layer; ``gen_environment`` then applies relations and explicit mappings.
+
+        Returns:
+            The config/framework environment with string-encoded values.
         """
         prefix = self.configuration_prefix
         env = {}
+        mappings = {
+            option.replace("-", "_"): mapping
+            for option, mapping in self._charm_state.config_options.options.items()
+        }
         for app_config_key, app_config_value in self._charm_state.user_defined_config.items():
+            mapping = mappings.get(app_config_key)
+            if app_config_key in self._charm_state.framework_config_field_names or isinstance(
+                mapping, EnvVarConfig
+            ):
+                continue
+            if isinstance(mapping, SecretEnvVarsConfig) and app_config_value is None:
+                continue
+            mapped_keys = (
+                mapping.secret_env_vars if isinstance(mapping, SecretEnvVarsConfig) else {}
+            )
             if isinstance(app_config_value, collections.abc.Mapping):
                 for k, v in app_config_value.items():
+                    if k in mapped_keys:
+                        continue
                     env[f"{prefix}{app_config_key.upper()}_{k.replace('-', '_').upper()}"] = (
                         encode_env(v)
                     )
             else:
                 env[f"{prefix}{app_config_key.upper()}"] = encode_env(app_config_value)
 
-        framework_config = self._charm_state.framework_config
+        framework_config = self._unmapped_framework_config()
         framework_config_prefix = self.framework_config_prefix
+        mapped_fields = self._mapped_framework_config_fields()
         env.update(
             {
                 f"{framework_config_prefix}{k.upper()}": encode_env(v)
@@ -488,7 +649,7 @@ class App:  # pylint: disable=too-many-instance-attributes
         if self._charm_state.base_url:
             env[f"{prefix}BASE_URL"] = self._charm_state.base_url
         secret_key_env = f"{prefix}SECRET_KEY"
-        if secret_key_env not in env:
+        if secret_key_env not in env and not {"secret_key", "app_secret_key"} & mapped_fields:
             env[secret_key_env] = self._charm_state.secret_key
         for proxy_variable in ("http_proxy", "https_proxy", "no_proxy"):
             proxy_value = getattr(self._charm_state.proxy, proxy_variable)
@@ -499,8 +660,6 @@ class App:  # pylint: disable=too-many-instance-attributes
         if self._charm_state.peer_fqdns is not None:
             env[f"{prefix}PEER_FQDNS"] = self._charm_state.peer_fqdns
 
-        env.update(self._generate_integration_environments(prefix=self.integrations_prefix))
-
         return env
 
     def _generate_integration_environments(self, prefix: str = "") -> dict[str, str]:

{paas_charm-2.0.dev3 → paas_charm-2.0.dev4}/src/paas_charm/charm.py

@@ -18,7 +18,12 @@ from ops.model import Container
 from pydantic import BaseModel, ValidationError
 
 from paas_charm.app import App, WorkloadConfig
-from paas_charm.charm_state import CharmState, IntegrationRequirers
+from paas_charm.charm_state import (
+    CharmState,
+    IntegrationRequirers,
+    framework_config_option_fields,
+    is_user_defined_config,
+)
 from paas_charm.charm_utils import block_if_invalid_data
 from paas_charm.database_migration import DatabaseMigration, DatabaseMigrationStatus
 from paas_charm.databases import make_database_requirers
@@ -32,6 +37,7 @@ from paas_charm.oauth import PaaSOAuthRequirer
 from paas_charm.observability import Observability
 from paas_charm.paas_config import (
     FRAMEWORKS_SUPPORTING_LOGGING_FORMAT,
+    ConfigOptions,
     LoggingFormat,
     read_paas_config,
 )
@@ -45,6 +51,7 @@ from paas_charm.tracing import PaaSTracingEndpointRequirer
 from paas_charm.utils import (
     build_validation_error_message,
     config_get_with_secret,
+    config_metadata,
     get_endpoints_by_interface_name,
     merge_cos_directories,
 )
@@ -96,6 +103,19 @@ class PaasCharm(abc.ABC, ops.CharmBase):  # pylint: disable=too-many-instance-at
         super().__init__(framework)
         self._framework_name = framework_name
         self._paas_config = read_paas_config()
+        config_options: ConfigOptions = self._paas_config.config
+        if config_options.options:  # pylint: disable=no-member
+            options = config_metadata(pathlib.Path(self.charm_dir))["options"]
+            framework_fields = framework_config_option_fields(
+                self.framework_config_class, options.keys()
+            )
+            unsupported = {
+                option
+                for option in options
+                if not is_user_defined_config(option, framework_name)
+                and option not in framework_fields
+            }
+            config_options.validate_sources(options, unsupported)  # pylint: disable=no-member
 
         self._secret_key = SecretKeyStorage(charm=self, label="app-secret-key")
         self._peers = Peers(charm=self)
@@ -769,6 +789,7 @@ class PaasCharm(abc.ABC, ops.CharmBase):  # pylint: disable=too-many-instance-at
             config=config,
             framework=self._framework_name,
             framework_config=self.get_framework_config(),
+            config_options=self._paas_config.config,
             secret_key=self._secret_key,
             peers=self._peers,
             integration_requirers=IntegrationRequirers(

{paas_charm-2.0.dev3 → paas_charm-2.0.dev4}/src/paas_charm/charm_state.py

@@ -9,13 +9,14 @@ import pathlib
 import typing
 from dataclasses import dataclass, field
 
-from pydantic import BaseModel, Field, ValidationError, create_model
+from pydantic import AliasChoices, BaseModel, Field, ValidationError, create_model
 
 from paas_charm.exceptions import (
     CharmConfigInvalidError,
     InvalidRelationDataError,
     RelationDataError,
 )
+from paas_charm.paas_config import ConfigOptions
 from paas_charm.peers import Peers
 from paas_charm.relations import CustomRelation
 from paas_charm.secret_key import SecretKeyStorage
@@ -50,6 +51,9 @@ class CharmState:  # pylint: disable=too-many-instance-attributes
         secret_key: the charm managed application secret key.
         is_secret_key_ready: whether the application secret key is ready.
         proxy: proxy information.
+        config_options: Settings for existing charm configuration options.
+        framework_config_fields: Accepted framework config input names mapped to model fields.
+        framework_config_field_names: Framework fields protected from implicit user config outputs.
     """
 
     def __init__(  # pylint: disable=too-many-arguments
@@ -58,12 +62,15 @@ class CharmState:  # pylint: disable=too-many-instance-attributes
         framework: str,
         is_secret_key_ready: bool,
         user_defined_config: dict[str, int | str | bool | dict[str, str]] | None = None,
-        framework_config: dict[str, int | str] | None = None,
+        framework_config: dict[str, int | str | dict[str, str]] | None = None,
         secret_key: str | None = None,
         peer_fqdns: str | None = None,
         integrations: "IntegrationsState | None" = None,
         base_url: str | None = None,
+        config_options: ConfigOptions | None = None,
+        framework_config_fields: dict[str, str] | None = None,
         custom_relations: list[CustomRelation] | None = None,
+        framework_config_field_names: set[str] | None = None,
     ):
         """Initialize a new instance of the CharmState class.
 
@@ -76,7 +83,10 @@ class CharmState:  # pylint: disable=too-many-instance-attributes
             peer_fqdns: The FQDN of units in the peer relation.
             integrations: Information about the integrations.
             base_url: Base URL for the service.
+            config_options: Settings for existing charm configuration options.
+            framework_config_fields: Accepted framework config input names mapped to model fields.
             custom_relations: Custom relations.
+            framework_config_field_names: Framework fields protected from implicit user outputs.
         """
         self.framework = framework
         self._framework_config = framework_config if framework_config is not None else {}
@@ -86,6 +96,9 @@ class CharmState:  # pylint: disable=too-many-instance-attributes
         self.peer_fqdns = peer_fqdns
         self.integrations = integrations or IntegrationsState()
         self.base_url = base_url
+        self.config_options = config_options if config_options is not None else ConfigOptions()
+        self.framework_config_fields = framework_config_fields or {}
+        self.framework_config_field_names = framework_config_field_names or set()
         self.custom_relations = custom_relations or []
 
     @classmethod
@@ -101,6 +114,7 @@ class CharmState:  # pylint: disable=too-many-instance-attributes
         integration_requirers: "IntegrationRequirers",
         custom_relations: list[CustomRelation] | None = None,
         base_url: str | None = None,
+        config_options: ConfigOptions | None = None,
     ) -> "CharmState":
         """Initialize a new instance of the CharmState class from the associated charm.
 
@@ -114,6 +128,7 @@ class CharmState:  # pylint: disable=too-many-instance-attributes
             integration_requirers: The collection of integration requirers.
             custom_relations: Custom relations.
             base_url: Base URL for the service.
+            config_options: Settings for existing charm configuration options.
 
         Return:
             The CharmState instance created by the provided charm.
@@ -122,16 +137,22 @@ class CharmState:  # pylint: disable=too-many-instance-attributes
             CharmConfigInvalidError: If some parameter in invalid.
             RelationDataError: When relation data is either unavailable, invalid or not usable.
         """
+        framework_fields = framework_config_option_fields(type(framework_config), config.keys())
+        for option, field_name in framework_config_option_fields(
+            type(framework_config), config_metadata(pathlib.Path(charm_dir))["options"]
+        ).items():
+            if field_name not in framework_fields.values():
+                framework_fields[option] = field_name
+        framework_options = set(framework_fields)
         user_defined_config = {
             k.replace("-", "_"): v
             for k, v in config.items()
-            if is_user_defined_config(k, framework)
-        }
-        user_defined_config = {
-            k: v for k, v in user_defined_config.items() if k not in framework_config.dict().keys()
+            if is_user_defined_config(k, framework) and k not in framework_options
         }
 
-        app_config_class = app_config_class_factory(charm_dir, framework)
+        app_config_class = app_config_class_factory(
+            charm_dir, framework, framework_options=framework_options
+        )
         try:
             app_config_class(**user_defined_config)
         except ValidationError as exc:
@@ -230,6 +251,9 @@ class CharmState:  # pylint: disable=too-many-instance-attributes
             secret_key=(secret_key.get_secret_key() if secret_key.is_ready else None),
             is_secret_key_ready=secret_key.is_ready,
             peer_fqdns=peer_fqdns,
+            config_options=config_options,
+            framework_config_fields=framework_fields,
+            framework_config_field_names=set(type(framework_config).model_fields),
             integrations=integrations,
             base_url=base_url,
             custom_relations=custom_relations,
@@ -256,7 +280,7 @@ class CharmState:  # pylint: disable=too-many-instance-attributes
         )
 
     @property
-    def framework_config(self) -> dict[str, str | int | bool]:
+    def framework_config(self) -> dict[str, str | int | bool | dict[str, str]]:
         """Get the value of the framework application specific configuration.
 
         Returns:
@@ -413,12 +437,19 @@ def _create_config_attribute(option_name: str, option: dict) -> tuple[str, tuple
     return (option_name, type_tuple)
 
 
-def app_config_class_factory(charm_dir: pathlib.Path, framework: str) -> type[BaseModel]:
+def app_config_class_factory(
+    charm_dir: pathlib.Path,
+    framework: str,
+    *,
+    framework_options: set[str] | None = None,
+) -> type[BaseModel]:
     """App config class factory.
 
     Args:
         charm_dir: The charm directory.
         framework: The framework name.
+        framework_options: Exact framework-owned option names to exclude.
+            If omitted, only reserved prefixes are excluded.
 
     Returns:
         Constructed app config class.
@@ -428,11 +459,43 @@ def app_config_class_factory(charm_dir: pathlib.Path, framework: str) -> type[Ba
         _create_config_attribute(option_name, config_options[option_name])
         for option_name in config_options
         if is_user_defined_config(option_name, framework)
+        and (framework_options is None or option_name not in framework_options)
     )
     # mypy doesn't like the model_attributes dict
     return create_model("AppConfig", **model_attributes)  # type: ignore[call-overload]
 
 
+def framework_config_option_fields(
+    framework_config_class: type[BaseModel], options: typing.Collection[str]
+) -> dict[str, str]:
+    """Map accepted flat config inputs to their framework model fields.
+
+    Args:
+        framework_config_class: Framework configuration model class.
+        options: Available charm configuration option names.
+
+    Returns:
+        Exact input names selected according to the model's alias validation rules.
+    """
+    config = framework_config_class.model_config
+    allow_name = config.get("validate_by_name", config.get("populate_by_name", False))
+    fields: dict[str, str] = {}
+    for field_name, model_field in framework_config_class.model_fields.items():
+        names: list[str] = []
+        alias = model_field.validation_alias
+        if config.get("validate_by_alias") is not False:
+            if isinstance(alias, str):
+                names.append(alias)
+            elif isinstance(alias, AliasChoices):
+                names.extend(name for name in alias.choices if isinstance(name, str))
+        if alias is None or allow_name:
+            names.append(field_name)
+        source = next((name for name in names if name in options), None)
+        if source is not None:
+            fields[source] = field_name
+    return fields
+
+
 def is_user_defined_config(option_name: str, framework: str) -> bool:
     """Check if a config option is user defined.
 

{paas_charm-2.0.dev3 → paas_charm-2.0.dev4}/src/paas_charm/fastapi/app.py

@@ -78,13 +78,13 @@ class FastAPIApp(App):
             )
             logger.debug("Pushed %s to container", filename)
 
-    def gen_environment(self) -> dict[str, str]:
-        """Return the application environment, adding logging vars when JSON is configured.
+    def _framework_environment(self) -> dict[str, str]:
+        """Build the config/framework layer, including structured logging variables.
 
         Returns:
-            A dictionary representing the application environment variables.
+            Config and library-owned variables before relations and explicit mappings.
         """
-        env = super().gen_environment()
+        env = super()._framework_environment()
         if self._workload_config.logging_format == LoggingFormat.JSON:
             existing = env.get("PYTHONPATH", "")
             env["PYTHONPATH"] = (

{paas_charm-2.0.dev3 → paas_charm-2.0.dev4}/src/paas_charm/paas_config.py

@@ -153,6 +153,110 @@ class PrometheusConfig(BaseModel):
         return self
 
 
+class EnvVarConfig(BaseModel):
+    """Environment variable name for a non-secret charm configuration option.
+
+    Attributes:
+        env_var: Complete environment variable name.
+        model_config: Pydantic model configuration.
+    """
+
+    env_var: str = Field(alias="env-var")
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+
+class SecretEnvVarsConfig(BaseModel):
+    """Environment variable names for a secret charm configuration option.
+
+    Attributes:
+        secret_env_vars: Secret content keys mapped to complete environment variable names.
+        model_config: Pydantic model configuration.
+    """
+
+    secret_env_vars: dict[str, str] = Field(alias="secret-env-vars")
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+
+class ConfigOptions(BaseModel):
+    """Settings for existing charm configuration options.
+
+    Attributes:
+        options: Exact charm configuration option names mapped to their settings.
+        model_config: Pydantic model configuration.
+    """
+
+    options: dict[str, EnvVarConfig | SecretEnvVarsConfig] = Field(default_factory=dict)
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    @model_validator(mode="after")
+    def validate_destinations(self) -> "ConfigOptions":
+        """Validate destination names and reject ambiguous mappings.
+
+        Returns:
+            The validated configuration.
+
+        Raises:
+            ValueError: If a destination is invalid or used by multiple sources.
+        """
+        destinations: dict[str, str] = {}
+        for option, mapping in self.options.items():  # pylint: disable=no-member
+            entries = (
+                mapping.secret_env_vars.items()
+                if isinstance(mapping, SecretEnvVarsConfig)
+                else [(None, mapping.env_var)]
+            )
+            for key, destination in entries:
+                source = option if key is None else f"{option}.{key}"
+                if not destination or "\0" in destination or "=" in destination:
+                    raise ValueError(
+                        f"Invalid environment variable name for {source!r} in {CONFIG_FILE_NAME}: "
+                        "destination names must be non-empty and contain neither '=' nor NUL"
+                    )
+                if destination in destinations:
+                    raise ValueError(
+                        f"Environment variable {destination!r} is mapped from both "
+                        f"{destinations[destination]!r} and {source!r}"
+                    )
+                destinations[destination] = source
+        return self
+
+    def validate_sources(self, options: dict, unsupported: set[str]) -> None:
+        """Validate sources against charm configuration metadata.
+
+        Args:
+            options: Charm configuration option metadata.
+            unsupported: Option names without mappable environment outputs.
+
+        Raises:
+            PaasConfigError: If an option is unknown, unsupported, or has the wrong mapping shape.
+        """
+        for option, mapping in self.options.items():  # pylint: disable=no-member
+            if option not in options:
+                raise PaasConfigError(
+                    f"{CONFIG_FILE_NAME}: config.options references unknown "
+                    f"charm configuration option {option!r}"
+                )
+            if option in unsupported:
+                raise PaasConfigError(
+                    f"{CONFIG_FILE_NAME}: config.options cannot map option {option!r}: "
+                    "it has no configuration-derived environment output"
+                )
+            normalized = option.replace("-", "_")
+            for other in options:
+                if other != option and other.replace("-", "_") == normalized:
+                    raise PaasConfigError(
+                        f"{CONFIG_FILE_NAME}: config.options cannot distinguish charm configuration "
+                        f"options {option!r} and {other!r}: hyphens and underscores are "
+                        "treated identically internally"
+                    )
+            is_secret = options[option]["type"] == "secret"
+            if is_secret != isinstance(mapping, SecretEnvVarsConfig):
+                expected = "secret-env-vars" if is_secret else "env-var"
+                raise PaasConfigError(
+                    f"{CONFIG_FILE_NAME}: config.options.{option} must use {expected!r}"
+                )
+
+
 class PaasConfig(BaseModel):
     """Configuration from paas-config.yaml file.
 
@@ -165,11 +269,13 @@ class PaasConfig(BaseModel):
         port: Optional override for the port on which the application server listens.
         metrics_port: Optional override for the port on which the application serves metrics.
         metrics_path: Optional override for the path on which the application serves metrics.
+        config: Settings for existing charm configuration options.
     """
 
     prometheus: PrometheusConfig | None = Field(
         default=None, description="Prometheus configuration"
     )
+    config: ConfigOptions = Field(default_factory=ConfigOptions)
     framework_logging_format: LoggingFormat = Field(
         default=LoggingFormat.NONE,
         description="Structured logging format for the framework server (e.g. 'json').",
@@ -273,7 +379,7 @@ def read_paas_config(charm_root: pathlib.Path | None = None) -> PaasConfig:
     try:
         return PaasConfig(**config_data)
     except ValidationError as exc:
-        error_details = build_validation_error_message(exc, underscore_to_dash=True)
+        error_details = build_validation_error_message(exc)
         error_msg = f"Invalid {CONFIG_FILE_NAME}: {error_details.short}"
         logger.error("%s: %s", error_msg, error_details.long)
         raise PaasConfigError(error_msg) from exc

{paas_charm-2.0.dev3 → paas_charm-2.0.dev4}/src/paas_charm/springboot/charm.py

@@ -360,20 +360,23 @@ class SpringBootApp(App):
     generate_prometheus_env = staticmethod(generate_prometheus_env)
     generate_oauth_env = staticmethod(generate_oauth_env)
 
-    def gen_environment(self) -> dict[str, str]:
-        """Generate a environment dictionary from the charm configurations.
+    def _framework_environment(self) -> dict[str, str]:
+        """Build the config/framework layer with Spring Boot-specific settings.
 
-        Adds to the base environment variables specific ones for the Spring Boot framework.
+        Relation outputs and explicit mappings are applied afterward.
 
         Returns:
-            A dictionary representing the application environment variables.
+            Config and library-owned variables before relations and explicit mappings.
         """
-        env = super().gen_environment()
+        env = super()._framework_environment()
         env.pop("METRICS_PORT", None)
         env.pop("METRICS_PATH", None)
         # Name of the profiles field in SpringBootConfig
         profiles_field = "app_profiles"
-        if profiles_field in self._charm_state.framework_config:
+        if (
+            profiles_field in self._charm_state.framework_config
+            and profiles_field not in self._mapped_framework_config_fields()
+        ):
             env["spring.profiles.active"] = str(self._charm_state.framework_config[profiles_field])
         # Required because of the strip prefix in the ingress configuration.
         env["server.forward-headers-strategy"] = "framework"

{paas_charm-2.0.dev3 → paas_charm-2.0.dev4}/src/paas_charm.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paas-charm
-Version: 2.0.dev3
+Version: 2.0.dev4
 Summary: Companion library for 12-factor app support in Charmcraft & Rockcraft.
 Author-email: Canonical IS DevOps team <is-devops-team@canonical.com>
 Project-URL: Repository, https://github.com/canonical/paas-charm