Fix #21: use Pydantic for validation of env config (#101)

The application now features comprehensive validation for the Environment
configuration (env.toml) using Pydantic. This ensures all configuration files strictly 
adhere to the required schema, enforcing correct data types for fields (e.g., paths,
URLs, network addresses) and immediately catching errors like missing keys or 
incorrect values. This change stabilizes the configuration loading process and
eliminates runtime errors caused by misconfigured environments.

Signed-off-by: sushant-suse <[email protected]>

Author: sushant-suse

changelog.d/101.bugfix.rst

@@ -0,0 +1 @@
+The application now features comprehensive validation for the Environment Configuration (`env.toml`) using Pydantic. This ensures all configuration files strictly adhere to the required schema, enforcing correct data types for fields (for example, paths, URLs, network addresses) and immediately catching errors like missing keys or incorrect values. This change stabilizes the configuration loading process and eliminates runtime errors caused by misconfigured environments.

src/docbuild/cli/cmd_cli.py

@@ -15,6 +15,8 @@
 from ..config.app import replace_placeholders
 from ..config.load import handle_config
 from ..models.config_model.app import AppConfig
+from ..models.config_model.env import EnvConfig 
+
 from ..constants import (
     APP_CONFIG_BASENAMES,
     APP_NAME,
@@ -159,12 +161,12 @@ def cli(
     logging_config = context.appconfig.logging.model_dump(by_alias=True, exclude_none=True)
     setup_logging(cliverbosity=verbose, user_config={'logging': logging_config})
 
-    # --- PHASE 2: Load Environment Config and Acquire Lock ---
+    # --- PHASE 2: Load Environment Config, Validate, and Acquire Lock ---
 
-    # Load Environment Config (still returns raw dict)
+    # 1. Load raw Environment Config
     (
         context.envconfigfiles,
-        context.envconfig,
+        raw_envconfig, # Renaming context.envconfig to raw_envconfig locally
         context.envconfig_from_defaults,
     ) = handle_config(
         env_config,
@@ -174,10 +176,23 @@ def cli(
         DEFAULT_ENV_CONFIG,
     )
 
-    env_config_path = context.envconfigfiles[0] if context.envconfigfiles else None
+    # Explicitly cast the raw_envconfig type to silence Pylance
+    raw_envconfig = cast(dict[str, Any], raw_envconfig)
 
-    # Explicitly cast the context.envconfig type to silence Pylance
-    context.envconfig = cast(dict[str, Any], context.envconfig)
+    # 2. VALIDATE the raw environment config dictionary using Pydantic
+    try:
+        # Pydantic validation handles placeholder replacement via @model_validator
+        # The result is the validated Pydantic object, stored in context.envconfig
+        context.envconfig = EnvConfig.from_dict(raw_envconfig)
+    except (ValueError, ValidationError) as e:
+        log.error(
+             "Environment configuration failed validation: "
+             "Error in config file(s): %s %s",
+             context.envconfigfiles, e
+        )
+        ctx.exit(1)
+    
+    env_config_path = context.envconfigfiles[0] if context.envconfigfiles else None
 
     # --- CONCURRENCY CONTROL: Use explicit __enter__ and cleanup registration ---
     if env_config_path:
@@ -203,11 +218,6 @@ def cli(
         # expected by __exit__, satisfying the click.call_on_close requirement.
         ctx.call_on_close(lambda: ctx.obj.env_lock.__exit__(None, None, None))
 
-    # Final config processing must happen outside the lock acquisition check
-    context.envconfig = replace_placeholders(
-        context.envconfig,
-    )
-    
 # Add subcommand
 cli.add_command(build)
 cli.add_command(c14n)

src/docbuild/cli/cmd_config/environment.py

@@ -1,8 +1,9 @@
 """CLI interface to showsthe configuration of the environment files."""
 
 import click
-from rich import print  # noqa: A004
+from rich import print 
 from rich.pretty import Pretty
+from rich import print_json
 
 
 @click.command(
@@ -14,6 +15,15 @@ def env(ctx: click.Context) -> None:
 
     :param ctx: The Click context object.
     """
-    path = ', '.join(str(path) for path in ctx.obj.envconfigfiles)
+
+    # Check if envconfigfiles is None (which it is when the default config is used)
+    if ctx.obj.envconfigfiles is None:
+        path = '(Default configuration used)'
+    else:
+        path = ', '.join(str(path) for path in ctx.obj.envconfigfiles)
+        
     click.secho(f"# ENV Config file '{path}'", fg='blue')
-    print(Pretty(ctx.obj.envconfig, expand_all=True))
+    
+    serialized_config = ctx.obj.envconfig.model_dump_json()
+
+    print_json(serialized_config)

src/docbuild/cli/defaults.py

@@ -9,6 +9,7 @@
 
 from ..constants import APP_NAME
 
+
 DEFAULT_APP_CONFIG = {
     'debug': False,
     'role': 'production',
@@ -24,16 +25,56 @@
 }
 """Default configuration for the application."""
 
+# --- FIXED DEFAULT_ENV_CONFIG ---
 DEFAULT_ENV_CONFIG = {
-    'role': 'production',
+    # 1. ROOT SECTIONS MUST BE PRESENT AND VALIDATED AGAINST EnvConfig
+    'server': {
+        'name': 'default-local-env',
+        'role': 'production',
+        'host': '127.0.0.1',
+        'enable_mail': False,
+    },
+    'config': {
+        'default_lang': 'en-us',
+        'languages': ['en-us'],
+        'canonical_url_domain': 'http://localhost/',
+    },
     'paths': {
         'config_dir': '/etc/docbuild',
+        'root_config_dir': '/etc/docbuild',
+        'jinja_dir': '/etc/docbuild/jinja',
+        'server_rootfiles_dir': '/etc/docbuild/root-files',
         'repo_dir': '/data/docserv/repos/permanent-full/',
         'temp_repo_dir': '/data/docserv/repos/temporary-branches/',
+        'base_cache_dir': '/var/cache/docserv',
+        'base_server_cache_dir': '/var/cache/docserv/default',
+        'meta_cache_dir': '/var/cache/docserv/default/meta',
+        'base_tmp_dir': f'/var/tmp/{APP_NAME}',
+
+        'tmp': {
+            'tmp_base_dir': f'/var/tmp/{APP_NAME}',
+            'tmp_dir': '{tmp_base_dir}/default-local',
+            'tmp_deliverable_dir': '{tmp_dir}/deliverable',
+            'tmp_metadata_dir': '{tmp_dir}/metadata',
+            'tmp_build_dir': '{tmp_dir}/build/default', 
+            'tmp_out_dir': '{tmp_dir}/out',
+            'log_dir': '{tmp_dir}/log',
+            'tmp_deliverable_name': 'default_deliverable', 
+        },
+        'target': {
+            'target_dir': 'file:///tmp/docbuild/target',
+            'backup_dir': '/tmp/docbuild/backup',
+        }
     },
-    'paths.tmp': {
-        'tmp_base_dir': f'/var/tmp/{APP_NAME}',
-        'tmp_dir': '{tmp_base_dir}/doc-example-com',
+    'build': {
+        'daps': {
+            'command': 'daps',
+            'meta': 'daps metadata',
+        },
+        'container': {
+            'container': 'none',
+        },
     },
+    'xslt-params': {},
 }
-"""Default configuration for the environment."""
+"""Default configuration for the environment."""

src/docbuild/config/load.py

@@ -10,32 +10,7 @@
 from .merge import deep_merge
 
 
-def process_envconfig(envconfigfile: str | Path | None) -> tuple[Path, dict[str, Any]]:
-    """Process the env config.
-
-    Note: This function now returns the raw dictionary. Validation and
-    placeholder replacement should be done by the caller using a Pydantic model
-    (e.g., EnvConfig).
-
-    :param envconfigfile: Path to the env TOML config file.
-    :return: Tuple of the env config file path and the config object (raw dict).
-    :raise ValueError: If neither envconfigfile nor role is provided.
-    """
-    if envconfigfile:
-        envconfigfile = Path(envconfigfile)
-
-    # If we don't have a envconfigfile, we need to find the default one.
-    # We will look for the default env config file in the current directory.
-    elif (rfile := Path(DEFAULT_ENV_CONFIG_FILENAME)).exists():
-        envconfigfile = rfile
-
-    else:
-        raise ValueError(
-            'Could not find default ENV configuration file.',
-        )
-
-    rawconfig = load_single_config(envconfigfile)
-    return envconfigfile, rawconfig
+# --- REMOVED THE OBSOLETE `process_envconfig` FUNCTION ---
 
 
 def load_single_config(configfile: str | Path) -> dict[str, Any]:

src/docbuild/models/config_model/__init__.py

@@ -0,0 +1,5 @@
+"""Config model package for the docbuild application."""
+
+
+from .env import EnvConfig 
+from .app import AppConfig