mgf-common 0.1.0__py3-none-any.whl

mgf/common/__init__.py

@@ -0,0 +1,35 @@
+"""mgf.common — shared infrastructure for MGF projects.
+
+Three core components today:
+
+  - :mod:`mgf.common.exceptions` — typed exception hierarchy
+    (``AppError`` base + 7 category bases + 6 generic concretes).
+  - :mod:`mgf.common.config`     — :class:`BaseAppSettings` +
+    layered loader (kwargs > env > .env > YAML > defaults) +
+    cross-OS path helpers.
+  - :mod:`mgf.common.observability` — structured logging
+    (JSON / text formatters, multi-sink :func:`setup_logging`),
+    crash reporter, sys / threading excepthooks, optional
+    OpenTelemetry instrumentation.
+
+Identity is process-wide: call :func:`configure` once at startup
+to set the app name + version that every observability function
+reads (log paths, env-var prefixes, OTel service name, crash
+report ``app`` field).
+
+See ``docs/standards/`` (lands in Phase 4) for the cross-project
+engineering standards this package implements, and ``COMMON.md``
+(lands in Phase 5) for the extraction plan.
+"""
+
+from __future__ import annotations
+
+from mgf.common._identity import app_name, app_version, configure
+
+__all__ = ["app_name", "app_version", "configure"]
+
+# Version string for the package itself. Bumped when a release is
+# tagged; consumers rarely need to read this — they use
+# ``mgf.common.app_version()`` for THEIR own app version, set via
+# ``configure(app_version=...)``.
+__version__ = "0.1.0"

mgf/common/_identity.py

@@ -0,0 +1,69 @@
+"""App-identity cache for the mgf.common observability stack.
+
+Set once at startup via :func:`mgf.common.configure`. Subsequent
+calls in the observability layer (``setup_logging``, ``setup_otel``,
+``report_now``, ``install_excepthook``, ...) read the identity
+from the module-level cache here.
+
+Why module-level state and not a contextvar:
+- The identity is process-scoped, not request-scoped.
+- A contextvar would suggest "different apps in the same process"
+  which is not a real use case for any consumer of this library.
+- Module-level state is faster (no descriptor lookup) and simpler
+  to reason about.
+
+The defaults below are intentionally placeholder strings — every
+production caller MUST call :func:`mgf.common.configure` before any
+observability function runs. The defaults exist only so unit tests
+that touch the observability layer don't trip on uninitialised
+state.
+"""
+
+from __future__ import annotations
+
+# Defaults are placeholders. Real consumers MUST call configure().
+_APP_NAME: str = "app"
+_APP_VERSION: str = "unknown"
+
+
+def configure(app_name: str, app_version: str = "unknown") -> None:
+    """Set the app identity for the entire mgf.common stack.
+
+    Call once at startup, before any other ``mgf.common.*`` function
+    that emits observability data (logging setup, OTel setup, crash
+    reporter, excepthook installation).
+
+    Parameters
+    ----------
+    app_name
+        Short lower-case name for the consuming application
+        (e.g., ``"vmanager"``). Used as the default service name in
+        OTel traces, the log file directory under ``<state>/``, the
+        prefix for env vars (``<APP_NAME>_CRASH_SINK``,
+        ``<APP_NAME>_LOG_HTTP_SINK``, ``<APP_NAME>_SYSLOG_ADDR``),
+        and the SYSLOG identifier for journald.
+    app_version
+        Version string included in crash reports. Default
+        ``"unknown"``. Pass ``__version__`` from your top-level
+        package.
+
+    Idempotent: calling again replaces the cached identity. In
+    practice this is only useful in tests that exercise multiple
+    consumer-app shapes; production callers configure once.
+    """
+    global _APP_NAME, _APP_VERSION
+    _APP_NAME = app_name
+    _APP_VERSION = app_version
+
+
+def app_name() -> str:
+    """Return the current app name. Call AFTER :func:`configure`."""
+    return _APP_NAME
+
+
+def app_version() -> str:
+    """Return the current app version. Call AFTER :func:`configure`."""
+    return _APP_VERSION
+
+
+__all__ = ["app_name", "app_version", "configure"]

