Remove completed secrets bootstrap plans
This commit is contained in:
@@ -1,396 +0,0 @@
|
|||||||
# Configured secrets bootstrap implementation plan
|
|
||||||
|
|
||||||
## Scope and execution
|
|
||||||
|
|
||||||
Implement the [secrets-directory roadmap](secrets-directory.md) and accepted
|
|
||||||
[ADR 0023](../adr/0023-explicit-configured-secrets-bootstrap.md). The starting
|
|
||||||
revision is `fb0560d`. Read [development](../development.md), the
|
|
||||||
[agent policy](../policy/agents.md), and the applicable architecture, testing,
|
|
||||||
and documentation policies before implementing a stage.
|
|
||||||
|
|
||||||
The stages run sequentially in one sprint. Intermediate stages may leave callers
|
|
||||||
temporarily uncompilable while an internal handoff changes. Finish the shared
|
|
||||||
integration before final validation. Keep tests with their behavior's owning
|
|
||||||
stage and reuse existing fixtures and failure seams. Each stage is intended to
|
|
||||||
fit one Luna implementation prompt.
|
|
||||||
|
|
||||||
The completed feature provides explicit bootstrap before ordinary configuration
|
|
||||||
loading. Discovery and the captured main document are shared between those two
|
|
||||||
calls. Ordinary secret resolution continues to read the environment at its
|
|
||||||
existing lifecycle point. Filesystem access and bootstrap finish synchronously.
|
|
||||||
|
|
||||||
## Decisions for implementation
|
|
||||||
|
|
||||||
### Public API
|
|
||||||
|
|
||||||
Keep the existing function and its exact function type. Add these root-owned
|
|
||||||
public declarations, following the existing facade-to-engine conversion pattern.
|
|
||||||
|
|
||||||
```go
|
|
||||||
func LoadSecretsIntoEnvironment(directory string) (*SecretsReport, error)
|
|
||||||
|
|
||||||
type SecretsOptions struct {
|
|
||||||
Overwrite bool
|
|
||||||
}
|
|
||||||
|
|
||||||
func LoadSecretsIntoEnvironmentWithOptions(
|
|
||||||
directory string, options SecretsOptions,
|
|
||||||
) (*SecretsReport, error)
|
|
||||||
|
|
||||||
type SecretsFromConfigOptions struct {
|
|
||||||
Filesystem *FilesystemContext
|
|
||||||
Overwrite *bool
|
|
||||||
}
|
|
||||||
|
|
||||||
func LoadSecretsIntoEnvironmentFromConfig(
|
|
||||||
main Source, supplied ...SecretsFromConfigOptions,
|
|
||||||
) (*SecretsReport, Source, error)
|
|
||||||
```
|
|
||||||
|
|
||||||
The companion accepts zero or one options value, matching the load entry points.
|
|
||||||
Multiple values produce `LoadError` with `CodeOptionsInvalid`, an empty non-nil
|
|
||||||
report, and zero `Source` before acquisition or writes. Snapshot the supplied
|
|
||||||
context and Boolean value at call entry using existing conversion conventions.
|
|
||||||
Nil overwrite uses YAML, then false. A supplied false or true wins over YAML.
|
|
||||||
|
|
||||||
The companion accepts host `File` and `SearchConfig` sources and `NoSource`.
|
|
||||||
A prepared host source can also be supplied to an explicit companion call using
|
|
||||||
its captured main. Reject other source kinds and native filesystem contexts as
|
|
||||||
`LoadError` option failures before consuming them. Preserve constructor and search
|
|
||||||
validation diagnostics through the existing helpers. NoSource and optional search
|
|
||||||
exhaustion succeed with an empty report and `NoSource()`. Explicit context on an
|
|
||||||
absent input follows existing absent-host-context validation; subsequent absent
|
|
||||||
loading uses the ordinary caller-supplied context rules.
|
|
||||||
|
|
||||||
Every failure returns a non-nil report and zero `Source`. Discovery, acquisition,
|
|
||||||
parse, control, and preparation-context failures use `LoadError`. Directory
|
|
||||||
resolution/inspection, credential reads, and environment writes use
|
|
||||||
`SecretsError`. Keep both error wrappers and their existing safe rendering and
|
|
||||||
detached records. Successful preparation with no directory returns the prepared
|
|
||||||
main and an empty report.
|
|
||||||
|
|
||||||
### Controls and source roles
|
|
||||||
|
|
||||||
Recognize root `config.secrets_dir` as a nonempty string containing a relative
|
|
||||||
host path and root `config.secrets_overwrite` as a Boolean. Accept ordinary YAML
|
|
||||||
Boolean spellings through the parser's existing type handling. Nulls, wrong
|
|
||||||
types, empty directory strings, absolute paths, and host volume-qualified paths
|
|
||||||
are invalid. Treat path text literally using host path operations. Parent-relative
|
|
||||||
paths are usable when their canonical targets stay inside the selected root.
|
|
||||||
|
|
||||||
Only the main input's document root owns these controls. Imports, underlays,
|
|
||||||
and selected overlays containing them produce a source-local control diagnostic.
|
|
||||||
Nested application `config` mappings and root application data introduced by
|
|
||||||
placement, defaults, CLI, or resolution retain their existing meaning under
|
|
||||||
[ADR 0020](../adr/0020-document-root-controls.md).
|
|
||||||
|
|
||||||
Normal loading checks and consumes the main controls, with imports enabled or
|
|
||||||
disabled. Filesystem checks for the declared secrets directory happen in the
|
|
||||||
companion helper. Both ordinary loading entry points perform their usual secret
|
|
||||||
lookup. Preparation validates the root control mapping and the bootstrap fields,
|
|
||||||
while other control grammars and import enablement are checked by the later load.
|
|
||||||
Retain the original main tree so imports and collection declarations are still
|
|
||||||
available to that load. A valid overwrite declaration without a directory is a
|
|
||||||
no-op. Invalid bootstrap fields fail even if a Go overwrite choice is supplied.
|
|
||||||
|
|
||||||
Use existing diagnostic codes. Use `CodeSecretsInvalidPath` for invalid directory
|
|
||||||
syntax, `CodeSecretsInvalidValue` for a non-Boolean overwrite setting, and the
|
|
||||||
existing directive-context codes for misplaced controls (`CodeImportInvalid` or
|
|
||||||
`CodeOverlayDirective`). Root mapping errors keep their current classification.
|
|
||||||
Bootstrap-field diagnostics carry `/config/secrets_dir` or
|
|
||||||
`/config/secrets_overwrite` and source-local locations, inside a `LoadError`.
|
|
||||||
Avoid raw input, parser errors, or credential contents in messages.
|
|
||||||
|
|
||||||
### Captured-source ownership and context
|
|
||||||
|
|
||||||
Represent preparation privately as a captured host-file payload attached to an
|
|
||||||
engine `sourceFile`. Keep public `Source` opaque and report `SourceKindFile`.
|
|
||||||
Capture the original parsed document, original byte count, canonical main path,
|
|
||||||
canonical base, and canonical containment root. Retain the unconsumed controls.
|
|
||||||
Keep captured data read-only and give each load an owned document clone with
|
|
||||||
fresh source IDs and accounting. Namespace tokens and acquisition state belong
|
|
||||||
to each load. Retain passive path facts with the source.
|
|
||||||
|
|
||||||
Normal acquisition consumes the captured main without discovery, file reading,
|
|
||||||
or bootstrap. Apply the usual byte, document, placement, and aggregate accounting
|
|
||||||
to the captured input in every load. A preparation-time count never substitutes
|
|
||||||
for load-wide admission. Imports and resources continue to be acquired when their
|
|
||||||
normal operations run. Main deletion or modification does not change captured
|
|
||||||
contents; later filesystem operations may fail under their existing contracts.
|
|
||||||
|
|
||||||
Use the captured context when later loading supplies none. Resolve an explicit
|
|
||||||
later host context against the captured canonical main path. It is compatible
|
|
||||||
when its canonical root, base, and main path match the captured facts. Compare
|
|
||||||
path facts using the existing host path rules, allowing equivalent spellings
|
|
||||||
and root symlink aliases. Native contexts, a supplied file BaseDir, and genuinely
|
|
||||||
different roots fail with `CodeOptionsInvalid` in `LoadError`. Avoid re-resolving
|
|
||||||
the original main filename to compare contexts, since it may now point elsewhere.
|
|
||||||
Use the same check for ordinary options and layered main input contexts before
|
|
||||||
import or overlay handling can substitute a context.
|
|
||||||
|
|
||||||
### Directory bootstrap semantics
|
|
||||||
|
|
||||||
Reuse `loadSecretsDir` and its environment/access seams for all three public
|
|
||||||
helpers. Preservation mode retains both existing-variable checks, including
|
|
||||||
empty values and a variable created between preflight and application.
|
|
||||||
Overwrite mode reads existing names' eligible files and applies them regardless
|
|
||||||
of environment presence. Unrelated environment variables retain their values.
|
|
||||||
Use the existing loaded/skipped/failed/not-applied statuses. `ExistingEmpty`
|
|
||||||
continues to describe skipped existing values.
|
|
||||||
|
|
||||||
Configured directory resolution uses the captured base and root. Canonicalize
|
|
||||||
the selected directory with the existing filesystem helpers and check containment
|
|
||||||
of that canonical target before reads or writes. A directory symlink can resolve
|
|
||||||
to a contained target, following the existing bootstrap directory convention.
|
|
||||||
Return `SecretsError` with `CodeSecretsInvalidPath` for an outside-root target;
|
|
||||||
use existing filesystem classifications for missing or unreadable targets.
|
|
||||||
The direct-directory helpers keep their existing path resolution behavior.
|
|
||||||
|
|
||||||
Bootstrap includes all eligible directory entries, independently of the later
|
|
||||||
typed schema. Reuse dot-entry exclusion, regular-file checks, limits, sorted
|
|
||||||
order, newline handling, empty-file handling, and NUL rejection. Complete
|
|
||||||
metadata checks and required reads before writes. A write failure retains prior
|
|
||||||
writes and reports remaining entries as not applied. Later load failures leave
|
|
||||||
bootstrap effects in place. Reports and prepared sources retain no credential
|
|
||||||
bytes from secret files. Applications own startup ordering and concurrent
|
|
||||||
process-environment mutation under the existing bootstrap contract.
|
|
||||||
|
|
||||||
## Stage 1 — Extend shared directory bootstrap with overwrite
|
|
||||||
|
|
||||||
**Completed.**
|
|
||||||
|
|
||||||
Work in `internal/engine/secrets.go` and `internal/engine/secrets_test.go`.
|
|
||||||
|
|
||||||
1. Add a small engine options value for overwrite and keep `LoadSecretsDir`
|
|
||||||
delegating with preservation enabled. Add its options-bearing counterpart.
|
|
||||||
Extend the shared private worker and existing test seams accordingly.
|
|
||||||
2. Make overwrite affect only staging and applying values. Preserve sorted
|
|
||||||
enumeration, all metadata validation before reads, bounded reads before
|
|
||||||
writes, skipped-file behavior in preservation mode, and failure reporting.
|
|
||||||
3. Add focused behavioral cases for overwriting nonempty and empty existing
|
|
||||||
variables, overwriting with empty file content, and leaving names without
|
|
||||||
files alone. Extend the existing staged-presence-race and partial-apply-failure
|
|
||||||
cases to cover overwrite. Reuse current read-limit, dot-file, NUL, and safe
|
|
||||||
error coverage. Process-mutating tests restore state and run serially.
|
|
||||||
|
|
||||||
Stage completion means both policies work through one bootstrap worker and
|
|
||||||
existing preservation behavior remains covered. Run the relevant existing and
|
|
||||||
new `LoadSecretsDir` tests once callers compile.
|
|
||||||
|
|
||||||
## Stage 2 — Add main-scoped bootstrap control parsing
|
|
||||||
|
|
||||||
**Completed.**
|
|
||||||
|
|
||||||
Work primarily in `internal/engine/directives.go`, `acquisition.go`, and the
|
|
||||||
directive/version parsing handoffs in `source_version.go`.
|
|
||||||
|
|
||||||
1. Introduce a small private bootstrap-settings value with declaration presence,
|
|
||||||
directory text, overwrite value, and source-local diagnostic locations. Share
|
|
||||||
its field validation between preparation and normal control extraction.
|
|
||||||
2. Give extraction enough source-role information to allow these controls only
|
|
||||||
on the actual main document. `rootDirectiveContextSource` and
|
|
||||||
`rootDirectiveContextLayered` alone cannot identify that role because those
|
|
||||||
contexts also occur on contributions. Carry the role through the relevant
|
|
||||||
acquisition/version and import traversal call sites.
|
|
||||||
3. Keep bootstrap-only extraction usable before normal imports/sequence grammar
|
|
||||||
validation. The companion can prepare a main that declares imports without
|
|
||||||
enabling or acquiring them. Normal extraction checks the complete control
|
|
||||||
block and removes it before placement and application decoding.
|
|
||||||
4. Extend directive-scope and facade-control tests with main declarations,
|
|
||||||
disabled imports, wrong types, explicit false, misplaced controls, and nested
|
|
||||||
ordinary data. Verify source-version control-overlap checks recognize the
|
|
||||||
new fields and that version acceptance itself stays in the load.
|
|
||||||
|
|
||||||
Stage completion means the normal load accepts and consumes valid main settings
|
|
||||||
while leaving environment state untouched. Other source-root controls retain
|
|
||||||
their existing grammar, enablement, and error precedence.
|
|
||||||
|
|
||||||
## Stage 3 — Share host-main selection and capture
|
|
||||||
|
|
||||||
**Completed.**
|
|
||||||
|
|
||||||
Work in `internal/engine/source.go`, `parse.go`, `discovery.go`, and the initial
|
|
||||||
selection/read portion of `acquisition.go`. A focused `prepared_source.go` may
|
|
||||||
hold the new private payload and preparation helpers.
|
|
||||||
|
|
||||||
1. Factor the existing selection and bounded main parsing handoff for reuse by
|
|
||||||
normal acquisition and preparation. Reuse `resolveSearchInput`, search option
|
|
||||||
checks, `readSource`, and YAML adapter diagnostics. Keep candidate ordering,
|
|
||||||
optional exhaustion, selected-file failure, and regular-file semantics.
|
|
||||||
2. Add the captured host payload specified above. Preserve original source line
|
|
||||||
locations and all controls. Construct independent documents for subsequent
|
|
||||||
loads with `document.Clone` and `setDocumentSourceID`. Count captured bytes
|
|
||||||
under the current read limits before returning a document to acquisition.
|
|
||||||
3. For capture, resolve and validate the host base/root through existing
|
|
||||||
`filesystemOptionDiagnostics`, `resolveFilesystemContext`, and directory
|
|
||||||
validation. Store path facts without access handles or a preparation token.
|
|
||||||
4. Add internal cases proving captured data stays fixed after the original file
|
|
||||||
changes, becomes absent, or another search candidate appears. Retain ordinary
|
|
||||||
File/SearchConfig reread behavior. Cover parser/read failures and limits with
|
|
||||||
existing narrow test fixtures. Keep sources and payloads private until the
|
|
||||||
public wrapper stage.
|
|
||||||
|
|
||||||
Stage completion means the acquisition front end can consume an ordinary host
|
|
||||||
file or its captured payload through the same parsed-source handoff.
|
|
||||||
|
|
||||||
## Stage 4 — Integrate captured contexts with ordinary loading
|
|
||||||
|
|
||||||
**Completed.**
|
|
||||||
|
|
||||||
Work in `options.go`, `filesystem_context.go`, `filesystem.go`, `acquisition.go`,
|
|
||||||
`load_input.go`, `selected_overlay.go`, and `source_context.go` as needed.
|
|
||||||
|
|
||||||
1. Make context resolution select captured path facts and enforce the explicit
|
|
||||||
context equivalence rule at the shared acquisition boundary. Ensure both
|
|
||||||
imported and standalone branches receive the selected resolved context.
|
|
||||||
2. Carry the captured base/root into standalone main acquisition, ordinary
|
|
||||||
overlay resolution, and passive source-context completion. Ordinary overlays
|
|
||||||
keep their established root-relative lookup convention.
|
|
||||||
3. Preserve file-kind records, canonical paths, source-local diagnostics, and
|
|
||||||
placement projection. Reuse normal source registration and accounting.
|
|
||||||
4. Add focused internal cases for omitted/equivalent/incompatible later contexts,
|
|
||||||
explicit wider roots, a symlinked selected main, main removal, destinations,
|
|
||||||
and ordinary overlay/resource-context behavior. Compare relevant records and
|
|
||||||
values with a normal load of the same unmodified file.
|
|
||||||
|
|
||||||
Stage completion means an ordinary load uses captured contents and context
|
|
||||||
through all its normal paths. Real filesystem failures are handled at the
|
|
||||||
existing access boundaries without retaining an open handle in the source.
|
|
||||||
|
|
||||||
## Stage 5 — Integrate imports and layered main-relative consumers
|
|
||||||
|
|
||||||
**Completed.**
|
|
||||||
|
|
||||||
Work in `import_acquisition.go`, `load_request.go`, and layered/context owners
|
|
||||||
identified by the shared acquisition handoff.
|
|
||||||
|
|
||||||
1. Feed the captured main document and resolved context into imported acquisition.
|
|
||||||
Charge its raw bytes and nodes through existing accounting exactly once per
|
|
||||||
load. Keep placement wrapper accounting and per-tier repetition tracking.
|
|
||||||
2. Treat the captured main as the same canonical host file for repeated-file and
|
|
||||||
cycle checks. A fresh load gets its own host namespace and source IDs.
|
|
||||||
3. Ensure layered acquisition propagates the captured main context to declared
|
|
||||||
MainRelative underlays and selected overlays, with existing explicit context
|
|
||||||
and fallback precedence. Preserve main-first acquisition and tier precedence.
|
|
||||||
4. Verify live imports after main capture, repeat/cycle detection involving the
|
|
||||||
captured main, source/version evidence with imports, an explicitly wider root
|
|
||||||
permitting contained parent-relative imports, and independent repeated loads.
|
|
||||||
Include one integrated layered case with a main-relative underlay and overlay.
|
|
||||||
Use existing import/placement/version suites for unchanged semantics.
|
|
||||||
|
|
||||||
Stage completion means prepared main sources behave as host main inputs across
|
|
||||||
ordinary and layered composition, metadata, and main-relative bindings.
|
|
||||||
|
|
||||||
## Stage 6 — Implement configured bootstrap orchestration
|
|
||||||
|
|
||||||
**Completed.**
|
|
||||||
|
|
||||||
Add a focused engine companion in `secrets_from_config.go`, using the capture
|
|
||||||
and bootstrap helpers from earlier stages.
|
|
||||||
|
|
||||||
1. Validate and snapshot options, resolve the main, capture its document and
|
|
||||||
context, and extract bootstrap settings. Return the no-directory and absent
|
|
||||||
cases under the public return contract. A valid Go overwrite override does
|
|
||||||
not bypass validation of malformed YAML bootstrap fields.
|
|
||||||
2. Join the declared directory to the captured base. Add an optional internal
|
|
||||||
containment-root constraint to shared directory preparation so canonical
|
|
||||||
resolution and containment validation occur before the worker uses that
|
|
||||||
canonical directory. Direct-directory calls supply no such constraint.
|
|
||||||
3. Select overwrite using Go, YAML, then false, and invoke the shared worker.
|
|
||||||
Return the prepared source only after successful bootstrap. All branches
|
|
||||||
return the non-nil report and appropriate existing error family.
|
|
||||||
4. Test no declaration, overwrite without a directory, optional/required missing
|
|
||||||
main, unsupported source/context, malformed controls, missing or outside-root
|
|
||||||
directory, and directory symlink containment. Assert empty/partial reports and
|
|
||||||
zero prepared sources on errors. Use the existing environment seam for
|
|
||||||
deterministic apply failures and verify safe error/report output.
|
|
||||||
|
|
||||||
Stage completion means configured bootstrap can finish independently of schema,
|
|
||||||
imports, version hooks, resolution, and validation, returning a reusable main
|
|
||||||
only when its own operation succeeds.
|
|
||||||
|
|
||||||
## Stage 7 — Expose root-owned APIs and convert both error families
|
|
||||||
|
|
||||||
**Completed.**
|
|
||||||
|
|
||||||
Work in root `secrets.go`, `source.go`, and existing facade conversion owners.
|
|
||||||
|
|
||||||
1. Add the two options types and new functions with the signatures above. Keep
|
|
||||||
the existing function type intact and route its default behavior through the
|
|
||||||
shared bootstrap implementation.
|
|
||||||
2. Convert the companion's report, prepared engine Source, and errors to the
|
|
||||||
existing public wrappers. Preserve `LoadError` source records as well as
|
|
||||||
diagnostics. Preserve `SecretsError` without exposing underlying filesystem
|
|
||||||
or environment errors. Add only the small conversion logic this boundary
|
|
||||||
needs, reusing existing converters.
|
|
||||||
3. Document signatures, options precedence, reports, error types, and source
|
|
||||||
ownership on their declarations. Explain captured reuse versus File/SearchConfig
|
|
||||||
reuse in Source's documentation. Keep implementation types private.
|
|
||||||
4. Add facade tests for both new functions and assignment of the old function to
|
|
||||||
`func(string) (*SecretsReport, error)`. Exercise YAML true with explicit Go
|
|
||||||
false, YAML false with Go true, omitted choices, and multiple options. Verify
|
|
||||||
public `errors.As` behavior for preparation and bootstrap failures.
|
|
||||||
|
|
||||||
Stage completion means applications can use the complete two-call startup flow
|
|
||||||
through ConfigKit's public package with the documented ownership and errors.
|
|
||||||
|
|
||||||
## Stage 8 — Verify the complete startup handoff
|
|
||||||
|
|
||||||
**Completed.**
|
|
||||||
|
|
||||||
Extend public integration coverage and add one maintained consumer startup
|
|
||||||
example with ordinary and layered use explained from the same helper.
|
|
||||||
|
|
||||||
1. Start in a different working directory, discover a main with relative secrets,
|
|
||||||
bootstrap all eligible entries including an SDK-only name, and load the
|
|
||||||
prepared source. Verify configured overwrite and existing empty-variable
|
|
||||||
behavior with disposable environment names.
|
|
||||||
2. Change the main, discovery candidates, an import, and an environment value
|
|
||||||
after preparation. Verify captured main values, live import values, fresh
|
|
||||||
environment lookup, and independent metadata/results across subsequent loads.
|
|
||||||
Include selected-main provenance and source resource context assertions.
|
|
||||||
3. Exercise the layered handoff with explicit root preparation and companion
|
|
||||||
inputs. Confirm compatible later context succeeds and incompatible context
|
|
||||||
fails safely after the already-completed bootstrap.
|
|
||||||
4. Show a later version/decoding or validation failure preserves the bootstrap
|
|
||||||
report and environment effects. Separately verify ordinary Load/LoadLayered
|
|
||||||
on a main containing the controls perform no environment writes, even with
|
|
||||||
YAML overwrite true. Existing secret-resolution tests continue to own
|
|
||||||
credential lookup and redaction behavior.
|
|
||||||
5. Verify captured sources retain no handles through successful and failed
|
|
||||||
preparation. Use existing resource-lifetime techniques and narrow seams,
|
|
||||||
avoiding a new filesystem framework. Exercise independent captured-source
|
|
||||||
loads under the race detector without concurrent process mutation.
|
|
||||||
|
|
||||||
Stage completion means the feature works through normal entry points and its
|
|
||||||
integration risks are covered without duplicating every internal test at the
|
|
||||||
facade boundary.
|
|
||||||
|
|
||||||
## Stage 9 — Update canonical documentation and validate the sprint
|
|
||||||
|
|
||||||
**Completed.**
|
|
||||||
|
|
||||||
1. Update `docs/config.md` with the two main controls, preparation and bootstrap
|
|
||||||
boundaries, lookup timing, overwrite precedence, reports/errors, host scope,
|
|
||||||
and prepared-source reuse/context behavior. Keep source-local controls
|
|
||||||
distinct from application paths and preserve existing loading semantics.
|
|
||||||
2. Update `docs/consumers/README.md` and its test map to link the new maintained
|
|
||||||
example. Update `docs/development.md` only where navigation/test ownership
|
|
||||||
changes. Explain internal capture and acquisition handoffs in
|
|
||||||
`docs/internal/overview.md` and relevant import documentation.
|
|
||||||
3. Update the implemented-behavior paragraphs in architecture policy and retire
|
|
||||||
its roadmap implementation-status link. Keep ADR 0023's accepted decision
|
|
||||||
text intact. Preserve the existing bootstrap limits and concurrency/rollback
|
|
||||||
contract while documenting explicit overwrite as the selected extension.
|
|
||||||
4. Format changed Go files and run the focused tests for changed owners. Run
|
|
||||||
`./scripts/check.sh` and `go test -race ./...` on the completed implementation.
|
|
||||||
Verify edited Markdown links and headings, exported declaration comments,
|
|
||||||
and the public example. Reuse successful checks for unchanged content.
|
|
||||||
5. Review the final diff for captured-state aliasing, handles, extra parsing or
|
|
||||||
discovery, secret disclosure, omitted accounting, and accidental changes to
|
|
||||||
current configuration processing or helper signatures. Resolve failures and
|
|
||||||
finish the documented target before marking the sprint complete.
|
|
||||||
|
|
||||||
The final result is the implemented feature with current documentation and
|
|
||||||
appropriate behavioral coverage. Release preparation follows its separate
|
|
||||||
procedure when requested.
|
|
||||||
@@ -1,209 +0,0 @@
|
|||||||
# Main-relative secrets directories
|
|
||||||
|
|
||||||
Status: implemented. [ADR 0023](../adr/0023-explicit-configured-secrets-bootstrap.md)
|
|
||||||
supersedes ADR 0004 and records explicit configured bootstrap and optional
|
|
||||||
overwrite. The decisions below preserve ordinary loading without environment
|
|
||||||
writes and the existing direct-directory helper's Go signature.
|
|
||||||
|
|
||||||
## Motivation and baseline
|
|
||||||
|
|
||||||
Applications can use `SearchConfig` to select their main configuration file
|
|
||||||
during a load. They can also call `LoadSecretsIntoEnvironment` during startup,
|
|
||||||
but that helper takes a native directory path before the load begins. A relative
|
|
||||||
argument uses the process working directory. Using a directory beside the
|
|
||||||
discovered file therefore requires the application to take over main-file
|
|
||||||
selection or perform a preliminary load. [Configuration discovery](../config.md#configuration-discovery) · [Secrets bootstrap](../config.md#explicit-secrets-directory-bootstrap)
|
|
||||||
|
|
||||||
ConfigKit already retains filesystem context for acquired main files and binds
|
|
||||||
companion inputs to that context. Typed `Secret` references read the environment
|
|
||||||
after application resolution and before final validation. A companion bootstrap
|
|
||||||
helper can use the main's context before loading while preserving this
|
|
||||||
processing order. [Main-relative contexts](../adr/0022-main-relative-context.md) · [Typed secret references](../config.md#typed-secret-references)
|
|
||||||
|
|
||||||
## Target behavior
|
|
||||||
|
|
||||||
### Declaration and path resolution
|
|
||||||
|
|
||||||
An application explicitly calls a companion to
|
|
||||||
`LoadSecretsIntoEnvironment` before `Load` or `LoadLayered`. The selected main
|
|
||||||
document supplies the directory and overwrite policy through its root control
|
|
||||||
mapping. For example, the following declaration in `/etc/demo/config.yml`
|
|
||||||
selects `/etc/demo/secrets` and authorizes replacement of existing variables
|
|
||||||
when the companion helper is called.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
config:
|
|
||||||
secrets_dir: secrets
|
|
||||||
secrets_overwrite: true
|
|
||||||
|
|
||||||
api_key: DEMO_API_KEY
|
|
||||||
```
|
|
||||||
|
|
||||||
Interpret these fields at the main document's root before placement and
|
|
||||||
composition. They are bootstrap settings consumed as document controls.
|
|
||||||
`Load` and `LoadLayered` recognize the controls and perform their usual
|
|
||||||
environment lookup without invoking bootstrap. The companion helper call is
|
|
||||||
the explicit authorization for environment writes.
|
|
||||||
|
|
||||||
Only the main document selects the bootstrap directory and YAML overwrite
|
|
||||||
policy. Diagnose these controls in unsupported source-control contexts.
|
|
||||||
Nested application data follows the existing `config` rules. Imports,
|
|
||||||
underlays, overlays, CLI overrides, and application resolution retain their
|
|
||||||
ordinary effects on application configuration. They do not redirect this
|
|
||||||
bootstrap operation.
|
|
||||||
|
|
||||||
`secrets_overwrite` is an optional Boolean with a default of `false`.
|
|
||||||
An explicitly supplied Go overwrite choice takes precedence over YAML,
|
|
||||||
including when that choice is `false`. If the main supplies no directory,
|
|
||||||
bootstrap is a no-op and the prepared main can still be loaded. An optional
|
|
||||||
search that finds no main preserves the existing absent-main lifecycle.
|
|
||||||
|
|
||||||
Resolve the directory from the selected main file's canonical base within its
|
|
||||||
existing filesystem root. For a discovered symlink, the base is the selected
|
|
||||||
file's canonical target directory. Parent-relative paths follow the same
|
|
||||||
containment rule as other main-relative inputs. The declaration must be a
|
|
||||||
nonempty relative path and requires a usable main-file context. Keep the
|
|
||||||
declaration and any diagnostics in source-local coordinates. [Document-root controls](../adr/0020-document-root-controls.md) · [Layered loading](../config.md#layered-loading)
|
|
||||||
|
|
||||||
### Companion helper and prepared main source
|
|
||||||
|
|
||||||
The companion accepts the main `Source`, including a `SearchConfig` source,
|
|
||||||
and returns a secrets report and a prepared main source. Its options accept an
|
|
||||||
explicit host `FilesystemContext` for main preparation and an optional overwrite
|
|
||||||
choice. Represent overwrite as `*bool`: nil defers to YAML, while a supplied
|
|
||||||
false or true takes precedence. The public names below are illustrative.
|
|
||||||
|
|
||||||
```go
|
|
||||||
main := configkit.SearchConfig("demo", search)
|
|
||||||
report, preparedMain, err := configkit.LoadSecretsIntoEnvironmentFromConfig(main)
|
|
||||||
if err != nil {
|
|
||||||
// Handle the bootstrap failure and inspect report.
|
|
||||||
return err
|
|
||||||
}
|
|
||||||
result, err := configkit.Load[AppConfig](preparedMain)
|
|
||||||
```
|
|
||||||
|
|
||||||
For layered loading, supply the prepared source as the main `Input.Source`.
|
|
||||||
The helper resolves discovery once, reads the selected main document, extracts
|
|
||||||
the bootstrap controls, and performs bootstrap. It returns the captured main
|
|
||||||
contents with the selected file's identity and filesystem context so the later
|
|
||||||
load consumes that same main document. Keep its remaining controls, including
|
|
||||||
imports and collection declarations, available to normal loading.
|
|
||||||
|
|
||||||
Apply the supplied host context using the existing main-file root rules during
|
|
||||||
preparation. Without an explicit context, derive the usual context from the
|
|
||||||
selected main file. Capture the resolved canonical base and containment root
|
|
||||||
with the document. Later loading uses that captured context when no explicit
|
|
||||||
context is supplied. An explicit later context must resolve to the same context;
|
|
||||||
diagnose an incompatible context rather than silently rebinding the prepared
|
|
||||||
source. A caller needing a different root prepares the original source again.
|
|
||||||
This rule applies to ordinary loading options and layered main `Input` alike.
|
|
||||||
|
|
||||||
The helper prepares only the main document. Composition, import acquisition,
|
|
||||||
inheritance, typed decoding, application resolution, secret lookup, and
|
|
||||||
validation run through the subsequent ordinary or layered load. Main
|
|
||||||
preparation must retain the applicable source limits and root constraints.
|
|
||||||
Source records, diagnostics, placements, imports, and main-relative companions
|
|
||||||
use the selected main's identity and context.
|
|
||||||
|
|
||||||
Release library-owned file handles before the helper returns, including on
|
|
||||||
error. Prepared sources are reusable snapshots of the main contents, with
|
|
||||||
passive filesystem context and no shared mutable load state. Reusing one neither
|
|
||||||
rediscovers nor rereads the main file and does not repeat bootstrap. This differs
|
|
||||||
from reusing the original `File` or `SearchConfig` source. Later imports and
|
|
||||||
resources observe the filesystem when accessed. A later load reads the environment
|
|
||||||
at its normal secret-resolution step. Each load accounts for the captured main
|
|
||||||
under its normal source limits and creates its own source and inspection records.
|
|
||||||
[Complete-on-return loading](../adr/0008-complete-on-return-loading.md) · [Source resource contexts](../config.md#source-resource-contexts)
|
|
||||||
|
|
||||||
### Preparation failures and return values
|
|
||||||
|
|
||||||
Use the existing error families at their respective boundaries. Discovery,
|
|
||||||
main-file acquisition, YAML parsing, bootstrap-control validation, and preparation
|
|
||||||
context failures return `LoadError` with applicable source records and source-local
|
|
||||||
diagnostics. Secret-directory inspection, reads, and environment writes return
|
|
||||||
`SecretsError` with the existing safe diagnostics. Do not introduce another error
|
|
||||||
or reporting framework.
|
|
||||||
|
|
||||||
Return a secrets report on every attempt. Before directory processing begins,
|
|
||||||
it has no entries; after processing begins, it retains the entries and outcomes
|
|
||||||
observed so far. On any error, return a zero, unusable prepared `Source`. Earlier
|
|
||||||
environment writes remain reported and are not rolled back. A caller must handle
|
|
||||||
the failure before attempting configuration loading.
|
|
||||||
|
|
||||||
On success, return a reusable prepared source, including when no directory was
|
|
||||||
declared. Optional search exhaustion returns the absent-main source and an empty
|
|
||||||
report. Preparation validates YAML and the bootstrap settings needed for its
|
|
||||||
operation; it does not claim the later configuration load will succeed. Normal
|
|
||||||
version checks, composition, decoding, and application validation remain in that
|
|
||||||
load. A later incompatible-context error is a loading error and does not undo
|
|
||||||
bootstrap writes.
|
|
||||||
|
|
||||||
### Shared bootstrap and overwrite behavior
|
|
||||||
|
|
||||||
Keep `LoadSecretsIntoEnvironment(string) (*SecretsReport, error)` unchanged,
|
|
||||||
including its nonvariadic function type and preservation behavior. Add a separately
|
|
||||||
named options-bearing helper for explicit overwrite. Changing the existing helper
|
|
||||||
to accept variadic options would preserve ordinary calls but break assignments to
|
|
||||||
its existing function type. The new public names below are provisional.
|
|
||||||
|
|
||||||
```go
|
|
||||||
report, err := configkit.LoadSecretsIntoEnvironment("/etc/demo/secrets")
|
|
||||||
report, err = configkit.LoadSecretsIntoEnvironmentWithOptions(
|
|
||||||
"/etc/demo/secrets",
|
|
||||||
configkit.SecretsOptions{Overwrite: true},
|
|
||||||
)
|
|
||||||
```
|
|
||||||
|
|
||||||
The existing helper, options-bearing helper, and main-config companion use the
|
|
||||||
same directory-bootstrap implementation. The direct helper's Boolean option
|
|
||||||
defaults to false; it has no YAML policy to override. With overwrite
|
|
||||||
disabled, existing variables win, including empty ones, with presence checked
|
|
||||||
again immediately before application as today. With overwrite enabled,
|
|
||||||
eligible files are read even for existing variables and their values replace
|
|
||||||
those variables. Variables without a corresponding file are left alone.
|
|
||||||
An applied empty file supplies an empty value in either mode.
|
|
||||||
|
|
||||||
Bootstrap processes the directory's eligible entries, including credentials
|
|
||||||
used by SDKs or subprocesses outside typed `Secret` fields. Reuse the existing
|
|
||||||
dot-entry handling, file checks, content rules, limits, and filename ordering.
|
|
||||||
Validate metadata and read all content needed by the chosen overwrite policy
|
|
||||||
before beginning writes.
|
|
||||||
Directory and file failures produce the existing safe reporting behavior.
|
|
||||||
The secrets report identifies writes, skips, and partial failures without
|
|
||||||
retaining credential bytes.
|
|
||||||
|
|
||||||
Call bootstrap during startup before starting concurrent work. Successful
|
|
||||||
bootstrap precedes configuration loading and validation. A later load failure
|
|
||||||
leaves the completed environment writes in place. A bootstrap write failure
|
|
||||||
stops further writes, leaves earlier writes in place, and reports remaining
|
|
||||||
entries as `not_applied`. The existing lack of rollback and concurrent
|
|
||||||
environment transaction guarantees continues to apply.
|
|
||||||
|
|
||||||
Keep bootstrap reporting separate from the subsequent configuration's secret
|
|
||||||
lookup evidence. Each operation describes what it observed and performed.
|
|
||||||
[Secrets bootstrap](../config.md#explicit-secrets-directory-bootstrap) · [Explicit configured bootstrap](../adr/0023-explicit-configured-secrets-bootstrap.md)
|
|
||||||
|
|
||||||
### Filesystem scope
|
|
||||||
|
|
||||||
Support discovered and explicitly selected host files, including their existing
|
|
||||||
main-root options. This covers the requested deployment pattern and reuses the
|
|
||||||
native secret-file checks. Caller-supplied filesystem support is a possible
|
|
||||||
later extension requiring decisions about file-type and symlink capabilities.
|
|
||||||
|
|
||||||
## Target integration
|
|
||||||
|
|
||||||
Main-file selection and bounded capture are shared with normal acquisition.
|
|
||||||
The prepared source carries the main contents, identity, and context through
|
|
||||||
ordinary and layered loading with normal placement, accounting, and source
|
|
||||||
records. Directory bootstrap has one implementation behind the existing helper,
|
|
||||||
the options-bearing helper, and the configured companion.
|
|
||||||
|
|
||||||
Canonical configuration and public source documentation describe the two-call
|
|
||||||
startup flow, capture lifetime, and overwrite policy. Consumer examples and
|
|
||||||
behavioral tests cover discovery, prepared-source reuse, relative inputs,
|
|
||||||
failure reporting, environment effects, and ordinary loading's boundaries under
|
|
||||||
the [testing policy](../policy/testing.md).
|
|
||||||
|
|
||||||
The [implementation plan](implementation.md) owns the selected API names,
|
|
||||||
execution stages, and validation work needed to reach this target.
|
|
||||||
Reference in New Issue
Block a user