Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

feature/Secrets-before-sink · L-261003-17ff45 (#1322)

Louis Choquel0ceca4f66dc3
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.toml
index ebb116a37..d7042d04c 100644
--- a/.drift/acks/cli-docs.toml
+++ b/.drift/acks/cli-docs.toml
@@ -1,8 +1,8 @@
contract = "cli-docs"
-digest = "sha256:9ba08b783d4a8cbd140a7e64af16b43ccc7987be97ea9ee0bcfe76d30da7fae2"
+digest = "sha256:485194a5b58846f1599a2f0d12cdd4822eb920e74e971fdbedd04a49f19b871b"
reviewed_by = "Claude (Opus 5.5)"
-reviewed_at = "2026-10-02T21:24:09Z"
-rationale = "clean-pass: merging dev into the judgment cogt branch leaves one trigger change against dev's ack, check-model's --type help naming judgment, which matches ModelCategory's members as pipelex/builder/operations/models_ops.py defines them; no page under docs/tools/cli/ enumerates check-model's categories, the agent CLI CLAUDE.md describes --type without listing them, and docs/tools/cli/update.md lists 6_judgment_deck.toml among the managed deck files."
+reviewed_at = "2026-10-03T14:26:33Z"
+rationale = "real-catch: check_models now reports a secrets provider that raises on a lookup in the models row instead of failing the command, and quotes every setup failure scrubbed with the log redaction patterns; pipelex/cli/agent_cli/CLAUDE.md said only the secrets_provider and log_sink messages were scrubbed and said nothing of a lookup failure, and now names checks.models for both. docs/tools/cli/ lists doctor in tables only and describes none of its rows, so nothing there went stale."
[trigger_files]
"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
@@ -20,7 +20,7 @@ rationale = "clean-pass: merging dev into the judgment cogt branch leaves one tr
"pipelex/cli/agent_cli/commands/codegen/check_cmd.py" = "blob:9e8beb084a9f04f39e8acca9e6ae2554d40cb667"
"pipelex/cli/agent_cli/commands/codegen/types_cmd.py" = "blob:dea775a8a469816f2c84ea4f6a5c9234c4af6705"
"pipelex/cli/agent_cli/commands/concept_cmd.py" = "blob:8e5c1881805cda39a1dae06be247a4fc257ccf69"
-"pipelex/cli/agent_cli/commands/doctor_cmd.py" = "blob:33d142c3ecdeb10c4ac83bd43f4949afcdd1d455"
+"pipelex/cli/agent_cli/commands/doctor_cmd.py" = "blob:9bfdb8c24a39a859665d2a9ff6b57883da0bd666"
"pipelex/cli/agent_cli/commands/fix/__init__.py" = "blob:65662c86f17f610ad55ecfc3e27a022b9aa26e8b"
"pipelex/cli/agent_cli/commands/fix/app.py" = "blob:e6190d9bde6a05755c04bd21806f699461038ac0"
"pipelex/cli/agent_cli/commands/fix/bundle_cmd.py" = "blob:37b13a1ead7b55d601f53b23647c285fc85418cd"
@@ -82,7 +82,7 @@ rationale = "clean-pass: merging dev into the judgment cogt branch leaves one tr
"pipelex/cli/commands/codegen/inputs_cmd.py" = "blob:20738a9e42f0e5ef7ffc489093348af3cb4643a0"
"pipelex/cli/commands/codegen/types_cmd.py" = "blob:b7c9c7a3664c9fbe66f9b4c3c5ebf9ea1322445c"
"pipelex/cli/commands/crate_loading.py" = "blob:3d7d651931ecf1a15a3e2d72411b3212b55d74ef"
-"pipelex/cli/commands/doctor_cmd.py" = "blob:930e8fc7b3d87fef36ce369fd2715b1e4aea9132"
+"pipelex/cli/commands/doctor_cmd.py" = "blob:230c30f13e7bf19b70a6e2a03398725dcc2c422e"
"pipelex/cli/commands/fix/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/commands/fix/_diff_sandbox.py" = "blob:d39c0df92b95567f74881deb01f8c1b3119fc8ef"
"pipelex/cli/commands/fix/_fix_core.py" = "blob:dac7056fcaf50210c910e4cad1ba14328b7f8adc"
diff --git a/.drift/acks/config-docs.toml b/.drift/acks/config-docs.toml
index dbf1c75e1..488c876a1 100644
--- a/.drift/acks/config-docs.toml
+++ b/.drift/acks/config-docs.toml
@@ -1,8 +1,8 @@
contract = "config-docs"
-digest = "sha256:10a3b527deabf7461808de985a1961fadfafaa59ada33d90cc0ffd53cb2b4034"
-reviewed_by = "Louis Choquel"
-reviewed_at = "2026-09-30T15:10:39Z"
-rationale = "clean-pass: merging dev into feature/Render-pdf-local joins two separately acked trigger changes, the kit manifest stamping for backends/internal.toml in config_loader.py (docs updated in inference-backend-config.md) and a docstring-only edit in secrets_config.py; the merge adds no new trigger content and no config model, default or validator changed, so the configuration docs and migration ledgers need nothing further."
+digest = "sha256:5463c426f182dfc580d84505a36eed593388135d626dba5b9843de45dfa12472"
+reviewed_by = "Claude (Opus 5.5)"
+reviewed_at = "2026-10-03T14:00:06Z"
+rationale = "real-catch: the review found that logging-config.md said resolved sink values exist only in the exporter or the Cloud Logging client, and log_config.py said the resolved key path goes to the client alone, while the gcp credential errors deliberately quote the resolved path beside its placeholder; both sentences now say where each resolved value goes, and the page says the doctor quotes a provider's or a sink's failure redacted with the configured extra_patterns. No config key, default or model field moved, so the migration ledgers, configs.py and config_cogt.py are unaffected."
[trigger_files]
"pipelex/cogt/config_cogt.py" = "blob:02f71cb4a6b01aebda59c2e31f262ef9c865e17b"
@@ -10,7 +10,7 @@ rationale = "clean-pass: merging dev into feature/Render-pdf-local joins two sep
"pipelex/graph/graph_config.py" = "blob:dc0939a6d2730c0a10b88aa1a6e0b2dd583462a6"
"pipelex/language/mthds_config.py" = "blob:353009ad8c59dc5266bdd9dfa42b1ad18b67dca7"
"pipelex/methods/methods_config.py" = "blob:76ca9a0e64f8c10ef6a355aafd0d79d36b09f06a"
-"pipelex/pipelex.toml" = "blob:ca10eca8a5c04a73601ed1fc1f5fae0221ffadb0"
+"pipelex/pipelex.toml" = "blob:cb3431d9d8a3265121d730eaef34cfbe5e8c4cbf"
"pipelex/system/configuration/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
"pipelex/system/configuration/config_check.py" = "blob:2d5de29aba3d2ce205d3d82b4623f37b53108332"
"pipelex/system/configuration/config_loader.py" = "blob:b1940ff11d9be7f9b8e113ec564d041ec53bb0ce"
@@ -21,7 +21,7 @@ rationale = "clean-pass: merging dev into feature/Render-pdf-local joins two sep
"pipelex/system/configuration/pipe_func_config.py" = "blob:dc8890e914fbcdb611147e42eaa0cd87b32288a5"
"pipelex/system/telemetry/telemetry_config.py" = "blob:7070951a6d3e4c10cb7d59822ce168c6590c53be"
"pipelex/tools/aws/aws_config.py" = "blob:c1aeafeae08d3921464db33795f11a29ff3892ba"
-"pipelex/tools/log/log_config.py" = "blob:5b98b3ebe7090fa306cd5253c96812605f0d3dbc"
+"pipelex/tools/log/log_config.py" = "blob:63dd9f81fdbafc1a095aec6cde1b047d0ebdd2d4"
"pipelex/tools/network/network_config.py" = "blob:e12d1d0e4a40d04859f10a77addeaf8fe2b00414"
"pipelex/tools/secrets/secrets_config.py" = "blob:cf30aaec1c76c9cabc0531a5b9fe681e153d7024"
"pipelex/tools/storage/storage_config.py" = "blob:3ba0fee5282937e2639d2707ee8ab61aad7bf206"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c20b600fe..0f4eef591 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,20 +6,24 @@
- **A `judgment` inference family**: a new family beside `llm`, `img_gen`, `extract`, `search` and `doc_gen`, for models that answer a closed-form question over some material — yes or no, one option out of a declared set, or a position on a declared scale — and report how sure they are. The worker contract is batch-shaped (one state, a map of questions, a map of answers), every measure of uncertainty is optional so a backend that measures none can still serve the family honestly, and usage is reported as real input and output tokens priced per million. The deck gains a `[judgment]` section in a new managed file, `6_judgment_deck.toml`, which `pipelex update` installs, and a deck installed before it keeps loading with no judgment model; it ships with no `choice_default`, because the family's models come with your own key and a default the Pipelex Gateway does not serve would fail every boot, so a judgment names its own model. `pipelex-agent models` lists the new category, and a `judgment` pytest marker joins the inference markers.
- **TypeSafe, the judgment family's first backend**: a built-in `typesafe` plugin, installed with the new `pipelex[typesafe]` extra, serves the family from TypeSafe's System One API and is reachable as `@default-judgment`, pinned to the versioned model `jev-1.13.0`. Set `TYPESAFE_API_KEY` to use it: the default routing profile sends `jev-*` models to the backend whenever it is enabled, because the Pipelex Gateway does not serve them. A rating scale longer than ten levels is refused by this backend before any request is made, and a response answered by a model other than the pinned one is reported as a warning.
+- **Log sink settings can name secrets**: the values of `headers` under `[runtime.log.otlp]` and `credentials_file_path` under `[runtime.log.gcp]` accept the `${…}` placeholders the inference backends use, resolved through the configured secrets provider, so a collector's token is written `"Bearer ${OTLP_AUTH_TOKEN}"` and the key path `"${GCP_CREDENTIALS_FILE_PATH}"`. The configuration keeps the placeholders, and one that does not resolve stops the boot with `LogSinkVariableError` naming the section, the key and the variable. A header value that holds a line break once resolved, as a secret read from a file often does, stops the boot with `LogSinkHeaderValueError` rather than installing an exporter that refuses every batch. `pipelex doctor` gains a Secrets Provider row, `checks.secrets_provider` in `pipelex-agent doctor`.
### Changed
- **The method-app template and the SDK references link `Pipelex/pipelex-sdk`**: the SDKs and the method-app templates now live in the `Pipelex/pipelex-sdk` repository, so the README and the documentation's **Quick Start** link the method-app template to its `method-apps/` directory, the webapp's by-hand commands clone it and copy `method-apps/webapp-js/`, and the `@pipelex/sdk` and `pipelex-sdk` references point at its `js/docs/` and `python/docs/` directories.
+- **Boot builds the secrets provider before the log sink, and a sink factory receives it (Breaking)**: a `LogSinkFactoryFn` is now called as `factory(log_config, secrets_provider=…)`, and the plugin API version moves to 5, so a plugin declaring `targets_api = 4` is refused at discovery and is rebuilt against this release. A secrets provider that fails to build now reports on stderr, redacted, rather than through the configured sink.
### Fixed
- **Markdown with unclosed emphasis is converted in memory proportional to its length**: the Markdown parser behind the `markdown` filter, the `Markdown` concept's HTML and the built-in PDF engine held memory growing with the square of the text when emphasis or strikethrough markers were left unmatched, about 1.5 GB for 64,000 characters of `**a `; it now joins the text they leave behind in one pass, and renders the same HTML.
- **Routing profiles no longer rewrite their own routes**: matching a model merged the enabled `optional_routes` into the profile's declared `routes` in place, so after the first match a route declared optional had become an unconditional one in the loaded profile. Only the enablement checks each match repeats kept that from changing a routing decision.
- **The logging documentation no longer promises that a server refuses the `console` sink**: the log-sink, logging, logging-configuration and Rich-imports pages said a server installed without the `cli` extra stops at boot when it selects the `console` sink or the `rich` pretty-print mode. The core dependencies `typer` and `instructor` install Rich anyway, so such a server boots on the Rich surface; the pages now say a server selects `json` and a Rich-free mode in its own configuration, since nothing at boot makes that choice for it.
+- **`pipelex doctor` checks the backends against the configured secrets provider**: the backend-file probe and the Models row resolved credentials from environment variables whatever `[runtime.secrets] method` selected, so a deployment on another secrets method was diagnosed against secrets it does not use. Both now use the provider the configuration selects, and say they could not run when it does not build; a provider that raises on a lookup, an unreachable vault or a missing SDK, is reported in the Models row rather than stopping the doctor.
### Security
- **Every template render spends from a budget (Breaking)**: a render is charged for what it reads, allocates and prints, and an operation that would overdraw its budget, such as `'x' * 10 ** 9`, a huge format width, `lipsum(n=10 ** 9)`, nested empty loops or a runaway recursive macro, is refused before it allocates and raises `Jinja2TemplateBudgetError`. Converting Markdown to HTML, with the `markdown` filter or by printing a Markdown value in an HTML template, is charged for every character and table cell of its source, so one render converts at most about 65,000 characters of Markdown. Template arithmetic stops at 64-bit integers, and a template can no longer call `str.encode` or `int.to_bytes`. A filter or test registered on a template environment needs a cost in the render budget's tables, or the first compile raises a `TypeError` naming it, and Pipelex now requires `jinja2` below 3.2.
+- **`pipelex doctor` redacts the failures its rows quote**: the log-sink row printed a sink's failure as raised, so a credential an exporter or a client quoted in its error reached the terminal and the JSON of `pipelex-agent doctor`. That row, the new Secrets Provider row and the Models row, which quotes a secrets provider's own text when a backend's credential does not resolve, now scrub the text with the patterns the log redaction uses, the configured `extra_patterns` included.
## [v0.71.1] - 2026-10-01
diff --git a/docs/configuration/config-practical/logging-config.md b/docs/configuration/config-practical/logging-config.md
index b587146a4..01ab64b55 100644
--- a/docs/configuration/config-practical/logging-config.md
+++ b/docs/configuration/config-practical/logging-config.md
@@ -211,11 +211,11 @@ Configuration section: `[runtime.log.otlp]`, read only when `sink = "otlp"`.
```toml
[runtime.log.otlp]
endpoint = "http://collector:4318/v1/logs"
-headers = { Authorization = "Bearer ..." }
+headers = { Authorization = "Bearer ${OTLP_AUTH_TOKEN}" }
```
- `endpoint`: The collector's logs URL. Left unset, the exporter follows the OpenTelemetry environment conventions: `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`, then `OTEL_EXPORTER_OTLP_ENDPOINT` with the `/v1/logs` path, then the collector default on localhost
-- `headers`: Headers sent with every export, an authorization header typically. Empty, the default, leaves `OTEL_EXPORTER_OTLP_HEADERS` in charge
+- `headers`: Headers sent with every export, an authorization header typically. Empty, the default, leaves `OTEL_EXPORTER_OTLP_HEADERS` in charge. A value may name a secret rather than carry it, as the example's bearer token does, and the keys are taken as written: see [Secrets in Sink Settings](#secrets-in-sink-settings). This is the spelling `telemetry.toml` uses for the trace exporter's headers, so the two OTLP exporters of one process name the same credential the same way
- The records are exported in batches on the OTLP HTTP protocol, with the same service identity as the spans the runtime already exports, so a collector files the two together
- Each record carries the trace context of OpenTelemetry's current span, your own code's, so a collector files the record under your span; a record logged where no current span names a trace carries none. The Pipelex span active at the log call, the pipe's own or the LLM call's during a run, rides as the `pipelex.trace_id` and `pipelex.span_id` attributes, in hex. Pipelex never makes its own spans current in the process's OpenTelemetry context, so your own instrumentation is never re-parented under them
- The keys the sink writes itself — the source location `code.file.path`, `code.function.name` and `code.line.number`, `pipelex.trace_id` and `pipelex.span_id`, and the `exception.*` keys — are reserved on every record whether or not it carries an exception or a Pipelex span, exactly as the `json` sink reserves its own keys: a field named like one of them is carried under the same `field_` prefix, so nothing is overwritten and a field keeps one wire name whichever sink is selected
@@ -235,12 +235,12 @@ Configuration section: `[runtime.log.gcp]`, read only when `sink = "gcp"`. The s
[runtime.log.gcp]
log_name = "pipelex"
project_id = "my-project"
-credentials_file_path = "gcp_credentials.json"
+credentials_file_path = "${GCP_CREDENTIALS_FILE_PATH}"
```
- `log_name`: the Cloud Logging log the entries land under. Default: `"pipelex"`
- `project_id`: the project to write to. Left unset, the client library resolves it from the credentials or from the metadata server of the machine the process runs on
-- `credentials_file_path`: a service-account JSON file to build the client from. Left unset, authentication is Application Default Credentials, which is what a process already running on Google Cloud has. This is a plain config value rather than a secret id read through the secrets provider, because the log sink is the first capability boot resolves — deliberately ahead of the secrets provider, so that every later line of the boot goes through the sink the configuration chose — and there is no provider to ask when this section is read
+- `credentials_file_path`: a service-account JSON file to build the client from. Left unset, authentication is Application Default Credentials, which is what a process already running on Google Cloud has. The path may be written as it is, `"gcp_credentials.json"`, or name a secret, as the example does with `GCP_CREDENTIALS_FILE_PATH`, the secret the `gcp` storage provider reads, so that one secret serves both: see [Secrets in Sink Settings](#secrets-in-sink-settings). When the path came from a placeholder, the credential errors below name the placeholder beside the resolved path, so you know to fix the secret rather than the TOML
### Credentials are checked at boot
@@ -262,6 +262,17 @@ Each record becomes one Cloud Logging entry with a JSON payload:
- What the export path logs never leaves through the sink: the library reports a refused batch through a logger of its own, and a report exported through the pipeline it reports on would fail with it and be reported again. The handler rejects those records, and every record emitted on the library's export thread, before its lock is taken — the same guard the `otlp` sink carries, against the same deadlock at exit. What the sink's own credentials check logs while a teardown's flush waits on it is rejected the same way and printed on stderr, so the check still answers when the process's exit holds the handler's lock
- A refused write is still said: the library marks a refused batch done, so the flush succeeds and nothing else would report it, and the entries in it are lost. The export path's warnings and errors are printed on stderr instead, the first one in each window of time with its traceback and the ones after it counted in a single line once that window has passed — with the next failure, on the next line the process logs, or at the teardown at the latest — so a process whose writes Cloud Logging refuses says so without printing once per line it logs
+## Secrets in Sink Settings
+
+The values of the `otlp` sink's `headers` and the `gcp` sink's `credentials_file_path` accept the `${…}` placeholders the [inference backends](../config-technical/inference-backend-config.md) use, resolved through the secrets provider `[runtime.secrets]` selects. Boot builds that provider before it installs the sink for this reason, and hands it to the sink's factory.
+
+- `${NAME}` and `${secret:NAME}` read `NAME` from the secrets provider, which with the default `env` method is the environment variable of that name
+- `${env:NAME}` reads the environment variable whatever the secrets method
+- `${env:NAME|secret:OTHER}` tries each in turn
+- A placeholder can sit inside a longer value, `"Bearer ${OTLP_AUTH_TOKEN}"`, and the rest of the value is kept as written
+
+The configuration keeps the placeholders, so nothing that prints the configuration can print a credential. A header's resolved value reaches the exporter alone, and the resolved key path reaches the Cloud Logging client and the `gcp` sink's credential errors, which quote it beside its placeholder. A placeholder that does not resolve stops the boot with `LogSinkVariableError`, whose message names the section, the key and the variable, never a value, rather than sending the placeholder to the collector as if it were the token and losing every record while the boot reports success; `pipelex doctor` reports the same message in its log-sink row. A header value that holds a line break once resolved stops the boot with `LogSinkHeaderValueError`, naming the key and never the value: no HTTP header can carry one, and the exporter would otherwise be installed and refuse every batch. A secret read from a file often ends with a newline, so store it without one. There is no escape syntax, so a header value that genuinely contains `${` cannot be written. A secrets provider that fails to build stops the boot before any sink exists, and the lines logged until then are written to stderr, redacted, as they are for any boot that dies before its sink. `pipelex doctor` quotes that failure in its Secrets Provider row, and a sink's failure in its log-sink row, scrubbed with the same redaction patterns, the configured `extra_patterns` included.
+
## Example Configuration
```toml
@@ -325,7 +336,8 @@ Two of those keys chose a behaviour their deletion undoes, and no operation in t
2. **Production Environment**:
- - Select the `json` sink behind a log agent, the `otlp` sink in front of a collector, or the `gcp` sink for a process that must write to Google Cloud Logging directly
+ - Prefer a sink that holds no credential: the `json` sink on stderr, shipped by a collector or by the platform's log agent, which authenticates on the process's behalf with the platform's own identity. Nothing in the process then holds a logging credential, and a misconfigured one cannot lose its records
+ - Select the `otlp` sink in front of a collector that needs a token, or the `gcp` sink for a process that must write to Google Cloud Logging directly, only when no agent can ship the lines; their credentials then belong in the secrets provider, named in [their settings](#secrets-in-sink-settings) rather than written there
- Disable caller info for performance
- Use INFO or higher log levels
diff --git a/docs/errors/log-sink-header-value-error.md b/docs/errors/log-sink-header-value-error.md
new file mode 100644
index 000000000..3aad17bd4
--- /dev/null
+++ b/docs/errors/log-sink-header-value-error.md
@@ -0,0 +1,21 @@
+---
+title: "Log sink header value holds a line break"
+description: "Reference for the `LogSinkHeaderValueError` Pipelex error class."
+---
+
+<!-- pipelex:generated -->
+
+# Log sink header value holds a line break
+
+Raised at boot when an ``otlp`` sink header value holds a line break once its placeholders resolve.
+
+| Field | Value |
+|---|---|
+| `error_type` | `LogSinkHeaderValueError` |
+| `title` | Log sink header value holds a line break |
+| `type_uri` | `https://docs.pipelex.com/latest/errors/log-sink-header-value-error/` |
+| `error_domain` | `config` |
+| Defined in | `pipelex.tools.log.exceptions` |
+| Parent class | [`CredentialsError`](credentials-error.md) |
+
+[Back to Error Reference](index.md)
diff --git a/docs/errors/log-sink-variable-error.md b/docs/errors/log-sink-variable-error.md
new file mode 100644
index 000000000..e7f99620d
--- /dev/null
+++ b/docs/errors/log-sink-variable-error.md
@@ -0,0 +1,21 @@
+---
+title: "Log sink variable did not resolve"
+description: "Reference for the `LogSinkVariableError` Pipelex error class."
+---
+
+<!-- pipelex:generated -->
+
+# Log sink variable did not resolve
+
+Raised at boot when a ``${…}`` placeholder in a log sink's settings does not resolve.
+
+| Field | Value |
+|---|---|
+| `error_type` | `LogSinkVariableError` |
+| `title` | Log sink variable did not resolve |
+| `type_uri` | `https://docs.pipelex.com/latest/errors/log-sink-variable-error/` |
+| `error_domain` | `config` |
+| Defined in | `pipelex.tools.log.exceptions` |
+| Parent class | [`CredentialsError`](credentials-error.md) |
+
+[Back to Error Reference](index.md)
diff --git a/docs/errors/platform-and-tooling.md b/docs/errors/platform-and-tooling.md
index c4f34a74a..c0eae5e09 100644
--- a/docs/errors/platform-and-tooling.md
+++ b/docs/errors/platform-and-tooling.md
@@ -38,6 +38,8 @@ own page. Classes are grouped by subsystem.
- [`Jinja2TemplateSecurityError`](jinja2-template-security-error.md) — Jinja 2 template security
- [`Jinja2TemplateSyntaxError`](jinja2-template-syntax-error.md) — Jinja 2 template syntax
- [`JsonTypeError`](json-type-error.md) — Json type
+- [`LogSinkHeaderValueError`](log-sink-header-value-error.md) — Log sink header value holds a line break
+- [`LogSinkVariableError`](log-sink-variable-error.md) — Log sink variable did not resolve
- [`ModuleFileError`](module-file-error.md) — Module file
- [`PyPdfium2RendererError`](py-pdfium2-renderer-error.md) — Py pdfium 2 renderer
- [`RemoteFileFetchError`](remote-file-fetch-error.md) — Remote file could not be fetched
diff --git a/docs/under-the-hood/log-sink-plugins.md b/docs/under-the-hood/log-sink-plugins.md
index 06d333c61..d65f4d6dd 100644
--- a/docs/under-the-hood/log-sink-plugins.md
+++ b/docs/under-the-hood/log-sink-plugins.md
@@ -9,7 +9,7 @@ Every record the runtime emits, a `log.info(...)` in a pipe operator, a warning
Core names no sink by import or by string. The built-in sinks (`json`, `console`, `otlp`, `gcp`) are a plugin too, the always-on `LogSinkPlugin`, riding the exact same seam an out-of-tree package would. This page documents that seam, the contract a plugin registers, what a sink reads off a record, and how to write one.
-This is the third application of the mechanism the [storage provider](storage-provider-plugins.md) seam introduced and the [secrets provider](secrets-provider-plugins.md) seam reused; the three pages describe the same shape with the nouns swapped, and this one adds what is particular to logging: the sink is resolved after logging is already configured, and every sink shares one record contract.
+This is the third application of the mechanism the [storage provider](storage-provider-plugins.md) seam introduced and the [secrets provider](secrets-provider-plugins.md) seam reused; the three pages describe the same shape with the nouns swapped, and this one adds what is particular to logging: the sink is resolved after logging is already configured, it is handed the secrets provider built just before it, and every sink shares one record contract.
---
@@ -34,8 +34,9 @@ RuntimeBoot.setup
└─ for each installed entry point in the requested groups
└─ plugin.register(registrar) # side-effect-free
└─ registrar.add_log_sink(method=…, factory=…)
+ └─ secrets_provider = … # setup()'s argument, else the runtime.secrets.method factory
└─ LogSinkRegistry(registrar.log_sinks)
- └─ sink = registry.get_required(method=runtime.log.sink)(runtime.log)
+ └─ sink = registry.get_required(method=runtime.log.sink)(runtime.log, secrets_provider=secrets_provider)
└─ log.install_sink(sink) # the sink's handler replaces the holding handler,
# which replays what it held through it, in order
teardown
@@ -46,9 +47,11 @@ teardown
Logging is configured as soon as the configuration is read, in `RuntimeBoot.__init__`, so that everything the boot says afterwards is a record on a module-named logger at the configured level. The sink, though, is a plugin capability, and plugin discovery runs a little later, in `setup()`, once the boot knows which built-ins and which entry-point groups it reads. Rather than choose a default renderer for that window, `configure` installs a **holding handler** that keeps every record, and `install_sink` replays them through the selected sink's handler the moment it is installed, in the order they were emitted. A boot's own lines are therefore rendered by the sink the configuration chose, never dropped and never written in a shape nothing chose.
-The sink is the first capability resolved out of the registrar, ahead of secrets and storage, precisely so that every later line of the boot goes through it. A boot that dies before that point, on the gateway terms gate for instance, releases its process globals through `log.reset()`, which closes the holding handler: what it still holds gets the stdlib's last-resort treatment: every held record reaches stderr, since each passed the level the configuration set, and the redaction processor runs over each one first, behind the guard a sink's handler would have put it behind.
+The sink is the second capability resolved out of the registrar, right after the secrets provider and ahead of telemetry and storage, so that every later line of the boot goes through it while its own settings can still name a secret: an OTLP collector's bearer token, the path of the service-account key the `gcp` sink reads. Building the provider first costs nothing in kind, because the holding handler already covers the window: what the provider logs is held like every line before it, and the remote-config fetch and plugin discovery were in that window already. A boot that dies before the sink is installed, on the gateway terms gate or on a secrets provider that cannot be built for instance, releases its process globals through `log.reset()`, which closes the holding handler: what it still holds gets the stdlib's last-resort treatment: every held record reaches stderr, since each passed the level the configuration set, and the redaction processor runs over each one first, behind the guard a sink's handler would have put it behind. The only built-in secrets provider, `env`, does no I/O and logs nothing, so in practice only an external secrets plugin can fail there.
-`pipelex doctor`, which deliberately bypasses `Pipelex.make` to diagnose a broken configuration, selects its sink the same way: the pure `build_registrar` discovery, then the `runtime.log.sink` lookup. Where boot stops on a token nobody registered, the doctor installs the console sink instead and reports the token in a row of its own, naming the registered sinks, so the report it exists to produce is still produced.
+This is the usual order elsewhere. Spring Boot resolves its configuration, vault-backed properties included, before it initialises logging and replays what was logged meanwhile; ASP.NET Core reads Key Vault as a configuration source before logging is configured, with a bootstrap logger covering the gap.
+
+`pipelex doctor`, which deliberately bypasses `Pipelex.make` to diagnose a broken configuration, selects its sink the same way: the pure `build_registrar` discovery, the secrets provider `runtime.secrets.method` selects, then the `runtime.log.sink` lookup. Where boot stops on a token nobody registered, on a sink that fails to build or on a secrets provider that fails to build, the doctor installs the console sink instead and reports what stopped it in a row of its own, so the report it exists to produce is still produced. When the secrets provider does not build, the doctor does not try the sink against a stand-in: its row says it was not checked.
---
@@ -56,13 +59,18 @@ The sink is the first capability resolved out of the registrar, ahead of secrets
### `LogSinkFactoryFn`
-A sink is produced by a typed **callable**, whole log config in, sink out (`pipelex/plugins/log_sink_registry.py`):
+A sink is produced by a typed **callable**, whole log config and the boot's secrets provider in, sink out (`pipelex/plugins/log_sink_registry.py`):
```python
-LogSinkFactoryFn = Callable[[LogConfig], LogSink]
+class LogSinkFactoryFn(Protocol):
+ def __call__(self, config: LogConfig, /, *, secrets_provider: SecretsProviderAbstract) -> LogSink: ...
```
-Passing the whole `LogConfig` is deliberate: a factory reads whatever it needs, the stream target, its own settings section, at the boot apply-point, never at registration. A plugin contributes one factory per method it serves by calling the registrar menu in its `register`, passing the token as a raw string:
+Passing the whole `LogConfig` is deliberate: a factory reads whatever it needs, the stream target, its own settings section, at the boot apply-point, never at registration. The secrets provider is passed rather than read off the hub, because boot sets it on the hub only after the sink is installed: the keyword is the one way a factory reaches a secret, so the order is one the type checker enforces, and a factory that calls `get_secrets_provider()` instead fails loud at boot. A sink whose settings name no secret accepts the keyword and ignores it, as the built-in `json` and `console` factories do. The built-in `otlp` and `gcp` factories resolve the `${…}` placeholders in their header values and key path through it, on a copy of their settings, so the configuration keeps the placeholders; a placeholder that does not resolve raises `LogSinkVariableError`, naming the section, the key and the variable, and an `otlp` header value holding a line break once resolved raises `LogSinkHeaderValueError`, since the exporter would accept it and then refuse every batch. `config` is positional-only in the protocol, so an implementation names its first parameter as it likes.
+
+The keyword arrived with plugin API version 5. A factory written against version 4 would be called with a keyword it does not accept, so discovery refuses a plugin still declaring `targets_api = 4` with `PluginApiVersionMismatchError`, naming it, rather than letting the boot fail on a bare `TypeError`.
+
+A plugin contributes one factory per method it serves by calling the registrar menu in its `register`, passing the token as a raw string:
```python
registrar.add_log_sink(method="gcp", factory=_make_gcp_log_sink)
@@ -156,6 +164,8 @@ An external sink has no settings section of its own in `LogConfig`, whose sub-mo
|-----------|-------|
| `runtime.log.sink` names no registered sink | `UnknownLogSinkError` (lists the registered tokens) |
| the selected sink's package is not installed | `MissingDependencyError` (package + `pipelex[<extra>]` hint), raised at install, at boot |
+| a `${…}` placeholder in the `otlp` sink's headers or the `gcp` sink's key path does not resolve | `LogSinkVariableError` (names the section, the key and the variable, never a value) |
+| an `otlp` header value holds a line break once its placeholders resolve | `LogSinkHeaderValueError` (names the section and the key, never the value) |
| two plugins register the same `method` | `DuplicateLogSinkError` (names both plugins) |
| `name` (`"log_sinks"`) in `runtime.plugins.disabled` | `CoreUnconditionalPluginDisabledError` |
| published under the retired `pipelex.plugins` group | `RetiredPluginEntryPointGroupError` |
@@ -170,8 +180,9 @@ The duplicate detection is the same fail-loud `_add` helper the storage and secr
A third-party log sink plugin is a distribution that:
1. implements a `LogSink` subclass whose `make_handler` builds the handler and performs whatever SDK import the handler needs, so the module stays import-light; the handler reads the record through `carried_attributes`, serializes on emit, and never raises;
-2. defines a plugin class (`name`, `targets_api`, `register`) whose `register` calls `add_log_sink(method="<token>", factory=...)` and nothing else;
-3. advertises itself under the `pipelex.plugins.kernel` entry-point group, a log sink being a kernel-layer capability (see [Inference Backend Plugins](inference-backend-plugins.md#shipping-it-as-an-out-of-tree-plugin) for what each group means):
+2. defines a factory matching `LogSinkFactoryFn`, which takes the log config positionally and the secrets provider as the `secrets_provider` keyword, the way to read a credential the sink needs; `substitute_vars` in `pipelex/tools/secrets/secrets_utils.py` resolves a `${…}` placeholder through it with the syntax the built-in sinks accept;
+3. defines a plugin class (`name`, `targets_api`, `register`) whose `register` calls `add_log_sink(method="<token>", factory=...)` and nothing else;
+4. advertises itself under the `pipelex.plugins.kernel` entry-point group, a log sink being a kernel-layer capability (see [Inference Backend Plugins](inference-backend-plugins.md#shipping-it-as-an-out-of-tree-plugin) for what each group means):
```toml
# pyproject.toml of your plugin package
diff --git a/docs/under-the-hood/secrets-provider-plugins.md b/docs/under-the-hood/secrets-provider-plugins.md
index 0904a9f5a..df22dd3ed 100644
--- a/docs/under-the-hood/secrets-provider-plugins.md
+++ b/docs/under-the-hood/secrets-provider-plugins.md
@@ -35,15 +35,17 @@ boot (Pipelex.setup)
└─ registrar.add_secrets_provider(method=…, factory=…)
└─ SecretsProviderRegistry(registrar.secrets_providers) # stored on the hub
└─ secrets_provider = registry.get_required(method=runtime.secrets.method)(runtime.secrets)
- └─ set_secrets_provider(secrets_provider) # the one provider every consumer reads
+ └─ log sink factory(runtime.log, secrets_provider=secrets_provider) # the first consumer, handed it
+ └─ set_secrets_provider(secrets_provider) # the one provider every later consumer reads
```
There is no `match runtime.secrets.method:` anywhere in boot — the token set is open, so validation *is* the registry lookup. Adding a backend means registering a factory for its token; nothing in core changes. Every downstream consumer (`get_secret(...)`, telemetry credentials, the storage `gcp` arm, search/extract workers) keeps calling `get_secrets_provider()` and is unaffected by which method was selected.
### Where in boot secrets is resolved
-Secrets is resolved **early** — right after plugin discovery, after the gateway/terms precondition gate but before the telemetry factory (its first in-process consumer) and well before storage selection. Two consequences that this ordering guarantees:
+Secrets is the **first capability resolved out of the registrar** — right after plugin discovery, after the gateway/terms precondition gate, before the log sink and well before storage selection. Three consequences that this ordering guarantees:
+- **The log sink**, its first consumer, receives the provider as the `secrets_provider` keyword of its factory, so a sink's settings can name secrets: the built-in `otlp` sink's header values and the `gcp` sink's key path accept `${…}` placeholders (see [Log Sink Plugins](log-sink-plugins.md#logsinkfactoryfn)). The provider goes on the hub only after the sink is installed, so the keyword is the one way a sink reaches it. Because the sink does not exist yet, what the provider logs while it is built is held and replayed into the sink, and a provider whose factory raises stops the boot with those held lines written to stderr, redacted, rather than through the configured sink.
- **Telemetry** receives the config-selected secrets provider when it is constructed.
- **Storage's `gcp` factory** reads the config-selected secrets provider from the hub at *its* apply-point (it resolves `GCP_CREDENTIALS_FILE_PATH`) — secrets is already on the hub by then. This ordering is pinned by an integration test that boots a non-`env` secrets method alongside `gcp` storage and asserts the gcp arm read the external provider.
@@ -81,7 +83,7 @@ registrar.add_secrets_provider(method="vault", factory=_make_vault_secrets_provi
The factory is a plain callable stored at registration and **invoked only at the boot apply-point**. Two invariants follow, and they are what let an SDK-backed provider ship without weighing down every boot:
- **Import-light.** The plugin module must import no backend SDK at module load. The built-in `SecretsPlugin` needs none (the `env` provider reads environment variables); an out-of-tree `pipelex-secrets-vault` plugin must keep its `hvac`/`boto3`/etc. import *inside* the provider's methods (or its factory), never at module top-level, so discovery stays import-light even when the extra is installed.
-- **Fail at use, not at boot.** An optional dependency raises `MissingDependencyError` (naming the package and the `pipelex[<extra>]` install hint) when the backend is *used*, not when it is registered or selected.
+- **Fail at use, not at boot.** An optional dependency raises `MissingDependencyError` (naming the package and the `pipelex[<extra>]` install hint) when the backend is *used*, not when it is registered or selected. `pipelex doctor` resolves the backends' credentials through the provider the configuration selects, so a lookup that raises, whatever the exception, is reported in its Models row, scrubbed with the log redaction patterns, rather than stopping the report.
---
@@ -130,7 +132,7 @@ Whether that token names an *installed* provider is validated at **registry look
| Condition | Error |
|-----------|-------|
-| `runtime.secrets.method` names no registered provider | `UnknownSecretsMethodError` (lists the registered methods) |
+| `runtime.secrets.method` names no registered provider | `UnknownSecretsMethodError` (lists the registered methods), raised before any log sink exists, so it reaches stderr |
| published under the retired `pipelex.plugins` group | `RetiredPluginEntryPointGroupError` (names the plugins and the group each should move to) |
| two plugins register the same `method` | `DuplicateSecretsProviderError` (names both plugins) |
| `name` (`"secrets"`) in `runtime.plugins.disabled` | `CoreUnconditionalPluginDisabledError` |
diff --git a/docs/under-the-hood/writing-an-inference-plugin.md b/docs/under-the-hood/writing-an-inference-plugin.md
index 50628bf9e..e1938cd65 100644
--- a/docs/under-the-hood/writing-an-inference-plugin.md
+++ b/docs/under-the-hood/writing-an-inference-plugin.md
@@ -110,7 +110,7 @@ class HelloInferencePlugin:
name = "hello_inference"
# The plugin API version this plugin was written against, as a literal: never import the
# runtime's PLUGIN_API_VERSION here, or the check that catches a breaking runtime upgrade always passes.
- targets_api = 4
+ targets_api = 5
def register(self, registrar: PluginRegistrar) -> None:
registrar.add_inference_backend(family=InferenceFamily.LLM, sdk="hello", make_worker=_make_hello_llm_worker)
diff --git a/pipelex/cli/agent_cli/CLAUDE.md b/pipelex/cli/agent_cli/CLAUDE.md
index aa7b2851e..3d3607bc2 100644
--- a/pipelex/cli/agent_cli/CLAUDE.md
+++ b/pipelex/cli/agent_cli/CLAUDE.md
@@ -97,7 +97,7 @@ commands/
| `models` | Lists available model presets, aliases, and waterfalls. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value) |
| `check-model` | Validates a model reference and suggests alternatives if invalid. `--type`/`-t` for model category, `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value) |
| `migrate` | Migrates this machine's configuration files (global `~/.pipelex/` and project `.pipelex/`, non-recursively) to the current schema by replaying each surface's ledger. Does **not** boot — it is the command for a configuration that cannot load. Writes only with `--yes`; `--dry-run` plans and is the default; the two together are refused with exit 2. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json`. The verdict is the structured `needs_attention`, not the exit code. |
-| `doctor` | Checks config, credentials, models health. `--global`/`-g` for global dir. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). The telemetry check carries a `finding` (`healthy`/`not_found`/`unparseable`/`out_of_date`/`invalid`) beside its `healthy` and `message`; branch on that, and note `out_of_date` is `pipelex migrate`'s and never `pipelex init telemetry`'s — a reset would discard the settings the migration keeps — and that it means the migration would actually rewrite that file, so a file it would only report on is `invalid`. `checks.pending_migrations` is the machine-wide half: a `finding` (`up_to_date`/`pending`/`needs_attention`/`unavailable`) plus `migratable_files` and `attention_files`. It is the only channel a machine has for a pending migration — a tolerated boot warns a person and this CLI silences logging — and it is **not** scoped by `--global`, because it answers for `pipelex migrate`, which walks both directories. `checks.plugins` is present once the runtime setup discovered the plugins the way boot does: `healthy` and `message`, not healthy when the plugin registry did not build, in which case the message names the plugin error. `checks.log_sink` is present once the runtime setup ran: `healthy` and `message`, not healthy when `[runtime.log] sink` names no registered sink, when the configured sink failed to install or when the registry did not build. The message says why, and says where the report's own lines went: onto the console sink on stderr, which the doctor installs in place of the one that failed, or onto a sink already recorded, which it leaves alone rather than installing over — a sink is recorded before the held records are replayed, so a failed installation does not always leave nothing behind. The fourth case is its own: a sink that was installed and then failed while the records held since logging was configured were replayed through it, where the report runs on that sink, which stays installed, and the message says what it raised. |
+| `doctor` | Checks config, credentials, models health. `--global`/`-g` for global dir. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). The telemetry check carries a `finding` (`healthy`/`not_found`/`unparseable`/`out_of_date`/`invalid`) beside its `healthy` and `message`; branch on that, and note `out_of_date` is `pipelex migrate`'s and never `pipelex init telemetry`'s — a reset would discard the settings the migration keeps — and that it means the migration would actually rewrite that file, so a file it would only report on is `invalid`. `checks.pending_migrations` is the machine-wide half: a `finding` (`up_to_date`/`pending`/`needs_attention`/`unavailable`) plus `migratable_files` and `attention_files`. It is the only channel a machine has for a pending migration — a tolerated boot warns a person and this CLI silences logging — and it is **not** scoped by `--global`, because it answers for `pipelex migrate`, which walks both directories. `checks.plugins` is present once the runtime setup ran, which discovers the plugins the way boot does: `healthy` and `message`, not healthy when the plugin registry did not build, in which case the message names the plugin error. `checks.secrets_provider` is present once the runtime setup ran, which builds the provider `[runtime.secrets] method` selects before the sink, as boot does: `healthy` and `message`, not healthy when the method names no registered provider, when its factory raised or when the registry did not build. It is built even when logging was configured before the doctor ran, since `checks.models` resolves the backends' credentials through it, and when it did not build the models check says it could not run; a provider that raises on a lookup is reported in `checks.models` rather than failing the command. `checks.log_sink` is present once the runtime setup ran: `healthy` and `message`, not healthy when `[runtime.log] sink` names no registered sink, when the configured sink failed to install (a `${…}` placeholder in its settings that does not resolve among the causes), when the secrets provider did not build, in which case the sink is not attempted, or when the registry did not build. The message says why, and says where the report's own lines went: onto the console sink on stderr, which the doctor installs in place of the one that failed, or onto a sink already recorded, which it leaves alone rather than installing over — a sink is recorded before the held records are replayed, so a failed installation does not always leave nothing behind. The fourth case is its own: a sink that was installed and then failed while the records held since logging was configured were replayed through it, where the report runs on that sink, which stays installed, and the message says what it raised. A failure the `secrets_provider` and `log_sink` messages quote is scrubbed with the log redaction patterns, the configured `extra_patterns` included, because the envelope reaches its reader without passing through any sink, and so is a failure of the backends' setup that the `models` message quotes, where a secrets provider's own text can appear; the backend-file findings and the gateway and plugin-registry failures it quotes are Pipelex's own text and are quoted as raised. |
## Key Patterns
diff --git a/pipelex/cli/agent_cli/commands/doctor_cmd.py b/pipelex/cli/agent_cli/commands/doctor_cmd.py
index 33d142c3e..9bfdb8c24 100644
--- a/pipelex/cli/agent_cli/commands/doctor_cmd.py
+++ b/pipelex/cli/agent_cli/commands/doctor_cmd.py
@@ -18,6 +18,7 @@ from pipelex.cli.commands.doctor_cmd import (
PendingMigrationsCheck,
PendingMigrationsFinding,
PluginsCheck,
+ SecretsProviderCheck,
TelemetryConfigCheck,
TelemetryConfigFinding,
check_backend_credentials,
@@ -134,6 +135,12 @@ def _format_doctor_markdown(result: dict[str, Any]) -> str:
lines.append(f"\n## Plugins \u2014 {_status_icon(healthy=plugins_check['healthy'])}\n")
lines.append(plugins_check["message"])
+ # Secrets Provider, present only when the runtime setup ran
+ secrets_provider_check = checks.get("secrets_provider")
+ if secrets_provider_check is not None:
+ lines.append(f"\n## Secrets Provider \u2014 {_status_icon(healthy=secrets_provider_check['healthy'])}\n")
+ lines.append(secrets_provider_check["message"])
+
# Log Sink, present only when the runtime setup ran
log_sink_check = checks.get("log_sink")
if log_sink_check is not None:
@@ -269,11 +276,13 @@ def _do_agent_doctor_cmd(*, global_: bool, output_format: CliOutputFormat, error
backend_file_reports: dict[str, BackendFileReport]
log_sink_check: LogSinkCheck | None = None
plugins_check: PluginsCheck | None = None
+ secrets_provider_check: SecretsProviderCheck | None = None
if config_healthy:
try:
runtime_setup = setup_doctor_runtime(log_config_overrides=AGENT_CLI_STDERR_LOG_FIELDS, config_dir=config_dir)
log_sink_check = runtime_setup.log_sink
plugins_check = runtime_setup.plugins
+ secrets_provider_check = runtime_setup.secrets_provider
# Pin discipline BEFORE check_models. setup_doctor_runtime uses
# log.configure_if_unset(), which no-ops when a prior process already configured
# logging (embedded reuse, interleaved tests) — in that case AGENT_CLI_STDERR_LOG_FIELDS
@@ -281,7 +290,9 @@ def _do_agent_doctor_cmd(*, global_: bool, output_format: CliOutputFormat, error
# apply_agent_cli_output_discipline mutates the existing handler unconditionally via
# log.redirect_to_stderr, closing that window before any check fires.
apply_agent_cli_output_discipline()
- models_healthy, models_message, backend_file_reports = check_models(config_dir=config_dir)
+ models_healthy, models_message, backend_file_reports = check_models(
+ secrets_provider=runtime_setup.built_secrets_provider, config_dir=config_dir
+ )
except PipelexConfigError as exc:
# A config can pass check_config_files's shape check and still fail full validation
# inside setup_doctor_runtime (e.g. a layered override file). Surface the translated
@@ -313,6 +324,7 @@ def _do_agent_doctor_cmd(*, global_: bool, output_format: CliOutputFormat, error
and models_healthy
and (log_sink_check is None or log_sink_check.is_healthy)
and (plugins_check is None or plugins_check.is_healthy)
+ and (secrets_provider_check is None or secrets_provider_check.is_healthy)
)
# Build backend credential details
@@ -376,6 +388,10 @@ def _do_agent_doctor_cmd(*, global_: bool, output_format: CliOutputFormat, error
recommended_actions.append(
"Fix, upgrade or uninstall the plugin the plugins check names, or take a core plugin out of runtime.plugins.disabled"
)
+ if secrets_provider_check is not None and not secrets_provider_check.is_healthy:
+ recommended_actions.append(
+ "Set 'method' in [runtime.secrets] to a registered secrets provider, or fix what the secrets_provider check says stopped it"
+ )
if log_sink_check is not None and not log_sink_check.is_healthy:
recommended_actions.append("Set 'sink' in [runtime.log] to a registered log sink, or fix what the log_sink check says stopped it")
@@ -416,6 +432,8 @@ def _do_agent_doctor_cmd(*, global_: bool, output_format: CliOutputFormat, error
}
if plugins_check is not None:
result["checks"]["plugins"] = {"healthy": plugins_check.is_healthy, "message": plugins_check.message}
+ if secrets_provider_check is not None:
+ result["checks"]["secrets_provider"] = {"healthy": secrets_provider_check.is_healthy, "message": secrets_provider_check.message}
if log_sink_check is not None:
result["checks"]["log_sink"] = {"healthy": log_sink_check.is_healthy, "message": log_sink_check.message}
diff --git a/pipelex/cli/commands/doctor_cmd.py b/pipelex/cli/commands/doctor_cmd.py
index 930e8fc7b..230c30f13 100644
--- a/pipelex/cli/commands/doctor_cmd.py
+++ b/pipelex/cli/commands/doctor_cmd.py
@@ -7,7 +7,7 @@ import io
import sys
from enum import StrEnum
from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, NamedTuple
from pydantic import BaseModel, ConfigDict, Field, ValidationError
from rich.markup import escape
@@ -57,6 +57,7 @@ from pipelex.migration.run import config_directories_to_migrate, migrate_config_
from pipelex.plugins.discovery import build_registrar
from pipelex.plugins.exceptions import PluginError
from pipelex.plugins.log_sink_registry import LogSinkRegistry
+from pipelex.plugins.secrets_provider_registry import SecretsProviderRegistry
from pipelex.runtime_hub import RuntimeHub, get_console, set_runtime_hub
from pipelex.system.configuration.config_loader import CONFIG_REFUSED, config_manager, pydantic_error_behind
from pipelex.system.configuration.config_surface import PIPELEX_CONFIG_SURFACE_ID, TELEMETRY_CONFIG_SURFACE_ID, strip_reserved_meta
@@ -76,13 +77,13 @@ from pipelex.system.pipelex_service.remote_config_fetcher import RemoteConfigFet
from pipelex.system.telemetry.telemetry_config import TELEMETRY_CONFIG_FILE_NAME, TelemetryConfig
from pipelex.tools.log.console_log_sink import ConsoleLogSink
from pipelex.tools.log.log_config import LogConfig
+from pipelex.tools.log.log_redaction import redaction_patterns, scrub_secrets
from pipelex.tools.log.log_sink import LogSinkMethod
from pipelex.tools.misc.dict_utils import extract_vars_from_strings_recursive
from pipelex.tools.misc.exceptions import TomlError
from pipelex.tools.misc.json_utils import deep_update
from pipelex.tools.misc.placeholder import value_is_placeholder
from pipelex.tools.misc.toml_utils import load_toml_from_base_and_overrides, load_toml_from_path
-from pipelex.tools.secrets.env_secrets_provider import EnvSecretsProvider
if TYPE_CHECKING:
from collections.abc import Mapping
@@ -90,6 +91,7 @@ if TYPE_CHECKING:
from pipelex.cogt.model_backends.gateway_config import GatewayConfig
from pipelex.plugins.registrar import PluginRegistrar
from pipelex.system.pipelex_service.types import RemoteConfigSource
+ from pipelex.tools.secrets.secrets_provider_abstract import SecretsProviderAbstract
class ConfigLocationInfo(BaseModel):
@@ -566,10 +568,14 @@ def _is_error_about_backend(*, exc: BaseException, backend_name: str, backend_fi
return backend_file_path in str(exc)
-def check_backend_files(*, config_dir: Path | None = None) -> tuple[bool, dict[str, BackendFileReport], str]:
+def check_backend_files(
+ *, secrets_provider: SecretsProviderAbstract, config_dir: Path | None = None
+) -> tuple[bool, dict[str, BackendFileReport], str]:
"""Check individual backend configuration files for validity.
Args:
+ secrets_provider: The provider the configuration selects, which the backends' credentials resolve
+ through, as they do at boot.
config_dir: Explicit config directory override (e.g. for --global).
If None, uses layered resolution (project .pipelex/ → global ~/.pipelex/).
@@ -624,7 +630,6 @@ def check_backend_files(*, config_dir: Path | None = None) -> tuple[bool, dict[s
try:
# Create a temporary backend library and try to load this backend
- secrets_provider = EnvSecretsProvider()
temp_library = InferenceBackendLibrary.make_empty()
# This row reports on file shape, so the load is lenient: a backend whose gateway
@@ -693,6 +698,7 @@ def display_health_report(
models_skipped: bool = False,
log_sink_check: LogSinkCheck | None = None,
plugins_check: PluginsCheck | None = None,
+ secrets_provider_check: SecretsProviderCheck | None = None,
) -> None:
"""Display a comprehensive health report.
@@ -723,9 +729,12 @@ def display_health_report(
setup never ran, in which case the row is not rendered.
plugins_check: What the runtime setup found when it discovered the plugins; None when it
never did, in which case the row is not rendered.
+ secrets_provider_check: What the runtime setup found when it built the secrets provider;
+ None when it never did, in which case the row is not rendered.
"""
log_sink_healthy = log_sink_check is None or log_sink_check.is_healthy
plugins_healthy = plugins_check is None or plugins_check.is_healthy
+ secrets_provider_healthy = secrets_provider_check is None or secrets_provider_check.is_healthy
all_healthy = (
config_healthy
and pending_migrations_check.is_healthy
@@ -736,6 +745,7 @@ def display_health_report(
and internal_backend_healthy
and log_sink_healthy
and plugins_healthy
+ and secrets_provider_healthy
)
# Overall status panel
@@ -798,6 +808,16 @@ def display_health_report(
console.print(f" [red]✗[/red] {escape(plugins_check.message)}")
console.print()
+ # Secrets Provider section: built before the sink, as at boot, because the sink's settings and the
+ # backends' credentials resolve through it.
+ if secrets_provider_check is not None:
+ console.print("[bold]Secrets Provider[/bold]")
+ if secrets_provider_check.is_healthy:
+ console.print(f" [green]✓[/green] {escape(secrets_provider_check.message)}")
+ else:
+ console.print(f" [red]✗[/red] {escape(secrets_provider_check.message)}")
+ console.print()
+
# Log Sink section: where this very report's lines go, so a token nobody registered is a row
# rather than the end of the report.
if log_sink_check is not None:
@@ -908,6 +928,7 @@ def display_health_report(
can_auto_fix_config
or not log_sink_healthy
or not plugins_healthy
+ or not secrets_provider_healthy
or can_auto_fix_telemetry
or can_migrate
or migrations_need_a_look
@@ -959,6 +980,12 @@ def display_health_report(
" • Fix, upgrade or uninstall the plugin named in the Plugins row, or take a core plugin out of runtime.plugins.disabled"
)
+ if not secrets_provider_healthy:
+ console.print(
+ f" • Set [cyan]method[/cyan] in {escape('[runtime.secrets]')} to a registered secrets provider, "
+ "or fix what the Secrets Provider row says stopped it"
+ )
+
if not log_sink_healthy:
console.print(
f" • Set [cyan]sink[/cyan] in {escape('[runtime.log]')} to a registered log sink, or fix what the Log Sink row says stopped it"
@@ -1131,17 +1158,28 @@ class PluginsCheck(BaseModel):
message: str
-class DoctorRuntimeSetup(BaseModel):
- """What ``setup_doctor_runtime`` found on its way to a configured logger, one row each.
-
- ``plugins`` is ``None`` when logging was already configured in this process, since the doctor then
- keeps the sink in place and never discovers the plugins.
- """
+class SecretsProviderCheck(BaseModel):
+ """What the doctor found about ``[runtime.secrets] method``: the configured provider built, or what stopped it."""
model_config = ConfigDict(frozen=True)
+ is_healthy: bool
+ message: str
+
+
+class DoctorRuntimeSetup(NamedTuple):
+ """What ``setup_doctor_runtime`` found on its way to a configured logger, one row each, and the secrets provider it built.
+
+ ``built_secrets_provider`` is the provider the configuration selects, the one boot would build: the
+ log sink, the backend-file probe and the models check resolve credentials through it. It is ``None``
+ when it did not build, and the ``secrets_provider`` row says why. A provider is no pydantic type,
+ which is why this holder is a ``NamedTuple``: it never travels, so it needs no schema.
+ """
+
+ plugins: PluginsCheck
+ secrets_provider: SecretsProviderCheck
log_sink: LogSinkCheck
- plugins: PluginsCheck | None
+ built_secrets_provider: SecretsProviderAbstract | None
FALLBACK_LOG_SINK_NOTE = f"this report goes through the '{LogSinkMethod.CONSOLE}' sink on stderr instead"
@@ -1170,11 +1208,25 @@ def _install_fallback_log_sink(*, log_config: LogConfig) -> str:
return FALLBACK_LOG_SINK_NOTE
-def install_doctor_log_sink(*, registry: LogSinkRegistry | None, log_config: LogConfig) -> LogSinkCheck:
+def redacted_failure(*, exc: Exception, log_config: LogConfig) -> str:
+ """An exception's text as a report row may print it, scrubbed with the patterns the log sink's redaction uses.
+
+ A row reaches the console and the agent's JSON and Markdown without passing through any sink, so the
+ redaction a log line gets has to be applied here. The failures the rows quote are the ones most likely
+ to carry a credential: a vault's connection error quoting its token, a sink factory's error quoting a
+ setting resolved from a secret.
+ """
+ return scrub_secrets(text=str(exc), patterns=redaction_patterns(config=log_config.redaction))
+
+
+def install_doctor_log_sink(
+ *, registry: LogSinkRegistry | None, log_config: LogConfig, secrets_provider: SecretsProviderAbstract | None
+) -> LogSinkCheck:
"""Install the configured sink, or the console sink on stderr with a finding when it cannot be.
- Boot stops on an unregistered token, on a factory that raises and on a registry that did not
- build. The doctor must not, since where its own lines go is one of the things it diagnoses: it
+ Boot stops on an unregistered token, on a factory that raises, a ``${…}`` placeholder in the sink's
+ settings that does not resolve among them, on a registry that did not build and on a secrets
+ provider that did not build. The doctor must not, since where its own lines go is one of the things it diagnoses: it
installs the console sink on stderr instead and reports why in a row of its own, so the rest of
the report is still produced. The retry is usually safe because ``log.install_sink`` builds the
handler before it touches the root logger, so a sink that failed to build left nothing installed —
@@ -1193,6 +1245,14 @@ def install_doctor_log_sink(*, registry: LogSinkRegistry | None, log_config: Log
is_healthy=False,
message=f"The log sink '{log_config.sink}' could not be resolved because the plugin registry did not build; {note}",
)
+ if secrets_provider is None:
+ # Boot hands the sink the provider it built, so trying the sink against a stand-in would answer a
+ # question about a configuration nobody wrote.
+ note = _install_fallback_log_sink(log_config=log_config)
+ return LogSinkCheck(
+ is_healthy=False,
+ message=f"The log sink '{log_config.sink}' was not checked because the secrets provider did not build; {note}",
+ )
if not registry.has(method=log_config.sink):
note = _install_fallback_log_sink(log_config=log_config)
return LogSinkCheck(
@@ -1200,23 +1260,25 @@ def install_doctor_log_sink(*, registry: LogSinkRegistry | None, log_config: Log
message=(f"No log sink is registered for '{log_config.sink}' in [runtime.log]; {note}. Registered sinks: {', '.join(registry.methods)}"),
)
try:
- log.install_sink(registry.get_required(method=log_config.sink)(log_config))
+ log.install_sink(registry.get_required(method=log_config.sink)(log_config, secrets_provider=secrets_provider))
except Exception as exc: # ruff: ignore[blind-except]
# A factory or a handler that raises on this configuration, a console target no sink writes
# to or a dependency the sink needs: the row says so, and the report goes on.
if log.sink is not None:
- failure = f"was installed but then failed while the records held since logging was configured were replayed through it: {exc}"
+ replay_failure = redacted_failure(exc=exc, log_config=log_config)
+ failure = f"was installed but then failed while the records held since logging was configured were replayed through it: {replay_failure}"
return LogSinkCheck(is_healthy=False, message=f"The log sink '{log_config.sink}' {failure}")
note = _install_fallback_log_sink(log_config=log_config)
- return LogSinkCheck(is_healthy=False, message=f"The log sink '{log_config.sink}' could not be installed: {exc}; {note}")
+ install_failure = redacted_failure(exc=exc, log_config=log_config)
+ return LogSinkCheck(is_healthy=False, message=f"The log sink '{log_config.sink}' could not be installed: {install_failure}; {note}")
return LogSinkCheck(is_healthy=True, message=f"Log sink '{log_config.sink}' installed")
def build_doctor_registrar() -> PluginRegistrar:
"""Discover the plugins the way a full boot does, with no boot orchestrator.
- Pure and safe to run more than once, like ``build_registrar`` itself: the doctor runs it for the log sink row and
- again for the models row, which needs the internal models and deck defaults the plugins declare.
+ Pure and safe to run more than once, like ``build_registrar`` itself: the doctor runs it for the secrets provider and
+ log sink rows and again for the models row, which needs the internal models and deck defaults the plugins declare.
Raises:
PluginError: a plugin could not be discovered or registered.
@@ -1230,23 +1292,72 @@ def build_doctor_registrar() -> PluginRegistrar:
)
-def discover_plugins_and_install_doctor_log_sink(*, log_config: LogConfig) -> DoctorRuntimeSetup:
- """Discover the plugins the way boot does, then install the configured sink, each a row rather than the end of the report.
+def build_doctor_secrets_provider(
+ *, registrar: PluginRegistrar | None, log_config: LogConfig
+) -> tuple[SecretsProviderCheck, SecretsProviderAbstract | None]:
+ """Build the secrets provider ``[runtime.secrets] method`` selects, the way boot does, or say in a row what stopped it.
+
+ Boot stops on a registry that did not build, on an unregistered method and on a factory that raises,
+ which only an external secrets plugin can do. The doctor reports each instead, and hands back
+ ``None`` so that the rows needing the provider say they could not run rather than run against
+ secrets the configuration does not use. A factory's failure is quoted redacted, with the patterns
+ ``log_config`` carries.
+ """
+ method = get_config().runtime.secrets.method
+ if registrar is None:
+ return (
+ SecretsProviderCheck(
+ is_healthy=False, message=f"The secrets provider '{method}' could not be resolved because the plugin registry did not build"
+ ),
+ None,
+ )
+ registry = SecretsProviderRegistry(registrar.secrets_providers)
+ if not registry.has(method=method):
+ message = f"No secrets provider is registered for '{method}' in [runtime.secrets]. Registered methods: {', '.join(registry.methods)}"
+ return SecretsProviderCheck(is_healthy=False, message=message), None
+ try:
+ secrets_provider = registry.get_required(method=method)(get_config().runtime.secrets)
+ except Exception as exc: # ruff: ignore[blind-except]
+ # A third-party factory can fail in any way it likes, a vault that cannot be reached for one: the
+ # row says so, and the report goes on.
+ failure = redacted_failure(exc=exc, log_config=log_config)
+ return SecretsProviderCheck(is_healthy=False, message=f"The secrets provider '{method}' could not be built: {failure}"), None
+ return SecretsProviderCheck(is_healthy=True, message=f"Secrets provider '{method}' built"), secrets_provider
+
+
+def discover_doctor_runtime(*, log_config: LogConfig, installs_log_sink: bool) -> DoctorRuntimeSetup:
+ """Discover the plugins, build the secrets provider and install the sink, in boot's order, each a row rather than the end of the report.
``build_registrar`` is fail-loud: a plugin built against another plugin API, a broken third-party
module or a core plugin named in ``runtime.plugins.disabled`` raises a ``PluginError``, which is not
a configuration error and which the doctor exists to diagnose rather than die on.
+
+ The secrets provider comes before the sink, as at boot, because the sink's settings may name
+ secrets. It is built even when ``installs_log_sink`` is false, logging having been configured before
+ the doctor ran, since the models row resolves the backends' credentials through it.
"""
+ registrar: PluginRegistrar | None
try:
registrar = build_doctor_registrar()
except PluginError as exc:
- return DoctorRuntimeSetup(
- plugins=PluginsCheck(is_healthy=False, message=f"The plugin registry did not build: {exc.message}"),
- log_sink=install_doctor_log_sink(registry=None, log_config=log_config),
+ registrar = None
+ plugins_check = PluginsCheck(is_healthy=False, message=f"The plugin registry did not build: {exc.message}")
+ else:
+ plugins_check = PluginsCheck(is_healthy=True, message="Plugins discovered and registered")
+ secrets_provider_check, secrets_provider = build_doctor_secrets_provider(registrar=registrar, log_config=log_config)
+ if installs_log_sink:
+ log_sink_check = install_doctor_log_sink(
+ registry=LogSinkRegistry(registrar.log_sinks) if registrar is not None else None,
+ log_config=log_config,
+ secrets_provider=secrets_provider,
)
+ else:
+ log_sink_check = LogSinkCheck(is_healthy=True, message="Logging was already configured in this process, and its sink stays")
return DoctorRuntimeSetup(
- plugins=PluginsCheck(is_healthy=True, message="Plugins discovered and registered"),
- log_sink=install_doctor_log_sink(registry=LogSinkRegistry(registrar.log_sinks), log_config=log_config),
+ plugins=plugins_check,
+ secrets_provider=secrets_provider_check,
+ log_sink=log_sink_check,
+ built_secrets_provider=secrets_provider,
)
@@ -1271,13 +1382,15 @@ def setup_doctor_runtime(*, log_config_overrides: Mapping[str, Any] | None = Non
``log.configure`` is invoked through ``configure_if_unset`` so that if a library
embedding or interleaved test has already configured logging, this call no-ops
- instead of raising the once-per-process ``RuntimeError``. When it does apply, the
- sink is selected the way boot selects it: the pure ``build_registrar`` discovery,
- then the ``runtime.log.sink`` lookup — the doctor bypasses ``Pipelex.make`` but not
- the configuration's choice of where its own lines go. Where boot would stop, on a
- registry that does not build, a token nobody registered or a sink that fails to
- install, the doctor installs the console sink on stderr and says so in the rows it
- returns.
+ instead of raising the once-per-process ``RuntimeError``. Either way the plugins are
+ discovered with the pure ``build_registrar`` and the secrets provider is built from
+ ``runtime.secrets.method``, since the models row needs it. When the configure does
+ apply, the sink is then selected the way boot selects it, from ``runtime.log.sink``
+ and handed that provider — the doctor bypasses ``Pipelex.make`` but not the
+ configuration's choice of where its own lines go. Where boot would stop, on a
+ registry that does not build, a secrets provider that does not build, a token nobody
+ registered or a sink that fails to install, the doctor installs the console sink on
+ stderr and says so in the rows it returns.
Args:
log_config_overrides: Optional mapping of ``LogConfig`` field names → values to
@@ -1286,10 +1399,10 @@ def setup_doctor_runtime(*, log_config_overrides: Mapping[str, Any] | None = Non
project/global layering is bypassed and only this directory is read.
Returns:
- The plugins row and the log sink row. The log sink row is healthy when the configured
- sink was installed, or when logging was already configured and its sink stays; not
- healthy when the console sink on stderr stands in, and the message says why. The
- plugins row is ``None`` when logging was already configured.
+ The plugins, secrets provider and log sink rows, and the secrets provider built. The
+ log sink row is healthy when the configured sink was installed, or when logging was
+ already configured and its sink stays; not healthy when the console sink on stderr
+ stands in, and the message says why.
Raises:
PipelexConfigError: If config validation fails. Translation of
@@ -1312,33 +1425,40 @@ def setup_doctor_runtime(*, log_config_overrides: Mapping[str, Any] | None = Non
deep_update(merged, updates=log_config_overrides)
log_config = LogConfig.model_validate(merged)
runtime_hub.set_console_print_target(target=log_config.console_print_target)
- runtime_setup = DoctorRuntimeSetup(
- log_sink=LogSinkCheck(is_healthy=True, message="Logging was already configured in this process, and its sink stays"),
- plugins=None,
- )
- if log.configure_if_unset(log_config=log_config):
- runtime_setup = discover_plugins_and_install_doctor_log_sink(log_config=log_config)
+ # Configured before the discovery, so that what discovery and the secrets provider log is held for the sink, as at boot.
+ installs_log_sink = log.configure_if_unset(log_config=log_config)
+ runtime_setup = discover_doctor_runtime(log_config=log_config, installs_log_sink=installs_log_sink)
runtime_hub.set_pretty_print_mode(mode=log_config.pretty_print_mode)
if (stale_warning := config_manager.take_stale_configuration_warning()) is not None:
log.warning(stale_warning)
return runtime_setup
-def check_models(*, config_dir: Path | None = None) -> tuple[bool, str, dict[str, BackendFileReport]]:
+def check_models(
+ *, secrets_provider: SecretsProviderAbstract | None, config_dir: Path | None = None
+) -> tuple[bool, str, dict[str, BackendFileReport]]:
"""Check if models are valid, including backend file validation.
Assumes ``setup_doctor_runtime`` has already run — the function reads from the
active hub and relies on ``log`` being configured.
Args:
+ secrets_provider: The provider ``setup_doctor_runtime`` built from the configuration, which the
+ backends' credentials resolve through as they do at boot; ``None`` when it did not build, and
+ then nothing here can be checked.
config_dir: Explicit config directory override (e.g. for --global).
If None, uses layered resolution (project .pipelex/ → global ~/.pipelex/).
Returns:
Tuple of (is_healthy, message, backend_file_reports)
"""
+ # The backends resolve their credentials through the configured provider, so without it no backend
+ # loads the way boot would load it; the secrets provider row already says why it did not build.
+ if secrets_provider is None:
+ return False, "Error checking models: the secrets provider did not build, so the backends and the model deck cannot be checked", {}
+
# First check backend files individually
- backend_files_healthy, backend_file_reports, _ = check_backend_files(config_dir=config_dir)
+ backend_files_healthy, backend_file_reports, _ = check_backend_files(secrets_provider=secrets_provider, config_dir=config_dir)
# If backend files have issues, report that immediately
if not backend_files_healthy:
@@ -1397,8 +1517,10 @@ def check_models(*, config_dir: Path | None = None) -> tuple[bool, str, dict[str
backend_file_reports,
)
+ # The setup reaches the backends' credentials through the configured provider, so a failure it quotes may
+ # carry that provider's own text; the row quotes it scrubbed, like the secrets provider row.
+ log_config = get_config().runtime.log
models_manager = ModelManager()
- secrets_provider = EnvSecretsProvider()
try:
models_manager.setup(
secrets_provider=secrets_provider,
@@ -1420,7 +1542,7 @@ def check_models(*, config_dir: Path | None = None) -> tuple[bool, str, dict[str
if _is_error_about_backend(exc=exc, backend_name=backend_name, backend_file_path=backend_file_report.file_path):
backend_file_report.is_valid = False
backend_file_report.error_message = error_str
- return False, f"Error checking models: {exc}", backend_file_reports
+ return False, f"Error checking models: {redacted_failure(exc=exc, log_config=log_config)}", backend_file_reports
except (
RoutingProfileLibraryNotFoundError,
InferenceBackendLibraryNotFoundError,
@@ -1433,7 +1555,15 @@ def check_models(*, config_dir: Path | None = None) -> tuple[bool, str, dict[str
GatewayUnknownModelError,
PluginModelDeclarationError,
) as exc:
- return False, f"Error checking models: {exc}", backend_file_reports
+ return False, f"Error checking models: {redacted_failure(exc=exc, log_config=log_config)}", backend_file_reports
+ except Exception as exc: # ruff: ignore[blind-except]
+ # Doctor probe: an external secrets provider may raise anything on a lookup, an unreachable vault or
+ # an SDK it imports at use. Boot stops on it; the doctor reports it in this row and goes on.
+ return (
+ False,
+ f"Error checking models: the setup failed on a {type(exc).__name__}: {redacted_failure(exc=exc, log_config=log_config)}",
+ backend_file_reports,
+ )
return True, "Models are valid", backend_file_reports
@@ -1505,12 +1635,14 @@ def do_doctor_cmd(
backend_file_reports: dict[str, BackendFileReport]
log_sink_check: LogSinkCheck | None = None
plugins_check: PluginsCheck | None = None
+ secrets_provider_check: SecretsProviderCheck | None = None
if config_healthy:
try:
runtime_setup = setup_doctor_runtime()
log_sink_check = runtime_setup.log_sink
plugins_check = runtime_setup.plugins
- models_healthy, models_message, backend_file_reports = check_models()
+ secrets_provider_check = runtime_setup.secrets_provider
+ models_healthy, models_message, backend_file_reports = check_models(secrets_provider=runtime_setup.built_secrets_provider)
models_skipped = False
except PipelexConfigError as exc:
models_healthy = False
@@ -1550,6 +1682,7 @@ def do_doctor_cmd(
fix_mode=fix,
log_sink_check=log_sink_check,
plugins_check=plugins_check,
+ secrets_provider_check=secrets_provider_check,
)
all_healthy = (
@@ -1562,6 +1695,7 @@ def do_doctor_cmd(
and internal_backend_healthy
and (log_sink_check is None or log_sink_check.is_healthy)
and (plugins_check is None or plugins_check.is_healthy)
+ and (secrets_provider_check is None or secrets_provider_check.is_healthy)
)
# Exit code: 0 if healthy, 1 if issues found
diff --git a/pipelex/migration/goldens/pipelex-config/[email protected] b/pipelex/migration/goldens/pipelex-config/[email protected]
index ca10eca8a..cb3431d9d 100644
--- a/pipelex/migration/goldens/pipelex-config/[email protected]
+++ b/pipelex/migration/goldens/pipelex-config/[email protected]
@@ -106,6 +106,9 @@ keywords_to_hilight = []
# (for instance "http://localhost:4318/v1/logs"); left unset, the exporter follows the OpenTelemetry
# environment conventions: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT, then OTEL_EXPORTER_OTLP_ENDPOINT, then
# the collector default on localhost. Empty headers likewise leave OTEL_EXPORTER_OTLP_HEADERS in charge.
+# A header value may name a secret rather than carry it, a collector's bearer token written
+# "Bearer ${OTLP_AUTH_TOKEN}" for one: it is resolved through the secrets provider [runtime.secrets]
+# selects, which boot builds before the sink, and a variable that does not resolve stops the boot.
[runtime.log.otlp]
headers = {}
@@ -116,6 +119,8 @@ headers = {}
# Cloud Logging log the entries land under. A project_id key names the project when it is not the
# ambient one the credentials or the metadata server declare, and a credentials_file_path key names a
# service-account JSON file when Application Default Credentials are not what the process should use.
+# The path may be a secret too, "${GCP_CREDENTIALS_FILE_PATH}" being the one the gcp storage provider
+# reads, resolved through the secrets provider the way the otlp headers are.
[runtime.log.gcp]
log_name = "pipelex"
diff --git a/pipelex/pipelex.toml b/pipelex/pipelex.toml
index ca10eca8a..cb3431d9d 100644
--- a/pipelex/pipelex.toml
+++ b/pipelex/pipelex.toml
@@ -106,6 +106,9 @@ keywords_to_hilight = []
# (for instance "http://localhost:4318/v1/logs"); left unset, the exporter follows the OpenTelemetry
# environment conventions: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT, then OTEL_EXPORTER_OTLP_ENDPOINT, then
# the collector default on localhost. Empty headers likewise leave OTEL_EXPORTER_OTLP_HEADERS in charge.
+# A header value may name a secret rather than carry it, a collector's bearer token written
+# "Bearer ${OTLP_AUTH_TOKEN}" for one: it is resolved through the secrets provider [runtime.secrets]
+# selects, which boot builds before the sink, and a variable that does not resolve stops the boot.
[runtime.log.otlp]
headers = {}
@@ -116,6 +119,8 @@ headers = {}
# Cloud Logging log the entries land under. A project_id key names the project when it is not the
# ambient one the credentials or the metadata server declare, and a credentials_file_path key names a
# service-account JSON file when Application Default Credentials are not what the process should use.
+# The path may be a secret too, "${GCP_CREDENTIALS_FILE_PATH}" being the one the gcp storage provider
+# reads, resolved through the secrets provider the way the otlp headers are.
[runtime.log.gcp]
log_name = "pipelex"
diff --git a/pipelex/plugins/contract.py b/pipelex/plugins/contract.py
index 9014fa046..9cba47e0b 100644
--- a/pipelex/plugins/contract.py
+++ b/pipelex/plugins/contract.py
@@ -33,7 +33,12 @@ if TYPE_CHECKING:
# ``add_internal_model`` and ``add_doc_gen_default`` — plain data a plugin declares for the model manager to merge at
# boot: a model of the internal backend, as the table a backend file would hold, and the model deck's default engine for
# one document format and source — joined under v4 without a bump, on the same reasoning as ``add_log_sink``.
-PLUGIN_API_VERSION: int = 4
+#
+# v5 changed the log-sink factory contract: boot now resolves the secrets provider before the log sink, and
+# a ``LogSinkFactoryFn`` receives it as the ``secrets_provider`` keyword argument, so a sink's settings can
+# name a secret. A factory written against v4 would be called with a keyword it does not accept and fail at
+# boot with a bare ``TypeError``; the bump turns that into a discovery-time mismatch naming the plugin.
+PLUGIN_API_VERSION: int = 5
@runtime_checkable
diff --git a/pipelex/plugins/log_sink_registry.py b/pipelex/plugins/log_sink_registry.py
index 55dc47aa4..49c568ca7 100644
--- a/pipelex/plugins/log_sink_registry.py
+++ b/pipelex/plugins/log_sink_registry.py
@@ -1,14 +1,27 @@
-from collections.abc import Callable
+from typing import Protocol
from pipelex.plugins.exceptions import UnknownLogSinkError
from pipelex.tools.log.log_config import LogConfig
from pipelex.tools.log.log_sink import LogSink
+from pipelex.tools.secrets.secrets_provider_abstract import SecretsProviderAbstract
-# A plugin's factory for one log sink: whole log config in, sink out. The whole config (not a
-# pre-resolved sub-config) is passed so a factory can read whatever it needs — the stream target, its
-# own settings section — at the boot apply-point, never at registration. The sink's handler is built
-# later still, when boot installs it, which is where a missing dependency fails loud.
-LogSinkFactoryFn = Callable[[LogConfig], LogSink]
+
+class LogSinkFactoryFn(Protocol):
+ """A plugin's factory for one log sink: whole log config and the boot's secrets provider in, sink out.
+
+ The whole config (not a pre-resolved sub-config) is passed so a factory can read whatever it needs —
+ the stream target, its own settings section — at the boot apply-point, never at registration. The
+ sink's handler is built later still, when boot installs it, which is where a missing dependency
+ fails loud.
+
+ The secrets provider is passed rather than read off the hub, because boot builds it before the sink
+ but sets it on the hub only afterwards: the keyword is the one way a factory reaches a secret, so
+ the order is one the type checker enforces rather than a ``RuntimeError`` at boot. A sink whose
+ settings name no secret accepts it and ignores it. ``config`` is positional-only here so that an
+ implementation may spell its own first parameter as it likes.
+ """
+
+ def __call__(self, config: LogConfig, /, *, secrets_provider: SecretsProviderAbstract) -> LogSink: ...
class LogSinkRegistry:
diff --git a/pipelex/providers/log_sinks/log_sink_plugin.py b/pipelex/providers/log_sinks/log_sink_plugin.py
index 6f7df28c3..e520cbd49 100644
--- a/pipelex/providers/log_sinks/log_sink_plugin.py
+++ b/pipelex/providers/log_sinks/log_sink_plugin.py
@@ -1,25 +1,59 @@
+import re
+
from pipelex.plugins.contract import PLUGIN_API_VERSION
from pipelex.plugins.registrar import PluginRegistrar
from pipelex.system.runtime import RunEnvironment
from pipelex.system.telemetry.otel_constants import OTelConstants
from pipelex.tools.log.console_log_sink import ConsoleLogSink
+from pipelex.tools.log.exceptions import LogSinkHeaderValueError, LogSinkVariableError
from pipelex.tools.log.gcp_log_sink import make_gcp_log_sink
from pipelex.tools.log.json_log_sink import JsonLogSink
from pipelex.tools.log.log_config import LogConfig
from pipelex.tools.log.log_sink import LogSink, LogSinkMethod, stream_for_target
from pipelex.tools.misc.package_utils import get_package_version
+from pipelex.tools.secrets.exceptions import UnknownVarPrefixError, VarFallbackPatternError, VarNotFoundError
+from pipelex.tools.secrets.secrets_provider_abstract import SecretsProviderAbstract
+from pipelex.tools.secrets.secrets_utils import VAR_PLACEHOLDER_PATTERN, substitute_vars
+
+OTLP_SECTION = "runtime.log.otlp"
+GCP_SECTION = "runtime.log.gcp"
+
+
+def _resolve_sink_setting(*, value: str, sink_method: LogSinkMethod, section: str, key: str, secrets_provider: SecretsProviderAbstract) -> str:
+ """One sink setting with its ``${…}`` placeholders resolved, the syntax the inference backends use.
+
+ Each placeholder is resolved on its own, so that one which does not resolve is named exactly, the
+ fallback spelling ``env:X|secret:Y`` included, and so that the error never quotes the rest of the
+ value. A placeholder left as written would be sent to the collector, or opened as a path, as if it
+ were the credential, so a miss stops the boot rather than keeping the placeholder the way the
+ telemetry settings do.
+
+ Raises:
+ LogSinkVariableError: If a placeholder does not resolve.
+
+ """
+
+ def resolve_placeholder( # kw-only: ignore — re.sub calls the replacement with the match positionally
+ match: re.Match[str],
+ ) -> str:
+ try:
+ return substitute_vars(match.group(0), secrets_provider=secrets_provider, raise_on_missing_var=True)
+ except (VarNotFoundError, VarFallbackPatternError, UnknownVarPrefixError) as exc:
+ raise LogSinkVariableError(sink_method=sink_method, section=section, key=key, variable=match.group(1), cause=exc.message) from exc
+
+ return VAR_PLACEHOLDER_PATTERN.sub(resolve_placeholder, value)
-def _make_json_log_sink(config: LogConfig) -> LogSink:
+def _make_json_log_sink(config: LogConfig, *, secrets_provider: SecretsProviderAbstract) -> LogSink: # ruff: ignore[unused-function-argument] - the json sink names no secret; uniform LogSinkFactoryFn signature
return JsonLogSink(stream=stream_for_target(target=config.console_log_target))
-def _make_console_log_sink(config: LogConfig) -> LogSink:
+def _make_console_log_sink(config: LogConfig, *, secrets_provider: SecretsProviderAbstract) -> LogSink: # ruff: ignore[unused-function-argument] - the console sink names no secret; uniform LogSinkFactoryFn signature
# Rich is imported when the sink builds its handler, at install, never here.
return ConsoleLogSink(rich_log_config=config.rich_log, target=config.console_log_target)
-def _make_otlp_log_sink(config: LogConfig) -> LogSink:
+def _make_otlp_log_sink(config: LogConfig, *, secrets_provider: SecretsProviderAbstract) -> LogSink:
# Deferred imports: the OpenTelemetry logs SDK and the exporter load only when this sink is
# selected, so registering the built-ins stays import-light and a process on another sink never
# pays for them. The sink module imports the SDK at load, which is why it is imported here too.
@@ -40,17 +74,46 @@ def _make_otlp_log_sink(config: LogConfig) -> LogSink:
deployment_attributes.DEPLOYMENT_ENVIRONMENT: RunEnvironment.get_from_env_var().value,
}
)
+ # The header values may name secrets, a collector's bearer token being the usual one; the keys are
+ # taken as written. The resolved values live only in the exporter, never in the configuration.
+ headers = {
+ name: _resolve_sink_setting(
+ value=value, sink_method=LogSinkMethod.OTLP, section=OTLP_SECTION, key=f"headers.{name}", secrets_provider=secrets_provider
+ )
+ for name, value in config.otlp.headers.items()
+ }
+ # The exporter takes any string and fails only at export, on a thread whose failures the sink filters out
+ # of its own stream, so a header no HTTP request can carry is refused here, while the boot can still say so.
+ for name, value in headers.items():
+ if "\r" in value or "\n" in value:
+ raise LogSinkHeaderValueError(sink_method=LogSinkMethod.OTLP, section=OTLP_SECTION, key=f"headers.{name}")
# ``None`` for an absent endpoint or empty headers leaves the exporter to the OTEL_EXPORTER_OTLP_*
# environment conventions, the way a collector-side deployment is configured.
- exporter = OTLPLogExporter(endpoint=config.otlp.endpoint, headers=config.otlp.headers or None)
+ exporter = OTLPLogExporter(endpoint=config.otlp.endpoint, headers=headers or None)
return OtlpLogSink(processor=BatchLogRecordProcessor(exporter), resource=resource)
-def _make_gcp_log_sink(config: LogConfig) -> LogSink:
+def _make_gcp_log_sink(config: LogConfig, *, secrets_provider: SecretsProviderAbstract) -> LogSink:
+ # The key path may name a secret, ``${GCP_CREDENTIALS_FILE_PATH}`` being the one the ``gcp`` storage
+ # provider reads. It is resolved on a copy, so the configuration keeps the placeholder, and the sink
+ # is handed the placeholder too, so that its credential errors name the spelling to fix beside the path.
+ gcp_config = config.gcp
+ placeholder: str | None = None
+ if gcp_config.credentials_file_path is not None:
+ resolved_path = _resolve_sink_setting(
+ value=gcp_config.credentials_file_path,
+ sink_method=LogSinkMethod.GCP,
+ section=GCP_SECTION,
+ key="credentials_file_path",
+ secrets_provider=secrets_provider,
+ )
+ if VAR_PLACEHOLDER_PATTERN.search(gcp_config.credentials_file_path) is not None:
+ placeholder = gcp_config.credentials_file_path
+ gcp_config = gcp_config.model_copy(update={"credentials_file_path": resolved_path})
# Deferred import: the Google Cloud Logging client library loads inside ``make_gcp_log_sink``,
# when this factory runs, so registering the built-ins imports none of it and a process on
# another sink never pays for it. A missing extra fails there, loud, with the install hint.
- return make_gcp_log_sink(config=config.gcp)
+ return make_gcp_log_sink(config=gcp_config, credentials_file_path_placeholder=placeholder)
class LogSinkPlugin:
diff --git a/pipelex/runtime_boot.py b/pipelex/runtime_boot.py
index b259182a9..3319c2cf9 100644
--- a/pipelex/runtime_boot.py
+++ b/pipelex/runtime_boot.py
@@ -512,10 +512,10 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
# Build the plugin registrar from the fully-resolved config (pure and import-light:
# registering the built-ins imports no backend SDK, constructs no client, touches no hub).
# Built here — after the gateway service/terms precondition gate above (so an unaccepted-terms or
- # first-run boot fails fast before any discovery work) and before the telemetry factory below,
- # which is the first consumer of the secrets provider. Secrets is now a config-selected plugin
- # seam: the built-in SecretsPlugin's factory (and any external pipelex-secrets-<backend>) is
- # looked up from the registrar-derived SecretsProviderRegistry just below. The other registries
+ # first-run boot fails fast before any discovery work) and before the secrets provider and the log
+ # sink below, the first two capabilities resolved out of it: the built-in SecretsPlugin's factory
+ # (and any external pipelex-secrets-<backend>) is looked up from the registrar-derived
+ # SecretsProviderRegistry, then the sink from the LogSinkRegistry. The other registries
# (inference, storage, …) are still built later at their own hub-set points, all referencing this
# same already-built registrar; the slot-claim thunks / teardown callbacks it also accumulates are
# applied at their ordered apply-points in later phases.
@@ -549,14 +549,30 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
if boot_orchestrator is not None and boot_orchestrator not in plugin_registrar.registered_plugin_names:
raise UnknownBootOrchestratorError(requested=boot_orchestrator)
- # The log sink: the first capability resolved out of the registrar, because every line the rest
+ # The secrets provider: the first capability resolved out of the registrar, because the log sink
+ # just below may name a secret in its settings (an OTLP collector's bearer token, the path of the
+ # service-account key the ``gcp`` sink reads), and so do the telemetry factory and the model setup
+ # further down. Precedence: explicit setup() param > config-selected registry factory. The built-in
+ # SecretsPlugin supplies the "env" method, so there is no separate core default. Building it ahead
+ # of the sink costs nothing in kind: what the provider logs is held like every line before the sink,
+ # and when it fails to build, the lines held until then reach stderr redacted through the holding
+ # handler, as they do when a remote-config fetch above fails, while its exception goes up to the
+ # caller as raised. It goes on the hub only further down: until then the keyword the sink factory
+ # receives is the one way to reach it.
+ secrets_provider_registry = SecretsProviderRegistry(plugin_registrar.secrets_providers)
+ self.runtime_hub.set_secrets_provider_registry(secrets_provider_registry)
+ if secrets_provider is None:
+ secrets_config = get_config().runtime.secrets
+ secrets_provider = secrets_provider_registry.get_required(method=secrets_config.method)(secrets_config)
+
+ # The log sink, resolved right after the secrets provider it receives, because every line the rest
# of this boot emits should be rendered by the sink the configuration chose. ``log.configure``
# ran in ``__init__``, before discovery could, and has held every record since; installing the
# sink replays them through it. The built-in LogSinkPlugin supplies every shipped sink, so there
# is no separate core default, and an unknown token fails loud here listing the registered ones.
log_config = get_config().runtime.log
log_sink_registry = LogSinkRegistry(plugin_registrar.log_sinks)
- log.install_sink(log_sink_registry.get_required(method=log_config.sink)(log_config))
+ log.install_sink(log_sink_registry.get_required(method=log_config.sink)(log_config, secrets_provider=secrets_provider))
# The pretty-print mode is checked beside the sink, for the same reason: a process asking for the
# ``rich`` panels without Rich installed stops here, naming the ``cli`` extra and the Rich-free modes,
# rather than failing at the first pipe that prints its output. The check asks whether Rich imports,
@@ -564,15 +580,6 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
if log_config.pretty_print_mode is PrettyPrintMode.RICH:
require_rich_for_rendering()
- # Secrets provider precedence: explicit setup() param > config-selected registry factory.
- # The built-in SecretsPlugin supplies the "env" method, so there is no separate core default.
- # Resolved here because the telemetry factory just below (and the model setup further down) consume it.
- secrets_provider_registry = SecretsProviderRegistry(plugin_registrar.secrets_providers)
- self.runtime_hub.set_secrets_provider_registry(secrets_provider_registry)
- if secrets_provider is None:
- secrets_config = get_config().runtime.secrets
- secrets_provider = secrets_provider_registry.get_required(method=secrets_config.method)(secrets_config)
-
# Whether the Pipelex Gateway telemetry stream is sent: the conditions, and why each one is
# there, are in `should_enable_pipelex_telemetry`.
#
@@ -617,7 +624,7 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
self.runtime_hub.set_func_registry(func_registry=self.func_registry)
self.runtime_hub.set_secrets_provider(secrets_provider=secrets_provider)
# Storage is selected from the config-driven StorageProviderRegistry, built from the plugin
- # registrar (constructed above, just before the telemetry factory). Its resolution and hub-set
+ # registrar (constructed above, just before the secrets provider). Its resolution and hub-set
# still happen later at the plugin-derived-registries block — after secrets is on the hub here,
# so the GCP factory's secret read works.
@@ -706,8 +713,8 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
raise PipelexSetupError(error_msg) from credentials_exc
# --- Plugin-derived registries --------------------------------------------------------
- # The plugin registrar was built earlier (with the boot-orchestrator gate checked and the
- # config-selected secrets provider resolved) just before the telemetry factory. Turn its
+ # The plugin registrar was built earlier, with the boot-orchestrator gate checked and the
+ # config-selected secrets provider and log sink resolved out of it right after. Turn its
# accumulated contributions into the hub registries here — after the gateway/model setup checks
# and before the hub setup points below — the family worker factories look their backends up on
# these at run time.
diff --git a/pipelex/tools/log/exceptions.py b/pipelex/tools/log/exceptions.py
index 1ab37e5db..2ff0a4e7b 100644
--- a/pipelex/tools/log/exceptions.py
+++ b/pipelex/tools/log/exceptions.py
@@ -12,3 +12,54 @@ class GcpLogSinkCredentialsError(CredentialsError):
error_domain = ErrorDomain.CONFIG
_declared_title = "Log sink credentials missing or refused"
+
+
+class LogSinkVariableError(CredentialsError):
+ """Raised at boot when a ``${…}`` placeholder in a log sink's settings does not resolve.
+
+ The ``otlp`` sink's header values and the ``gcp`` sink's key path are read through the secrets
+ provider, and a placeholder left as written would be sent to the collector, or opened as a path, as
+ if it were the credential: every record the sink exports would be refused on its export thread
+ while the boot reported success. So the boot stops instead, naming the section, the key and the
+ variable, never a value. Fixed by an operator setting the variable or selecting another sink.
+ """
+
+ error_domain = ErrorDomain.CONFIG
+ _declared_title = "Log sink variable did not resolve"
+
+ def __init__(self, *, sink_method: str, section: str, key: str, variable: str, cause: str):
+ self.sink_method = sink_method
+ self.section = section
+ self.key = key
+ self.variable = variable
+ msg = (
+ f"The '{sink_method}' log sink cannot be built: `{key}` under [{section}] names the variable "
+ f"'${{{variable}}}', which did not resolve ({cause}). Set it in the secrets provider that "
+ "[runtime.secrets] selects, or in the environment for an `env:` variable, or select the 'json' sink in [runtime.log]."
+ )
+ super().__init__(msg)
+
+
+class LogSinkHeaderValueError(CredentialsError):
+ """Raised at boot when an ``otlp`` sink header value holds a line break once its placeholders resolve.
+
+ No HTTP header can carry a line break, so the exporter would be built and installed, then refuse every
+ batch on its export thread, where the sink drops its own failures, while the boot reported success. A
+ secret read from a file often ends with a newline, which is how one gets there. So the boot stops
+ instead, naming the section and the key, never the value. Fixed by an operator storing the secret
+ without the line break.
+ """
+
+ error_domain = ErrorDomain.CONFIG
+ _declared_title = "Log sink header value holds a line break"
+
+ def __init__(self, *, sink_method: str, section: str, key: str):
+ self.sink_method = sink_method
+ self.section = section
+ self.key = key
+ msg = (
+ f"The '{sink_method}' log sink cannot be built: `{key}` under [{section}] holds a line break once its "
+ "placeholders resolve, and no HTTP header can carry one, so the collector would receive nothing. A secret "
+ "read from a file often ends with a newline: store it without one, in the secrets provider that [runtime.secrets] selects."
+ )
+ super().__init__(msg)
diff --git a/pipelex/tools/log/gcp_log_sink.py b/pipelex/tools/log/gcp_log_sink.py
index 6c0239e23..4e87a6eb3 100644
--- a/pipelex/tools/log/gcp_log_sink.py
+++ b/pipelex/tools/log/gcp_log_sink.py
@@ -648,20 +648,31 @@ class GcpLogSink(LogSink):
return handler
-def _credentials_source(*, config: GcpLogSinkConfig) -> str:
- """The credentials the sink authenticates with, as a sentence names them."""
+def _credentials_source(*, config: GcpLogSinkConfig, credentials_file_path_placeholder: str | None) -> str:
+ """The credentials the sink authenticates with, as a sentence names them, with the placeholder the path came from."""
if config.credentials_file_path is None:
return "the Application Default Credentials"
+ if credentials_file_path_placeholder is not None:
+ return f"the service-account key at '{config.credentials_file_path}' (resolved from '{credentials_file_path_placeholder}')"
return f"the service-account key at '{config.credentials_file_path}'"
-def _credentials_remedy(*, config: GcpLogSinkConfig) -> str:
- """What renews the credentials, for the error that stops the boot."""
+def _credentials_remedy(*, config: GcpLogSinkConfig, credentials_file_path_placeholder: str | None) -> str:
+ """What renews the credentials, for the error that stops the boot.
+
+ A path that came from a placeholder is fixed where the variable is set, not in the TOML, so the
+ remedy says so.
+ """
if config.credentials_file_path is None:
return (
"Renew them (`gcloud auth application-default login` on a workstation, or the service account the machine runs as "
"on Google Cloud), or point `credentials_file_path` in [runtime.log.gcp] at a valid service-account key"
)
+ if credentials_file_path_placeholder is not None:
+ return (
+ f"Point the variable that `credentials_file_path` in [runtime.log.gcp] names, '{credentials_file_path_placeholder}', "
+ "at a valid service-account key where it is set"
+ )
return "Point `credentials_file_path` in [runtime.log.gcp] at a valid service-account key"
@@ -710,9 +721,13 @@ def confirm_credentials_at_boot(*, credentials_check: GcpCredentialsCheck, remed
)
-def make_gcp_log_sink(*, config: GcpLogSinkConfig) -> GcpLogSink:
+def make_gcp_log_sink(*, config: GcpLogSinkConfig, credentials_file_path_placeholder: str | None = None) -> GcpLogSink:
"""Build the sink that writes to Cloud Logging through the client library's background thread.
+ ``config`` carries the key path already resolved; ``credentials_file_path_placeholder`` is the
+ ``${…}`` spelling it was resolved from, when it was one, which the credential errors name beside
+ the path so that a reader knows to fix the variable rather than the TOML.
+
Where the dependency is paid for: the client library is imported here, so a process that selected
another sink never loads it, and one that selected this sink without the extra fails here, at
boot, with the extra and the ``json`` alternative named.
@@ -750,8 +765,8 @@ def make_gcp_log_sink(*, config: GcpLogSinkConfig) -> GcpLogSink:
message=msg,
) from exc
- source = _credentials_source(config=config)
- remedy = _credentials_remedy(config=config)
+ source = _credentials_source(config=config, credentials_file_path_placeholder=credentials_file_path_placeholder)
+ remedy = _credentials_remedy(config=config, credentials_file_path_placeholder=credentials_file_path_placeholder)
client: Any
if config.credentials_file_path is not None:
# The key is loaded apart from the client, so that the catch covers the file and nothing else: a
diff --git a/pipelex/tools/log/log_config.py b/pipelex/tools/log/log_config.py
index 5b98b3ebe..63dd9f81f 100644
--- a/pipelex/tools/log/log_config.py
+++ b/pipelex/tools/log/log_config.py
@@ -71,6 +71,11 @@ class OtlpLogSinkConfig(ConfigModel):
``OTEL_EXPORTER_OTLP_LOGS_ENDPOINT``, then ``OTEL_EXPORTER_OTLP_ENDPOINT`` with the ``/v1/logs``
path, then the collector default on localhost. Empty ``headers`` likewise leave
``OTEL_EXPORTER_OTLP_HEADERS`` in charge.
+
+ A header value may name a secret with the ``${…}`` placeholders the inference backends use, a
+ collector's bearer token written ``"Bearer ${OTLP_AUTH_TOKEN}"`` for one. The sink's factory
+ resolves them through the secrets provider, which boot builds before the sink, and hands the
+ resolved values to the exporter alone: this model keeps the placeholders.
"""
endpoint: str | None = None
@@ -86,10 +91,10 @@ class GcpLogSinkConfig(ConfigModel):
Application Default Credentials, which is what a process already running on Google Cloud has; a
path names a service-account JSON file to build the client from instead.
- The path is a plain config value rather than a secret id resolved through the secrets provider,
- because the log sink is the first capability boot resolves — ahead of the secrets provider, so
- that every later line of the boot goes through the sink the configuration chose — and there is no
- provider on the hub to ask at the moment this section is read.
+ The path may be a ``${…}`` placeholder, ``"${GCP_CREDENTIALS_FILE_PATH}"`` being the secret the
+ ``gcp`` storage provider reads. The sink's factory resolves it through the secrets provider, which
+ boot builds before the sink, and hands the resolved path to the client and to the credential errors,
+ which quote it beside the placeholder: this model keeps the placeholder.
"""
log_name: str
diff --git a/pipelex/tools/log/log_redaction.py b/pipelex/tools/log/log_redaction.py
index e8f6933d4..cb3d7424b 100644
--- a/pipelex/tools/log/log_redaction.py
+++ b/pipelex/tools/log/log_redaction.py
@@ -196,13 +196,22 @@ def escape_control_characters(*, text: str) -> str:
return CONTROL_CHARACTERS.sub(_escaped_control_character, text)
+def redaction_patterns(*, config: LogRedactionConfig) -> tuple[RedactionPattern, ...]:
+ """The shipped families followed by the patterns the configuration added, compiled.
+
+ The processor scrubs records with them, and so does any text that reaches a reader without passing
+ through a sink, ``pipelex doctor``'s rows for one, so that both remove the same things.
+ """
+ return SECRET_PATTERNS + tuple((re.compile(extra), REDACTED_TEXT) for extra in config.extra_patterns)
+
+
def make_redaction_processor(*, config: LogRedactionConfig) -> LogRecordProcessor:
"""One processor for the sink seam, carrying the shipped families and whatever the configuration added.
The patterns are compiled once, here, rather than on every record: a processor runs on the calling
thread of every log call in the process.
"""
- patterns = SECRET_PATTERNS + tuple((re.compile(extra), REDACTED_TEXT) for extra in config.extra_patterns)
+ patterns = redaction_patterns(config=config)
def redact(record: logging.LogRecord) -> None: # kw-only: ignore — the sink seam calls a processor positionally
try:
diff --git a/pipelex/tools/secrets/secrets_utils.py b/pipelex/tools/secrets/secrets_utils.py
index 55d5c83da..a49243bf9 100644
--- a/pipelex/tools/secrets/secrets_utils.py
+++ b/pipelex/tools/secrets/secrets_utils.py
@@ -11,6 +11,10 @@ from pipelex.tools.secrets.exceptions import (
)
from pipelex.tools.secrets.secrets_provider_abstract import SecretsProviderAbstract
+# A ``${…}`` placeholder: ``${VAR_NAME}``, ``${prefix:VAR_NAME}`` or ``${env:VAR|secret:VAR}``. Restricted so as not to
+# match across newlines, quotes or nested braces. Its one group is what sits between the braces.
+VAR_PLACEHOLDER_PATTERN = re.compile(r"\$\{([^}\n\"'$]+)\}")
+
class VarPrefix(StrEnum):
"""Variable prefix types for variable substitution."""
@@ -83,10 +87,7 @@ def substitute_vars(
raise
return match.group(0) # Keep original placeholder
- # Pattern matches ${VAR_NAME} or ${prefix:VAR_NAME} or ${env:VAR|secret:VAR}
- # Restrict to not match across newlines, quotes, or nested braces
- pattern = r"\$\{([^}\n\"'$]+)\}"
- return re.sub(pattern, replace_var, content)
+ return VAR_PLACEHOLDER_PATTERN.sub(replace_var, content)
def _handle_fallback_pattern(var_spec: str, *, secrets_provider: SecretsProviderAbstract) -> str:
diff --git a/tests/data/errors/error_identity.txt b/tests/data/errors/error_identity.txt
index 2bd4e302f..ce6893101 100644
--- a/tests/data/errors/error_identity.txt
+++ b/tests/data/errors/error_identity.txt
@@ -171,6 +171,8 @@ LinkupError | Linkup | https://docs.pipelex.com/latest/errors/linkup-error/
LinkupSearchEmptyResultError | Linkup search empty result | https://docs.pipelex.com/latest/errors/linkup-search-empty-result-error/
LinkupSearchResponseError | Linkup search response | https://docs.pipelex.com/latest/errors/linkup-search-response-error/
ListWhereSingularError | List where singular | https://docs.pipelex.com/latest/errors/list-where-singular-error/
+LogSinkHeaderValueError | Log sink header value holds a line break | https://docs.pipelex.com/latest/errors/log-sink-header-value-error/
+LogSinkVariableError | Log sink variable did not resolve | https://docs.pipelex.com/latest/errors/log-sink-variable-error/
ManifoldCredentialsError | Manifold credentials | https://docs.pipelex.com/latest/errors/manifold-credentials-error/
ManifoldEndpointError | Manifold endpoint | https://docs.pipelex.com/latest/errors/manifold-endpoint-error/
ManifoldError | Manifold | https://docs.pipelex.com/latest/errors/manifold-error/
diff --git a/tests/helpers/doctor_log_sink.py b/tests/helpers/doctor_log_sink.py
new file mode 100644
index 000000000..5861d71fb
--- /dev/null
+++ b/tests/helpers/doctor_log_sink.py
@@ -0,0 +1,39 @@
+"""Fakes and readings shared by the doctor's log-sink and secrets-provider row tests."""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+from rich.logging import RichHandler
+from typing_extensions import override
+
+from pipelex.system.configuration.config_loader import ConfigLoader
+from pipelex.system.console_target import ConsoleTarget
+from pipelex.tools.log.console_log_sink import ConsoleLogSink
+from pipelex.tools.log.log import log
+from pipelex.tools.log.log_config import LogConfig
+from pipelex.tools.log.log_sink import LogSink
+from pipelex.tools.misc.toml_utils import load_toml_from_path
+
+
+def doctor_log_config(*, sink: str, console_log_target: ConsoleTarget = ConsoleTarget.STDERR) -> LogConfig:
+ """The shipped ``[runtime.log]``, with the sink and the console target the test names."""
+ config_dict = load_toml_from_path(ConfigLoader().pipelex_root_dir / "pipelex.toml")
+ return LogConfig.model_validate({**config_dict["runtime"]["log"], "sink": sink, "console_log_target": console_log_target})
+
+
+def assert_the_fallback_console_sink_is_installed_on_stderr() -> None:
+ sink = log.sink
+ assert isinstance(sink, ConsoleLogSink)
+ handler = sink.handler
+ assert isinstance(handler, RichHandler)
+ assert handler.console.file is sys.stderr
+
+
+class NullLogSink(LogSink):
+ """A sink whose handler drops every record."""
+
+ @override
+ def make_handler(self) -> logging.Handler:
+ return logging.NullHandler()
diff --git a/tests/helpers/log_sink_variables.py b/tests/helpers/log_sink_variables.py
new file mode 100644
index 000000000..c5a3bd907
--- /dev/null
+++ b/tests/helpers/log_sink_variables.py
@@ -0,0 +1,75 @@
+"""Fakes and builders shared by the tests of the built-in sink factories resolving ``${…}`` placeholders."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from typing import TYPE_CHECKING, cast
+
+from typing_extensions import override
+
+from pipelex.plugins.discovery import build_registrar
+from pipelex.plugins.log_sink_registry import LogSinkFactoryFn, LogSinkRegistry
+from pipelex.providers.builtins import KERNEL_BUILTIN_PLUGINS, KERNEL_CORE_UNCONDITIONAL_PLUGIN_NAMES, KERNEL_ENTRY_POINT_GROUPS
+from pipelex.system.configuration.config_loader import ConfigLoader
+from pipelex.tools.log.log_config import LogConfig
+from pipelex.tools.misc.toml_utils import load_toml_from_path
+from pipelex.tools.secrets.exceptions import SecretNotFoundError
+from pipelex.tools.secrets.secrets_provider_abstract import SecretsProviderAbstract
+
+if TYPE_CHECKING:
+ from pytest_mock import MockerFixture
+
+ from pipelex.system.configuration.configs import PipelexConfig
+ from pipelex.tools.log.log_sink import LogSinkMethod
+
+
+class DictSecretsProvider(SecretsProviderAbstract):
+ """The secrets a test hands it, and nothing else."""
+
+ def __init__(self, *, secrets: dict[str, str]) -> None:
+ self._secrets = secrets
+
+ @override
+ def get_required_secret(self, secret_id: str) -> str:
+ if secret_id not in self._secrets:
+ msg = f"No secret '{secret_id}' in this test provider"
+ raise SecretNotFoundError(msg)
+ return self._secrets[secret_id]
+
+ @override
+ def get_optional_secret(self, secret_id: str) -> str | None:
+ return self._secrets.get(secret_id)
+
+ @override
+ def get_required_secret_specific_version(self, secret_id: str, *, version_id: str) -> str:
+ raise NotImplementedError
+
+ @override
+ def get_optional_secret_specific_version(self, secret_id: str, *, version_id: str) -> str | None:
+ raise NotImplementedError
+
+ @override
+ def set_secret_as_env_var(self, secret_id: str, *, version_id: str = "latest") -> None:
+ raise NotImplementedError
+
+
+def sink_settings_log_config(*, otlp_headers: dict[str, str] | None = None, gcp_credentials_file_path: str | None = None) -> LogConfig:
+ """The shipped ``[runtime.log]``, with the ``otlp`` headers and the ``gcp`` key path the test names."""
+ config_dict = load_toml_from_path(ConfigLoader().pipelex_root_dir / "pipelex.toml")
+ log_dict = config_dict["runtime"]["log"]
+ otlp = {**log_dict["otlp"], "headers": otlp_headers or {}}
+ gcp = {**log_dict["gcp"], "credentials_file_path": gcp_credentials_file_path}
+ return LogConfig.model_validate({**log_dict, "otlp": otlp, "gcp": gcp})
+
+
+def builtin_log_sink_factory(*, method: LogSinkMethod, mocker: MockerFixture) -> LogSinkFactoryFn:
+ """The factory the built-in plugins register for ``method``, discovered with no external plugin."""
+ mocker.patch("pipelex.plugins.discovery._external_entry_points", return_value=[])
+ registrar = build_registrar(
+ config=cast("PipelexConfig", SimpleNamespace(runtime=SimpleNamespace(plugins=SimpleNamespace(disabled=[])))),
+ boot_orchestrator=None,
+ builtin_plugins=KERNEL_BUILTIN_PLUGINS,
+ core_unconditional_plugin_names=KERNEL_CORE_UNCONDITIONAL_PLUGIN_NAMES,
+ entry_point_groups=KERNEL_ENTRY_POINT_GROUPS,
+ )
+ return LogSinkRegistry(registrar.log_sinks).get_required(method=method)
diff --git a/tests/integration/pipelex/plugins/test_log_sink_external_plugin.py b/tests/integration/pipelex/plugins/test_log_sink_external_plugin.py
index fd1fcba7d..eba9c1c8d 100644
--- a/tests/integration/pipelex/plugins/test_log_sink_external_plugin.py
+++ b/tests/integration/pipelex/plugins/test_log_sink_external_plugin.py
@@ -34,6 +34,7 @@ if TYPE_CHECKING:
from pipelex.plugins.registrar import PluginRegistrar
from pipelex.tools.log.log_config import LogConfig
+ from pipelex.tools.secrets.secrets_provider_abstract import SecretsProviderAbstract
EXTERNAL_SINK_METHOD = "test_sink"
EXTERNAL_PLUGIN_NAME = "test_log_sink_ext"
@@ -61,7 +62,7 @@ class _RecordingLogSink(LogSink):
return self.recording_handler
-def _make_fake_external_sink(_config: LogConfig) -> LogSink:
+def _make_fake_external_sink(_config: LogConfig, /, *, secrets_provider: SecretsProviderAbstract) -> LogSink: # ruff: ignore[unused-function-argument] - the LogSinkFactoryFn shape
return _RecordingLogSink()
diff --git a/tests/integration/pipelex/plugins/test_otlp_sink_header_secret_at_boot.py b/tests/integration/pipelex/plugins/test_otlp_sink_header_secret_at_boot.py
new file mode 100644
index 000000000..a7221ba03
--- /dev/null
+++ b/tests/integration/pipelex/plugins/test_otlp_sink_header_secret_at_boot.py
@@ -0,0 +1,84 @@
+"""A boot on the ``otlp`` sink resolves a header naming a secret for the exporter, and nowhere else.
+
+The configuration keeps the placeholder, so the resolved token reaches the exporter it authenticates and
+no record, no line on stdout or stderr and no reading of the configuration carries it.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar
+
+import pytest
+from opentelemetry.sdk._logs.export import InMemoryLogRecordExporter
+
+from pipelex import log
+from pipelex.config import get_config
+from pipelex.pipelex import Pipelex
+from pipelex.system.runtime import IntegrationMode, runtime_manager
+from pipelex.tools.log.log_sink import LogSinkMethod
+from tests.helpers.log_sink_variables import DictSecretsProvider
+
+if TYPE_CHECKING:
+ from collections.abc import Generator
+
+ from pytest_mock import MockerFixture
+
+COLLECTOR_TOKEN = "collector-token-0123456789abcdef"
+OTLP_EXPORTER_PATH = "opentelemetry.exporter.otlp.proto.http._log_exporter.OTLPLogExporter"
+
+
+class _RecordingOtlpExporter(InMemoryLogRecordExporter):
+ """Stands in for the OTLP HTTP exporter: keeps what it was built with and what it was asked to export."""
+
+ built: ClassVar[list[_RecordingOtlpExporter]] = []
+
+ def __init__(self, *, endpoint: str | None = None, headers: dict[str, str] | None = None, **_kwargs: Any) -> None:
+ super().__init__()
+ self.endpoint = endpoint
+ self.headers = headers
+ _RecordingOtlpExporter.built.append(self)
+
+
[email protected](autouse=True)
+def reset_pipelex_config_fixture() -> Generator[None, None, None]:
+ """Override the global module fixture: this module boots per test and tears down."""
+ Pipelex.teardown_if_needed()
+ yield
+ Pipelex.teardown_if_needed()
+
+
+def _test_integration_mode() -> IntegrationMode:
+ return IntegrationMode.CI if runtime_manager.is_ci_testing else IntegrationMode.PYTEST
+
+
+class TestOtlpSinkHeaderSecretAtBoot:
+ def test_the_header_is_resolved_for_the_exporter_while_the_config_and_every_record_keep_the_token_out(
+ self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]
+ ) -> None:
+ _RecordingOtlpExporter.built.clear()
+ mocker.patch(OTLP_EXPORTER_PATH, _RecordingOtlpExporter)
+
+ Pipelex.make(
+ integration_mode=_test_integration_mode(),
+ needs_inference=False,
+ secrets_provider=DictSecretsProvider(secrets={"OTLP_COLLECTOR_TOKEN": COLLECTOR_TOKEN}),
+ config_overrides={
+ "runtime": {
+ "log": {"sink": LogSinkMethod.OTLP.value, "otlp": {"headers": {"Authorization": "Bearer ${OTLP_COLLECTOR_TOKEN}"}}},
+ }
+ },
+ )
+ log.info("a line after the boot")
+ assert get_config().runtime.log.otlp.headers == {"Authorization": "Bearer ${OTLP_COLLECTOR_TOKEN}"}
+ Pipelex.teardown_if_needed()
+
+ (exporter,) = _RecordingOtlpExporter.built
+ assert exporter.headers == {"Authorization": f"Bearer {COLLECTOR_TOKEN}"}
+ exported = exporter.get_finished_logs()
+ assert any(log_data.log_record.body == "a line after the boot" for log_data in exported)
+ for log_data in exported:
+ assert COLLECTOR_TOKEN not in str(log_data.log_record.body)
+ assert COLLECTOR_TOKEN not in str(log_data.log_record.attributes)
+ captured = capsys.readouterr()
+ assert COLLECTOR_TOKEN not in captured.out
+ assert COLLECTOR_TOKEN not in captured.err
diff --git a/tests/integration/pipelex/plugins/test_secrets_before_log_sink.py b/tests/integration/pipelex/plugins/test_secrets_before_log_sink.py
new file mode 100644
index 000000000..30bdf9f0e
--- /dev/null
+++ b/tests/integration/pipelex/plugins/test_secrets_before_log_sink.py
@@ -0,0 +1,199 @@
+"""Boot resolves the secrets provider before it installs the log sink, and hands that provider to the sink's factory.
+
+A fake external plugin registers a recording secrets method and a recording sink; the boot selects both.
+The secrets factory runs first and the sink factory receives the very provider the hub ends up holding,
+or the explicit ``setup(secrets_provider=...)`` one when there is one. The provider is not on the hub
+while the sink is built, so the keyword is the only way a sink reaches a secret. A secrets factory that
+raises stops the boot before any sink exists, and the lines held until then reach stderr, redacted.
+"""
+
+from __future__ import annotations
+
+import logging
+from types import SimpleNamespace
+from typing import TYPE_CHECKING, cast
+
+import pytest
+from typing_extensions import override
+
+from pipelex import log
+from pipelex.pipelex import Pipelex
+from pipelex.plugins.contract import PLUGIN_API_VERSION
+from pipelex.plugins.discovery import GroupedEntryPoint
+from pipelex.plugins.plugin_group import PluginGroup
+from pipelex.runtime_hub import get_secrets_provider
+from pipelex.system.runtime import IntegrationMode, runtime_manager
+from pipelex.tools.log.log_sink import LogSink
+from pipelex.tools.secrets.env_secrets_provider import EnvSecretsProvider
+from pipelex.tools.secrets.exceptions import SecretNotFoundError
+from pipelex.tools.secrets.secrets_provider_abstract import SecretsProviderAbstract
+
+if TYPE_CHECKING:
+ from collections.abc import Generator
+ from importlib.metadata import EntryPoint
+
+ from pytest_mock import MockerFixture
+
+ from pipelex.plugins.registrar import PluginRegistrar
+ from pipelex.tools.log.log_config import LogConfig
+ from pipelex.tools.secrets.secrets_config import SecretsProviderConfig
+
+EXTERNAL_PLUGIN_NAME = "test_secrets_before_sink_ext"
+RECORDING_SECRETS_METHOD = "test_recording_secret"
+FAILING_SECRETS_METHOD = "test_failing_secret"
+RECORDING_SINK_METHOD = "test_recording_sink"
+LEAKED_TOKEN = "held-line-token-0123456789abcdef"
+
+
+class _NoSecretsProvider(SecretsProviderAbstract):
+ """A provider holding no secret, whose only use is to be recognised: the tests compare it by identity."""
+
+ @override
+ def get_required_secret(self, secret_id: str) -> str:
+ msg = f"No secret '{secret_id}' in this test provider"
+ raise SecretNotFoundError(msg)
+
+ @override
+ def get_optional_secret(self, secret_id: str) -> str | None:
+ return None
+
+ @override
+ def get_required_secret_specific_version(self, secret_id: str, *, version_id: str) -> str:
+ raise NotImplementedError
+
+ @override
+ def get_optional_secret_specific_version(self, secret_id: str, *, version_id: str) -> str | None:
+ raise NotImplementedError
+
+ @override
+ def set_secret_as_env_var(self, secret_id: str, *, version_id: str = "latest") -> None:
+ pass
+
+
+class _BootRecorder:
+ """What the fake factories saw, in the order they ran, shared across one boot."""
+
+ def __init__(self) -> None:
+ self.calls: list[str] = []
+ self.built_provider: SecretsProviderAbstract | None = None
+ self.provider_handed_to_sink: SecretsProviderAbstract | None = None
+ self.hub_lookup_during_sink_build: Exception | None = None
+
+ def clear(self) -> None:
+ self.calls.clear()
+ self.built_provider = None
+ self.provider_handed_to_sink = None
+ self.hub_lookup_during_sink_build = None
+
+
+_recorder = _BootRecorder()
+
+
+class _NullLogSink(LogSink):
+ @override
+ def make_handler(self) -> logging.Handler:
+ return logging.NullHandler()
+
+
+def _make_recording_secrets_provider(_config: SecretsProviderConfig) -> SecretsProviderAbstract:
+ _recorder.calls.append("secrets")
+ _recorder.built_provider = _NoSecretsProvider()
+ return _recorder.built_provider
+
+
+def _make_failing_secrets_provider(_config: SecretsProviderConfig) -> SecretsProviderAbstract:
+ # A line the provider logs before it fails, quoting a credential the way a careless error path would.
+ log.warning(f"Could not reach the vault with Authorization: Bearer {LEAKED_TOKEN}")
+ msg = "the vault is unreachable"
+ raise ConnectionError(msg)
+
+
+def _make_recording_sink(_config: LogConfig, /, *, secrets_provider: SecretsProviderAbstract) -> LogSink:
+ _recorder.calls.append("sink")
+ _recorder.provider_handed_to_sink = secrets_provider
+ try:
+ get_secrets_provider()
+ except RuntimeError as exc:
+ _recorder.hub_lookup_during_sink_build = exc
+ return _NullLogSink()
+
+
+class _FakeSecretsAndSinkPlugin:
+ name = EXTERNAL_PLUGIN_NAME
+ targets_api = PLUGIN_API_VERSION
+
+ def register(self, registrar: PluginRegistrar) -> None:
+ registrar.add_secrets_provider(method=RECORDING_SECRETS_METHOD, factory=_make_recording_secrets_provider)
+ registrar.add_secrets_provider(method=FAILING_SECRETS_METHOD, factory=_make_failing_secrets_provider)
+ registrar.add_log_sink(method=RECORDING_SINK_METHOD, factory=_make_recording_sink)
+
+
[email protected](autouse=True)
+def reset_pipelex_config_fixture() -> Generator[None, None, None]:
+ """Override the global module fixture: this module boots per test and tears down."""
+ _recorder.clear()
+ Pipelex.teardown_if_needed()
+ yield
+ Pipelex.teardown_if_needed()
+
+
[email protected](autouse=True)
+def external_plugin_fixture(mocker: MockerFixture) -> None:
+ fake_entry_point = SimpleNamespace(name=EXTERNAL_PLUGIN_NAME, load=lambda: _FakeSecretsAndSinkPlugin)
+ grouped = GroupedEntryPoint(group=PluginGroup.KERNEL, entry_point=cast("EntryPoint", fake_entry_point))
+ mocker.patch("pipelex.plugins.discovery._external_entry_points", return_value=[grouped])
+
+
+def _test_integration_mode() -> IntegrationMode:
+ return IntegrationMode.CI if runtime_manager.is_ci_testing else IntegrationMode.PYTEST
+
+
+class TestSecretsBeforeLogSink:
+ def test_the_secrets_provider_is_built_before_the_sink_and_handed_to_its_factory(self) -> None:
+ Pipelex.make(
+ integration_mode=_test_integration_mode(),
+ needs_inference=False,
+ config_overrides={"runtime": {"secrets": {"method": RECORDING_SECRETS_METHOD}, "log": {"sink": RECORDING_SINK_METHOD}}},
+ )
+
+ assert _recorder.calls == ["secrets", "sink"]
+ assert _recorder.built_provider is not None
+ assert _recorder.provider_handed_to_sink is _recorder.built_provider
+ assert get_secrets_provider() is _recorder.built_provider
+
+ def test_the_explicit_secrets_provider_is_the_one_handed_to_the_sink(self) -> None:
+ explicit = EnvSecretsProvider()
+ Pipelex.make(
+ integration_mode=_test_integration_mode(),
+ needs_inference=False,
+ secrets_provider=explicit,
+ config_overrides={"runtime": {"secrets": {"method": RECORDING_SECRETS_METHOD}, "log": {"sink": RECORDING_SINK_METHOD}}},
+ )
+
+ assert _recorder.calls == ["sink"]
+ assert _recorder.provider_handed_to_sink is explicit
+ assert get_secrets_provider() is explicit
+
+ def test_the_provider_is_not_on_the_hub_while_the_sink_is_built(self) -> None:
+ Pipelex.make(
+ integration_mode=_test_integration_mode(),
+ needs_inference=False,
+ config_overrides={"runtime": {"secrets": {"method": RECORDING_SECRETS_METHOD}, "log": {"sink": RECORDING_SINK_METHOD}}},
+ )
+
+ assert isinstance(_recorder.hub_lookup_during_sink_build, RuntimeError)
+
+ def test_a_secrets_provider_that_fails_stops_the_boot_and_the_held_lines_reach_stderr_redacted(self, capsys: pytest.CaptureFixture[str]) -> None:
+ with pytest.raises(ConnectionError, match="the vault is unreachable"):
+ Pipelex.make(
+ integration_mode=_test_integration_mode(),
+ needs_inference=False,
+ config_overrides={"runtime": {"secrets": {"method": FAILING_SECRETS_METHOD}, "log": {"sink": RECORDING_SINK_METHOD}}},
+ )
+
+ assert "sink" not in _recorder.calls
+ assert log.sink is None
+ assert Pipelex.get_optional_instance() is None
+ stderr = capsys.readouterr().err
+ assert "Could not reach the vault with Authorization: Bearer [REDACTED]" in stderr
+ assert LEAKED_TOKEN not in stderr
diff --git a/tests/unit/pipelex/cli/test_agent_doctor_cmd.py b/tests/unit/pipelex/cli/test_agent_doctor_cmd.py
index 5c9a389f4..1a167fd3c 100644
--- a/tests/unit/pipelex/cli/test_agent_doctor_cmd.py
+++ b/tests/unit/pipelex/cli/test_agent_doctor_cmd.py
@@ -23,6 +23,7 @@ from pipelex.cli.commands.doctor_cmd import (
PendingMigrationsCheck,
PendingMigrationsFinding,
PluginsCheck,
+ SecretsProviderCheck,
TelemetryConfigCheck,
TelemetryConfigFinding,
)
@@ -34,6 +35,7 @@ from pipelex.tools.log.log import log
from pipelex.tools.log.log_config import LogConfig
from pipelex.tools.log.log_sink import LogSink
from pipelex.tools.misc.toml_utils import load_toml_from_path
+from pipelex.tools.secrets.env_secrets_provider import EnvSecretsProvider
NO_PENDING_MIGRATIONS = PendingMigrationsCheck(
finding=PendingMigrationsFinding.UP_TO_DATE,
@@ -43,7 +45,14 @@ NO_PENDING_MIGRATIONS = PendingMigrationsCheck(
HEALTHY_LOG_SINK = LogSinkCheck(is_healthy=True, message="Log sink 'console' installed")
HEALTHY_PLUGINS = PluginsCheck(is_healthy=True, message="Plugins discovered and registered")
-HEALTHY_RUNTIME_SETUP = DoctorRuntimeSetup(log_sink=HEALTHY_LOG_SINK, plugins=HEALTHY_PLUGINS)
+HEALTHY_SECRETS_PROVIDER = SecretsProviderCheck(is_healthy=True, message="Secrets provider 'env' built")
+BUILT_SECRETS_PROVIDER = EnvSecretsProvider()
+HEALTHY_RUNTIME_SETUP = DoctorRuntimeSetup(
+ plugins=HEALTHY_PLUGINS,
+ secrets_provider=HEALTHY_SECRETS_PROVIDER,
+ log_sink=HEALTHY_LOG_SINK,
+ built_secrets_provider=BUILT_SECRETS_PROVIDER,
+)
class _NullSink(LogSink):
@@ -141,6 +150,8 @@ class TestAgentDoctorCmd:
return_value=DoctorRuntimeSetup(
log_sink=LogSinkCheck(is_healthy=False, message="No log sink is registered for 'jsn' in [runtime.log]; registered: console, json"),
plugins=HEALTHY_PLUGINS,
+ secrets_provider=HEALTHY_SECRETS_PROVIDER,
+ built_secrets_provider=BUILT_SECRETS_PROVIDER,
),
)
mocker.patch("pipelex.cli.agent_cli.commands.doctor_cmd.check_config_files", return_value=(True, 0, "All config files present"))
@@ -169,6 +180,10 @@ class TestAgentDoctorCmd:
is_healthy=False, message="The log sink 'json' could not be resolved because the plugin registry did not build"
),
plugins=PluginsCheck(is_healthy=False, message="The plugin registry did not build: Plugin 'storage' is required by core"),
+ secrets_provider=SecretsProviderCheck(
+ is_healthy=False, message="The secrets provider 'env' could not be resolved because the plugin registry did not build"
+ ),
+ built_secrets_provider=None,
),
)
mocker.patch("pipelex.cli.agent_cli.commands.doctor_cmd.check_config_files", return_value=(True, 0, "All config files present"))
@@ -187,6 +202,37 @@ class TestAgentDoctorCmd:
assert "'storage'" in parsed["checks"]["plugins"]["message"]
assert any("plugins check" in action for action in parsed["recommended_actions"])
+ def test_a_secrets_provider_that_did_not_build_rides_the_envelope_with_its_action(
+ self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]
+ ) -> None:
+ mocker.patch(
+ "pipelex.cli.agent_cli.commands.doctor_cmd.setup_doctor_runtime",
+ return_value=DoctorRuntimeSetup(
+ plugins=HEALTHY_PLUGINS,
+ secrets_provider=SecretsProviderCheck(is_healthy=False, message="The secrets provider 'vault' could not be built: unreachable"),
+ log_sink=LogSinkCheck(is_healthy=False, message="The log sink 'json' was not checked because the secrets provider did not build"),
+ built_secrets_provider=None,
+ ),
+ )
+ mocker.patch("pipelex.cli.agent_cli.commands.doctor_cmd.check_config_files", return_value=(True, 0, "All config files present"))
+ mocker.patch(
+ "pipelex.cli.agent_cli.commands.doctor_cmd.check_telemetry_config",
+ return_value=TelemetryConfigCheck(finding=TelemetryConfigFinding.HEALTHY, message="Telemetry configured"),
+ )
+ mocker.patch("pipelex.cli.agent_cli.commands.doctor_cmd.check_backend_credentials", return_value=(True, {}, "All backends healthy"))
+ mock_check_models = mocker.patch("pipelex.cli.agent_cli.commands.doctor_cmd.check_models", return_value=(True, "Models valid", {}))
+
+ agent_doctor_cmd(output_format=CliOutputFormat.JSON)
+
+ parsed = json.loads(capsys.readouterr().out)
+ assert parsed["all_healthy"] is False
+ assert parsed["checks"]["secrets_provider"] == {
+ "healthy": False,
+ "message": "The secrets provider 'vault' could not be built: unreachable",
+ }
+ assert any("[runtime.secrets]" in action for action in parsed["recommended_actions"])
+ assert mock_check_models.call_args.kwargs["secrets_provider"] is None
+
@pytest.mark.parametrize(
("finding", "expected_action"),
[
diff --git a/tests/unit/pipelex/cli/test_doctor_backend_checks.py b/tests/unit/pipelex/cli/test_doctor_backend_checks.py
index 84d61e128..757e1a2b3 100644
--- a/tests/unit/pipelex/cli/test_doctor_backend_checks.py
+++ b/tests/unit/pipelex/cli/test_doctor_backend_checks.py
@@ -14,6 +14,7 @@ from pipelex.cli.commands.doctor_cmd import (
)
from pipelex.cogt.exceptions import InferenceBackendLibraryError
from pipelex.kit.paths import get_kit_configs_dir
+from pipelex.tools.secrets.env_secrets_provider import EnvSecretsProvider
if TYPE_CHECKING:
import pytest
@@ -47,6 +48,10 @@ def _write_backends_override(config_dir: Path, content: str) -> Path:
return override
+# The provider the doctor's runtime setup built from ``[runtime.secrets]``.
+SECRETS_PROVIDER = EnvSecretsProvider()
+
+
class TestDoctorBackendChecks:
def test_credentials_backends_toml_missing(self, tmp_path: Path) -> None:
"""No backends.toml means the credentials check fails with a clear message."""
@@ -106,7 +111,7 @@ class TestDoctorBackendChecks:
def test_backend_files_no_backends_dir(self, tmp_path: Path) -> None:
"""A missing inference/backends directory is healthy (nothing to check)."""
- healthy, reports, message = check_backend_files(config_dir=tmp_path)
+ healthy, reports, message = check_backend_files(secrets_provider=SECRETS_PROVIDER, config_dir=tmp_path)
assert healthy is True
assert reports == {}
@@ -116,7 +121,7 @@ class TestDoctorBackendChecks:
"""A backends dir without backends.toml is healthy (nothing to check)."""
(tmp_path / "inference" / "backends").mkdir(parents=True)
- healthy, reports, message = check_backend_files(config_dir=tmp_path)
+ healthy, reports, message = check_backend_files(secrets_provider=SECRETS_PROVIDER, config_dir=tmp_path)
assert healthy is True
assert reports == {}
@@ -127,7 +132,7 @@ class TestDoctorBackendChecks:
_write_backends_toml(tmp_path, content="not [ valid toml")
(tmp_path / "inference" / "backends").mkdir(parents=True)
- healthy, reports, message = check_backend_files(config_dir=tmp_path)
+ healthy, reports, message = check_backend_files(secrets_provider=SECRETS_PROVIDER, config_dir=tmp_path)
assert healthy is False
assert reports == {}
@@ -147,10 +152,11 @@ class TestDoctorBackendChecks:
library_mock = mocker.Mock()
mocker.patch("pipelex.cli.commands.doctor_cmd.InferenceBackendLibrary.make_empty", return_value=library_mock)
- healthy, reports, message = check_backend_files(config_dir=tmp_path)
+ healthy, reports, message = check_backend_files(secrets_provider=SECRETS_PROVIDER, config_dir=tmp_path)
assert healthy is True
assert message == "All backend files are valid"
+ assert library_mock.load.call_args.kwargs["secrets_provider"] is SECRETS_PROVIDER
assert reports["openai"].is_valid is True
assert reports["openai"].error_message is None
# openai ships in the kit, so the template is found by the real probe
@@ -163,7 +169,7 @@ class TestDoctorBackendChecks:
library_mock.load.side_effect = InferenceBackendLibraryError("invalid model spec", backend_name="openai")
mocker.patch("pipelex.cli.commands.doctor_cmd.InferenceBackendLibrary.make_empty", return_value=library_mock)
- healthy, reports, message = check_backend_files(config_dir=tmp_path)
+ healthy, reports, message = check_backend_files(secrets_provider=SECRETS_PROVIDER, config_dir=tmp_path)
assert healthy is False
assert message == "1 backend file(s) have validation errors"
@@ -177,7 +183,7 @@ class TestDoctorBackendChecks:
library_mock.load.side_effect = InferenceBackendLibraryError("some unrelated failure")
mocker.patch("pipelex.cli.commands.doctor_cmd.InferenceBackendLibrary.make_empty", return_value=library_mock)
- healthy, reports, _ = check_backend_files(config_dir=tmp_path)
+ healthy, reports, _ = check_backend_files(secrets_provider=SECRETS_PROVIDER, config_dir=tmp_path)
assert healthy is True
assert reports["openai"].is_valid is True
@@ -191,7 +197,7 @@ class TestDoctorBackendChecks:
)
mocker.patch("pipelex.cli.commands.doctor_cmd.InferenceBackendLibrary.make_empty", return_value=library_mock)
- healthy, reports, _ = check_backend_files(config_dir=tmp_path)
+ healthy, reports, _ = check_backend_files(secrets_provider=SECRETS_PROVIDER, config_dir=tmp_path)
assert healthy is True
assert reports["openai"].is_valid is True
@@ -221,7 +227,7 @@ class TestDoctorBackendChecks:
self._copy_kit_inference(tmp_path)
_write_backends_override(tmp_path, "[openai]\nenabled = false\n\n[vertexai]\nenabled = true\n")
- healthy, reports, _ = check_backend_files(config_dir=tmp_path)
+ healthy, reports, _ = check_backend_files(secrets_provider=SECRETS_PROVIDER, config_dir=tmp_path)
assert healthy is True
assert "openai" not in reports
@@ -233,7 +239,7 @@ class TestDoctorBackendChecks:
"""
self._copy_kit_inference(tmp_path)
- healthy, reports, message = check_backend_files(config_dir=tmp_path)
+ healthy, reports, message = check_backend_files(secrets_provider=SECRETS_PROVIDER, config_dir=tmp_path)
assert healthy is True
assert message == "All backend files are valid"
@@ -246,7 +252,7 @@ class TestDoctorBackendChecks:
anthropic_file = backends_dir / "anthropic.toml"
anthropic_file.write_text(anthropic_file.read_text(encoding="utf-8") + '\n[bogus_key_table]\nfoo = "bar"\n', encoding="utf-8")
- healthy, reports, message = check_backend_files(config_dir=tmp_path)
+ healthy, reports, message = check_backend_files(secrets_provider=SECRETS_PROVIDER, config_dir=tmp_path)
assert healthy is False
assert message == "1 backend file(s) have validation errors"
diff --git a/tests/unit/pipelex/cli/test_doctor_check_models.py b/tests/unit/pipelex/cli/test_doctor_check_models.py
index 0ded8946f..f5d3a176b 100644
--- a/tests/unit/pipelex/cli/test_doctor_check_models.py
+++ b/tests/unit/pipelex/cli/test_doctor_check_models.py
@@ -14,6 +14,8 @@ import pytest
from pipelex.cli.commands.doctor_cmd import BackendFileReport, check_models
from pipelex.cogt.exceptions import (
+ InferenceBackendCredentialsError,
+ InferenceBackendCredentialsErrorType,
InferenceBackendLibraryError,
InferenceBackendLibraryValidationError,
ModelDeckValidationError,
@@ -23,6 +25,7 @@ from pipelex.cogt.model_backends.backend import LEGACY_GATEWAY_MODEL_SPECS_SECTI
from pipelex.system.pipelex_service.exceptions import RemoteConfigUnavailableError
from pipelex.system.pipelex_service.remote_config import PipelexPosthogConfig, RemoteConfig
from pipelex.system.pipelex_service.types import RemoteConfigSource
+from pipelex.tools.secrets.env_secrets_provider import EnvSecretsProvider
if TYPE_CHECKING:
from pathlib import Path
@@ -30,6 +33,11 @@ if TYPE_CHECKING:
from pytest_mock import MockerFixture
+# The provider the doctor's runtime setup built from ``[runtime.secrets]``: what the backends resolve their credentials through.
+SECRETS_PROVIDER = EnvSecretsProvider()
+VAULT_TOKEN = "hvs.models-row-token-0123456789"
+
+
class TestCheckModels:
@pytest.fixture
def healthy_backend_files(self, mocker: MockerFixture) -> None:
@@ -62,7 +70,7 @@ class TestCheckModels:
)
manager_class_mock = mocker.patch("pipelex.cli.commands.doctor_cmd.ModelManager")
- healthy, message, reports = check_models()
+ healthy, message, reports = check_models(secrets_provider=SECRETS_PROVIDER)
assert healthy is False
assert message == "Backend configuration error: openai: bad spec"
@@ -72,7 +80,7 @@ class TestCheckModels:
@pytest.mark.usefixtures("healthy_backend_files", "gateway_disabled")
def test_gateway_disabled_happy_path(self, models_manager: Any) -> None:
"""With the gateway disabled and a valid deck, models are healthy."""
- healthy, message, reports = check_models()
+ healthy, message, reports = check_models(secrets_provider=SECRETS_PROVIDER)
assert healthy is True
assert message == "Models are valid"
@@ -90,7 +98,7 @@ class TestCheckModels:
)
mocker.patch("pipelex.cli.commands.doctor_cmd.load_pipelex_service_config_if_exists", return_value=None)
- healthy, message, _ = check_models()
+ healthy, message, _ = check_models(secrets_provider=SECRETS_PROVIDER)
assert healthy is False
assert message == "Pipelex Gateway is enabled but service configuration is missing"
@@ -105,7 +113,7 @@ class TestCheckModels:
service_config = SimpleNamespace(agreement=SimpleNamespace(terms_accepted=False))
mocker.patch("pipelex.cli.commands.doctor_cmd.load_pipelex_service_config_if_exists", return_value=service_config)
- healthy, message, _ = check_models()
+ healthy, message, _ = check_models(secrets_provider=SECRETS_PROVIDER)
assert healthy is False
assert message == "Pipelex Gateway is enabled but terms have not been accepted"
@@ -124,7 +132,7 @@ class TestCheckModels:
side_effect=RemoteConfigUnavailableError("offline, cold cache"),
)
- healthy, message, _ = check_models()
+ healthy, message, _ = check_models(secrets_provider=SECRETS_PROVIDER)
assert healthy is False
assert message == "Failed to fetch Pipelex Gateway remote configuration: offline, cold cache"
@@ -148,7 +156,7 @@ class TestCheckModels:
)
mocker.patch("pipelex.cli.commands.doctor_cmd.RemoteConfigFetcher.fetch_remote_config", return_value=fetch_result)
- healthy, message, _ = check_models()
+ healthy, message, _ = check_models(secrets_provider=SECRETS_PROVIDER)
assert healthy is True
assert message == "Models are valid"
@@ -163,7 +171,7 @@ class TestCheckModels:
"""A deck validation failure is reported as a models error."""
models_manager.validate_model_deck.side_effect = ModelDeckValidationError("preset broken")
- healthy, message, _ = check_models()
+ healthy, message, _ = check_models(secrets_provider=SECRETS_PROVIDER)
assert healthy is False
assert message == "Error checking models: preset broken"
@@ -182,7 +190,7 @@ class TestCheckModels:
)
models_manager.setup.side_effect = InferenceBackendLibraryError("cannot resolve model", backend_name="openai")
- healthy, message, reports = check_models()
+ healthy, message, reports = check_models(secrets_provider=SECRETS_PROVIDER)
assert healthy is False
assert message == "Error checking models: cannot resolve model"
@@ -208,7 +216,7 @@ class TestCheckModels:
backend_name="openai",
)
- healthy, _, reports = check_models()
+ healthy, _, reports = check_models(secrets_provider=SECRETS_PROVIDER)
assert healthy is False
assert reports["openai"].is_valid is False
@@ -220,7 +228,7 @@ class TestCheckModels:
"""The likeliest override typo — `active = "nope"` — is the routing library's own refusal, and the doctor must report it, not crash."""
models_manager.setup.side_effect = RoutingProfileLibraryError("Active profile 'nope' not found in the routing profile library")
- healthy, message, reports = check_models()
+ healthy, message, reports = check_models(secrets_provider=SECRETS_PROVIDER)
assert healthy is False
assert "Active profile 'nope' not found" in message
@@ -229,7 +237,7 @@ class TestCheckModels:
@pytest.mark.usefixtures("healthy_backend_files", "gateway_disabled")
def test_global_pins_both_documents_as_base_plus_override(self, models_manager: Any, tmp_path: Path) -> None:
"""`--global` hands the model manager that directory's base and its own override, for both documents."""
- check_models(config_dir=tmp_path)
+ check_models(secrets_provider=SECRETS_PROVIDER, config_dir=tmp_path)
kwargs = models_manager.setup.call_args.kwargs
assert kwargs["backends_library_paths"] == [tmp_path / "inference" / "backends.toml", tmp_path / "inference" / "backends_override.toml"]
@@ -246,9 +254,62 @@ class TestCheckModels:
side_effect=InferenceBackendLibraryValidationError("Invalid inference backend library 'x' with overrides 'y': TOML parsing error"),
)
- healthy, message, reports = check_models()
+ healthy, message, reports = check_models(secrets_provider=SECRETS_PROVIDER)
assert healthy is False
assert "TOML parsing error" in message
assert reports == {}
models_manager.setup.assert_not_called()
+
+ @pytest.mark.usefixtures("gateway_disabled")
+ def test_the_configured_secrets_provider_is_the_one_the_backends_are_checked_against(self, mocker: MockerFixture, models_manager: Any) -> None:
+ """Not a provider of the doctor's own choosing: a deployment on another secrets method is diagnosed against its own secrets."""
+ check_backend_files = mocker.patch(
+ "pipelex.cli.commands.doctor_cmd.check_backend_files",
+ return_value=(True, {}, "All backend files are valid"),
+ )
+
+ healthy, _, _ = check_models(secrets_provider=SECRETS_PROVIDER)
+
+ assert healthy is True
+ assert check_backend_files.call_args.kwargs["secrets_provider"] is SECRETS_PROVIDER
+ assert models_manager.setup.call_args.kwargs["secrets_provider"] is SECRETS_PROVIDER
+
+ def test_without_a_secrets_provider_nothing_is_checked_and_the_row_says_why(self, mocker: MockerFixture, models_manager: Any) -> None:
+ check_backend_files = mocker.patch("pipelex.cli.commands.doctor_cmd.check_backend_files")
+
+ healthy, message, reports = check_models(secrets_provider=None)
+
+ assert healthy is False
+ assert "the secrets provider did not build" in message
+ assert reports == {}
+ check_backend_files.assert_not_called()
+ models_manager.setup.assert_not_called()
+
+ @pytest.mark.usefixtures("healthy_backend_files", "gateway_disabled")
+ def test_a_provider_failing_on_a_lookup_is_a_row_finding_quoted_redacted(self, models_manager: Any) -> None:
+ """An external provider may raise anything on a lookup: the row reports it, scrubbed, instead of the doctor stopping."""
+ models_manager.setup.side_effect = ConnectionError(f"vault unreachable; request headers had Authorization: Bearer {VAULT_TOKEN}")
+
+ healthy, message, _ = check_models(secrets_provider=SECRETS_PROVIDER)
+
+ assert healthy is False
+ assert message.startswith("Error checking models: the setup failed on a ConnectionError: vault unreachable")
+ assert "Authorization: Bearer [REDACTED]" in message
+ assert VAULT_TOKEN not in message
+
+ @pytest.mark.usefixtures("healthy_backend_files", "gateway_disabled")
+ def test_a_credentials_error_quoting_the_providers_text_is_redacted_in_the_row(self, models_manager: Any) -> None:
+ """The loader copies a provider's not-found text into its own error, so the row scrubs a Pipelex error too."""
+ models_manager.setup.side_effect = InferenceBackendCredentialsError(
+ credentials_error_type=InferenceBackendCredentialsErrorType.VAR_NOT_FOUND,
+ backend_name="openai",
+ key_name="api_key",
+ message=f"Could not get variable 'OPENAI_API_KEY': vault said no to Authorization: Bearer {VAULT_TOKEN}",
+ )
+
+ healthy, message, _ = check_models(secrets_provider=SECRETS_PROVIDER)
+
+ assert healthy is False
+ assert "Authorization: Bearer [REDACTED]" in message
+ assert VAULT_TOKEN not in message
diff --git a/tests/unit/pipelex/cli/test_doctor_cmd.py b/tests/unit/pipelex/cli/test_doctor_cmd.py
index 8e31073e1..9ccb2be8b 100644
--- a/tests/unit/pipelex/cli/test_doctor_cmd.py
+++ b/tests/unit/pipelex/cli/test_doctor_cmd.py
@@ -17,6 +17,7 @@ from pipelex.cli.commands.doctor_cmd import (
PendingMigrationsCheck,
PendingMigrationsFinding,
PluginsCheck,
+ SecretsProviderCheck,
TelemetryConfigCheck,
TelemetryConfigFinding,
check_backend_credentials,
@@ -26,6 +27,7 @@ from pipelex.cli.commands.doctor_cmd import (
from pipelex.cogt.models.deck_manifest import DeckSyncReport
from pipelex.system.configuration.config_loader import ConfigLoader
from pipelex.system.telemetry.telemetry_config import TELEMETRY_CONFIG_FILE_NAME
+from pipelex.tools.secrets.env_secrets_provider import EnvSecretsProvider
# Minimal valid telemetry TOML — only [custom_posthog].mode is needed, rest defaults
TELEMETRY_OFF = '[custom_posthog]\nmode = "off"\n'
@@ -41,7 +43,14 @@ NO_PENDING_MIGRATIONS = PendingMigrationsCheck(
HEALTHY_LOG_SINK = LogSinkCheck(is_healthy=True, message="Log sink 'console' installed")
HEALTHY_PLUGINS = PluginsCheck(is_healthy=True, message="Plugins discovered and registered")
-HEALTHY_RUNTIME_SETUP = DoctorRuntimeSetup(log_sink=HEALTHY_LOG_SINK, plugins=HEALTHY_PLUGINS)
+HEALTHY_SECRETS_PROVIDER = SecretsProviderCheck(is_healthy=True, message="Secrets provider 'env' built")
+BUILT_SECRETS_PROVIDER = EnvSecretsProvider()
+HEALTHY_RUNTIME_SETUP = DoctorRuntimeSetup(
+ plugins=HEALTHY_PLUGINS,
+ secrets_provider=HEALTHY_SECRETS_PROVIDER,
+ log_sink=HEALTHY_LOG_SINK,
+ built_secrets_provider=BUILT_SECRETS_PROVIDER,
+)
class TestDoctorLayeredResolution:
@@ -109,7 +118,8 @@ class TestDoctorLayeredResolution:
mock_check_config.assert_called_once_with()
mock_check_telemetry.assert_called_once_with()
mock_check_backends.assert_called_once_with()
- mock_check_models.assert_called_once_with()
+ # The models row resolves the backends' credentials through the provider the bootstrap built.
+ mock_check_models.assert_called_once_with(secrets_provider=BUILT_SECRETS_PROVIDER)
mock_check_deck.assert_called_once_with()
mock_check_internal_backend.assert_called_once_with()
# The migration row takes no directory at all — it answers for `pipelex migrate`, which
diff --git a/tests/unit/pipelex/cli/test_doctor_display_report.py b/tests/unit/pipelex/cli/test_doctor_display_report.py
index aee750f31..519686841 100644
--- a/tests/unit/pipelex/cli/test_doctor_display_report.py
+++ b/tests/unit/pipelex/cli/test_doctor_display_report.py
@@ -14,6 +14,7 @@ from pipelex.cli.commands.doctor_cmd import (
PendingMigrationsCheck,
PendingMigrationsFinding,
PluginsCheck,
+ SecretsProviderCheck,
TelemetryConfigCheck,
TelemetryConfigFinding,
display_health_report,
@@ -130,6 +131,25 @@ class TestDoctorDisplayReport:
assert "Plugin 'storage' is required by core" in output
assert "plugin named in the Plugins row" in output
+ def test_a_secrets_provider_that_did_not_build_is_a_row_of_its_own_and_flags_the_report(self, console: Console) -> None:
+ kwargs = _healthy_report_kwargs()
+ kwargs["secrets_provider_check"] = SecretsProviderCheck(
+ is_healthy=False, message="The secrets provider 'vault' could not be built: the vault did not answer"
+ )
+
+ display_health_report(**kwargs)
+
+ output = console.export_text()
+ assert "Overall Status: ⚠️ Issues Found" in output
+ assert "Secrets Provider" in output
+ assert "the vault did not answer" in output
+ assert "Set method in [runtime.secrets] to a registered secrets provider" in output
+
+ def test_without_a_runtime_setup_there_is_no_secrets_provider_row(self, console: Console) -> None:
+ display_health_report(**_healthy_report_kwargs())
+
+ assert "Secrets Provider" not in console.export_text()
+
def test_without_a_plugin_discovery_there_is_no_plugins_row(self, console: Console) -> None:
display_health_report(**_healthy_report_kwargs())
diff --git a/tests/unit/pipelex/cli/test_doctor_log_sink.py b/tests/unit/pipelex/cli/test_doctor_log_sink.py
index e3ab51da9..d0a1385fc 100644
--- a/tests/unit/pipelex/cli/test_doctor_log_sink.py
+++ b/tests/unit/pipelex/cli/test_doctor_log_sink.py
@@ -1,50 +1,45 @@
"""The doctor installs the configured log sink, or the console sink on stderr with a finding when it cannot.
-Boot stops on an unregistered token, on a sink that fails to install and on a plugin registry that does
-not build. The doctor exists to diagnose exactly that kind of misconfiguration, so it must not die on
-where its own lines go: the rows say what was set and what stopped it. Once the report is out, the
-doctor releases the logging it configured, and only that.
+Boot stops on an unregistered token, on a sink that fails to install, on a sink setting naming a variable
+that does not resolve and on a plugin registry that does not build. The doctor exists to diagnose exactly
+that kind of misconfiguration, so it must not die on where its own lines go: the row says what was set and
+what stopped it, quoting a failure redacted, since a row reaches the reader without passing through any
+sink. Once the report is out, the doctor releases the logging it configured, and only that.
"""
from __future__ import annotations
import logging
-import sys
-from typing import TYPE_CHECKING, Any
+from types import SimpleNamespace
+from typing import TYPE_CHECKING, Any, cast
import pytest
-from rich.logging import RichHandler
from typing_extensions import override
from pipelex.cli.commands import doctor_cmd
-from pipelex.cli.commands.doctor_cmd import FALLBACK_LOG_SINK_NOTE, discover_plugins_and_install_doctor_log_sink, install_doctor_log_sink
+from pipelex.cli.commands.doctor_cmd import FALLBACK_LOG_SINK_NOTE, discover_doctor_runtime, install_doctor_log_sink
+from pipelex.plugins.discovery import build_registrar
from pipelex.plugins.exceptions import CoreUnconditionalPluginDisabledError
from pipelex.plugins.log_sink_registry import LogSinkRegistry
-from pipelex.system.configuration.config_loader import ConfigLoader
+from pipelex.providers.builtins import KERNEL_BUILTIN_PLUGINS, KERNEL_CORE_UNCONDITIONAL_PLUGIN_NAMES, KERNEL_ENTRY_POINT_GROUPS
from pipelex.system.console_target import ConsoleTarget
from pipelex.tools.log.console_log_sink import ConsoleLogSink
from pipelex.tools.log.log import log
-from pipelex.tools.log.log_config import LogConfig
from pipelex.tools.log.log_sink import LogSink, LogSinkMethod
-from pipelex.tools.misc.toml_utils import load_toml_from_path
+from pipelex.tools.secrets.env_secrets_provider import EnvSecretsProvider
+from tests.helpers.doctor_log_sink import NullLogSink, assert_the_fallback_console_sink_is_installed_on_stderr, doctor_log_config
if TYPE_CHECKING:
from collections.abc import Iterator
from pytest_mock import MockerFixture
+ from pipelex.system.configuration.configs import PipelexConfig
+ from pipelex.tools.log.log_config import LogConfig
+ from pipelex.tools.secrets.secrets_provider_abstract import SecretsProviderAbstract
-def _log_config(*, sink: str, console_log_target: ConsoleTarget = ConsoleTarget.STDERR) -> LogConfig:
- config_dict = load_toml_from_path(ConfigLoader().pipelex_root_dir / "pipelex.toml")
- return LogConfig.model_validate({**config_dict["runtime"]["log"], "sink": sink, "console_log_target": console_log_target})
-
-def _assert_the_fallback_console_sink_is_installed_on_stderr() -> None:
- sink = log.sink
- assert isinstance(sink, ConsoleLogSink)
- handler = sink.handler
- assert isinstance(handler, RichHandler)
- assert handler.console.file is sys.stderr
+COLLECTOR_TOKEN = "collector-token-0123456789abcdef"
class _NamedSink(LogSink):
@@ -57,12 +52,6 @@ class _NamedSink(LogSink):
raise NotImplementedError
-class _NullSink(LogSink):
- @override
- def make_handler(self) -> logging.Handler:
- return logging.NullHandler()
-
-
class _UnrecoverableHandler(logging.Handler):
"""Cannot render a record, and cannot say so either: the shape a closed stderr gives a handler at its ``handleError``."""
@@ -85,13 +74,29 @@ class _FailsOnReplaySink(LogSink):
return _UnrecoverableHandler()
+def _make_named_console_sink(_config: LogConfig, /, *, secrets_provider: SecretsProviderAbstract) -> LogSink: # ruff: ignore[unused-function-argument] - the LogSinkFactoryFn shape
+ return _NamedSink(name=LogSinkMethod.CONSOLE)
+
+
+def _make_named_json_sink(_config: LogConfig, /, *, secrets_provider: SecretsProviderAbstract) -> LogSink: # ruff: ignore[unused-function-argument] - the LogSinkFactoryFn shape
+ return _NamedSink(name=LogSinkMethod.JSON)
+
+
+def _make_console_sink_from_config(config: LogConfig, /, *, secrets_provider: SecretsProviderAbstract) -> LogSink: # ruff: ignore[unused-function-argument] - the LogSinkFactoryFn shape
+ return ConsoleLogSink(rich_log_config=config.rich_log, target=config.console_log_target)
+
+
+def _make_fails_on_replay_sink(_config: LogConfig, /, *, secrets_provider: SecretsProviderAbstract) -> LogSink: # ruff: ignore[unused-function-argument] - the LogSinkFactoryFn shape
+ return _FailsOnReplaySink()
+
+
+def _make_sink_failing_with_its_token(_config: LogConfig, /, *, secrets_provider: SecretsProviderAbstract) -> LogSink: # ruff: ignore[unused-function-argument] - the LogSinkFactoryFn shape
+ msg = f"the collector refused the exporter built with Authorization: Bearer {COLLECTOR_TOKEN}"
+ raise ConnectionError(msg)
+
+
def _registry() -> LogSinkRegistry:
- return LogSinkRegistry(
- {
- LogSinkMethod.CONSOLE: lambda _config: _NamedSink(name=LogSinkMethod.CONSOLE),
- LogSinkMethod.JSON: lambda _config: _NamedSink(name=LogSinkMethod.JSON),
- }
- )
+ return LogSinkRegistry({LogSinkMethod.CONSOLE: _make_named_console_sink, LogSinkMethod.JSON: _make_named_json_sink})
class TestDoctorLogSink:
@@ -106,13 +111,13 @@ class TestDoctorLogSink:
@pytest.mark.usefixtures("released_log")
def test_the_doctor_releases_the_logging_it_configured_once_the_report_is_out(self, mocker: MockerFixture) -> None:
- sink = _NullSink()
+ sink = NullLogSink()
# The handler the install put on the root logger, captured while it is there: the release discards
# it, and ``sink.handler`` read afterwards builds a new one that could never be on the root.
installed: list[logging.Handler] = []
def report_through_a_sink(**_options: Any) -> None:
- log.configure(log_config=_log_config(sink=LogSinkMethod.CONSOLE))
+ log.configure(log_config=doctor_log_config(sink=LogSinkMethod.CONSOLE))
log.install_sink(sink)
assert log.sink is sink
installed.append(sink.handler)
@@ -128,8 +133,8 @@ class TestDoctorLogSink:
@pytest.mark.usefixtures("released_log")
def test_the_doctor_leaves_logging_an_embedder_configured_before_calling_in(self, mocker: MockerFixture) -> None:
- sink = _NullSink()
- log.configure(log_config=_log_config(sink=LogSinkMethod.CONSOLE))
+ sink = NullLogSink()
+ log.configure(log_config=doctor_log_config(sink=LogSinkMethod.CONSOLE))
log.install_sink(sink)
mocker.patch.object(doctor_cmd, "do_doctor_cmd")
@@ -142,7 +147,9 @@ class TestDoctorLogSink:
def test_a_registered_token_installs_that_sink_and_the_row_is_healthy(self, mocker: MockerFixture) -> None:
install_sink = mocker.patch.object(doctor_cmd.log, "install_sink")
- check = install_doctor_log_sink(registry=_registry(), log_config=_log_config(sink=LogSinkMethod.JSON))
+ check = install_doctor_log_sink(
+ registry=_registry(), log_config=doctor_log_config(sink=LogSinkMethod.JSON), secrets_provider=EnvSecretsProvider()
+ )
assert check.is_healthy
assert LogSinkMethod.JSON in check.message
@@ -154,7 +161,7 @@ class TestDoctorLogSink:
def test_an_unregistered_token_installs_the_console_sink_and_names_the_registered_ones(self, mocker: MockerFixture) -> None:
install_sink = mocker.patch.object(doctor_cmd.log, "install_sink")
- check = install_doctor_log_sink(registry=_registry(), log_config=_log_config(sink="jsn"))
+ check = install_doctor_log_sink(registry=_registry(), log_config=doctor_log_config(sink="jsn"), secrets_provider=EnvSecretsProvider())
assert not check.is_healthy
assert "'jsn'" in check.message
@@ -165,28 +172,39 @@ class TestDoctorLogSink:
@pytest.mark.usefixtures("released_log")
def test_a_sink_that_fails_to_install_on_this_config_is_a_row_and_the_report_goes_on_through_stderr(self) -> None:
"""The shipped default, the console sink, on a console target no sink writes to: the fallback cannot read the same field."""
- log_config = _log_config(sink=LogSinkMethod.CONSOLE, console_log_target=ConsoleTarget.FILE)
+ log_config = doctor_log_config(sink=LogSinkMethod.CONSOLE, console_log_target=ConsoleTarget.FILE)
log.configure(log_config=log_config)
- registry = LogSinkRegistry(
- {LogSinkMethod.CONSOLE: lambda config: ConsoleLogSink(rich_log_config=config.rich_log, target=config.console_log_target)}
- )
+ registry = LogSinkRegistry({LogSinkMethod.CONSOLE: _make_console_sink_from_config})
- check = install_doctor_log_sink(registry=registry, log_config=log_config)
+ check = install_doctor_log_sink(registry=registry, log_config=log_config, secrets_provider=EnvSecretsProvider())
assert not check.is_healthy
assert "could not be installed" in check.message
assert "choose stdout or stderr" in check.message
- _assert_the_fallback_console_sink_is_installed_on_stderr()
+ assert_the_fallback_console_sink_is_installed_on_stderr()
+
+ @pytest.mark.usefixtures("released_log")
+ def test_a_sink_failure_quoting_a_token_is_redacted_in_the_row(self) -> None:
+ log_config = doctor_log_config(sink=LogSinkMethod.JSON)
+ log.configure(log_config=log_config)
+ registry = LogSinkRegistry({LogSinkMethod.JSON: _make_sink_failing_with_its_token})
+
+ check = install_doctor_log_sink(registry=registry, log_config=log_config, secrets_provider=EnvSecretsProvider())
+
+ assert not check.is_healthy
+ assert "the collector refused the exporter built with Authorization: Bearer [REDACTED]" in check.message
+ assert COLLECTOR_TOKEN not in check.message
+ assert_the_fallback_console_sink_is_installed_on_stderr()
@pytest.mark.usefixtures("released_log")
def test_a_sink_that_failed_after_being_recorded_is_a_row_and_the_installed_sink_is_kept(self) -> None:
"""The failure comes out of the replay, past the point where the sink was recorded, so there is nothing for a fallback to install."""
- log_config = _log_config(sink=LogSinkMethod.JSON)
+ log_config = doctor_log_config(sink=LogSinkMethod.JSON)
log.configure(log_config=log_config)
log.warning("a record held until the sink arrives")
- registry = LogSinkRegistry({LogSinkMethod.JSON: lambda _config: _FailsOnReplaySink()})
+ registry = LogSinkRegistry({LogSinkMethod.JSON: _make_fails_on_replay_sink})
- check = install_doctor_log_sink(registry=registry, log_config=log_config)
+ check = install_doctor_log_sink(registry=registry, log_config=log_config, secrets_provider=EnvSecretsProvider())
assert not check.is_healthy
assert "stderr is closed" in check.message
@@ -194,19 +212,21 @@ class TestDoctorLogSink:
@pytest.mark.usefixtures("released_log")
def test_a_plugin_registry_that_does_not_build_is_a_row_and_the_report_goes_on_through_stderr(self, mocker: MockerFixture) -> None:
- log_config = _log_config(sink=LogSinkMethod.JSON)
+ log_config = doctor_log_config(sink=LogSinkMethod.JSON)
log.configure(log_config=log_config)
mocker.patch.object(doctor_cmd, "get_config")
mocker.patch.object(doctor_cmd, "build_registrar", side_effect=CoreUnconditionalPluginDisabledError(plugin_name="storage"))
- runtime_setup = discover_plugins_and_install_doctor_log_sink(log_config=log_config)
+ runtime_setup = discover_doctor_runtime(log_config=log_config, installs_log_sink=True)
- assert runtime_setup.plugins is not None
assert not runtime_setup.plugins.is_healthy
assert "'storage'" in runtime_setup.plugins.message
+ assert not runtime_setup.secrets_provider.is_healthy
+ assert "registry did not build" in runtime_setup.secrets_provider.message
+ assert runtime_setup.built_secrets_provider is None
assert not runtime_setup.log_sink.is_healthy
assert "registry did not build" in runtime_setup.log_sink.message
- _assert_the_fallback_console_sink_is_installed_on_stderr()
+ assert_the_fallback_console_sink_is_installed_on_stderr()
@pytest.mark.usefixtures("released_log")
def test_a_fallback_refused_because_a_sink_is_already_recorded_says_so_and_keeps_that_sink(self) -> None:
@@ -215,15 +235,42 @@ class TestDoctorLogSink:
installation left nothing behind: installing on top would raise in place of the failure it was called to report, and
a row promising the console fallback would name a sink that never stood in.
"""
- log_config = _log_config(sink=LogSinkMethod.JSON)
+ log_config = doctor_log_config(sink=LogSinkMethod.JSON)
log.configure(log_config=log_config)
- already_recorded = _NullSink()
+ already_recorded = NullLogSink()
log.install_sink(already_recorded)
- check = install_doctor_log_sink(registry=None, log_config=log_config)
+ check = install_doctor_log_sink(registry=None, log_config=log_config, secrets_provider=EnvSecretsProvider())
assert not check.is_healthy
assert "registry did not build" in check.message
assert "already recorded" in check.message
assert FALLBACK_LOG_SINK_NOTE not in check.message
assert log.sink is already_recorded
+
+ @pytest.mark.usefixtures("released_log")
+ def test_a_sink_header_naming_a_variable_that_does_not_resolve_is_a_row_naming_it(
+ self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ monkeypatch.delenv("PIPELEX_TEST_UNSET_COLLECTOR_TOKEN", raising=False)
+ mocker.patch("pipelex.plugins.discovery._external_entry_points", return_value=[])
+ registrar = build_registrar(
+ config=cast("PipelexConfig", SimpleNamespace(runtime=SimpleNamespace(plugins=SimpleNamespace(disabled=[])))),
+ boot_orchestrator=None,
+ builtin_plugins=KERNEL_BUILTIN_PLUGINS,
+ core_unconditional_plugin_names=KERNEL_CORE_UNCONDITIONAL_PLUGIN_NAMES,
+ entry_point_groups=KERNEL_ENTRY_POINT_GROUPS,
+ )
+ log_config = doctor_log_config(sink=LogSinkMethod.OTLP)
+ log_config = log_config.model_copy(
+ update={"otlp": log_config.otlp.model_copy(update={"headers": {"Authorization": "Bearer ${PIPELEX_TEST_UNSET_COLLECTOR_TOKEN}"}})}
+ )
+ log.configure(log_config=log_config)
+
+ check = install_doctor_log_sink(registry=LogSinkRegistry(registrar.log_sinks), log_config=log_config, secrets_provider=EnvSecretsProvider())
+
+ assert not check.is_healthy
+ assert "`headers.Authorization` under [runtime.log.otlp]" in check.message
+ assert "PIPELEX_TEST_UNSET_COLLECTOR_TOKEN" in check.message
+ assert FALLBACK_LOG_SINK_NOTE in check.message
+ assert_the_fallback_console_sink_is_installed_on_stderr()
diff --git a/tests/unit/pipelex/cli/test_doctor_secrets_provider.py b/tests/unit/pipelex/cli/test_doctor_secrets_provider.py
new file mode 100644
index 000000000..9bff6dca3
--- /dev/null
+++ b/tests/unit/pipelex/cli/test_doctor_secrets_provider.py
@@ -0,0 +1,201 @@
+"""The doctor builds the configured secrets provider before the log sink, as boot does, or says in a row what stopped it.
+
+The provider is handed to the sink, and it is built even when logging was configured before the doctor
+ran, since the models row resolves the backends' credentials through it. A factory that fails is quoted
+redacted, with the shipped patterns and the configured ones, since a row reaches the console and the
+agent's JSON without passing through any sink.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from typing import TYPE_CHECKING, cast
+
+import pytest
+
+from pipelex.cli.commands import doctor_cmd
+from pipelex.cli.commands.doctor_cmd import discover_doctor_runtime
+from pipelex.plugins.contract import PLUGIN_API_VERSION
+from pipelex.plugins.registrar import PluginOrigin, PluginRegistrar
+from pipelex.tools.log.log import log
+from pipelex.tools.log.log_sink import LogSink, LogSinkMethod
+from pipelex.tools.secrets.env_secrets_provider import EnvSecretsProvider
+from pipelex.tools.secrets.secrets_config import SecretsProviderConfig
+from tests.helpers.doctor_log_sink import NullLogSink, assert_the_fallback_console_sink_is_installed_on_stderr, doctor_log_config
+
+if TYPE_CHECKING:
+ from collections.abc import Iterator
+
+ from pytest_mock import MockerFixture
+
+ from pipelex.plugins.log_sink_registry import LogSinkFactoryFn
+ from pipelex.plugins.secrets_provider_registry import SecretsProviderFactoryFn
+ from pipelex.system.configuration.configs import PipelexConfig
+ from pipelex.tools.log.log_config import LogConfig
+ from pipelex.tools.secrets.secrets_provider_abstract import SecretsProviderAbstract
+
+EXTERNAL_SECRETS_METHOD = "vault"
+VAULT_TOKEN = "hvs-0123456789abcdef0123"
+VAULT_SESSION = "vault-session-0123456789ab"
+VAULT_SESSION_PATTERN = r"vault-session-[0-9a-f]{12}"
+
+
+class _VaultSecretsProvider(EnvSecretsProvider):
+ """The provider an external ``vault`` method builds; only its identity matters here."""
+
+
+class _SinkFactoryRecorder:
+ """A ``json`` sink factory that records the provider it was handed."""
+
+ def __init__(self) -> None:
+ self.handed: list[SecretsProviderAbstract] = []
+
+ def __call__(self, _config: LogConfig, /, *, secrets_provider: SecretsProviderAbstract) -> LogSink:
+ self.handed.append(secrets_provider)
+ return NullLogSink()
+
+
+def _make_vault_secrets_provider(_config: SecretsProviderConfig) -> SecretsProviderAbstract:
+ return _VaultSecretsProvider()
+
+
+def _make_unreachable_vault_secrets_provider(_config: SecretsProviderConfig) -> SecretsProviderAbstract:
+ msg = "the vault at vault.internal:8200 did not answer"
+ raise ConnectionError(msg)
+
+
+def _make_vault_secrets_provider_quoting_its_token(_config: SecretsProviderConfig) -> SecretsProviderAbstract:
+ msg = f"the vault refused the request sent with Authorization: Bearer {VAULT_TOKEN}"
+ raise ConnectionError(msg)
+
+
+def _make_vault_secrets_provider_quoting_its_session(_config: SecretsProviderConfig) -> SecretsProviderAbstract:
+ msg = f"the vault session {VAULT_SESSION} has expired"
+ raise ConnectionError(msg)
+
+
+def _registrar(*, secrets_factory: SecretsProviderFactoryFn | None, sink_factory: LogSinkFactoryFn) -> PluginRegistrar:
+ """A registrar holding one ``json`` sink and, when given, the external ``vault`` secrets method."""
+ registrar = PluginRegistrar(config=cast("PipelexConfig", SimpleNamespace(runtime=SimpleNamespace(plugins=SimpleNamespace(disabled=[])))))
+ registrar.begin_plugin(name="test_vault", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)
+ if secrets_factory is not None:
+ registrar.add_secrets_provider(method=EXTERNAL_SECRETS_METHOD, factory=secrets_factory)
+ registrar.add_log_sink(method=LogSinkMethod.JSON, factory=sink_factory)
+ return registrar
+
+
+def _select_vault_secrets(mocker: MockerFixture) -> None:
+ secrets_config = SecretsProviderConfig(method=EXTERNAL_SECRETS_METHOD)
+ mocker.patch.object(doctor_cmd, "get_config", return_value=SimpleNamespace(runtime=SimpleNamespace(secrets=secrets_config)))
+
+
+class TestDoctorSecretsProvider:
+ @pytest.fixture
+ def released_log(self) -> Iterator[None]:
+ log.reset()
+ try:
+ yield
+ finally:
+ log.reset()
+
+ @pytest.mark.usefixtures("released_log")
+ def test_the_configured_secrets_provider_is_built_first_and_handed_to_the_sink(self, mocker: MockerFixture) -> None:
+ log_config = doctor_log_config(sink=LogSinkMethod.JSON)
+ log.configure(log_config=log_config)
+ _select_vault_secrets(mocker)
+ sink_factory = _SinkFactoryRecorder()
+ registrar = _registrar(secrets_factory=_make_vault_secrets_provider, sink_factory=sink_factory)
+ mocker.patch.object(doctor_cmd, "build_doctor_registrar", return_value=registrar)
+
+ runtime_setup = discover_doctor_runtime(log_config=log_config, installs_log_sink=True)
+
+ assert runtime_setup.secrets_provider.is_healthy
+ assert f"'{EXTERNAL_SECRETS_METHOD}'" in runtime_setup.secrets_provider.message
+ assert isinstance(runtime_setup.built_secrets_provider, _VaultSecretsProvider)
+ assert sink_factory.handed == [runtime_setup.built_secrets_provider]
+ assert runtime_setup.log_sink.is_healthy
+
+ @pytest.mark.usefixtures("released_log")
+ def test_a_secrets_provider_that_fails_to_build_is_a_row_the_sink_is_not_checked_and_the_report_goes_on_through_stderr(
+ self, mocker: MockerFixture
+ ) -> None:
+ log_config = doctor_log_config(sink=LogSinkMethod.JSON)
+ log.configure(log_config=log_config)
+ _select_vault_secrets(mocker)
+ sink_factory = _SinkFactoryRecorder()
+ registrar = _registrar(secrets_factory=_make_unreachable_vault_secrets_provider, sink_factory=sink_factory)
+ mocker.patch.object(doctor_cmd, "build_doctor_registrar", return_value=registrar)
+
+ runtime_setup = discover_doctor_runtime(log_config=log_config, installs_log_sink=True)
+
+ assert runtime_setup.plugins.is_healthy
+ assert not runtime_setup.secrets_provider.is_healthy
+ assert "could not be built" in runtime_setup.secrets_provider.message
+ assert "did not answer" in runtime_setup.secrets_provider.message
+ assert runtime_setup.built_secrets_provider is None
+ assert not runtime_setup.log_sink.is_healthy
+ assert "not checked because the secrets provider did not build" in runtime_setup.log_sink.message
+ assert sink_factory.handed == []
+ assert_the_fallback_console_sink_is_installed_on_stderr()
+
+ @pytest.mark.usefixtures("released_log")
+ def test_a_secrets_method_nobody_registered_is_a_row_naming_the_registered_ones(self, mocker: MockerFixture) -> None:
+ log_config = doctor_log_config(sink=LogSinkMethod.JSON)
+ log.configure(log_config=log_config)
+ _select_vault_secrets(mocker)
+ mocker.patch.object(doctor_cmd, "build_doctor_registrar", return_value=_registrar(secrets_factory=None, sink_factory=_SinkFactoryRecorder()))
+
+ runtime_setup = discover_doctor_runtime(log_config=log_config, installs_log_sink=True)
+
+ assert not runtime_setup.secrets_provider.is_healthy
+ assert f"No secrets provider is registered for '{EXTERNAL_SECRETS_METHOD}' in [runtime.secrets]" in runtime_setup.secrets_provider.message
+ assert runtime_setup.built_secrets_provider is None
+
+ @pytest.mark.usefixtures("released_log")
+ def test_logging_configured_before_the_doctor_keeps_its_sink_and_the_provider_is_still_built(self, mocker: MockerFixture) -> None:
+ log_config = doctor_log_config(sink=LogSinkMethod.JSON)
+ log.configure(log_config=log_config)
+ already_installed = NullLogSink()
+ log.install_sink(already_installed)
+ _select_vault_secrets(mocker)
+ sink_factory = _SinkFactoryRecorder()
+ mocker.patch.object(
+ doctor_cmd, "build_doctor_registrar", return_value=_registrar(secrets_factory=_make_vault_secrets_provider, sink_factory=sink_factory)
+ )
+
+ runtime_setup = discover_doctor_runtime(log_config=log_config, installs_log_sink=False)
+
+ assert isinstance(runtime_setup.built_secrets_provider, _VaultSecretsProvider)
+ assert runtime_setup.secrets_provider.is_healthy
+ assert runtime_setup.log_sink.is_healthy
+ assert "already configured" in runtime_setup.log_sink.message
+ assert sink_factory.handed == []
+ assert log.sink is already_installed
+
+ @pytest.mark.usefixtures("released_log")
+ def test_a_factory_failure_quoting_a_token_is_redacted_in_the_row(self, mocker: MockerFixture) -> None:
+ log_config = doctor_log_config(sink=LogSinkMethod.JSON)
+ log.configure(log_config=log_config)
+ _select_vault_secrets(mocker)
+ registrar = _registrar(secrets_factory=_make_vault_secrets_provider_quoting_its_token, sink_factory=_SinkFactoryRecorder())
+ mocker.patch.object(doctor_cmd, "build_doctor_registrar", return_value=registrar)
+
+ runtime_setup = discover_doctor_runtime(log_config=log_config, installs_log_sink=True)
+
+ assert not runtime_setup.secrets_provider.is_healthy
+ assert "the vault refused the request sent with Authorization: Bearer [REDACTED]" in runtime_setup.secrets_provider.message
+ assert VAULT_TOKEN not in runtime_setup.secrets_provider.message
+
+ @pytest.mark.usefixtures("released_log")
+ def test_a_configured_extra_pattern_redacts_the_factory_failure_too(self, mocker: MockerFixture) -> None:
+ shipped = doctor_log_config(sink=LogSinkMethod.JSON)
+ log_config = shipped.model_copy(update={"redaction": shipped.redaction.model_copy(update={"extra_patterns": [VAULT_SESSION_PATTERN]})})
+ log.configure(log_config=log_config)
+ _select_vault_secrets(mocker)
+ registrar = _registrar(secrets_factory=_make_vault_secrets_provider_quoting_its_session, sink_factory=_SinkFactoryRecorder())
+ mocker.patch.object(doctor_cmd, "build_doctor_registrar", return_value=registrar)
+
+ runtime_setup = discover_doctor_runtime(log_config=log_config, installs_log_sink=True)
+
+ assert "the vault session [REDACTED] has expired" in runtime_setup.secrets_provider.message
+ assert VAULT_SESSION not in runtime_setup.secrets_provider.message
diff --git a/tests/unit/pipelex/cli/test_format_doctor_markdown.py b/tests/unit/pipelex/cli/test_format_doctor_markdown.py
index 15ca169b5..14dd43f8f 100644
--- a/tests/unit/pipelex/cli/test_format_doctor_markdown.py
+++ b/tests/unit/pipelex/cli/test_format_doctor_markdown.py
@@ -106,6 +106,18 @@ class TestFormatDoctorMarkdown:
assert "The plugin registry did not build" in _format_doctor_markdown(with_plugins)
assert "## Plugins" not in _format_doctor_markdown(self._HEALTHY_RESULT)
+ def test_secrets_provider_section_renders_only_when_the_check_ran(self) -> None:
+ with_secrets: dict[str, Any] = {
+ **self._HEALTHY_RESULT,
+ "checks": {
+ **self._HEALTHY_RESULT["checks"],
+ "secrets_provider": {"healthy": False, "message": "The secrets provider 'vault' could not be built"},
+ },
+ }
+ assert "## Secrets Provider" in _format_doctor_markdown(with_secrets)
+ assert "The secrets provider 'vault' could not be built" in _format_doctor_markdown(with_secrets)
+ assert "## Secrets Provider" not in _format_doctor_markdown(self._HEALTHY_RESULT)
+
def test_healthy_output_has_no_recommended_actions(self) -> None:
"""Healthy result should not include a Recommended Actions section."""
output = _format_doctor_markdown(self._HEALTHY_RESULT)
diff --git a/tests/unit/pipelex/plugins/test_log_sink_registry.py b/tests/unit/pipelex/plugins/test_log_sink_registry.py
index 7216b7c6b..65b7d2c55 100644
--- a/tests/unit/pipelex/plugins/test_log_sink_registry.py
+++ b/tests/unit/pipelex/plugins/test_log_sink_registry.py
@@ -28,6 +28,7 @@ if TYPE_CHECKING:
from pipelex.system.configuration.configs import PipelexConfig
from pipelex.tools.log.log_config import LogConfig
+ from pipelex.tools.secrets.secrets_provider_abstract import SecretsProviderAbstract
def _fake_config() -> PipelexConfig:
@@ -44,7 +45,7 @@ class _NullLogSink(LogSink):
return logging.NullHandler()
-def _fake_factory(_config: LogConfig) -> LogSink:
+def _fake_factory(_config: LogConfig, /, *, secrets_provider: SecretsProviderAbstract) -> LogSink: # ruff: ignore[unused-function-argument] - the LogSinkFactoryFn shape
"""Stand-in factory: identity is all the registry tests assert (never actually invoked here)."""
return _NullLogSink()
diff --git a/tests/unit/pipelex/providers/log_sinks/test_gcp_credentials_file_path_variable.py b/tests/unit/pipelex/providers/log_sinks/test_gcp_credentials_file_path_variable.py
new file mode 100644
index 000000000..afb231013
--- /dev/null
+++ b/tests/unit/pipelex/providers/log_sinks/test_gcp_credentials_file_path_variable.py
@@ -0,0 +1,88 @@
+"""The built-in ``gcp`` sink factory resolves a ``${…}`` placeholder in ``credentials_file_path`` through the secrets provider it receives.
+
+The resolved path goes to ``make_gcp_log_sink`` with the placeholder it came from, so the credential errors
+can name both. A plain path is handed over as written, an unset one stays unset for Application Default
+Credentials, and a variable that does not resolve stops the boot with ``LogSinkVariableError`` naming it.
+The settings the factory was handed keep their placeholder.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import pytest
+
+from pipelex.tools.log.exceptions import LogSinkVariableError
+from pipelex.tools.log.log_sink import LogSinkMethod
+from tests.helpers.log_sink_variables import DictSecretsProvider, builtin_log_sink_factory, sink_settings_log_config
+
+if TYPE_CHECKING:
+ from pytest_mock import MockerFixture
+
+KEY_PATH = "/run/secrets/gcp-logging-key.json"
+
+
+class TestGcpCredentialsFilePathVariable:
+ @pytest.fixture
+ def made_gcp_sinks(self, mocker: MockerFixture) -> list[dict[str, Any]]:
+ """What the factory handed ``make_gcp_log_sink``, one entry per call, with no client library involved."""
+ calls: list[dict[str, Any]] = []
+
+ def record(**kwargs: Any) -> object:
+ calls.append(kwargs)
+ return object()
+
+ mocker.patch("pipelex.providers.log_sinks.log_sink_plugin.make_gcp_log_sink", side_effect=record)
+ return calls
+
+ @pytest.mark.parametrize("spelling", ["${GCP_CREDENTIALS_FILE_PATH}", "${secret:GCP_CREDENTIALS_FILE_PATH}"])
+ def test_the_key_path_is_resolved_through_the_secrets_provider(
+ self, mocker: MockerFixture, made_gcp_sinks: list[dict[str, Any]], spelling: str
+ ) -> None:
+ factory = builtin_log_sink_factory(method=LogSinkMethod.GCP, mocker=mocker)
+ log_config = sink_settings_log_config(gcp_credentials_file_path=spelling)
+
+ factory(log_config, secrets_provider=DictSecretsProvider(secrets={"GCP_CREDENTIALS_FILE_PATH": KEY_PATH}))
+
+ (call,) = made_gcp_sinks
+ assert call["config"].credentials_file_path == KEY_PATH
+ assert call["credentials_file_path_placeholder"] == spelling
+ assert log_config.gcp.credentials_file_path == spelling
+
+ def test_a_plain_key_path_is_handed_over_as_written_with_no_placeholder(
+ self, mocker: MockerFixture, made_gcp_sinks: list[dict[str, Any]]
+ ) -> None:
+ factory = builtin_log_sink_factory(method=LogSinkMethod.GCP, mocker=mocker)
+
+ factory(sink_settings_log_config(gcp_credentials_file_path=KEY_PATH), secrets_provider=DictSecretsProvider(secrets={}))
+
+ (call,) = made_gcp_sinks
+ assert call["config"].credentials_file_path == KEY_PATH
+ assert call["credentials_file_path_placeholder"] is None
+
+ def test_an_unset_key_path_stays_unset_for_application_default_credentials(
+ self, mocker: MockerFixture, made_gcp_sinks: list[dict[str, Any]]
+ ) -> None:
+ factory = builtin_log_sink_factory(method=LogSinkMethod.GCP, mocker=mocker)
+
+ factory(sink_settings_log_config(gcp_credentials_file_path=None), secrets_provider=DictSecretsProvider(secrets={}))
+
+ (call,) = made_gcp_sinks
+ assert call["config"].credentials_file_path is None
+ assert call["credentials_file_path_placeholder"] is None
+
+ def test_a_key_path_variable_that_does_not_resolve_stops_the_boot_naming_it(
+ self, mocker: MockerFixture, made_gcp_sinks: list[dict[str, Any]]
+ ) -> None:
+ factory = builtin_log_sink_factory(method=LogSinkMethod.GCP, mocker=mocker)
+
+ with pytest.raises(LogSinkVariableError) as exc_info:
+ factory(
+ sink_settings_log_config(gcp_credentials_file_path="${GCP_CREDENTIALS_FILE_PATH}"), secrets_provider=DictSecretsProvider(secrets={})
+ )
+
+ message = str(exc_info.value)
+ assert "credentials_file_path" in message
+ assert "[runtime.log.gcp]" in message
+ assert "GCP_CREDENTIALS_FILE_PATH" in message
+ assert made_gcp_sinks == []
diff --git a/tests/unit/pipelex/providers/log_sinks/test_otlp_header_variables.py b/tests/unit/pipelex/providers/log_sinks/test_otlp_header_variables.py
new file mode 100644
index 000000000..2cc06db16
--- /dev/null
+++ b/tests/unit/pipelex/providers/log_sinks/test_otlp_header_variables.py
@@ -0,0 +1,158 @@
+"""The built-in ``otlp`` sink factory resolves the ``${…}`` placeholders in its header values through the secrets provider it receives.
+
+The values are read through ``substitute_vars``, the syntax the inference backends use: ``${X}`` and
+``${secret:X}`` ask the secrets provider, ``${env:X}`` the environment, ``${env:X|secret:Y}`` one then the
+other, and a partial value such as ``"Bearer ${X}"`` keeps its literal part. Header keys are never touched. A
+variable that does not resolve stops the boot with ``LogSinkVariableError``, naming the section, the key and
+the variable and never a value. A resolved value holding a line break, which no HTTP header can carry, stops
+the boot with ``LogSinkHeaderValueError``, naming the key and never the value. The settings the factory was
+handed keep their placeholders: only the exporter holds the resolved value.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar
+
+import pytest
+from opentelemetry.sdk._logs.export import InMemoryLogRecordExporter
+
+from pipelex.tools.log.exceptions import LogSinkHeaderValueError, LogSinkVariableError
+from pipelex.tools.log.log_sink import LogSinkMethod
+from pipelex.tools.log.otlp_log_sink import OtlpLogSink
+from tests.helpers.log_sink_variables import DictSecretsProvider, builtin_log_sink_factory, sink_settings_log_config
+
+if TYPE_CHECKING:
+ from collections.abc import Iterator
+
+ from pytest_mock import MockerFixture
+
+ from pipelex.plugins.log_sink_registry import LogSinkFactoryFn
+ from pipelex.tools.log.log_config import LogConfig
+ from pipelex.tools.secrets.secrets_provider_abstract import SecretsProviderAbstract
+
+OTLP_EXPORTER_PATH = "opentelemetry.exporter.otlp.proto.http._log_exporter.OTLPLogExporter"
+TOKEN = "a-collector-token-0123456789"
+
+
+class _RecordingOtlpExporter(InMemoryLogRecordExporter):
+ """Stands in for the OTLP HTTP exporter: records what it was built with, sends nothing."""
+
+ built: ClassVar[list[_RecordingOtlpExporter]] = []
+
+ def __init__(self, *, endpoint: str | None = None, headers: dict[str, str] | None = None, **_kwargs: Any) -> None:
+ super().__init__()
+ self.endpoint = endpoint
+ self.headers = headers
+ _RecordingOtlpExporter.built.append(self)
+
+
+class TestOtlpHeaderVariables:
+ @pytest.fixture
+ def otlp_factory(self, mocker: MockerFixture) -> Iterator[LogSinkFactoryFn]:
+ _RecordingOtlpExporter.built.clear()
+ mocker.patch(OTLP_EXPORTER_PATH, _RecordingOtlpExporter)
+ built_sinks: list[OtlpLogSink] = []
+ factory = builtin_log_sink_factory(method=LogSinkMethod.OTLP, mocker=mocker)
+
+ def build(config: LogConfig, /, *, secrets_provider: SecretsProviderAbstract) -> OtlpLogSink:
+ sink = factory(config, secrets_provider=secrets_provider)
+ assert isinstance(sink, OtlpLogSink)
+ built_sinks.append(sink)
+ return sink
+
+ yield build
+ for sink in built_sinks:
+ sink.logger_provider.shutdown()
+
+ def _exported_headers(self) -> dict[str, str] | None:
+ (exporter,) = _RecordingOtlpExporter.built
+ return exporter.headers
+
+ @pytest.mark.parametrize(
+ ("header_value", "expected"),
+ [
+ ("${OTLP_TOKEN}", TOKEN),
+ ("${secret:OTLP_TOKEN}", TOKEN),
+ ("Bearer ${OTLP_TOKEN}", f"Bearer {TOKEN}"),
+ ("${env:PIPELEX_TEST_UNSET_OTLP_TOKEN|secret:OTLP_TOKEN}", TOKEN),
+ ("a plain value", "a plain value"),
+ ],
+ )
+ def test_a_header_value_is_resolved_through_the_secrets_provider(
+ self, otlp_factory: LogSinkFactoryFn, monkeypatch: pytest.MonkeyPatch, header_value: str, expected: str
+ ) -> None:
+ monkeypatch.delenv("PIPELEX_TEST_UNSET_OTLP_TOKEN", raising=False)
+ provider = DictSecretsProvider(secrets={"OTLP_TOKEN": TOKEN})
+
+ otlp_factory(sink_settings_log_config(otlp_headers={"Authorization": header_value}), secrets_provider=provider)
+
+ assert self._exported_headers() == {"Authorization": expected}
+
+ def test_a_header_value_is_resolved_from_the_environment(self, otlp_factory: LogSinkFactoryFn, monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setenv("PIPELEX_TEST_OTLP_TOKEN", TOKEN)
+
+ otlp_factory(
+ sink_settings_log_config(otlp_headers={"Authorization": "Bearer ${env:PIPELEX_TEST_OTLP_TOKEN}"}),
+ secrets_provider=DictSecretsProvider(secrets={}),
+ )
+
+ assert self._exported_headers() == {"Authorization": f"Bearer {TOKEN}"}
+
+ def test_the_header_keys_are_left_alone(self, otlp_factory: LogSinkFactoryFn) -> None:
+ provider = DictSecretsProvider(secrets={"OTLP_TOKEN": TOKEN, "TENANT": "acme"})
+
+ otlp_factory(sink_settings_log_config(otlp_headers={"${TENANT}": "${OTLP_TOKEN}"}), secrets_provider=provider)
+
+ assert self._exported_headers() == {"${TENANT}": TOKEN}
+
+ def test_empty_headers_still_reach_the_exporter_as_none(self, otlp_factory: LogSinkFactoryFn) -> None:
+ otlp_factory(sink_settings_log_config(otlp_headers={}), secrets_provider=DictSecretsProvider(secrets={}))
+
+ assert self._exported_headers() is None
+
+ def test_the_settings_handed_to_the_factory_keep_their_placeholder(self, otlp_factory: LogSinkFactoryFn) -> None:
+ log_config = sink_settings_log_config(otlp_headers={"Authorization": "Bearer ${OTLP_TOKEN}"})
+
+ otlp_factory(log_config, secrets_provider=DictSecretsProvider(secrets={"OTLP_TOKEN": TOKEN}))
+
+ assert log_config.otlp.headers == {"Authorization": "Bearer ${OTLP_TOKEN}"}
+
+ @pytest.mark.parametrize(
+ ("header_value", "variable"),
+ [
+ ("Bearer ${OTLP_TOKEN}", "OTLP_TOKEN"),
+ ("${env:PIPELEX_TEST_UNSET_OTLP_TOKEN}", "PIPELEX_TEST_UNSET_OTLP_TOKEN"),
+ ("${env:PIPELEX_TEST_UNSET_OTLP_TOKEN|secret:OTLP_TOKEN}", "env:PIPELEX_TEST_UNSET_OTLP_TOKEN|secret:OTLP_TOKEN"),
+ ("${vault:OTLP_TOKEN}", "vault:OTLP_TOKEN"),
+ ],
+ )
+ def test_a_variable_that_does_not_resolve_stops_the_boot_naming_the_section_the_key_and_the_variable(
+ self, otlp_factory: LogSinkFactoryFn, monkeypatch: pytest.MonkeyPatch, header_value: str, variable: str
+ ) -> None:
+ monkeypatch.delenv("PIPELEX_TEST_UNSET_OTLP_TOKEN", raising=False)
+ provider = DictSecretsProvider(secrets={"UNRELATED": TOKEN})
+
+ with pytest.raises(LogSinkVariableError) as exc_info:
+ otlp_factory(sink_settings_log_config(otlp_headers={"Authorization": header_value, "X-Other": "${UNRELATED}"}), secrets_provider=provider)
+
+ message = str(exc_info.value)
+ assert "headers.Authorization" in message
+ assert "[runtime.log.otlp]" in message
+ assert variable in message
+ assert "'json' sink" in message
+ assert TOKEN not in message
+ assert _RecordingOtlpExporter.built == []
+
+ @pytest.mark.parametrize("secret", [f"{TOKEN}\n", f"{TOKEN}\r\n", f"{TOKEN}\rX-Injected: 1"])
+ def test_a_header_value_resolving_to_a_line_break_stops_the_boot_naming_the_key_alone(self, otlp_factory: LogSinkFactoryFn, secret: str) -> None:
+ provider = DictSecretsProvider(secrets={"OTLP_TOKEN": secret})
+
+ with pytest.raises(LogSinkHeaderValueError) as exc_info:
+ otlp_factory(sink_settings_log_config(otlp_headers={"Authorization": "Bearer ${OTLP_TOKEN}"}), secrets_provider=provider)
+
+ message = str(exc_info.value)
+ assert "headers.Authorization" in message
+ assert "[runtime.log.otlp]" in message
+ assert "line break" in message
+ assert TOKEN not in message
+ assert _RecordingOtlpExporter.built == []
diff --git a/tests/unit/pipelex/tools/test_log_gcp_sink_credentials.py b/tests/unit/pipelex/tools/test_log_gcp_sink_credentials.py
index 596fdc14f..fa8976b0e 100644
--- a/tests/unit/pipelex/tools/test_log_gcp_sink_credentials.py
+++ b/tests/unit/pipelex/tools/test_log_gcp_sink_credentials.py
@@ -459,6 +459,20 @@ class TestGcpLogSinkCredentials:
assert "'json' sink" in message
assert isinstance(exc_info.value.__cause__, failure_type)
+ def test_a_key_path_resolved_from_a_placeholder_is_named_with_the_placeholder_to_fix(self, tmp_path: Path) -> None:
+ """The path came from a secret, so the reader is told which variable to fix rather than to edit the TOML."""
+ key_path = tmp_path / "missing-key.json"
+
+ with pytest.raises(GcpLogSinkCredentialsError) as exc_info:
+ make_gcp_log_sink(
+ config=GcpLogSinkConfig(log_name="pipelex", project_id="a-test-project", credentials_file_path=str(key_path)),
+ credentials_file_path_placeholder="${GCP_CREDENTIALS_FILE_PATH}",
+ )
+
+ message = str(exc_info.value)
+ assert f"could not load the service-account key at '{key_path}' (resolved from '${{GCP_CREDENTIALS_FILE_PATH}}')" in message
+ assert "Point the variable that `credentials_file_path` in [runtime.log.gcp] names, '${GCP_CREDENTIALS_FILE_PATH}'" in message
+
def test_a_key_file_without_a_project_is_not_a_credentials_failure(
self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch, mocker: MockerFixture
) -> None: