tigrcorn-config 0.3.16.dev5__py3-none-any.whl

tigrcorn_config/__init__.py

@@ -0,0 +1,46 @@
+from .audit import parser_public_defaults, resolve_effective_defaults
+from .env import load_env_config
+from .files import load_config_file
+from .load import build_config, build_config_from_namespace, build_config_from_sources, config_to_dict
+from .model import (
+    AppConfig,
+    HTTPConfig,
+    ListenerConfig,
+    LoggingConfig,
+    MetricsConfig,
+    ProcessConfig,
+    ProxyConfig,
+    QUICConfig,
+    SchedulerConfig,
+    ServerConfig,
+    TLSConfig,
+    WebSocketConfig,
+)
+from .profiles import get_profile_spec, list_blessed_profiles, resolve_effective_profile_mapping, resolve_profile_spec
+
+__all__ = [
+    "AppConfig",
+    "build_config",
+    "build_config_from_namespace",
+    "build_config_from_sources",
+    "config_to_dict",
+    "get_profile_spec",
+    "HTTPConfig",
+    "ListenerConfig",
+    "list_blessed_profiles",
+    "load_config_file",
+    "load_env_config",
+    "LoggingConfig",
+    "MetricsConfig",
+    "ProcessConfig",
+    "ProxyConfig",
+    "QUICConfig",
+    "parser_public_defaults",
+    "resolve_effective_defaults",
+    "SchedulerConfig",
+    "ServerConfig",
+    "TLSConfig",
+    "WebSocketConfig",
+    "resolve_effective_profile_mapping",
+    "resolve_profile_spec",
+]