mgf/common/config/__init__.py

@@ -0,0 +1,43 @@
+"""Reusable config infrastructure — base settings + loader + paths.
+
+Each consumer project subclasses :class:`BaseAppSettings` to declare
+its own typed fields and its own ``env_prefix``. The package
+contributes:
+
+  * :class:`BaseAppSettings` — pydantic-settings base with layered
+    sources, YAML file override, version-check validator.
+  * :func:`make_settings_config` — helper that builds a
+    :class:`SettingsConfigDict` with mgf.common's recommended
+    baseline, plus any consumer overrides (canonical pattern for
+    setting ``env_prefix`` on a subclass).
+  * :func:`load_settings` / :func:`save_settings` — typed loader
+    with optional migration callback + atomic writer.
+  * :func:`platform_dir` / :func:`default_config_path` — cross-OS
+    directory helpers honouring ``XDG_*`` env vars.
+  * :func:`expand_path` — reusable validator helper for ``~`` and
+    ``$VARS`` expansion on Path-typed fields.
+
+See ``docs/standards/CONFIGURATION.md`` for the design.
+"""
+
+from __future__ import annotations
+
+from mgf.common.config._loader import load_settings, save_settings
+from mgf.common.config._paths import (
+    PathKind,
+    default_config_path,
+    expand_path,
+    platform_dir,
+)
+from mgf.common.config._settings import BaseAppSettings, make_settings_config
+
+__all__ = [
+    "BaseAppSettings",
+    "PathKind",
+    "default_config_path",
+    "expand_path",
+    "load_settings",
+    "make_settings_config",
+    "platform_dir",
+    "save_settings",
+]

mgf/common/config/_loader.py

