diff --git a/docs/config.md b/docs/config.md index e735fc0..91457c7 100644 --- a/docs/config.md +++ b/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 | | 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 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 deliberately named `Value()` accessor and distinguish success with `IsResolved()`. 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 -writes to the environment. +so a previously resolved result cannot retain a stale credential. `Load` and +`LoadLayered` never write to the environment. 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 @@ -1078,17 +1078,80 @@ reference state without printing its value. ## Explicit secrets-directory bootstrap -If an application stores credentials in files, it can call this helper before -loading configuration. A file named `DEMO_API_KEY` containing the dummy text +If an application stores credentials in files, it can explicitly bootstrap +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 refer to that variable with `api_key: DEMO_API_KEY`. Applications that already receive environment variables do not need this file step. -Existing environment variables take priority over files. If `DEMO_API_KEY` is -already set to an empty string, its file is skipped and it stays empty. A later +By default existing environment variables take priority over files. If +`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 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: @@ -1101,18 +1164,20 @@ Read the report even when the helper returns an error: Render the returned `SecretsReport` separately from a later configuration load. It contains filenames, paths, and statuses, not credential contents. The -[maintained startup example](../examples/consumers/consumers_test.go) shows how to -keep bootstrap and configuration reports together in the application. +[configured startup example](../examples/consumers/secrets.go) prepares a source +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 -`LoadSecretsIntoEnvironment(directory)` is a separate, opt-in startup operation. -It is never called by `Load`, is not a YAML option, and does not participate in -configuration validation. Applications choose the native directory path and -should invoke the operation once before starting concurrent work. The selected -path may itself be a symlink; ConfigKit resolves it to an existing canonical -directory before examining -its immediate entries. +All bootstrap helpers are separate, opt-in startup operations. They are never +called by a configuration load and do not perform configuration validation. +Applications own startup ordering and should invoke bootstrap before concurrent +work or other process-environment mutation. The direct helpers accept a native +directory path; the configured helper resolves the declared path as described +above. The selected path may itself be a symlink; ConfigKit resolves it to an +existing canonical directory before examining its immediate 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` @@ -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 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 -or process state is changed. Existing environment variables win, including variables whose -value is empty; their files are not opened. Each eligible file is limited to 1 MiB, -and eligible content is limited to 8 MiB in total. ConfigKit removes exactly one +or process state is changed. In preservation mode existing environment variables +win, including variables whose value is empty; their files are not opened. In +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 rejects NUL bytes. -All eligible files are read successfully before application begins. Presence is -checked again immediately before each `os.Setenv`: a variable populated since -preflight is skipped. A write failure stops application without rollback, so prior -writes remain and later eligible entries are `not_applied`. This operation is not +All required files are read successfully before application begins. In +preservation mode presence is checked again immediately before each `os.Setenv`: +a variable populated since preflight is skipped. Overwrite mode applies the +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 mutation. @@ -1137,9 +1204,11 @@ mutation. records with `loaded`, `skipped_existing`, `not_applied`, or `failed` status. `ExistingEmpty` distinguishes an empty existing winner. `SecretsReport.WriteTo` 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 -report with a `*SecretsError` containing detached `secrets.*` diagnostics and no -raw filesystem or environment error chain. Applications should retain the report +it never retains or renders file contents. Directory and environment failures +return the non-nil partial report with a `*SecretsError` containing detached +`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 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 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 -`sequences` without enabling imports, but an `imports` field still requires +`config` mapping for `imports` and `sequences` controls. The main root may also +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 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; diff --git a/docs/consumers/README.md b/docs/consumers/README.md index 5db38c9..26dcb8a 100644 --- a/docs/consumers/README.md +++ b/docs/consumers/README.md @@ -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` | diff --git a/docs/development.md b/docs/development.md index 2762999..41295f2 100644 --- a/docs/development.md +++ b/docs/development.md @@ -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'` | | 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'` | -| 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$'` | | 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` | diff --git a/docs/internal/imports.md b/docs/internal/imports.md index cdc23d4..91d8e1d 100644 --- a/docs/internal/imports.md +++ b/docs/internal/imports.md @@ -27,6 +27,16 @@ Contextless bindings prepare declaration policies and assemble the declaring payload without opening filesystem access or recording selection evidence. 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. 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 diff --git a/docs/internal/overview.md b/docs/internal/overview.md index b7c7c39..9786d5d 100644 --- a/docs/internal/overview.md +++ b/docs/internal/overview.md @@ -125,6 +125,16 @@ for passive-context construction and ordinary-overlay handling: see [`filesystem_context.go`](../../internal/engine/filesystem_context.go) and [`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 normalization in [`import_selection.go`](../../internal/engine/import_selection.go), source reading and traversal admission in diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 74fbd10..715893c 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -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 configuration overlays are an explicit non-goal. Bootstrap preserves already set variables by default, including empty ones, and reports blocked files without -contents. [ADR 0023](../adr/0023-explicit-configured-secrets-bootstrap.md) permits -explicit overwrite and main-document-directed bootstrap as a separate startup -operation. Its implementation is tracked in the -[secrets-directory roadmap](../roadmap/secrets-directory.md); the -[configuration contract](../config.md#explicit-secrets-directory-bootstrap) +contents. Explicit overwrite and main-document-directed bootstrap are available +as separate startup operations. A prepared main retains its selected document +and passive filesystem context without retaining secret-file contents or open +handles. [ADR 0023](../adr/0023-explicit-configured-secrets-bootstrap.md) records +the decision; the [configuration contract](../config.md#explicit-secrets-directory-bootstrap) owns current behavior. Secrets must be considered throughout error handling and inspection. Library diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 4bb1338..e8c5834 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -368,6 +368,8 @@ 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 diff --git a/docs/roadmap/secrets-directory.md b/docs/roadmap/secrets-directory.md index 995a4f1..b4eb9cd 100644 --- a/docs/roadmap/secrets-directory.md +++ b/docs/roadmap/secrets-directory.md @@ -1,6 +1,6 @@ # 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 overwrite. The decisions below preserve ordinary loading without environment writes and the existing direct-directory helper's Go signature. diff --git a/internal/engine/directive_scope_test.go b/internal/engine/directive_scope_test.go index 4d53996..8f9cb89 100644 --- a/internal/engine/directive_scope_test.go +++ b/internal/engine/directive_scope_test.go @@ -2,6 +2,7 @@ package engine import ( "reflect" + "runtime" "testing" "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) { root := parseRootDirectiveDocument(t, "config: {secrets_dir: secrets, secrets_overwrite: true}\nvalue: ordinary\n") for _, context := range []rootDirectiveContext{rootDirectiveContextSource, rootDirectiveContextLayered} { diff --git a/internal/engine/directives.go b/internal/engine/directives.go index e718abc..ef5d7ad 100644 --- a/internal/engine/directives.go +++ b/internal/engine/directives.go @@ -1,6 +1,7 @@ package engine import ( + "os" "path" "path/filepath" "strings" @@ -66,7 +67,7 @@ func parseBootstrapField(settings *bootstrapSettings, entry document.Entry) *Dia value := entry.Value fieldPath := Keys(directiveKey, entry.Key) 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) return &diagnostic } diff --git a/internal/engine/prepared_source.go b/internal/engine/prepared_source.go index 0659d5a..80080f9 100644 --- a/internal/engine/prepared_source.go +++ b/internal/engine/prepared_source.go @@ -40,9 +40,9 @@ func captureHostMain(source Source, context *FilesystemContext) (Source, []Sourc if context.FS != nil { 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) if len(diagnostics) != 0 { diff --git a/internal/engine/secrets_from_config_test.go b/internal/engine/secrets_from_config_test.go index ad7a486..e73b722 100644 --- a/internal/engine/secrets_from_config_test.go +++ b/internal/engine/secrets_from_config_test.go @@ -89,6 +89,7 @@ func TestSecretsFromConfigReportsPreparationFailures(t *testing.T) { {"missing file", File(missing), nil, CodeSourceMissing}, {"required search", SearchConfig("app", Paths(missing), SearchOptions{Required: true}), nil, CodeSourceMissing}, {"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}, {"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 { 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()) + } }) } } diff --git a/secrets.go b/secrets.go index 1599364..a49a979 100644 --- a/secrets.go +++ b/secrets.go @@ -7,8 +7,8 @@ import ( "go.maximumdirect.net/configkit/internal/engine" ) -// SecretFileStatus describes the outcome for one file considered by -// LoadSecretsIntoEnvironment. +// SecretFileStatus describes the outcome for one file considered by an +// explicit secrets bootstrap helper. type SecretFileStatus string const ( @@ -102,8 +102,10 @@ type SecretsOptions struct { } // LoadSecretsIntoEnvironmentWithOptions loads immediate regular files into the -// environment using the selected policy. It returns a report even on error; -// applied values are not rolled back. Errors are reported as *SecretsError. +// environment using the selected policy. With Overwrite false it preserves +// 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) { report, err := engine.LoadSecretsDirWithOptions(directory, engine.SecretsDirOptions{Overwrite: options.Overwrite}) 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 // report. The returned source owns a reusable main-document snapshot and its // 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 // result. Preparation failures return *LoadError; directory or environment // failures return *SecretsError. Any error returns a zero Source and does not