loom-kernel 0.9.1__tar.gz → 0.9.2__tar.gz

{loom_kernel-0.9.1 → loom_kernel-0.9.2}/CHANGELOG.md

@@ -1,3 +1,20 @@
+# 🚀 Release 0.9.2 ([#39](https://github.com/the-reacher-data/loom-py/pull/39)) ([`f1a482d`](https://github.com/the-reacher-data/loom-py/commit/f1a482d03f8b83f8e0c7725e7af6160466ac6126))
+
+
+## ✨ Features
+### config
+- **config:** add SecretsManagerResolver + shared resolver utilities
+
+
+
+
+
+
+
+
+
+
+
 # 🚀 Release 0.9.1 ([#36](https://github.com/the-reacher-data/loom-py/pull/36)) ([`5c420c9`](https://github.com/the-reacher-data/loom-py/commit/5c420c9dd4efe0f697affb8a921054bc6504358f))
 
 

loom_kernel-0.9.2/CHANGELOG_RELEASE.md

@@ -0,0 +1,15 @@
+# 🚀 Release 0.9.2 ([#39](https://github.com/the-reacher-data/loom-py/pull/39)) ([`f1a482d`](https://github.com/the-reacher-data/loom-py/commit/f1a482d03f8b83f8e0c7725e7af6160466ac6126))
+
+
+## ✨ Features
+### config
+- **config:** add SecretsManagerResolver + shared resolver utilities
+
+
+
+
+
+
+
+
+

{loom_kernel-0.9.1 → loom_kernel-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loom-kernel
-Version: 0.9.1
+Version: 0.9.2
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Typing :: Typed

{loom_kernel-0.9.1 → loom_kernel-0.9.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "loom-kernel"
-version = "0.9.1"
+version = "0.9.2"
 description = "Loom Python project"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -247,7 +247,7 @@ markers = [
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.9.1"
+version = "0.9.2"
 tag_format = "v$version"
 version_files = [
     "pyproject.toml:project.version",

{loom_kernel-0.9.1 → loom_kernel-0.9.2}/src/loom/core/config/__init__.py

@@ -20,6 +20,7 @@ from loom.core.config.keys import ConfigKey
 from loom.core.config.loader import load_config, section
 from loom.core.config.observability import OtelConfig
 from loom.core.config.resolver import ConfigResolver
+from loom.core.config.secrets import SecretsManagerResolver
 from loom.core.config.ssm import SsmResolver
 
 __all__ = [
@@ -30,6 +31,7 @@ __all__ = [
     "ConfigResolver",
     "Configurable",
     "OtelConfig",
+    "SecretsManagerResolver",
     "SsmResolver",
     "StructBinder",
     "load_config",

loom_kernel-0.9.2/src/loom/core/config/_resolver_utils.py

@@ -0,0 +1,116 @@
+"""Shared utilities for config resolvers (SSM, Secrets Manager, etc.)."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+
+from loom.core.config.errors import ConfigError
+
+_ENV_VAR_PATTERN = re.compile(r"%([A-Z][A-Z0-9_]*)%")
+
+
+def _expand_env_vars(key: str) -> str:
+    """Expand ``%VAR_NAME%`` placeholders in *key* using environment variables.
+
+    Only uppercase identifiers matching ``[A-Z][A-Z0-9_]*`` are expanded.
+    The ``%VAR%`` syntax avoids conflicts with OmegaConf's ANTLR grammar,
+    which rejects bare ``{`` inside ``${resolver:...}`` interpolations.
+
+    Args:
+        key: Resolver path, possibly containing ``%VAR_NAME%`` tokens.
+
+    Returns:
+        Path with all tokens replaced by their environment variable values.
+
+    Raises:
+        ConfigError: When a referenced variable is absent from the environment.
+    """
+    if not _ENV_VAR_PATTERN.search(key):
+        return key
+
+    def _replace(match: re.Match[str]) -> str:
+        var_name = match.group(1)
+        value = os.environ.get(var_name)
+        if value is None:
+            raise ConfigError(
+                f"Env var {var_name!r} not found in environment "
+                f"(referenced in resolver path {key!r})"
+            )
+        return value
+
+    return _ENV_VAR_PATTERN.sub(_replace, key)
+
+
+def _split_resolver_key(key: str) -> tuple[str, list[str]]:
+    """Split a resolver key into the base path and JSON navigation keys.
+
+    The first dot after the last '/' separator marks the start of a JSON key
+    path. Both SSM and Secrets Manager use '/' as path separator, so a dot
+    is unambiguously a JSON navigation token.
+
+    Note: ARN-style SecretIds (``arn:aws:secretsmanager:...``) are not
+    supported for dot-notation — use short names instead.
+
+    **Limitation — env-var values with dots in the final path segment:**
+    If a ``%VAR%`` token expands to a value that contains a dot *and* that
+    token appears in the last path segment (after the final ``/``), the dot
+    will be interpreted as a JSON navigation separator, producing a confusing
+    ``ConfigError``. Example: ``/app/svc/%ENV%`` where ``ENV=db.prod`` becomes
+    ``/app/svc/db`` with JSON key ``["prod"]``.  Use env-var tokens only in
+    path segments that are guaranteed to be dot-free (environment names,
+    region codes, etc.).
+
+    Args:
+        key: Expanded resolver key, e.g. ``"/app/prod/db_config.host"``.
+
+    Returns:
+        A 2-tuple ``(base_path, json_keys)`` where *base_path* is the path
+        to fetch and *json_keys* is a list of dict keys to navigate
+        (empty list when no dot-notation is present).
+    """
+    if not key:
+        return key, []
+    last_slash = key.rfind("/")
+    after_last_slash = key[last_slash + 1 :] if last_slash != -1 else key
+    dot_pos = after_last_slash.find(".")
+    if dot_pos == -1:
+        return key, []
+    base_end = (last_slash + 1 + dot_pos) if last_slash != -1 else dot_pos
+    json_tail = key[base_end + 1 :]
+    return key[:base_end], [k for k in json_tail.split(".") if k]
+
+
+def _navigate_json(raw: str, keys: list[str], path: str) -> object:
+    """Parse *raw* as JSON and navigate to the value at *keys*.
+
+    Args:
+        raw: Raw string value from the resolver backend.
+        keys: Ordered list of dict keys to traverse.
+        path: Original path, used only in error messages.
+
+    Returns:
+        The value at the navigated position. May be any JSON-compatible type.
+
+    Raises:
+        ConfigError: When *raw* is not valid JSON, or a key is absent.
+    """
+    try:
+        data: object = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        # Suppress chain (from None) — JSONDecodeError.doc holds the raw secret
+        # and would be exposed via __cause__ in tracebacks / APM serialisation.
+        raise ConfigError(
+            f"Resolver path {path!r} value is not valid JSON "
+            f"(required for key navigation): {exc.msg} at position {exc.pos}"
+        ) from None
+    current: object = data
+    for k in keys:
+        if not isinstance(current, dict) or k not in current:
+            raise ConfigError(f"Key {k!r} not found at resolver path {path!r}")
+        current = current[k]
+    return current
+
+
+__all__ = ["_expand_env_vars", "_split_resolver_key", "_navigate_json"]

{loom_kernel-0.9.1 → loom_kernel-0.9.2}/src/loom/core/config/loader.py

@@ -212,7 +212,7 @@ def _register_resolvers(resolvers: Sequence[Any], omega_conf: Any) -> None:
     """
     for resolver in resolvers:
         with contextlib.suppress(Exception):
-            omega_conf.register_new_resolver(resolver.name, resolver.resolve)
+            omega_conf.register_new_resolver(resolver.name, resolver.resolve, use_cache=True)
 
 
 def load_config(

loom_kernel-0.9.2/src/loom/core/config/secrets.py

@@ -0,0 +1,144 @@
+"""AWS Secrets Manager resolver for loom configuration.
+
+Resolves ``${secrets:/path/to/secret}`` placeholders in OmegaConf configs
+by fetching values from AWS Secrets Manager at parse time.
+
+Example::
+
+    from loom.core.config import load_config
+    from loom.core.config.secrets import SecretsManagerResolver
+
+    cfg = load_config("config/prod.yaml", resolvers=[SecretsManagerResolver("eu-west-1")])
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+try:
+    import boto3 as _boto3_module  # type: ignore[import-untyped]
+except ImportError:
+    _boto3_module = None
+
+from loom.core.config._resolver_utils import (
+    _expand_env_vars,
+    _navigate_json,
+    _split_resolver_key,
+)
+from loom.core.config.errors import ConfigError
+
+logger = logging.getLogger(__name__)
+
+
+def _fetch_secret(client: Any, name: str) -> str:
+    """Fetch a string secret value from AWS Secrets Manager.
+
+    Args:
+        client: Boto3 secretsmanager client.
+        name: Secret name or short ARN. ARN-style names are supported for
+            plain fetches but not for dot-notation JSON navigation.
+
+    Returns:
+        The secret value as a string.
+
+    Raises:
+        ConfigError: When the secret is binary, or on any API error.
+    """
+    try:
+        result = client.get_secret_value(SecretId=name)
+    except Exception as exc:
+        raise ConfigError(f"Failed to fetch Secrets Manager secret {name!r}: {exc}") from exc
+    if "SecretString" not in result:
+        raise ConfigError(
+            f"Secrets Manager secret {name!r} is binary — only string secrets are supported"
+        )
+    return str(result["SecretString"])
+
+
+class SecretsManagerResolver:
+    """Resolves AWS Secrets Manager paths for use with :func:`~loom.core.config.load_config`.
+
+    Fetches secret values from AWS Secrets Manager. The boto3 client is
+    created lazily on first use and reused across calls.
+
+    Env-var tokens in the form ``%VAR_NAME%`` (uppercase letters, digits,
+    and underscores only) are expanded from ``os.environ`` before the
+    request is made.
+
+    Args:
+        region: AWS region name. Passed directly to ``boto3.client``.
+            Defaults to ``None``, which lets boto3 use its own resolution
+            chain (env vars, instance metadata, etc.).
+
+    Example::
+
+        resolver = SecretsManagerResolver("eu-west-1")
+        value = resolver.resolve("/myapp/%ENV%/db_password")
+    """
+
+    def __init__(self, region: str | None = None) -> None:
+        self._region = region
+        self._client: Any = None
+
+    @property
+    def name(self) -> str:
+        """OmegaConf resolver prefix.
+
+        Returns:
+            The string ``"secrets"``.
+        """
+        return "secrets"
+
+    def _get_client(self) -> Any:
+        """Return the boto3 secretsmanager client, creating it on first call.
+
+        Returns:
+            A boto3 secretsmanager client instance.
+
+        Raises:
+            ConfigError: When boto3 is not installed.
+        """
+        if self._client is None:
+            if _boto3_module is None:
+                raise ConfigError(
+                    "boto3 is required for SecretsManagerResolver. "
+                    "Install it with: pip install loom[config-ssm]"
+                )
+            self._client = _boto3_module.client("secretsmanager", region_name=self._region)
+        return self._client
+
+    def resolve(self, key: str) -> object:
+        """Resolve an AWS Secrets Manager path to its stored value.
+
+        Expands ``%VAR_NAME%`` tokens in *key* from the environment, then
+        fetches the secret from AWS Secrets Manager.
+
+        Args:
+            key: Secret path, optionally containing ``%VAR_NAME%``
+                placeholders that are replaced with environment variable values.
+                Supports dot-notation for JSON key navigation: ``/path/secret.key``
+                fetches ``/path/secret`` and returns ``secret["key"]``.
+
+        Returns:
+            Resolved value. A plain string for secrets without dot-notation;
+            a structured value (string, int, dict, etc.) when dot-notation
+            navigates into a JSON secret.
+
+        Raises:
+            ConfigError: When *key* is empty, an env-var placeholder is
+                missing, boto3 is not installed, the secret is binary,
+                or the API call fails.
+        """
+        if not key:
+            raise ConfigError("Secrets Manager key must not be empty")
+        expanded = _expand_env_vars(key)
+        path, json_keys = _split_resolver_key(expanded)
+        logger.info("secrets_resolver: fetching %s", path)
+        raw = _fetch_secret(self._get_client(), path)
+        if not json_keys:
+            return raw
+        return _navigate_json(raw, json_keys, path)
+
+
+__all__ = ["SecretsManagerResolver"]

{loom_kernel-0.9.1 → loom_kernel-0.9.2}/src/loom/core/config/ssm.py

@@ -13,10 +13,7 @@ Example::
 
 from __future__ import annotations
 
-import json
 import logging
-import os
-import re
 from typing import Any
 
 try:
@@ -24,42 +21,11 @@ try:
 except ImportError:
     _boto3_module = None
 
+from loom.core.config._resolver_utils import _expand_env_vars, _navigate_json, _split_resolver_key
 from loom.core.config.errors import ConfigError
 
 logger = logging.getLogger(__name__)
 
-_ENV_VAR_PATTERN = re.compile(r"\{([A-Z][A-Z0-9_]*)\}")
-
-
-def _expand_env_vars(key: str) -> str:
-    """Expand ``{VAR_NAME}`` placeholders in *key* using environment variables.
-
-    Only uppercase identifiers matching ``[A-Z][A-Z0-9_]*`` are expanded.
-
-    Args:
-        key: SSM parameter path, possibly containing ``{VAR_NAME}`` tokens.
-
-    Returns:
-        Path with all tokens replaced by their environment variable values.
-
-    Raises:
-        ConfigError: When a referenced variable is absent from the environment.
-    """
-    matches = _ENV_VAR_PATTERN.findall(key)
-    if not matches:
-        return key
-
-    def _replace(match: re.Match[str]) -> str:
-        var_name = match.group(1)
-        value = os.environ.get(var_name)
-        if value is None:
-            raise ConfigError(
-                f"Env var {var_name!r} not found in environment (referenced in SSM path {key!r})"
-            )
-        return value
-
-    return _ENV_VAR_PATTERN.sub(_replace, key)
-
 
 def _fetch_parameter(client: Any, name: str, with_decryption: bool) -> str:
     """Fetch a single parameter value from AWS SSM.
@@ -82,78 +48,13 @@ def _fetch_parameter(client: Any, name: str, with_decryption: bool) -> str:
     return str(result["Parameter"]["Value"])
 
 
-def _split_ssm_key(key: str) -> tuple[str, list[str]]:
-    """Split an SSM key into the parameter path and JSON navigation keys.
-
-    The first dot after the last '/' separator marks the start of a JSON key
-    path. SSM paths use '/' as their separator, so a dot is unambiguously a
-    JSON navigation token.
-
-    Args:
-        key: Expanded SSM key, e.g. ``"/app/prod/db_config.host"``.
-
-    Returns:
-        A 2-tuple ``(ssm_path, json_keys)`` where *ssm_path* is the SSM
-        parameter path to fetch and *json_keys* is a list of dict keys to
-        navigate (empty list when no dot-notation is present).
-
-    Examples:
-        >>> _split_ssm_key("/app/prod/token")
-        ('/app/prod/token', [])
-        >>> _split_ssm_key("/app/prod/db_config.host")
-        ('/app/prod/db_config', ['host'])
-        >>> _split_ssm_key("/app/prod/db.connection.host")
-        ('/app/prod/db', ['connection', 'host'])
-    """
-    if not key:
-        return key, []
-    last_slash = key.rfind("/")
-    after_last_slash = key[last_slash + 1 :] if last_slash != -1 else key
-    dot_pos = after_last_slash.find(".")
-    if dot_pos == -1:
-        return key, []
-    base_end = (last_slash + 1 + dot_pos) if last_slash != -1 else dot_pos
-    json_tail = key[base_end + 1 :]
-    return key[:base_end], [k for k in json_tail.split(".") if k]
-
-
-def _navigate_json(raw: str, keys: list[str], ssm_path: str) -> object:
-    """Parse *raw* as JSON and navigate to the value at *keys*.
-
-    Args:
-        raw: Raw string value from SSM.
-        keys: Ordered list of dict keys to traverse.
-        ssm_path: Original SSM path, used only in error messages.
-
-    Returns:
-        The value at the navigated position. May be any JSON-compatible type.
-
-    Raises:
-        ConfigError: When *raw* is not valid JSON, or a key is absent.
-    """
-    try:
-        data: object = json.loads(
-            raw
-        )  # json.loads returns Any; annotated as object to avoid implicit Any propagation
-    except json.JSONDecodeError as exc:
-        raise ConfigError(
-            f"SSM parameter {ssm_path!r} is not valid JSON (required for key navigation): {exc}"
-        ) from exc
-    current: object = data
-    for k in keys:
-        if not isinstance(current, dict) or k not in current:
-            raise ConfigError(f"Key {k!r} not found in SSM parameter {ssm_path!r}")
-        current = current[k]
-    return current
-
-
 class SsmResolver:
     """Resolves SSM Parameter Store paths for use with :func:`~loom.core.config.load_config`.
 
     Fetches parameter values from AWS Systems Manager Parameter Store.
     The boto3 client is created lazily on first use and reused across calls.
 
-    Env-var tokens in the form ``{VAR_NAME}`` (uppercase letters, digits,
+    Env-var tokens in the form ``%VAR_NAME%`` (uppercase letters, digits,
     and underscores only) are expanded from ``os.environ`` before the
     SSM request is made.
 
@@ -167,7 +68,7 @@ class SsmResolver:
     Example::
 
         resolver = SsmResolver("eu-west-1")
-        value = resolver.resolve("/myapp/{ENV}/db_password")
+        value = resolver.resolve("/myapp/%ENV%/db_password")
     """
 
     def __init__(
@@ -210,11 +111,11 @@ class SsmResolver:
     def resolve(self, key: str) -> object:
         """Resolve an SSM parameter path to its stored value.
 
-        Expands ``{VAR_NAME}`` tokens in *key* from the environment, then
+        Expands ``%VAR_NAME%`` tokens in *key* from the environment, then
         fetches the parameter from AWS SSM Parameter Store.
 
         Args:
-            key: SSM parameter path, optionally containing ``{VAR_NAME}``
+            key: SSM parameter path, optionally containing ``%VAR_NAME%``
                 placeholders that are replaced with environment variable values.
                 Supports dot-notation for JSON key navigation: ``/path/param.key``
                 fetches ``/path/param`` and returns ``param["key"]``.
@@ -231,7 +132,7 @@ class SsmResolver:
         if not key:
             raise ConfigError("SSM key must not be empty")
         expanded = _expand_env_vars(key)
-        ssm_path, json_keys = _split_ssm_key(expanded)
+        ssm_path, json_keys = _split_resolver_key(expanded)
         logger.info("ssm_resolver: fetching %s", ssm_path)
         client = self._get_client()
         raw = _fetch_parameter(client, ssm_path, self._with_decryption)

loom_kernel-0.9.2/tests/unit/core/config/test_resolver_utils.py

@@ -0,0 +1,130 @@
+"""Unit tests for shared resolver utilities (_resolver_utils).
+
+Tests _split_resolver_key, _expand_env_vars, and _navigate_json directly
+to catch edge-case regressions that are only indirectly covered by the
+SSM and Secrets Manager resolver test suites.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from loom.core.config._resolver_utils import (
+    _expand_env_vars,
+    _navigate_json,
+    _split_resolver_key,
+)
+from loom.core.config.errors import ConfigError
+
+# ---------------------------------------------------------------------------
+# _split_resolver_key
+# ---------------------------------------------------------------------------
+
+
+class TestSplitResolverKey:
+    def test_empty_string_returns_empty_and_no_keys(self) -> None:
+        assert _split_resolver_key("") == ("", [])
+
+    def test_plain_path_no_dot_returns_path_and_empty_keys(self) -> None:
+        assert _split_resolver_key("/prod/token") == ("/prod/token", [])
+
+    def test_single_dot_notation(self) -> None:
+        path, keys = _split_resolver_key("/prod/db_config.host")
+        assert path == "/prod/db_config"
+        assert keys == ["host"]
+
+    def test_nested_dot_notation(self) -> None:
+        path, keys = _split_resolver_key("/prod/db.connection.host")
+        assert path == "/prod/db"
+        assert keys == ["connection", "host"]
+
+    def test_no_slash_with_dot(self) -> None:
+        path, keys = _split_resolver_key("param.key")
+        assert path == "param"
+        assert keys == ["key"]
+
+    def test_no_slash_no_dot(self) -> None:
+        assert _split_resolver_key("simple") == ("simple", [])
+
+    def test_dot_only_in_first_segment_not_last(self) -> None:
+        # dot is in segment "db.prod" which is NOT the last segment
+        path, keys = _split_resolver_key("/app/db.prod/token")
+        assert path == "/app/db.prod/token"
+        assert keys == []
+
+    def test_trailing_dot_ignored(self) -> None:
+        # trailing dot produces an empty segment that is filtered out
+        path, keys = _split_resolver_key("/prod/db.")
+        assert path == "/prod/db"
+        assert keys == []
+
+    def test_consecutive_dots_filtered(self) -> None:
+        path, keys = _split_resolver_key("/prod/db..host")
+        assert path == "/prod/db"
+        assert keys == ["host"]
+
+    def test_path_with_only_slash(self) -> None:
+        assert _split_resolver_key("/") == ("/", [])
+
+
+# ---------------------------------------------------------------------------
+# _expand_env_vars
+# ---------------------------------------------------------------------------
+
+
+class TestExpandEnvVars:
+    def test_no_placeholders_returns_unchanged(self) -> None:
+        assert _expand_env_vars("/prod/token") == "/prod/token"
+
+    def test_single_placeholder_expanded(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("ENV", "staging")
+        assert _expand_env_vars("/app/%ENV%/token") == "/app/staging/token"
+
+    def test_multiple_placeholders_expanded(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("REGION", "eu-west-1")
+        monkeypatch.setenv("ENV", "prod")
+        assert _expand_env_vars("/%REGION%/%ENV%/key") == "/eu-west-1/prod/key"
+
+    def test_missing_env_var_raises_config_error(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("MISSING", raising=False)
+        with pytest.raises(ConfigError, match="MISSING"):
+            _expand_env_vars("/path/%MISSING%/token")
+
+    def test_lowercase_not_expanded(self) -> None:
+        assert _expand_env_vars("/path/%env%/token") == "/path/%env%/token"
+
+
+# ---------------------------------------------------------------------------
+# _navigate_json
+# ---------------------------------------------------------------------------
+
+
+class TestNavigateJson:
+    def test_single_key(self) -> None:
+        result = _navigate_json('{"host": "db.internal"}', ["host"], "/path")
+        assert result == "db.internal"
+
+    def test_nested_keys(self) -> None:
+        result = _navigate_json('{"conn": {"host": "db"}}', ["conn", "host"], "/path")
+        assert result == "db"
+
+    def test_missing_key_raises_config_error(self) -> None:
+        with pytest.raises(ConfigError, match="absent"):
+            _navigate_json('{"host": "db"}', ["absent"], "/path")
+
+    def test_invalid_json_raises_config_error(self) -> None:
+        with pytest.raises(ConfigError, match="not valid JSON"):
+            _navigate_json("not-json", ["key"], "/path")
+
+    def test_invalid_json_error_does_not_expose_raw_value(self) -> None:
+        """Security: JSONDecodeError.__cause__ must not hold the raw secret."""
+        secret_value = "my_raw_secret_value"
+        with pytest.raises(ConfigError) as exc_info:
+            _navigate_json(secret_value, ["key"], "/path")
+        assert exc_info.value.__cause__ is None, (
+            "ConfigError must not chain JSONDecodeError — its .doc attribute holds the raw secret"
+        )
+
+    def test_non_dict_intermediate_raises_config_error(self) -> None:
+        with pytest.raises(ConfigError):
+            _navigate_json('{"host": "db"}', ["host", "nested"], "/path")