@@ -0,0 +1,185 @@
+"""Generic YAML loader / saver for :class:`BaseAppSettings` subclasses.
+
+Layered loading per ``docs/standards/CONFIGURATION.md`` rule CF-02
+(top wins):
+
+  1. CLI flags / construction kwargs
+  2. Environment variables                  — prefix set by the subclass
+  3. ``.env`` file in the working directory — same prefix
+  4. On-disk YAML (``config.yaml``)         — see :func:`mgf.common.config.default_config_path`
+  5. Typed defaults declared on the subclass
+
+Schema versioning + migration (rule CF-03):
+
+  - The YAML file is read in :func:`load_settings` BEFORE the model
+    is built, so a version mismatch can be detected and migrated
+    on disk first.
+  - Loading a higher version than ``cls.CURRENT_VERSION`` fails loud.
+  - Loading a lower version runs the consumer-supplied ``migrate``
+    chain and writes the migrated content back atomically.
+
+Atomic writes (rule CF-04):
+
+  - :func:`save_settings` writes to a temp file in the same directory
+    then renames, mode ``0o600``.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, TypeVar
+
+import yaml
+from pydantic import ValidationError
+
+from mgf.common.config._settings import BaseAppSettings
+from mgf.common.exceptions import AppConfigError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+T = TypeVar("T", bound=BaseAppSettings)
+
+
+def load_settings(
+    settings_cls: type[T],
+    *,
+    path: Path | None = None,
+    migrate: Callable[[dict[str, Any], int], dict[str, Any]] | None = None,
+) -> T:
+    """Load ``config.yaml`` into a ``settings_cls`` instance.
+
+    A missing file is **not** an error — it returns the default
+    ``settings_cls()`` (with env / .env overrides applied) so first-run
+    users get sensible behaviour without writing a config file. A
+    malformed file raises :class:`AppConfigError`.
+
+    Parameters
+    ----------
+    settings_cls
+        A concrete :class:`BaseAppSettings` subclass.
+    path
+        Path to the YAML file. When ``None``, the caller MUST resolve
+        the default themselves (typically via
+        :func:`mgf.common.config.default_config_path`) — passing
+        ``None`` here means "do not read any file; use defaults +
+        env only".
+    migrate
+        Optional callback for upgrading older on-disk schema
+        versions. Signature ``(raw_dict, from_version) -> new_dict``.
+        When omitted, a version lower than ``settings_cls.CURRENT_VERSION``
+        is loaded as-is (the in-memory model fills any new fields
+        with their defaults).
+    """
+    yaml_for_pydantic: Path | None = None
+    if path is not None and path.exists():
+        try:
+            raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+        except yaml.YAMLError as e:
+            raise AppConfigError(f"could not parse {path}: {e}") from e
+        if raw is None:
+            # Empty / whitespace-only file → treat as defaults; do
+            # not pass it through pydantic-settings.
+            yaml_for_pydantic = None
+        elif not isinstance(raw, dict):
+            raise AppConfigError(
+                f"{path} must contain a YAML mapping at the top level, got {type(raw).__name__}"
+            )
+        else:
+            # Reject non-string keys at the top level. YAML happily
+            # accepts ``None`` / ints / lists / etc. as map keys
+            # (e.g., ``yaml.safe_load('?')`` returns ``{None: None}``)
+            # which would later crash pydantic-settings with a bare
+            # ``TypeError: keywords must be strings``. Catching it
+            # here gives the user a typed AppConfigError pointing at
+            # the offending key.
+            bad_keys = [k for k in raw if not isinstance(k, str)]
+            if bad_keys:
+                raise AppConfigError(f"{path} has non-string top-level keys: {bad_keys!r}")
+            current_version = settings_cls.CURRENT_VERSION
+            version = raw.get("version", current_version)
+            if not isinstance(version, int):
+                raise AppConfigError(f"version must be an int, got {type(version).__name__}")
+            if version > current_version:
+                raise AppConfigError(
+                    f"config.yaml version {version} is newer than supported "
+                    f"version {current_version}; upgrade the application"
+                )
+            if version < current_version and migrate is not None:
+                # Rewrite the file with the migrated content so
+                # subsequent loads see the current schema.
+                migrated = migrate(raw, version)
+                _write_yaml_atomic(path, migrated)
+            yaml_for_pydantic = path
+
+    # Tell the model where to read YAML from for THIS call, then
+    # construct. Reset afterwards so subsequent ``settings_cls()``
+    # constructions (e.g., in tests) don't accidentally pick up a
+    # stale path.
+    prior = settings_cls._yaml_file_override
+    settings_cls._yaml_file_override = yaml_for_pydantic
+    try:
+        return settings_cls()
+    except ValidationError as e:
+        # Aggregate every field error into one AppConfigError so the
+        # user sees every problem at once.
+        errors = "; ".join(
+            f"{'.'.join(str(p) for p in err['loc'])}: {err['msg']}" for err in e.errors()
+        )
+        raise AppConfigError(f"invalid configuration: {errors}") from e
+    finally:
+        settings_cls._yaml_file_override = prior
+
+
+def save_settings(cfg: BaseAppSettings, path: Path) -> None:
+    """Write a settings instance to ``config.yaml`` atomically.
+
+    Writes to a temp file in the same directory then renames, so a
+    crash mid-write never leaves a truncated file behind. Creates
+    the parent directory if it does not exist. File mode is
+    ``0o600`` — the config has no secrets today, but keeping it
+    user-private is a sensible default.
+    """
+    payload = cfg.to_yaml_dict()
+    # Ensure version is always written, even if the caller hand-built
+    # the model from pieces and forgot to set it.
+    payload["version"] = type(cfg).CURRENT_VERSION
+    _write_yaml_atomic(path, payload)
+
+
+# ---------------------------------------------------------------------------
+# Internal: atomic YAML write
+# ---------------------------------------------------------------------------
+
+
+def _write_yaml_atomic(target: Path, payload: dict[str, Any]) -> None:
+    """Atomic temp-file + rename write of a YAML payload.
+
+    Mode 0o600. Creates the parent directory if absent. On failure
+    the temp file is cleaned up before the exception propagates.
+
+    Used by :func:`save_settings` AND by :func:`load_settings` when a
+    migration step rewrites the on-disk representation.
+    """
+    target.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(prefix=".config.yaml.", dir=str(target.parent), text=True)
+    tmp_path = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            yaml.safe_dump(
+                payload,
+                fh,
+                sort_keys=False,
+                default_flow_style=False,
+                allow_unicode=True,
+            )
+        tmp_path.chmod(0o600)
+        tmp_path.replace(target)
+    except Exception:
+        tmp_path.unlink(missing_ok=True)
+        raise
+
+
+__all__ = ["load_settings", "save_settings"]

mgf/common/config/_paths.py

@@ -0,0 +1,114 @@
+"""Cross-platform per-OS directory helpers.
+
+Centralises the XDG / macOS Application Support / Windows AppData
+mapping so :func:`default_config_path` and any future state-/data-dir
+helper share one cross-platform map. Always honours ``XDG_*`` env
+vars when set so power-users keep control across all platforms.
+
+Resolved at call time (rule CF-04 lazy resolution) so tests
+monkeypatching ``HOME`` / ``APPDATA`` per test get the right path
+for that test.
+
+Pure stdlib — no other mgf.common imports.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Literal
+
+PathKind = Literal["config", "state", "data"]
+
+
+def platform_dir(kind: PathKind) -> Path:
+    """Return the per-OS base directory for ``kind``.
+
+    The mapping (without env overrides):
+
+    +---------+-------------------------+-------------------------------------+----------------------------+
+    | kind    | Linux                   | macOS                               | Windows                    |
+    +=========+=========================+=====================================+============================+
+    | config  | ``~/.config``           | ``~/Library/Application Support``   | ``%APPDATA%``              |
+    +---------+-------------------------+-------------------------------------+----------------------------+
+    | state   | ``~/.local/state``      | ``~/Library/Application Support``   | ``%LOCALAPPDATA%``         |
+    +---------+-------------------------+-------------------------------------+----------------------------+
+    | data    | ``~/.local/share``      | ``~/Library/Application Support``   | ``%LOCALAPPDATA%``         |
+    +---------+-------------------------+-------------------------------------+----------------------------+
+
+    XDG always wins when set (rule CF-09 — power users keep control
+    across all platforms).
+    """
+    xdg_var = {
+        "config": "XDG_CONFIG_HOME",
+        "state": "XDG_STATE_HOME",
+        "data": "XDG_DATA_HOME",
+    }[kind]
+    xdg = os.environ.get(xdg_var)
+    if xdg:
+        return Path(xdg)
+
+    if os.name == "nt":  # pragma: no cover — Linux CI; covered by smoke
+        env_var = "APPDATA" if kind == "config" else "LOCALAPPDATA"
+        env_value = os.environ.get(env_var)
+        if env_value:
+            return Path(env_value)
+        # Fall back to the canonical Roaming/Local path beneath
+        # USERPROFILE; matches what %APPDATA% resolves to by default.
+        suffix = "Roaming" if kind == "config" else "Local"
+        return Path.home() / "AppData" / suffix
+
+    if sys.platform == "darwin":  # pragma: no cover — Linux CI; covered by smoke
+        return Path.home() / "Library" / "Application Support"
+
+    # Linux / other Unix
+    fallback = {
+        "config": ".config",
+        "state": ".local/state",
+        "data": ".local/share",
+    }[kind]
+    return Path.home() / fallback
+
+
+def default_config_path(app: str | None = None) -> Path:
+    """Return the default ``config.yaml`` path for ``app`` (rule CF-09).
+
+    When ``app`` is ``None``, reads from :func:`mgf.common.app_name`
+    so the consumer's configured identity is used.
+    """
+    if app is None:
+        from mgf.common._identity import app_name
+
+        app = app_name()
+    return platform_dir("config") / app / "config.yaml"
+
+
+def expand_path(v: object) -> object:
+    """Expand ``~`` and ``$VARS`` in a Path-typed field.
+
+    Accepts ``str`` / ``Path`` / anything else (returns unchanged).
+    Lazy resolution per rule CF-04: paths are NOT expanded at
+    module import time, so tests that monkeypatch ``HOME`` per
+    test get the right path for that test.
+
+    Plug into a Pydantic ``BaseSettings`` subclass via::
+
+        @field_validator(*_PATH_FIELDS, mode="before")
+        @classmethod
+        def _expand_paths(cls, v: object) -> object:
+            return expand_path(v)
+    """
+    if isinstance(v, str):
+        v = Path(v)
+    if isinstance(v, Path):
+        return Path(os.path.expandvars(str(v))).expanduser()
+    return v
+
+
+__all__ = [
+    "PathKind",
+    "default_config_path",
+    "expand_path",
+    "platform_dir",
+]

