trailsign 0.1.0__py3-none-any.whl

trailsign/__init__.py

@@ -0,0 +1,24 @@
+"""Trailsign: resolves a declarative, self-describing config into plain
+values. See docs/design.md at the repo root for the full design."""
+
+from .settings import (
+    RESOLVE_KEY,
+    EnvironmentVariableResolver,
+    OracleKeyVaultResolver,
+    PlaintextResolver,
+    Settings,
+    SettingsError,
+    SettingsResolver,
+    default_resolvers,
+)
+
+__all__ = [
+    "RESOLVE_KEY",
+    "EnvironmentVariableResolver",
+    "OracleKeyVaultResolver",
+    "PlaintextResolver",
+    "Settings",
+    "SettingsError",
+    "SettingsResolver",
+    "default_resolvers",
+]

trailsign/settings.py

@@ -0,0 +1,185 @@
+"""Trailsign: resolves a declarative, self-describing config into plain
+values.
+
+Each value in the config declares its own source instead of the caller
+assuming where to look -- a plain scalar, an environment variable, and a
+vault secret are all just different `trailsign-resolve:` nodes resolved
+the same way. `trailsign-resolve:` is a reserved, namespaced key --
+never a bare word like `resolve` -- so it can never collide with a
+consuming project's own field names. See docs/design.md for the full
+design (data flow, diagrams, and why `trailsign-resolve:` has to be a
+dedicated key rather than reusing a subsystem's own `type:`-style
+discriminator).
+
+A reference implementation in Python, packaged and tested. Extracted
+2026-09-01 from a Telegram news-trend bot's settings work -- the design
+turned out to be genuinely content-independent, so it lives here as its
+own project now.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+from pathlib import Path
+from typing import Any, Protocol
+
+import yaml
+
+RESOLVE_KEY = "trailsign-resolve"
+
+
+class SettingsError(Exception):
+    """A setting couldn't be resolved -- missing path, a
+    `trailsign-resolve:` value naming an unregistered resolver, a
+    resolver's own required field absent, or (from validate()) one or
+    more required paths unresolvable. The message names exactly which."""
+
+
+class SettingsResolver(Protocol):
+    """Resolves one typed-value node ({"trailsign-resolve": <this
+    resolver's own name>, ...}) to a plain value. One implementation per
+    resolver name; a new source (AWS Secrets Manager, Azure Key Vault,
+    ...) is a new class registered by name, never a change to Settings
+    itself."""
+
+    def resolve(self, node: dict[str, Any], settings: "Settings") -> Any: ...
+
+
+class PlaintextResolver:
+    def resolve(self, node: dict[str, Any], settings: "Settings") -> Any:
+        try:
+            return node["value"]
+        except KeyError:
+            raise SettingsError("plaintext value missing its 'value' field") from None
+
+
+class EnvironmentVariableResolver:
+    def resolve(self, node: dict[str, Any], settings: "Settings") -> Any:
+        name = node.get("name")
+        if not name:
+            raise SettingsError("environment-variable value missing its 'name' field")
+        try:
+            return os.environ[name]
+        except KeyError:
+            raise SettingsError(f"environment variable {name!r} is not set") from None
+
+
+class OracleKeyVaultResolver:
+    """The only resolver allowed to import a cloud SDK -- lazily, so a
+    consumer with no oracleKeyVault nodes in their config never needs
+    the `oci` package installed at all."""
+
+    def resolve(self, node: dict[str, Any], settings: "Settings") -> Any:
+        settings.get_credential_source(node["source"])  # validates 'source' exists
+        secret_ocid = node.get("secret_ocid")
+        if not secret_ocid:
+            raise SettingsError("oracleKeyVault value missing its 'secret_ocid' field")
+
+        client = _oci_secrets_client()
+        response = client.get_secret_bundle(secret_ocid)
+        content = response.data.secret_bundle_content.content  # base64-encoded
+        return base64.b64decode(content).decode("utf-8")
+
+
+def _oci_secrets_client() -> Any:
+    """Builds an authenticated OCI SecretsClient using instance-principal
+    auth -- confirmed against a real production config (a sibling
+    project's local-infra/infrastructure.yaml) as the only auth shape
+    actually in use: every deployed secret fetch there runs `oci secrets
+    secret-bundle get --auth instance_principal`, no static credential,
+    from inside an OCI compute instance. `config={}` alongside a signer
+    is the correct SDK shape for this, not a placeholder for a real
+    config -- there deliberately isn't one. Calling this off an OCI
+    instance fails with an instance-metadata-service error, which is
+    expected, not a bug in this function.
+
+    A `credential_sources` entry's own `vault_ocid`/`compartment_ocid`
+    aren't used here: get_secret_bundle(secret_ocid) needs neither under
+    instance-principal auth (verified against a real vault secret via
+    tools/verify_oracle_vault.py) -- see docs/design.md's 'Still open'
+    section for whether they end up load-bearing for some other
+    OCI operation later."""
+    import oci  # local import -- see class docstring
+
+    signer = oci.auth.signers.InstancePrincipalsSecurityTokenSigner()
+    return oci.secrets.SecretsClient(config={}, signer=signer)
+
+
+def default_resolvers() -> dict[str, SettingsResolver]:
+    return {
+        "plaintext": PlaintextResolver(),
+        "environment-variable": EnvironmentVariableResolver(),
+        "oracleKeyVault": OracleKeyVaultResolver(),
+    }
+
+
+class Settings:
+    def __init__(self, raw: dict[str, Any], resolvers: dict[str, SettingsResolver] | None = None):
+        self._raw = raw
+        self._resolvers = resolvers if resolvers is not None else default_resolvers()
+
+    @classmethod
+    def from_yaml(cls, path: str | Path, resolvers: dict[str, SettingsResolver] | None = None) -> "Settings":
+        with open(path, encoding="utf-8") as f:
+            raw = yaml.safe_load(f)
+        return cls(raw, resolvers)
+
+    def resolved(self, path: str, default: Any = None, required: bool = False) -> Any:
+        """path is dotted, e.g. "news_source.gnews" or "models.main.api-key".
+        Returns the node at that path with every {"trailsign-resolve":
+        <name>, ...} descendant replaced by its resolved value -- plain
+        dicts/lists/scalars for everything else, unchanged."""
+        node = self._raw
+        for part in path.split("."):
+            if not isinstance(node, dict) or part not in node:
+                if required:
+                    raise SettingsError(f"required setting {path!r} is not present")
+                return default
+            node = node[part]
+        return self._resolve_node(node)
+
+    def get_credential_source(self, name: str) -> dict[str, Any]:
+        """Looked up by resolvers that need a named, reusable connection
+        block (see oracleKeyVault's `source:` field) -- not meant to be
+        called by ordinary settings consumers."""
+        try:
+            return self._raw["credential_sources"][name]
+        except KeyError:
+            raise SettingsError(f"no credential_sources entry named {name!r}") from None
+
+    def validate(self, required_paths: list[str]) -> None:
+        """Resolve every path up front and fail with ONE error listing
+        everything unresolvable, instead of the process starting,
+        looking healthy, and dying on first use of a missing key. A
+        consuming project's entry point should call this with its own
+        required-key list before doing anything else."""
+        errors = []
+        for path in required_paths:
+            try:
+                self.resolved(path, required=True)
+            except SettingsError as exc:
+                errors.append(str(exc))
+        if errors:
+            raise SettingsError("missing/invalid settings:\n  " + "\n  ".join(errors))
+
+    def _resolve_node(self, node: Any) -> Any:
+        """A dict is a resolvable value iff it carries the reserved
+        RESOLVE_KEY -- purely structural, independent of what resolvers
+        happen to be registered or what any subsystem's own
+        `type:`-style discriminator fields happen to say. A
+        `trailsign-resolve` value naming an unregistered resolver is an
+        error, not a silent pass-through -- once a node declares intent
+        to be resolved, an unrecognized target should never resolve to
+        itself unresolved."""
+        if isinstance(node, dict):
+            if RESOLVE_KEY in node:
+                name = node[RESOLVE_KEY]
+                resolver = self._resolvers.get(name)
+                if resolver is None:
+                    raise SettingsError(f"no resolver registered for '{RESOLVE_KEY}: {name}'")
+                return resolver.resolve(node, self)
+            return {k: self._resolve_node(v) for k, v in node.items()}
+        if isinstance(node, list):
+            return [self._resolve_node(v) for v in node]
+        return node

trailsign-0.1.0.dist-info/METADATA

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: trailsign
+Version: 0.1.0
+Summary: Resolves a declarative, self-describing config into plain values
+Project-URL: Homepage, https://github.com/nankma/trailsign
+Project-URL: Repository, https://github.com/nankma/trailsign
+Author-email: Nankang Ma <jjkkma@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Nankang Ma
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Trailsign
+
+A small, language-independent library for resolving application
+settings from a declarative, self-describing config — where each value
+states its own source (a literal, an environment variable, a vault
+secret, ...) instead of the calling code assuming where to look.
+
+```yaml
+api-key:
+  trailsign-resolve: environment-variable
+  name: GNEWS_API_KEY
+```
+
+`trailsign-resolve:` is a reserved, namespaced key — deliberately not a
+bare word like `resolve` — so it can never collide with a consuming
+project's own field names. It dispatches to a pluggable resolver;
+whatever it resolves to is handed to the consumer as a plain value, with
+no trace of where it came from left in the shape.
+
+## Status
+
+**Python package built out, as of 2026-09-01.** `src/trailsign/` is a
+real installable package (`pyproject.toml`, src layout) with a test
+suite covering the resolve walk, the three built-in resolvers
+(`OracleKeyVaultResolver` verified against a real OCI Vault secret —
+see `tools/verify_oracle_vault.py`), `validate()`'s combined-error
+behavior, and the `trailsign-resolve` vs. `type` non-collision
+regression. MIT licensed (see `LICENSE`). Public on GitHub; CI runs the
+test suite on every push/PR. Not yet published to PyPI. A port to at
+least one other language is still open, since the design's whole point
+is being language-independent, not just Python.
+
+### Installing it
+
+Not on PyPI yet — until then, install straight from GitHub, ideally
+pinned to a tag once one exists:
+
+```
+pip install git+https://github.com/nankma/trailsign.git@main
+```
+
+Install for development on this repo: `pip install -e ".[test]"`, then
+`pytest`.
+
+## Start here
+
+- [`docs/design.md`](docs/design.md) — the core design: the config
+  shape, the resolve/dispatch contract (holds equally for a Go
+  `interface`, a Rust `trait`, or a Python `typing.Protocol`), why it's
+  shaped this way, two worked examples with diagrams, and what's still
+  undecided.
+- [`src/trailsign/settings.py`](src/trailsign/settings.py) — the Python
+  reference implementation, matching `docs/design.md` exactly.
+- [`tests/`](tests/) — the test suite; `tests/conftest.py` has a shared
+  fixture config mirroring `docs/design.md`'s worked examples.
+- the `writing-system-design-docs` skill (global, not repo-local) — the
+  doc-writing convention `docs/design.md` follows, carried over
+  from where this project started in case future design docs here want
+  the same discipline (language-independent contracts, diagrams, a
+  "still open" section that's actually kept honest).
+
+## Origin
+
+This design started inside a Telegram news-trend bot (Auguring, formerly
+Argus) while building a settings abstraction so that bot could run
+standalone as well as on its current cloud deployment. The design turned
+out to be genuinely content-independent — nothing in it assumes anything
+bot-specific — so it's being extracted into its own project rather than
+staying bot-only. `docs/design.md`'s own "Origin" section has the
+originating project's actual settings inventory, kept for context on why
+the design has the shape it has.
+
+## The split that makes this portable
+
+Two jobs, two owners, and only one of them is this library's job:
+
+1. **Resolving a marked value to a plain value** — Trailsign's job, and
+   only Trailsign's job. Nothing here knows or cares what the resolved
+   value is *for*.
+2. **Turning a resolved config block into a live object** — never
+   Trailsign's job. Each consumer owns its own small factory (a plain
+   name→constructor map) that builds whatever it needs from the
+   already-resolved values this library hands it.
+
+Full reasoning for the split, plus two complete worked examples (a news
+source's API key from an environment variable, a telemetry backend's
+credential from a vault) with diagrams, is in `docs/design.md`.
+
+## What's not decided yet
+
+See `docs/design.md`'s own "Still open" section for full detail:
+
+- A non-instance-principal auth shape for `oracleKeyVault` (today it only
+  works from inside an OCI compute instance)
+- Validation-timing default (eager vs. lazy)
+- A port to a second language

trailsign-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+trailsign/__init__.py,sha256=uTw7Pambk8vzYiJ3w_o-0JzsGxkeNNRlhcBwqZg9Ge8,556
+trailsign/settings.py,sha256=oMXwKI09Q7yrZlOl3ZrtQV6JirDJ9lFfZJGLihfVALg,8139
+trailsign-0.1.0.dist-info/METADATA,sha256=9RGpm3QX0fx-IgVZ5T4wRMHKAFiSwtnZWqlqvGnM3Dk,5974
+trailsign-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+trailsign-0.1.0.dist-info/licenses/LICENSE,sha256=TFPB7yR0f7-B4aM_Vi0q5A9CwmdMpymCjBdGxjDsVK8,1067
+trailsign-0.1.0.dist-info/RECORD,,

trailsign-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

trailsign-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nankang Ma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.