tigrcorn_config/audit.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import re
+from typing import Any
+
+from .defaults import default_config
+from .load import build_config, config_to_dict
+from .model import ServerConfig
+from .profiles import get_profile_spec, list_blessed_profiles
+
+
+_RUNTIME_RANDOMIZED = '<runtime-randomized>'
+_RUNTIME_RANDOMIZED_PATTERNS = (
+    re.compile(r'^listeners\[\d+\]\.quic_secret$'),
+)
+
+
+def _jsonable(value: Any) -> Any:
+    if dataclasses.is_dataclass(value):
+        return {field.name: _jsonable(getattr(value, field.name)) for field in dataclasses.fields(value)}
+    if isinstance(value, dict):
+        return {str(key): _jsonable(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_jsonable(item) for item in value]
+    if isinstance(value, tuple):
+        return [_jsonable(item) for item in value]
+    if isinstance(value, bytes):
+        return value.decode('latin1')
+    return value
+
+
+def _sanitize_runtime_audit_values(value: Any, *, prefix: str = '') -> Any:
+    if isinstance(value, dict):
+        return {
+            key: _sanitize_runtime_audit_values(item, prefix=f'{prefix}.{key}' if prefix else str(key))
+            for key, item in value.items()
+        }
+    if isinstance(value, list):
+        return [
+            _sanitize_runtime_audit_values(item, prefix=f'{prefix}[{index}]')
+            for index, item in enumerate(value)
+        ]
+    if any(pattern.match(prefix) for pattern in _RUNTIME_RANDOMIZED_PATTERNS) and value is not None:
+        return _RUNTIME_RANDOMIZED
+    return value
+
+
+def _flatten(value: Any, *, prefix: str = '') -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    if isinstance(value, dict):
+        for key, item in value.items():
+            child_prefix = f'{prefix}.{key}' if prefix else str(key)
+            result.update(_flatten(item, prefix=child_prefix))
+        return result
+    if isinstance(value, list):
+        for index, item in enumerate(value):
+            child_prefix = f'{prefix}[{index}]'
+            result.update(_flatten(item, prefix=child_prefix))
+        if not value and prefix:
+            result[prefix] = []
+        return result
+    result[prefix] = value
+    return result
+
+
+def _diff(before: Any, after: Any) -> Any:
+    if isinstance(before, dict) and isinstance(after, dict):
+        diff: dict[str, Any] = {}
+        for key in sorted(set(before) | set(after)):
+            if key not in before:
+                diff[key] = {'from': None, 'to': after[key]}
+                continue
+            if key not in after:
+                diff[key] = {'from': before[key], 'to': None}
+                continue
+            child = _diff(before[key], after[key])
+            if child not in ({}, None):
+                diff[key] = child
+        return diff
+    if before != after:
+        return {'from': before, 'to': after}
+    return {}
+
+
+def parser_public_defaults() -> list[dict[str, Any]]:
+    from tigrcorn_runtime.cli import build_parser
+
+    parser = build_parser()
+    rows: list[dict[str, Any]] = []
+    for action in parser._actions:
+        if isinstance(action, argparse._HelpAction):
+            continue
+        if action.help == argparse.SUPPRESS:
+            continue
+        for flag in action.option_strings:
+            rows.append(
+                {
+                    'flag': flag,
+                    'dest': action.dest,
+                    'parser_default': _jsonable(action.default),
+                    'help': action.help,
+                    'choices': list(action.choices) if action.choices is not None else None,
+                    'required': bool(action.required),
+                }
+            )
+    return rows
+
+
+def resolve_effective_defaults(profile: str = 'default') -> dict[str, Any]:
+    raw_dataclass = _jsonable(dataclasses.asdict(ServerConfig()))
+    normalized = _jsonable(config_to_dict(default_config()))
+    profile_kwargs: dict[str, Any] = {}
+    for item in get_profile_spec(profile).get('required_overrides', []):
+        if item == 'tls.certfile':
+            profile_kwargs['ssl_certfile'] = 'cert.pem'
+        elif item == 'tls.keyfile':
+            profile_kwargs['ssl_keyfile'] = 'key.pem'
+        elif item == 'tls.ca_certs':
+            profile_kwargs['ssl_ca_certs'] = 'ca.pem'
+        elif item == 'static.mount':
+            profile_kwargs['static_path_mount'] = '/srv/static'
+    effective = _sanitize_runtime_audit_values(_jsonable(config_to_dict(build_config(profile=profile, **profile_kwargs))))
+    parser_rows = parser_public_defaults()
+    base_profile_kwargs: dict[str, Any] = {}
+    for item in get_profile_spec('default').get('required_overrides', []):
+        if item == 'static.mount':
+            base_profile_kwargs['static_path_mount'] = '/srv/static'
+    base_effective = _sanitize_runtime_audit_values(_jsonable(config_to_dict(build_config(profile='default', **base_profile_kwargs))))
+    return {
+        'profile': profile,
+        'blessed_profiles': list(list_blessed_profiles()),
+        'dataclass_model_defaults': raw_dataclass,
+        'dataclass_model_defaults_flat': _flatten(raw_dataclass),
+        'cli_parser_defaults': parser_rows,
+        'cli_parser_defaults_by_flag': {row['flag']: row['parser_default'] for row in parser_rows},
+        'normalization_backfills': _diff(raw_dataclass, normalized),
+        'normalization_backfills_flat': _flatten(_diff(raw_dataclass, normalized)),
+        'profile_overlays': _diff(base_effective, effective),
+        'profile_overlays_flat': _flatten(_diff(base_effective, effective)),
+        'effective_defaults': effective,
+        'effective_defaults_flat': _flatten(effective),
+    }

tigrcorn_config/defaults.py

@@ -0,0 +1,8 @@
+from .model import ServerConfig
+from .normalize import normalize_config
+
+
+def default_config() -> ServerConfig:
+    config = ServerConfig()
+    normalize_config(config)
+    return config

tigrcorn_config/env.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import json
+import os
+import shlex
+from pathlib import Path
+from typing import Any, Mapping
+
+from .merge import merge_config_dicts
+
+_FLAT_ENV_MAP = {
+    "APP": ("app", "target"),
+    "APP_INTERFACE": ("app", "interface"),
+    "FACTORY": ("app", "factory"),
+    "PROFILE": ("app", "profile"),
+    "APP_DIR": ("app", "app_dir"),
+    "LIFESPAN": ("app", "lifespan"),
+    "ENV_FILE": ("app", "env_file"),
+    "HOST": ("listeners", 0, "host"),
+    "PORT": ("listeners", 0, "port"),
+    "UDS": ("listeners", 0, "path"),
+    "TRANSPORT": ("listeners", 0, "kind"),
+    "USER": ("listeners", 0, "user"),
+    "GROUP": ("listeners", 0, "group"),
+    "UMASK": ("listeners", 0, "umask"),
+    "LOG_LEVEL": ("logging", "level"),
+    "ACCESS_LOG": ("logging", "access_log"),
+    "USE_COLORS": ("logging", "use_colors"),
+    "SSL_CERTFILE": ("tls", "certfile"),
+    "SSL_KEYFILE": ("tls", "keyfile"),
+    "SSL_KEYFILE_PASSWORD": ("tls", "keyfile_password"),
+    "SSL_CA_CERTS": ("tls", "ca_certs"),
+    "SSL_REQUIRE_CLIENT_CERT": ("tls", "require_client_cert"),
+    "HTTP": ("http", "http_versions"),
+    "PROTOCOL": ("listeners", 0, "protocols"),
+    "MAX_BODY_SIZE": ("http", "max_body_size"),
+    "MAX_HEADER_SIZE": ("http", "max_header_size"),
+    "HTTP1_MAX_INCOMPLETE_EVENT_SIZE": ("http", "http1_max_incomplete_event_size"),
+    "HTTP1_BUFFER_SIZE": ("http", "http1_buffer_size"),
+    "HTTP1_HEADER_READ_TIMEOUT": ("http", "http1_header_read_timeout"),
+    "HTTP1_KEEP_ALIVE": ("http", "http1_keep_alive"),
+    "HTTP2_MAX_CONCURRENT_STREAMS": ("http", "http2_max_concurrent_streams"),
+    "HTTP2_MAX_HEADERS_SIZE": ("http", "http2_max_headers_size"),
+    "HTTP2_MAX_FRAME_SIZE": ("http", "http2_max_frame_size"),
+    "HTTP2_ADAPTIVE_WINDOW": ("http", "http2_adaptive_window"),
+    "HTTP2_INITIAL_CONNECTION_WINDOW_SIZE": ("http", "http2_initial_connection_window_size"),
+    "HTTP2_INITIAL_STREAM_WINDOW_SIZE": ("http", "http2_initial_stream_window_size"),
+    "HTTP2_KEEP_ALIVE_INTERVAL": ("http", "http2_keep_alive_interval"),
+    "HTTP2_KEEP_ALIVE_TIMEOUT": ("http", "http2_keep_alive_timeout"),
+    "WEBSOCKET_MAX_MESSAGE_SIZE": ("websocket", "max_message_size"),
+    "WEBSOCKET_MAX_QUEUE": ("websocket", "max_queue"),
+    "WEBSOCKET_PING_INTERVAL": ("websocket", "ping_interval"),
+    "WEBSOCKET_PING_TIMEOUT": ("websocket", "ping_timeout"),
+    "WEBSOCKET_COMPRESSION": ("websocket", "compression"),
+    "PROXY_HEADERS": ("proxy", "proxy_headers"),
+    "FORWARDED_ALLOW_IPS": ("proxy", "forwarded_allow_ips"),
+    "ROOT_PATH": ("proxy", "root_path"),
+    "SERVER_HEADER": ("proxy", "server_header"),
+    "DATE_HEADER": ("proxy", "include_date_header"),
+    "HEADER": ("proxy", "default_headers"),
+    "SERVER_NAME": ("proxy", "server_names"),
+    "SSL_ALPN": ("tls", "alpn_protocols"),
+    "SSL_OCSP_MODE": ("tls", "ocsp_mode"),
+    "SSL_OCSP_CACHE_SIZE": ("tls", "ocsp_cache_size"),
+    "SSL_OCSP_MAX_AGE": ("tls", "ocsp_max_age"),
+    "SSL_CRL_MODE": ("tls", "crl_mode"),
+    "SSL_CRL": ("tls", "crl"),
+    "SSL_REVOCATION_FETCH": ("tls", "revocation_fetch"),
+    "CONNECT_POLICY": ("http", "connect_policy"),
+    "CONNECT_ALLOW": ("http", "connect_allow"),
+    "TRAILER_POLICY": ("http", "trailer_policy"),
+    "CONTENT_CODING_POLICY": ("http", "content_coding_policy"),
+    "CONTENT_CODINGS": ("http", "content_codings"),
+    "ENABLE_H2C": ("http", "enable_h2c"),
+    "QUIC_REQUIRE_RETRY": ("quic", "require_retry"),
+    "QUIC_MAX_DATAGRAM_SIZE": ("quic", "max_datagram_size"),
+    "QUIC_IDLE_TIMEOUT": ("quic", "idle_timeout"),
+    "QUIC_EARLY_DATA_POLICY": ("quic", "early_data_policy"),
+    "WEBTRANSPORT_MAX_SESSIONS": ("webtransport", "max_sessions"),
+    "WEBTRANSPORT_MAX_STREAMS": ("webtransport", "max_streams"),
+    "WEBTRANSPORT_MAX_DATAGRAM_SIZE": ("webtransport", "max_datagram_size"),
+    "WEBTRANSPORT_ORIGIN": ("webtransport", "origins"),
+    "WEBTRANSPORT_PATH": ("webtransport", "path"),
+    "TIMEOUT_KEEP_ALIVE": ("http", "keep_alive_timeout"),
+    "READ_TIMEOUT": ("http", "read_timeout"),
+    "WRITE_TIMEOUT": ("http", "write_timeout"),
+    "TIMEOUT_GRACEFUL_SHUTDOWN": ("http", "shutdown_timeout"),
+    "IDLE_TIMEOUT": ("http", "idle_timeout"),
+    "ALT_SVC": ("http", "alt_svc_headers"),
+    "ALT_SVC_AUTO": ("http", "alt_svc_auto"),
+    "ALT_SVC_MAX_AGE": ("http", "alt_svc_max_age"),
+    "ALT_SVC_PERSIST": ("http", "alt_svc_persist"),
+    "STATIC_PATH_ROUTE": ("static", "route"),
+    "STATIC_PATH_MOUNT": ("static", "mount"),
+    "STATIC_PATH_DIR_TO_FILE": ("static", "dir_to_file"),
+    "STATIC_PATH_INDEX_FILE": ("static", "index_file"),
+    "STATIC_PATH_EXPIRES": ("static", "expires"),
+    "RUNTIME": ("process", "runtime"),
+    "WORKER_HEALTHCHECK_TIMEOUT": ("process", "worker_healthcheck_timeout"),
+    "LIMIT_CONCURRENCY": ("scheduler", "limit_concurrency"),
+    "MAX_CONNECTIONS": ("scheduler", "max_connections"),
+    "MAX_TASKS": ("scheduler", "max_tasks"),
+    "MAX_STREAMS": ("scheduler", "max_streams"),
+}
+
+
+class EnvFileError(RuntimeError):
+    pass
+
+
+def _decode_scalar(value: str) -> Any:
+    lowered = value.strip().lower()
+    if lowered in {"true", "false"}:
+        return lowered == "true"
+    if lowered in {"none", "null"}:
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        pass
+    try:
+        return float(value)
+    except ValueError:
+        pass
+    if value and value[0] in "[{":
+        try:
+            return json.loads(value)
+        except Exception:
+            pass
+    if "," in value:
+        return [part.strip() for part in value.split(",") if part.strip()]
+    return value
+
+
+def _nested_set(data: dict[str, Any], path: tuple[str | int, ...], value: Any) -> None:
+    cursor: Any = data
+    for index, segment in enumerate(path[:-1]):
+        nxt = path[index + 1]
+        if isinstance(segment, int):
+            while len(cursor) <= segment:
+                cursor.append({} if not isinstance(nxt, int) else [])
+            cursor = cursor[segment]
+            continue
+        if segment not in cursor:
+            cursor[segment] = [] if isinstance(nxt, int) else {}
+        cursor = cursor[segment]
+    last = path[-1]
+    if isinstance(last, int):
+        while len(cursor) <= last:
+            cursor.append(None)
+        cursor[last] = value
+    else:
+        cursor[last] = value
+
+
+def load_env_file(path: str | Path | None) -> dict[str, str]:
+    if not path:
+        return {}
+    env_path = Path(path)
+    if not env_path.exists():
+        raise EnvFileError(f'env file does not exist: {env_path}')
+    result: dict[str, str] = {}
+    for line_no, raw_line in enumerate(env_path.read_text(encoding='utf-8').splitlines(), 1):
+        line = raw_line.strip()
+        if not line or line.startswith('#'):
+            continue
+        if line.startswith('export '):
+            line = line[7:].strip()
+        if '=' not in line:
+            raise EnvFileError(f'invalid env file line {line_no}: {raw_line!r}')
+        key, raw_value = line.split('=', 1)
+        key = key.strip()
+        if not key:
+            raise EnvFileError(f'invalid env file line {line_no}: empty key')
+        value = raw_value.strip()
+        if value and value[0] in {'"', "'"}:
+            try:
+                parsed = shlex.split(f'VALUE={value}', posix=True)
+                value = parsed[0].split('=', 1)[1]
+            except Exception as exc:
+                raise EnvFileError(f'invalid quoted value on line {line_no}') from exc
+        elif ' #' in value:
+            value = value.split(' #', 1)[0].rstrip()
+        result[key] = value
+    return result
+
+
+def load_env_config(prefix: str = "TIGRCORN", *, environ: Mapping[str, str] | None = None) -> dict[str, Any]:
+    env = dict(os.environ if environ is None else environ)
+    normalized_prefix = prefix.upper().replace("-", "_")
+    nested_prefix = f"{normalized_prefix}__"
+    flat_prefix = f"{normalized_prefix}_"
+    nested: dict[str, Any] = {}
+    flat: dict[str, Any] = {}
+
+    for key, raw_value in env.items():
+        if key.startswith(nested_prefix):
+            path_bits = key[len(nested_prefix):].split("__")
+            path: list[str | int] = []
+            for bit in path_bits:
+                if bit.isdigit():
+                    path.append(int(bit))
+                else:
+                    path.append(bit.lower())
+            _nested_set(nested, tuple(path), _decode_scalar(raw_value))
+        elif key.startswith(flat_prefix):
+            name = key[len(flat_prefix):]
+            path = _FLAT_ENV_MAP.get(name)
+            if path is not None:
+                _nested_set(flat, path, _decode_scalar(raw_value))
+    return merge_config_dicts(flat, nested)

tigrcorn_config/files.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import dataclasses
+import importlib
+import json
+import runpy
+from pathlib import Path
+from typing import Any, Mapping
+
+try:  # pragma: no cover
+    import tomllib  # type: ignore[attr-defined]
+except Exception:  # pragma: no cover
+    tomllib = None  # type: ignore[assignment]
+
+try:  # pragma: no cover
+    import yaml  # type: ignore[import-not-found]
+except Exception:  # pragma: no cover
+    yaml = None  # type: ignore[assignment]
+
+
+class ConfigFileError(RuntimeError):
+    pass
+
+
+def _object_to_mapping(value: Any) -> dict[str, Any]:
+    if isinstance(value, Mapping):
+        return dict(value)
+    if dataclasses.is_dataclass(value):
+        return dataclasses.asdict(value)
+    if callable(value):
+        return _object_to_mapping(value())
+    if hasattr(value, '__dict__'):
+        return {key: item for key, item in vars(value).items() if not key.startswith('_')}
+    raise ConfigFileError(f'config object did not resolve to a mapping: {value!r}')
+
+
+def _extract_python_payload(payload: Mapping[str, Any], *, label: str) -> dict[str, Any]:
+    for key in ('CONFIG', 'config', 'TIGRCORN_CONFIG'):
+        if key in payload:
+            return _object_to_mapping(payload[key])
+    raise ConfigFileError(f'{label} did not expose CONFIG/config/TIGRCORN_CONFIG')
+
+
+def load_config_file(path: str | Path | None) -> dict[str, Any]:
+    if not path:
+        return {}
+    config_path = Path(path)
+    if not config_path.exists():
+        raise ConfigFileError(f'config file does not exist: {config_path}')
+    suffix = config_path.suffix.lower()
+    if suffix == '.json':
+        return json.loads(config_path.read_text(encoding='utf-8'))
+    if suffix in {'.yaml', '.yml'}:
+        if yaml is None:
+            raise ConfigFileError(
+                'YAML loading is unavailable on this Python runtime; '
+                'install tigrcorn[config-yaml] to enable .yaml/.yml config files'
+            )
+        loaded = yaml.safe_load(config_path.read_text(encoding='utf-8'))
+        return _object_to_mapping(loaded or {})
+    if suffix == '.toml':
+        if tomllib is None:
+            raise ConfigFileError('TOML loading is unavailable on this Python runtime')
+        return tomllib.loads(config_path.read_text(encoding='utf-8'))
+    if suffix == '.py':
+        payload = runpy.run_path(str(config_path))
+        return _extract_python_payload(payload, label=f'python config {config_path}')
+    raise ConfigFileError(f'unsupported config file type: {config_path.suffix!r}')
+
+
+def load_config_module(module_name: str) -> dict[str, Any]:
+    module = importlib.import_module(module_name)
+    return _extract_python_payload(vars(module), label=f'config module {module_name}')
+
+
+def load_config_object(spec: str) -> dict[str, Any]:
+    if ':' not in spec:
+        raise ConfigFileError('object config references must use module:object syntax')
+    module_name, object_name = spec.split(':', 1)
+    module = importlib.import_module(module_name)
+    if not hasattr(module, object_name):
+        raise ConfigFileError(f'config object {spec!r} was not found')
+    value = getattr(module, object_name)
+    return _object_to_mapping(value)
+
+
+def load_config_source(source: str | Path | Mapping[str, Any] | Any | None) -> dict[str, Any]:
+    if source is None:
+        return {}
+    if isinstance(source, Mapping):
+        return dict(source)
+    if dataclasses.is_dataclass(source):
+        return dataclasses.asdict(source)
+    if isinstance(source, Path):
+        return load_config_file(source)
+    if isinstance(source, str):
+        candidate = Path(source)
+        if candidate.exists():
+            return load_config_file(candidate)
+        if source.startswith('module:'):
+            return load_config_module(source.split(':', 1)[1])
+        if source.startswith('object:'):
+            return load_config_object(source.split(':', 1)[1])
+        raise ConfigFileError(
+            'config source must be a file path or module:/object: reference '
+            f'(got {source!r})'
+        )
+    return _object_to_mapping(source)