Document and validate configured secrets bootstrap
This commit is contained in:
129
docs/config.md
129
docs/config.md
@@ -1019,7 +1019,7 @@ There are three separate tasks when working with credentials:
|
|||||||
| --- | --- |
|
| --- | --- |
|
||||||
| Read a credential from an environment variable | A typed `Secret` field whose YAML value is the variable's name |
|
| Read a credential from an environment variable | A typed `Secret` field whose YAML value is the variable's name |
|
||||||
| Hide a configuration value in inspection output | A `configkit:"secret"` tag or `Definition.Sensitive` |
|
| Hide a configuration value in inspection output | A `configkit:"secret"` tag or `Definition.Sensitive` |
|
||||||
| Populate environment variables from local files before loading | An explicit `LoadSecretsIntoEnvironment` call |
|
| Populate environment variables from local files before loading | An explicit [secrets bootstrap](#explicit-secrets-directory-bootstrap) call |
|
||||||
|
|
||||||
For example, YAML `api_key: DEMO_API_KEY` names an environment variable. Its
|
For example, YAML `api_key: DEMO_API_KEY` names an environment variable. Its
|
||||||
credential is available to trusted application code through `Secret.Value()`
|
credential is available to trusted application code through `Secret.Value()`
|
||||||
@@ -1051,8 +1051,8 @@ its effective source location for diagnostics. Each unique name is read with
|
|||||||
`os.LookupEnv` once per load. Validation can inspect the credential through the
|
`os.LookupEnv` once per load. Validation can inspect the credential through the
|
||||||
deliberately named `Value()` accessor and distinguish success with `IsResolved()`.
|
deliberately named `Value()` accessor and distinguish success with `IsResolved()`.
|
||||||
Later loads read the environment again, and cloned defaults are rebuilt from names
|
Later loads read the environment again, and cloned defaults are rebuilt from names
|
||||||
so a previously resolved result cannot retain a stale credential. `Load` never
|
so a previously resolved result cannot retain a stale credential. `Load` and
|
||||||
writes to the environment.
|
`LoadLayered` never write to the environment.
|
||||||
|
|
||||||
Credential bytes are held only in the per-load lookup state and the trusted returned
|
Credential bytes are held only in the per-load lookup state and the trusted returned
|
||||||
configuration, and are returned only by `Value`. Secret formatting uses a safe
|
configuration, and are returned only by `Value`. Secret formatting uses a safe
|
||||||
@@ -1078,17 +1078,80 @@ reference state without printing its value.
|
|||||||
|
|
||||||
## Explicit secrets-directory bootstrap
|
## Explicit secrets-directory bootstrap
|
||||||
|
|
||||||
If an application stores credentials in files, it can call this helper before
|
If an application stores credentials in files, it can explicitly bootstrap
|
||||||
loading configuration. A file named `DEMO_API_KEY` containing the dummy text
|
them before loading configuration. A file named `DEMO_API_KEY` containing the dummy text
|
||||||
`example-value` supplies environment variable `DEMO_API_KEY`. YAML can then
|
`example-value` supplies environment variable `DEMO_API_KEY`. YAML can then
|
||||||
refer to that variable with `api_key: DEMO_API_KEY`. Applications that already
|
refer to that variable with `api_key: DEMO_API_KEY`. Applications that already
|
||||||
receive environment variables do not need this file step.
|
receive environment variables do not need this file step.
|
||||||
|
|
||||||
Existing environment variables take priority over files. If `DEMO_API_KEY` is
|
By default existing environment variables take priority over files. If
|
||||||
already set to an empty string, its file is skipped and it stays empty. A later
|
`DEMO_API_KEY` is already set to an empty string, its file is skipped and it stays empty. A later
|
||||||
required `Secret` reference will still fail on that empty value. File bootstrap
|
required `Secret` reference will still fail on that empty value. File bootstrap
|
||||||
accepting an empty file is different from a required reference resolving to an
|
accepting an empty file is different from a required reference resolving to an
|
||||||
empty credential.
|
empty credential. `LoadSecretsIntoEnvironmentWithOptions` accepts
|
||||||
|
`SecretsOptions{Overwrite: true}` to replace existing values explicitly.
|
||||||
|
|
||||||
|
For a directory selected by the main file, call
|
||||||
|
`LoadSecretsIntoEnvironmentFromConfig` with a host `File` or `SearchConfig`
|
||||||
|
source before `Load` or `LoadLayered`. The main document may declare:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
config:
|
||||||
|
secrets_dir: secrets
|
||||||
|
secrets_overwrite: false
|
||||||
|
```
|
||||||
|
|
||||||
|
`secrets_dir` is a nonempty relative host path, interpreted literally relative
|
||||||
|
to the selected main file's canonical directory. Its canonical target must be
|
||||||
|
inside the main filesystem root; a contained directory symlink is allowed.
|
||||||
|
Parent-relative paths can reach other directories inside an explicitly wider
|
||||||
|
root. Rooted, absolute, and host volume-qualified paths are invalid. `secrets_overwrite`
|
||||||
|
is a Boolean and defaults to false. A non-nil Go `Overwrite` option wins over
|
||||||
|
the YAML value, including an explicit false. Invalid declarations fail even
|
||||||
|
when Go supplies an override. Overwrite without a directory is a no-op.
|
||||||
|
|
||||||
|
Only the main document root owns these controls. Imports and underlays reject
|
||||||
|
them with source-local import diagnostics; selected overlays reject them as
|
||||||
|
overlay directives. Nested application `config` mappings and data assembled at
|
||||||
|
the application root by placement, defaults, CLI, or resolution remain ordinary
|
||||||
|
data. Normal `Load` and `LoadLayered` validate and consume main controls whether
|
||||||
|
imports are enabled or disabled, but never bootstrap or write the environment.
|
||||||
|
Each load resolves typed secret names from the environment at the usual point.
|
||||||
|
|
||||||
|
The companion accepts at most one `SecretsFromConfigOptions`, including an
|
||||||
|
optional host `FilesystemContext`. It selects and parses the main once, validates
|
||||||
|
the bootstrap controls, and completes directory bootstrap before returning a
|
||||||
|
prepared source. It does not run import acquisition, version checks, decoding,
|
||||||
|
resolution, or validation. It loads every eligible directory entry, including
|
||||||
|
names unused by the application's typed schema. A main with no directory still
|
||||||
|
returns a prepared source and empty report. `NoSource` or an exhausted optional
|
||||||
|
search returns `NoSource` and an empty report. Explicit absent-input context
|
||||||
|
continues to follow the normal absent-host-context rules. The helper also accepts
|
||||||
|
a previously prepared source, reusing its captured main and explicitly performing
|
||||||
|
bootstrap again.
|
||||||
|
|
||||||
|
The prepared source is a reusable snapshot of the selected main document,
|
||||||
|
including its unconsumed controls, byte count, canonical file identity, base,
|
||||||
|
and containment root. A later load neither rediscovers nor rereads the main
|
||||||
|
and does not repeat bootstrap; it reads imports and resources when accessed and
|
||||||
|
looks up secrets anew. The main's source record retains `SourceKindFile`. Each
|
||||||
|
load clones the document, creates its own source IDs
|
||||||
|
and records, and applies normal input accounting. No file handle or secret-file
|
||||||
|
contents remain in the prepared source. With no later context, loading uses the
|
||||||
|
captured context. A supplied later host context must resolve to the same root,
|
||||||
|
base, and main path; equivalent path spellings and root symlink aliases are
|
||||||
|
accepted. Native contexts, a file `BaseDir`, and different roots fail with
|
||||||
|
`options.invalid`. A caller needing another root prepares the original source
|
||||||
|
again. These rules apply to ordinary options and layered main inputs.
|
||||||
|
|
||||||
|
The helper returns a non-nil report on every attempt and a zero, unusable source
|
||||||
|
on error. Discovery, source, parse, control, and preparation-context failures
|
||||||
|
return `*LoadError` with available source records and source-local diagnostics.
|
||||||
|
Directory inspection, reads, and environment writes return `*SecretsError`.
|
||||||
|
An invalid directory declaration uses `secrets.invalid_path`; a non-Boolean
|
||||||
|
overwrite declaration uses `secrets.invalid_value`. Later loading failures do
|
||||||
|
not undo bootstrap effects or change its report. Multiple options fail before
|
||||||
|
acquisition or writes.
|
||||||
|
|
||||||
Read the report even when the helper returns an error:
|
Read the report even when the helper returns an error:
|
||||||
|
|
||||||
@@ -1101,18 +1164,20 @@ Read the report even when the helper returns an error:
|
|||||||
|
|
||||||
Render the returned `SecretsReport` separately from a later configuration load.
|
Render the returned `SecretsReport` separately from a later configuration load.
|
||||||
It contains filenames, paths, and statuses, not credential contents. The
|
It contains filenames, paths, and statuses, not credential contents. The
|
||||||
[maintained startup example](../examples/consumers/consumers_test.go) shows how to
|
[configured startup example](../examples/consumers/secrets.go) prepares a source
|
||||||
keep bootstrap and configuration reports together in the application.
|
for either loading entry point; its [test](../examples/consumers/secrets_test.go)
|
||||||
|
shows both handoffs. The [direct-directory example](../examples/consumers/consumers_test.go)
|
||||||
|
shows how to keep bootstrap and configuration reports together.
|
||||||
|
|
||||||
### Preflight, limits, and partial writes
|
### Preflight, limits, and partial writes
|
||||||
|
|
||||||
`LoadSecretsIntoEnvironment(directory)` is a separate, opt-in startup operation.
|
All bootstrap helpers are separate, opt-in startup operations. They are never
|
||||||
It is never called by `Load`, is not a YAML option, and does not participate in
|
called by a configuration load and do not perform configuration validation.
|
||||||
configuration validation. Applications choose the native directory path and
|
Applications own startup ordering and should invoke bootstrap before concurrent
|
||||||
should invoke the operation once before starting concurrent work. The selected
|
work or other process-environment mutation. The direct helpers accept a native
|
||||||
path may itself be a symlink; ConfigKit resolves it to an existing canonical
|
directory path; the configured helper resolves the declared path as described
|
||||||
directory before examining
|
above. The selected path may itself be a symlink; ConfigKit resolves it to an
|
||||||
its immediate entries.
|
existing canonical directory before examining its immediate entries.
|
||||||
|
|
||||||
The bootstrap enumerates at most 1,024 entries, including dot-prefixed entries.
|
The bootstrap enumerates at most 1,024 entries, including dot-prefixed entries.
|
||||||
Entries whose names begin with `.` (files, directories, or symlinks, such as `.git`
|
Entries whose names begin with `.` (files, directories, or symlinks, such as `.git`
|
||||||
@@ -1120,16 +1185,18 @@ and `.gitignore`) are ignored before name or metadata validation, are never open
|
|||||||
and are omitted from the report. Remaining entries are sorted by filename; each
|
and are omitted from the report. Remaining entries are sorted by filename; each
|
||||||
must have an ASCII environment-variable name and be a regular, nonsymlink
|
must have an ASCII environment-variable name and be a regular, nonsymlink
|
||||||
file. Metadata for all remaining entries is validated before file content is read
|
file. Metadata for all remaining entries is validated before file content is read
|
||||||
or process state is changed. Existing environment variables win, including variables whose
|
or process state is changed. In preservation mode existing environment variables
|
||||||
value is empty; their files are not opened. Each eligible file is limited to 1 MiB,
|
win, including variables whose value is empty; their files are not opened. In
|
||||||
and eligible content is limited to 8 MiB in total. ConfigKit removes exactly one
|
overwrite mode their files are read and applied as well. Each eligible file is
|
||||||
|
limited to 1 MiB, and eligible content is limited to 8 MiB in total. ConfigKit removes exactly one
|
||||||
terminal LF or CRLF, preserves all other whitespace, accepts an empty value, and
|
terminal LF or CRLF, preserves all other whitespace, accepts an empty value, and
|
||||||
rejects NUL bytes.
|
rejects NUL bytes.
|
||||||
|
|
||||||
All eligible files are read successfully before application begins. Presence is
|
All required files are read successfully before application begins. In
|
||||||
checked again immediately before each `os.Setenv`: a variable populated since
|
preservation mode presence is checked again immediately before each `os.Setenv`:
|
||||||
preflight is skipped. A write failure stops application without rollback, so prior
|
a variable populated since preflight is skipped. Overwrite mode applies the
|
||||||
writes remain and later eligible entries are `not_applied`. This operation is not
|
staged value regardless of presence. A write failure stops application without
|
||||||
|
rollback, so prior writes remain and later eligible entries are `not_applied`. This operation is not
|
||||||
atomic and does not provide compare-and-set semantics for concurrent environment
|
atomic and does not provide compare-and-set semantics for concurrent environment
|
||||||
mutation.
|
mutation.
|
||||||
|
|
||||||
@@ -1137,9 +1204,11 @@ mutation.
|
|||||||
records with `loaded`, `skipped_existing`, `not_applied`, or `failed` status.
|
records with `loaded`, `skipped_existing`, `not_applied`, or `failed` status.
|
||||||
`ExistingEmpty` distinguishes an empty existing winner. `SecretsReport.WriteTo`
|
`ExistingEmpty` distinguishes an empty existing winner. `SecretsReport.WriteTo`
|
||||||
renders only quoted names, canonical paths, statuses, and that empty-state flag;
|
renders only quoted names, canonical paths, statuses, and that empty-state flag;
|
||||||
it never retains or renders file contents. Failures return the non-nil partial
|
it never retains or renders file contents. Directory and environment failures
|
||||||
report with a `*SecretsError` containing detached `secrets.*` diagnostics and no
|
return the non-nil partial report with a `*SecretsError` containing detached
|
||||||
raw filesystem or environment error chain. Applications should retain the report
|
`secrets.*` diagnostics and no raw filesystem or environment error chain.
|
||||||
|
Configured main-preparation failures return `*LoadError` as described above.
|
||||||
|
Applications should retain the report
|
||||||
alongside the later configuration result and explicitly present blocked and failed
|
alongside the later configuration result and explicitly present blocked and failed
|
||||||
files when appropriate; ConfigKit stores no implicit global report.
|
files when appropriate; ConfigKit stores no implicit global report.
|
||||||
|
|
||||||
@@ -1674,8 +1743,10 @@ rules below explain absence, patterns, placement, and ordering.
|
|||||||
### Declaration and selection rules
|
### Declaration and selection rules
|
||||||
|
|
||||||
Imports are opt-in. With `Options.Imports` enabled, a document may use its root
|
Imports are opt-in. With `Options.Imports` enabled, a document may use its root
|
||||||
`config` mapping for `imports` and `sequences` controls. Ordinary `Load` may use
|
`config` mapping for `imports` and `sequences` controls. The main root may also
|
||||||
`sequences` without enabling imports, but an `imports` field still requires
|
declare the [secrets bootstrap controls](#explicit-secrets-directory-bootstrap).
|
||||||
|
Ordinary `Load` may use `sequences` and main bootstrap controls without enabling
|
||||||
|
imports, but an `imports` field still requires
|
||||||
`Options.Imports`. ConfigKit removes recognized root controls before application
|
`Options.Imports`. ConfigKit removes recognized root controls before application
|
||||||
decoding. Each imports sequence item is a mapping with exactly one `path`,
|
decoding. Each imports sequence item is a mapping with exactly one `path`,
|
||||||
`dir`, or `glob` selector. `path` and `dir` accept a string or a list of strings;
|
`dir`, or `glob` selector. `path` and `dir` accept a string or a list of strings;
|
||||||
|
|||||||
@@ -26,7 +26,7 @@ Start with one file, then choose the tasks your application needs:
|
|||||||
| Add bundled defaults beneath application settings | [Native filesystem and layered input](#native-filesystem-and-layered-input) |
|
| Add bundled defaults beneath application settings | [Native filesystem and layered input](#native-filesystem-and-layered-input) |
|
||||||
| Select files or an overlay | [Discovery](#explicit-main-file-discovery), [import defaults](#import-defaults-and-selection-inspection), and the [overlay reference](../config.md#selected-overlays) |
|
| Select files or an overlay | [Discovery](#explicit-main-file-discovery), [import defaults](#import-defaults-and-selection-inspection), and the [overlay reference](../config.md#selected-overlays) |
|
||||||
| Reuse settings or combine record lists | [Inheritance](#named-sibling-inheritance) and [identified sequences](#identified-prompt-sequences) |
|
| Reuse settings or combine record lists | [Inheritance](#named-sibling-inheritance) and [identified sequences](#identified-prompt-sequences) |
|
||||||
| Handle credentials | [Typed-secret reference](../config.md#typed-secret-references) and the [startup example](../../examples/consumers/consumers_test.go) |
|
| Handle credentials | [Typed-secret reference](../config.md#typed-secret-references), [configured startup](#configured-secrets-startup), and the [direct-directory example](../../examples/consumers/consumers_test.go) |
|
||||||
| Inspect sources, earlier values, or changes | [Inspect a completed load](#inspect-a-completed-load) and [diffs](#effective-configuration-diffs) |
|
| Inspect sources, earlier values, or changes | [Inspect a completed load](#inspect-a-completed-load) and [diffs](#effective-configuration-diffs) |
|
||||||
| Upgrade an existing consumer | [Migration guidance](#intentional-migration-changes) |
|
| Upgrade an existing consumer | [Migration guidance](#intentional-migration-changes) |
|
||||||
|
|
||||||
@@ -57,6 +57,17 @@ discovery composed with sequences, see the
|
|||||||
For discovered main files with companion imports and an overlay, see the
|
For discovered main files with companion imports and an overlay, see the
|
||||||
[main-relative example](../../examples/consumers/main_relative.go).
|
[main-relative example](../../examples/consumers/main_relative.go).
|
||||||
|
|
||||||
|
## Configured secrets startup
|
||||||
|
|
||||||
|
Call [`PrepareStartup`](../../examples/consumers/secrets.go) with a host file
|
||||||
|
or search source and the selected containment root, then handle its report and
|
||||||
|
error before loading. Pass the returned source to ordinary `Load`, or place it
|
||||||
|
in the main `Input` for `LoadLayered`; the [maintained test](../../examples/consumers/secrets_test.go)
|
||||||
|
shows both. Preparation is explicit and loads eligible files even when their
|
||||||
|
names are used only by another SDK. The application owns startup ordering and
|
||||||
|
handling partial effects. See the [configuration contract](../config.md#explicit-secrets-directory-bootstrap)
|
||||||
|
for controls, overwrite precedence, errors, and source reuse.
|
||||||
|
|
||||||
## Happy path
|
## Happy path
|
||||||
|
|
||||||
Define the Go configuration type, choose one source, and call `Load`. Handle a
|
Define the Go configuration type, choose one source, and call `Load`. Handle a
|
||||||
@@ -520,7 +531,7 @@ focused behavioral owner:
|
|||||||
| `Load`, `NoSource`, validation, versions, resolution, `SecretEnv`, overrides, and explanation | Executable examples in [`example_test.go`](../../example_test.go) |
|
| `Load`, `NoSource`, validation, versions, resolution, `SecretEnv`, overrides, and explanation | Executable examples in [`example_test.go`](../../example_test.go) |
|
||||||
| Source/import/selected-overlay pipeline rules and artifact defaults | Narratio-shaped executable example and fixture |
|
| Source/import/selected-overlay pipeline rules and artifact defaults | Narratio-shaped executable example and fixture |
|
||||||
| Canonical module objects and dynamic option handling | WeatherReporter- and Notarius-shaped examples and migration tests |
|
| Canonical module objects and dynamic option handling | WeatherReporter- and Notarius-shaped examples and migration tests |
|
||||||
| `LoadSecretsIntoEnvironment`, bootstrap reporting, typed lookup, CLI explanation | `Example_weatherStartup` |
|
| Secrets bootstrap, prepared ordinary and layered sources, typed lookup | [`TestConfiguredSecretsStartup`](../../examples/consumers/secrets_test.go) and `Example_weatherStartup` |
|
||||||
| Native filesystem, grouped underlays, programmatic mapping, retained resource context | `Example_nativeFilesystem`, `Example_layeredCatalog`, and their focused consumer tests |
|
| Native filesystem, grouped underlays, programmatic mapping, retained resource context | `Example_nativeFilesystem`, `Example_layeredCatalog`, and their focused consumer tests |
|
||||||
| Literal input destinations, root-default compatibility, and mounted peer collections | `Example_inputDestination`, `LoadCollectionBundle`, and `destinations_test.go` |
|
| Literal input destinations, root-default compatibility, and mounted peer collections | `Example_inputDestination`, `LoadCollectionBundle`, and `destinations_test.go` |
|
||||||
| Named sibling inheritance, presence, and derivation | `Example_inheritedPresets` and `TestPresetCatalogOneLoadAndDerivation` |
|
| Named sibling inheritance, presence, and derivation | `Example_inheritedPresets` and `TestPresetCatalogOneLoadAndDerivation` |
|
||||||
|
|||||||
@@ -313,7 +313,7 @@ code changes. Use the component overview to find the corresponding implementatio
|
|||||||
| Resolution sequence matching and inspection | [Correspondence](../internal/engine/resolution_correspondence_test.go), [auditing and history](../internal/engine/resolution_compare_test.go), [public integration](../facade_resolution_sequences_test.go) | `go test ./internal/engine -run 'Resolution\|History\|Explain\|Sensitivity'` and `go test . -run 'Resolution\|SequenceIdentity\|Diff'` |
|
| Resolution sequence matching and inspection | [Correspondence](../internal/engine/resolution_correspondence_test.go), [auditing and history](../internal/engine/resolution_compare_test.go), [public integration](../facade_resolution_sequences_test.go) | `go test ./internal/engine -run 'Resolution\|History\|Explain\|Sensitivity'` and `go test . -run 'Resolution\|SequenceIdentity\|Diff'` |
|
||||||
| Paths, metadata, provenance | [Paths](../internal/engine/path_test.go), [metadata](../internal/engine/metadata_test.go), [provenance](../internal/engine/provenance_test.go) | `go test ./internal/engine -run 'Path\|Metadata\|Provenance\|Queries'` |
|
| Paths, metadata, provenance | [Paths](../internal/engine/path_test.go), [metadata](../internal/engine/metadata_test.go), [provenance](../internal/engine/provenance_test.go) | `go test ./internal/engine -run 'Path\|Metadata\|Provenance\|Queries'` |
|
||||||
| Passive resource contexts | [Engine contexts](../internal/engine/resource_context_test.go), [public contexts](../facade_resource_context_test.go) | `go test ./internal/engine -run 'Resource'` and `go test . -run 'SourceContext'` |
|
| Passive resource contexts | [Engine contexts](../internal/engine/resource_context_test.go), [public contexts](../facade_resource_context_test.go) | `go test ./internal/engine -run 'Resource'` and `go test . -run 'SourceContext'` |
|
||||||
| Secrets, bootstrap, redaction, explanation | [References](../internal/engine/secret_reference_test.go), [bootstrap](../internal/engine/secrets_test.go), [rendering](../internal/engine/render_test.go), [explanation](../internal/engine/explain_test.go) | `go test ./internal/engine -run 'Secret\|Bootstrap\|Effective\|Explain\|Explanation\|History\|Sensitivity'` |
|
| Secrets, bootstrap, redaction, explanation | [References](../internal/engine/secret_reference_test.go), [directory bootstrap](../internal/engine/secrets_test.go), [configured preparation](../internal/engine/secrets_from_config_test.go), [public handoff](../facade_secrets_handoff_test.go), [consumer example](../examples/consumers/secrets_test.go), [rendering](../internal/engine/render_test.go), [explanation](../internal/engine/explain_test.go) | `go test ./internal/engine -run 'Secret\|Bootstrap\|Effective\|Explain\|Explanation\|History\|Sensitivity'`, `go test . -run 'Secrets\|Bootstrap'`, and `go test ./examples/consumers -run 'ConfiguredSecrets'` |
|
||||||
| Effective configuration diff | [Engine comparison and masking tests](../internal/engine/diff_test.go), [engine operation tests](../internal/engine/diff_operation_test.go), [root facade tests](../facade_diff_test.go), and [consumer examples](../examples/consumers/diff_test.go) | `go test ./internal/engine -run 'Diff\|Explain\|History\|Secret\|Independent'`, `go test . -run 'Diff\|FacadeInspection\|PublicFacadeBoundary\|DependencyImportBoundary'`, `go test ./examples/consumers`, and `go test . -run '^ExampleDiff$'` |
|
| Effective configuration diff | [Engine comparison and masking tests](../internal/engine/diff_test.go), [engine operation tests](../internal/engine/diff_operation_test.go), [root facade tests](../facade_diff_test.go), and [consumer examples](../examples/consumers/diff_test.go) | `go test ./internal/engine -run 'Diff\|Explain\|History\|Secret\|Independent'`, `go test . -run 'Diff\|FacadeInspection\|PublicFacadeBoundary\|DependencyImportBoundary'`, `go test ./examples/consumers`, and `go test . -run '^ExampleDiff$'` |
|
||||||
| Consumer examples and migration fixtures | [Consumer tests](../examples/consumers/consumers_test.go), [native, layered, and ordinary relative-import examples](../examples/consumers/layered_test.go), [mounted collection examples](../examples/consumers/destinations_test.go), [API examples](../example_test.go) | `go test ./examples/consumers` and `go test . -run '^Example'` |
|
| Consumer examples and migration fixtures | [Consumer tests](../examples/consumers/consumers_test.go), [native, layered, and ordinary relative-import examples](../examples/consumers/layered_test.go), [mounted collection examples](../examples/consumers/destinations_test.go), [API examples](../example_test.go) | `go test ./examples/consumers` and `go test . -run '^Example'` |
|
||||||
| Assembly and layered scaling evidence | [Assembly benchmarks](../internal/engine/assembly_bench_test.go), [layered benchmarks](../internal/engine/underlay_bench_test.go) | `go test ./internal/engine -run '^$' -bench '^BenchmarkUnderlay' -benchmem`; repeat with `^BenchmarkCompose` and `^BenchmarkOverlay` |
|
| Assembly and layered scaling evidence | [Assembly benchmarks](../internal/engine/assembly_bench_test.go), [layered benchmarks](../internal/engine/underlay_bench_test.go) | `go test ./internal/engine -run '^$' -bench '^BenchmarkUnderlay' -benchmem`; repeat with `^BenchmarkCompose` and `^BenchmarkOverlay` |
|
||||||
|
|||||||
@@ -27,6 +27,16 @@ Contextless bindings prepare declaration policies and assemble the declaring
|
|||||||
payload without opening filesystem access or recording selection evidence.
|
payload without opening filesystem access or recording selection evidence.
|
||||||
Selected contexts use the existing acquisition and handle lifecycle.
|
Selected contexts use the existing acquisition and handle lifecycle.
|
||||||
|
|
||||||
|
A captured host main enters the same parsed-source and import traversal handoff
|
||||||
|
as an ordinarily selected file. Its original bytes and nodes are charged once per
|
||||||
|
load, including placement wrappers, and its canonical path participates in
|
||||||
|
cycle and repeated-source checks. Imports are still acquired live; layered
|
||||||
|
main-relative consumers receive the captured base and root, while each tier
|
||||||
|
continues to use its own namespace token and repetition state. The capture and
|
||||||
|
context checks are owned by
|
||||||
|
[`prepared_source.go`](../../internal/engine/prepared_source.go) and
|
||||||
|
[`filesystem_context.go`](../../internal/engine/filesystem_context.go).
|
||||||
|
|
||||||
Directory traversal tracks canonical directories on the active traversal path.
|
Directory traversal tracks canonical directories on the active traversal path.
|
||||||
It adds an identity when descending and removes it when the frame is popped, so
|
It adds an identity when descending and removes it when the frame is popped, so
|
||||||
only a back-edge to an active directory is a traversal cycle; a later alias is
|
only a back-edge to an active directory is a traversal cycle; a later alias is
|
||||||
|
|||||||
@@ -125,6 +125,16 @@ for passive-context construction and ordinary-overlay handling: see
|
|||||||
[`filesystem_context.go`](../../internal/engine/filesystem_context.go) and
|
[`filesystem_context.go`](../../internal/engine/filesystem_context.go) and
|
||||||
[`source_context.go`](../../internal/engine/source_context.go).
|
[`source_context.go`](../../internal/engine/source_context.go).
|
||||||
|
|
||||||
|
Explicit configured bootstrap uses
|
||||||
|
[`prepared_source.go`](../../internal/engine/prepared_source.go) to share host
|
||||||
|
discovery and bounded parsing with acquisition. It stores a read-only main tree,
|
||||||
|
byte count, and canonical path facts; each load clones the tree and assigns its
|
||||||
|
own source ID. [`secrets_from_config.go`](../../internal/engine/secrets_from_config.go)
|
||||||
|
validates just the bootstrap controls and calls the shared directory worker.
|
||||||
|
Acquisition checks any later explicit context against the captured facts before
|
||||||
|
imports or overlays, then applies normal source and aggregate accounting.
|
||||||
|
Captured state contains no access handles or secret-file values.
|
||||||
|
|
||||||
Import responsibilities are split across candidate selection and path
|
Import responsibilities are split across candidate selection and path
|
||||||
normalization in [`import_selection.go`](../../internal/engine/import_selection.go),
|
normalization in [`import_selection.go`](../../internal/engine/import_selection.go),
|
||||||
source reading and traversal admission in
|
source reading and traversal admission in
|
||||||
|
|||||||
@@ -407,11 +407,11 @@ accessor exposes a resolved credential to application code. Credential bytes mus
|
|||||||
never enter composition trees, history, or inspection. General environment-variable
|
never enter composition trees, history, or inspection. General environment-variable
|
||||||
configuration overlays are an explicit non-goal. Bootstrap preserves already
|
configuration overlays are an explicit non-goal. Bootstrap preserves already
|
||||||
set variables by default, including empty ones, and reports blocked files without
|
set variables by default, including empty ones, and reports blocked files without
|
||||||
contents. [ADR 0023](../adr/0023-explicit-configured-secrets-bootstrap.md) permits
|
contents. Explicit overwrite and main-document-directed bootstrap are available
|
||||||
explicit overwrite and main-document-directed bootstrap as a separate startup
|
as separate startup operations. A prepared main retains its selected document
|
||||||
operation. Its implementation is tracked in the
|
and passive filesystem context without retaining secret-file contents or open
|
||||||
[secrets-directory roadmap](../roadmap/secrets-directory.md); the
|
handles. [ADR 0023](../adr/0023-explicit-configured-secrets-bootstrap.md) records
|
||||||
[configuration contract](../config.md#explicit-secrets-directory-bootstrap)
|
the decision; the [configuration contract](../config.md#explicit-secrets-directory-bootstrap)
|
||||||
owns current behavior.
|
owns current behavior.
|
||||||
|
|
||||||
Secrets must be considered throughout error handling and inspection. Library
|
Secrets must be considered throughout error handling and inspection. Library
|
||||||
|
|||||||
@@ -368,6 +368,8 @@ facade boundary.
|
|||||||
|
|
||||||
## Stage 9 — Update canonical documentation and validate the sprint
|
## Stage 9 — Update canonical documentation and validate the sprint
|
||||||
|
|
||||||
|
**Completed.**
|
||||||
|
|
||||||
1. Update `docs/config.md` with the two main controls, preparation and bootstrap
|
1. Update `docs/config.md` with the two main controls, preparation and bootstrap
|
||||||
boundaries, lookup timing, overwrite precedence, reports/errors, host scope,
|
boundaries, lookup timing, overwrite precedence, reports/errors, host scope,
|
||||||
and prepared-source reuse/context behavior. Keep source-local controls
|
and prepared-source reuse/context behavior. Keep source-local controls
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
# Main-relative secrets directories
|
# Main-relative secrets directories
|
||||||
|
|
||||||
Status: planned, not implemented. [ADR 0023](../adr/0023-explicit-configured-secrets-bootstrap.md)
|
Status: implemented. [ADR 0023](../adr/0023-explicit-configured-secrets-bootstrap.md)
|
||||||
supersedes ADR 0004 and records explicit configured bootstrap and optional
|
supersedes ADR 0004 and records explicit configured bootstrap and optional
|
||||||
overwrite. The decisions below preserve ordinary loading without environment
|
overwrite. The decisions below preserve ordinary loading without environment
|
||||||
writes and the existing direct-directory helper's Go signature.
|
writes and the existing direct-directory helper's Go signature.
|
||||||
|
|||||||
@@ -2,6 +2,7 @@ package engine
|
|||||||
|
|
||||||
import (
|
import (
|
||||||
"reflect"
|
"reflect"
|
||||||
|
"runtime"
|
||||||
"testing"
|
"testing"
|
||||||
|
|
||||||
"go.maximumdirect.net/configkit/internal/document"
|
"go.maximumdirect.net/configkit/internal/document"
|
||||||
@@ -127,6 +128,19 @@ func TestBootstrapControlExtraction(t *testing.T) {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
func TestBootstrapDirectoryRejectsWindowsRootedPaths(t *testing.T) {
|
||||||
|
if runtime.GOOS != "windows" {
|
||||||
|
t.Skip("host path syntax differs")
|
||||||
|
}
|
||||||
|
for _, path := range []string{`C:relative`, `\rooted`} {
|
||||||
|
root := parseRootDirectiveDocument(t, "config: {secrets_dir: '"+path+"'}\n")
|
||||||
|
_, diagnostics := extractBootstrapSettings(root)
|
||||||
|
if len(diagnostics) != 1 || diagnostics[0].Code != CodeSecretsInvalidPath {
|
||||||
|
t.Fatalf("path %q: %#v", path, diagnostics)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
func TestBootstrapControlsRequireMainSource(t *testing.T) {
|
func TestBootstrapControlsRequireMainSource(t *testing.T) {
|
||||||
root := parseRootDirectiveDocument(t, "config: {secrets_dir: secrets, secrets_overwrite: true}\nvalue: ordinary\n")
|
root := parseRootDirectiveDocument(t, "config: {secrets_dir: secrets, secrets_overwrite: true}\nvalue: ordinary\n")
|
||||||
for _, context := range []rootDirectiveContext{rootDirectiveContextSource, rootDirectiveContextLayered} {
|
for _, context := range []rootDirectiveContext{rootDirectiveContextSource, rootDirectiveContextLayered} {
|
||||||
|
|||||||
@@ -1,6 +1,7 @@
|
|||||||
package engine
|
package engine
|
||||||
|
|
||||||
import (
|
import (
|
||||||
|
"os"
|
||||||
"path"
|
"path"
|
||||||
"path/filepath"
|
"path/filepath"
|
||||||
"strings"
|
"strings"
|
||||||
@@ -66,7 +67,7 @@ func parseBootstrapField(settings *bootstrapSettings, entry document.Entry) *Dia
|
|||||||
value := entry.Value
|
value := entry.Value
|
||||||
fieldPath := Keys(directiveKey, entry.Key)
|
fieldPath := Keys(directiveKey, entry.Key)
|
||||||
if entry.Key == "secrets_dir" {
|
if entry.Key == "secrets_dir" {
|
||||||
if value == nil || value.Kind != document.String || value.Text == "" || filepath.IsAbs(value.Text) || filepath.VolumeName(value.Text) != "" {
|
if value == nil || value.Kind != document.String || value.Text == "" || os.IsPathSeparator(value.Text[0]) || filepath.IsAbs(value.Text) || filepath.VolumeName(value.Text) != "" {
|
||||||
diagnostic := nodeImportDiagnostic(CodeSecretsInvalidPath, fieldPath, "secrets directory must be a nonempty relative host path", value)
|
diagnostic := nodeImportDiagnostic(CodeSecretsInvalidPath, fieldPath, "secrets directory must be a nonempty relative host path", value)
|
||||||
return &diagnostic
|
return &diagnostic
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -40,9 +40,9 @@ func captureHostMain(source Source, context *FilesystemContext) (Source, []Sourc
|
|||||||
if context.FS != nil {
|
if context.FS != nil {
|
||||||
return Source{}, nil, []Diagnostic{optionDiagnostic(CodeOptionsInvalid, "main preparation requires a host filesystem context")}
|
return Source{}, nil, []Diagnostic{optionDiagnostic(CodeOptionsInvalid, "main preparation requires a host filesystem context")}
|
||||||
}
|
}
|
||||||
if diagnostics := filesystemOptionDiagnostics(source, context); len(diagnostics) != 0 {
|
}
|
||||||
return Source{}, nil, diagnostics
|
if _, diagnostics := normalizeInput(loadInput{source: source, filesystem: context}, ""); len(diagnostics) != 0 {
|
||||||
}
|
return Source{}, nil, diagnostics
|
||||||
}
|
}
|
||||||
selected, failed, diagnostics := selectInputSource(source, sourceID, context)
|
selected, failed, diagnostics := selectInputSource(source, sourceID, context)
|
||||||
if len(diagnostics) != 0 {
|
if len(diagnostics) != 0 {
|
||||||
|
|||||||
@@ -89,6 +89,7 @@ func TestSecretsFromConfigReportsPreparationFailures(t *testing.T) {
|
|||||||
{"missing file", File(missing), nil, CodeSourceMissing},
|
{"missing file", File(missing), nil, CodeSourceMissing},
|
||||||
{"required search", SearchConfig("app", Paths(missing), SearchOptions{Required: true}), nil, CodeSourceMissing},
|
{"required search", SearchConfig("app", Paths(missing), SearchOptions{Required: true}), nil, CodeSourceMissing},
|
||||||
{"unsupported source", Bytes("main", []byte("{}\n")), nil, CodeOptionsInvalid},
|
{"unsupported source", Bytes("main", []byte("{}\n")), nil, CodeOptionsInvalid},
|
||||||
|
{"invalid search options", SearchConfig("app", Paths(malformed), SearchOptions{}, SearchOptions{}), nil, CodeOptionsInvalid},
|
||||||
{"native context", File(malformed), []SecretsFromConfigOptions{{Filesystem: &FilesystemContext{Root: ".", FS: &native}}}, CodeOptionsInvalid},
|
{"native context", File(malformed), []SecretsFromConfigOptions{{Filesystem: &FilesystemContext{Root: ".", FS: &native}}}, CodeOptionsInvalid},
|
||||||
{"multiple options", File(malformed), []SecretsFromConfigOptions{{}, {}}, CodeOptionsInvalid},
|
{"multiple options", File(malformed), []SecretsFromConfigOptions{{}, {}}, CodeOptionsInvalid},
|
||||||
} {
|
} {
|
||||||
@@ -98,6 +99,9 @@ func TestSecretsFromConfigReportsPreparationFailures(t *testing.T) {
|
|||||||
if report == nil || len(report.Entries()) != 0 || prepared.kind != sourceInvalid || !errors.As(err, &failure) || len(failure.Diagnostics()) == 0 || failure.Diagnostics()[0].Code != test.code {
|
if report == nil || len(report.Entries()) != 0 || prepared.kind != sourceInvalid || !errors.As(err, &failure) || len(failure.Diagnostics()) == 0 || failure.Diagnostics()[0].Code != test.code {
|
||||||
t.Fatalf("report = %#v, source = %#v, error = %#v", report, prepared, err)
|
t.Fatalf("report = %#v, source = %#v, error = %#v", report, prepared, err)
|
||||||
}
|
}
|
||||||
|
if test.code == CodeOptionsInvalid && len(failure.Sources()) != 0 {
|
||||||
|
t.Fatalf("option error acquired sources: %#v", failure.Sources())
|
||||||
|
}
|
||||||
})
|
})
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
11
secrets.go
11
secrets.go
@@ -7,8 +7,8 @@ import (
|
|||||||
"go.maximumdirect.net/configkit/internal/engine"
|
"go.maximumdirect.net/configkit/internal/engine"
|
||||||
)
|
)
|
||||||
|
|
||||||
// SecretFileStatus describes the outcome for one file considered by
|
// SecretFileStatus describes the outcome for one file considered by an
|
||||||
// LoadSecretsIntoEnvironment.
|
// explicit secrets bootstrap helper.
|
||||||
type SecretFileStatus string
|
type SecretFileStatus string
|
||||||
|
|
||||||
const (
|
const (
|
||||||
@@ -102,8 +102,10 @@ type SecretsOptions struct {
|
|||||||
}
|
}
|
||||||
|
|
||||||
// LoadSecretsIntoEnvironmentWithOptions loads immediate regular files into the
|
// LoadSecretsIntoEnvironmentWithOptions loads immediate regular files into the
|
||||||
// environment using the selected policy. It returns a report even on error;
|
// environment using the selected policy. With Overwrite false it preserves
|
||||||
// applied values are not rolled back. Errors are reported as *SecretsError.
|
// existing variables, including empty values. Dot-prefixed entries are ignored.
|
||||||
|
// It returns a report even on error; applied values are not rolled back.
|
||||||
|
// Errors are reported as *SecretsError.
|
||||||
func LoadSecretsIntoEnvironmentWithOptions(directory string, options SecretsOptions) (*SecretsReport, error) {
|
func LoadSecretsIntoEnvironmentWithOptions(directory string, options SecretsOptions) (*SecretsReport, error) {
|
||||||
report, err := engine.LoadSecretsDirWithOptions(directory, engine.SecretsDirOptions{Overwrite: options.Overwrite})
|
report, err := engine.LoadSecretsDirWithOptions(directory, engine.SecretsDirOptions{Overwrite: options.Overwrite})
|
||||||
return &SecretsReport{value: report}, fromEngineSecretsError(err)
|
return &SecretsReport{value: report}, fromEngineSecretsError(err)
|
||||||
@@ -123,6 +125,7 @@ type SecretsFromConfigOptions struct {
|
|||||||
// NoSource and an optional search with no match return NoSource and an empty
|
// NoSource and an optional search with no match return NoSource and an empty
|
||||||
// report. The returned source owns a reusable main-document snapshot and its
|
// report. The returned source owns a reusable main-document snapshot and its
|
||||||
// host context; imports and environment lookup remain part of each later load.
|
// host context; imports and environment lookup remain part of each later load.
|
||||||
|
// A later explicit host context must match the captured root and base.
|
||||||
// At most one options value is accepted. A non-nil report accompanies every
|
// At most one options value is accepted. A non-nil report accompanies every
|
||||||
// result. Preparation failures return *LoadError; directory or environment
|
// result. Preparation failures return *LoadError; directory or environment
|
||||||
// failures return *SecretsError. Any error returns a zero Source and does not
|
// failures return *SecretsError. Any error returns a zero Source and does not
|
||||||
|
|||||||
Reference in New Issue
Block a user