Document and validate configured secrets bootstrap

This commit is contained in:
2026-11-18 01:10:24 +00:00
parent ab6e610fb7
commit eeafc356e4
13 changed files with 172 additions and 46 deletions

View File

@@ -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) |
| 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) |
| 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) |
| 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
[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
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) |
| 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 |
| `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 |
| 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` |