mgf/common/config/_settings.py

@@ -0,0 +1,185 @@
+"""Reusable :class:`BaseAppSettings` for consumer projects to subclass.
+
+Each consumer project subclasses :class:`BaseAppSettings` to declare
+its own typed fields and its own ``env_prefix``. The base contributes:
+
+  - the layered source order (rule CF-02): kwargs > env > .env >
+    YAML > file_secrets;
+  - the YAML-file override hook (set by :func:`mgf.common.config.load_settings`
+    before constructing the model);
+  - the ``version`` field + version-check validator (rule CF-03);
+  - a ``to_yaml_dict`` helper that round-trips through :func:`load_settings`.
+
+Subclasses MUST set their own ``env_prefix`` in ``model_config``.
+Use :func:`make_settings_config` to get the recommended baseline plus
+your own overrides — this is the canonical pattern::
+
+    from mgf.common.config import BaseAppSettings, make_settings_config
+
+    class AppConfig(BaseAppSettings):
+        model_config = make_settings_config(env_prefix="VMANAGER_")
+
+        libvirt_uri: str = "qemu:///system"
+        ...
+
+The ``**BaseAppSettings.model_config`` spread does NOT work because
+pydantic-settings pre-populates ``model_config`` with ~40 defaults
+(including ``env_prefix=""``); spreading them and then passing
+``env_prefix="VMANAGER_"`` raises ``TypeError: got multiple values
+for keyword argument 'env_prefix'``. The helper is the safe path.
+
+See ``docs/standards/CONFIGURATION.md`` for the full standard.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, ClassVar, cast
+
+from pydantic import field_validator
+from pydantic_settings import (
+    BaseSettings,
+    SettingsConfigDict,
+    YamlConfigSettingsSource,
+)
+
+if TYPE_CHECKING:
+    from pydantic_settings import PydanticBaseSettingsSource
+
+
+def make_settings_config(**overrides: Any) -> SettingsConfigDict:
+    """Build a :class:`SettingsConfigDict` with mgf.common's recommended baseline.
+
+    Use this in every :class:`BaseAppSettings` subclass that needs to
+    set its own ``env_prefix`` (or override any other setting). The
+    helper applies these defaults first, then your ``overrides`` on top::
+
+        env_file              = ".env"
+        env_file_encoding     = "utf-8"
+        extra                 = "forbid"        # rule CF-06
+        case_sensitive        = False
+        validate_default      = True
+        arbitrary_types_allowed = True
+
+    Why a helper instead of ``**BaseAppSettings.model_config``: pydantic
+    fully materialises ``model_config`` with every setting's default
+    (``env_prefix=""`` among them), so spreading it and re-supplying
+    ``env_prefix="VMANAGER_"`` raises ``TypeError: got multiple values
+    for keyword argument 'env_prefix'``. The helper sidesteps that by
+    only passing the keys we explicitly opt into.
+    """
+    defaults: dict[str, Any] = {
+        "env_file": ".env",
+        "env_file_encoding": "utf-8",
+        # Reject unknown keys (rule CF-06). Typos in the YAML file
+        # surface as a single ValidationError listing every bad key.
+        "extra": "forbid",
+        "case_sensitive": False,
+        "validate_default": True,
+        "arbitrary_types_allowed": True,
+    }
+    defaults.update(overrides)
+    # ``SettingsConfigDict`` is a TypedDict — at runtime just a dict —
+    # so cast is the cheapest way to carry our dynamic-key dict across
+    # the type boundary. Mypy can't validate the keys here because
+    # ``overrides`` is typed ``Any``; pydantic-settings validates the
+    # keys when it actually consumes ``model_config`` on the subclass.
+    return cast("SettingsConfigDict", defaults)
+
+
+class BaseAppSettings(BaseSettings):
+    """Base typed application configuration (rule CF-01).
+
+    Subclasses :class:`pydantic_settings.BaseSettings`. Subclasses
+    MUST set their own ``env_prefix`` via :func:`make_settings_config`
+    (the base leaves it empty so consumers can't accidentally inherit
+    a stale one).
+    """
+
+    model_config = make_settings_config()
+
+    # Per-call YAML override. :func:`load_settings` sets this before
+    # constructing the model and resets it after. NOT thread-safe;
+    # load_settings is not called concurrently in any code path today.
+    # ``ClassVar`` tells pydantic this is a real class attribute
+    # (not a model field or private attribute), so it lives on the
+    # class itself and :meth:`settings_customise_sources` can read it.
+    _yaml_file_override: ClassVar[Path | None] = None
+
+    # Current schema version. Subclasses MAY override.
+    CURRENT_VERSION: ClassVar[int] = 1
+
+    # ── Schema version field ───────────────────────────────────────────────
+    version: int = 1
+
+    @field_validator("version")
+    @classmethod
+    def _check_version(cls, v: int) -> int:
+        if v > cls.CURRENT_VERSION:
+            raise ValueError(
+                f"config.yaml version {v} is newer than supported "
+                f"version {cls.CURRENT_VERSION}; upgrade the application"
+            )
+        return v
+
+    # ── Source customisation — wire YAML in at the right precedence ──────
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        """Define source precedence (rule CF-02 — leftmost wins).
+
+        ``init_settings`` (kwargs) > ``env_settings`` >
+        ``dotenv_settings`` > YAML > ``file_secret_settings``
+        (Docker-style file mounts).
+
+        The YAML source is only attached when
+        :attr:`_yaml_file_override` is set (by :func:`load_settings`)
+        and the file actually exists. This keeps direct
+        ``Settings()`` construction free of file IO and lets tests
+        construct settings without touching disk.
+        """
+        sources: list[PydanticBaseSettingsSource] = [
+            init_settings,
+            env_settings,
+            dotenv_settings,
+        ]
+        path = cls._yaml_file_override
+        if path is not None and path.exists():
+            sources.append(YamlConfigSettingsSource(settings_cls, yaml_file=path))
+        sources.append(file_secret_settings)
+        return tuple(sources)
+
+    # ── Serialisation helper ───────────────────────────────────────────────
+
+    def to_yaml_dict(self) -> dict[str, Any]:
+        """Return a plain dict suitable for ``yaml.safe_dump``.
+
+        ``Path`` fields are serialised as POSIX strings; enums /
+        Literals as their underlying values. The result round-trips
+        through :func:`load_settings`.
+
+        Kept for backwards compatibility — new code MAY use
+        :meth:`model_dump` directly with ``mode="json"``.
+        """
+        out: dict[str, Any] = {}
+        # Iterate over the CLASS-level ``model_fields`` (instance-level
+        # access is deprecated in Pydantic V2.11). Use ``getattr`` so
+        # Path fields stay as Path objects until we coerce them
+        # explicitly below.
+        for name in type(self).model_fields:
+            value = getattr(self, name)
+            if isinstance(value, Path):
+                out[name] = str(value)
+            else:
+                out[name] = value
+        return out
+
+
+__all__ = ["BaseAppSettings", "make_settings_config"]