45 Commits

Author SHA1 Message Date
4a7ae664a6 Remove retired roadmap references from development guide 2026-11-21 12:36:10 +00:00
eaace5bd10 Retire completed result inspection roadmaps 2026-11-21 12:33:28 +00:00
174e030dad Write ConfigKit v1.4.0 release notes 2026-11-21 12:32:27 +00:00
1305f2b9e9 Avoid metadata copies during scoped path enumeration 2026-11-21 12:01:47 +00:00
d6fcfc62d9 Clarify result value lookup semantics 2026-11-21 12:01:02 +00:00
ed5d57d061 Preserve terminal values during result lookup 2026-11-21 12:00:29 +00:00
bcee3f866f Record scoped enumeration efficiency finding 2026-11-21 04:33:34 +00:00
a57afc7d69 Record result access review findings 2026-11-21 04:21:25 +00:00
7a9ce01064 Document value access and focused inspection 2026-11-21 04:16:46 +00:00
37f38f3e54 Demonstrate composing two component consumers 2026-11-21 04:13:27 +00:00
ace9f98072 Demonstrate component result handoff 2026-11-21 04:12:15 +00:00
51e15753eb Verify scoped inspection history and provenance 2026-11-21 04:10:56 +00:00
b5e1c11c4a Compare focused inspection views 2026-11-21 04:09:41 +00:00
db743a4b3d Render focused inspection values safely 2026-11-21 04:07:57 +00:00
68a6da2388 Add scoped inspection views 2026-11-21 04:06:45 +00:00
f514936c9c Expose current configuration values 2026-11-21 04:05:27 +00:00
654fe9d306 Add current configuration value navigation 2026-11-21 04:03:37 +00:00
b3799be2fa Remove superseded consumer request 2026-11-21 04:00:27 +00:00
229ad5bfe7 Plan typed result access and focused inspection 2026-11-21 03:54:39 +00:00
afe83a6fd2 Record inspection comparison across application types 2026-11-21 03:37:15 +00:00
86a9060418 Settle canonical reporting scope identity 2026-11-21 03:20:20 +00:00
d11e749428 Settle inspection APIs and review roadmap consistency 2026-11-21 03:17:32 +00:00
4c2620c68b Settle dynamic value traversal using existing type rules 2026-11-21 03:12:59 +00:00
41622c54e0 Settle value access for manually constructed results 2026-11-21 03:07:14 +00:00
48e7f943d9 Add focused inspection to the result access roadmap 2026-11-21 03:00:57 +00:00
472ac551c2 Plan typed value access from configuration results 2026-11-21 02:26:31 +00:00
652ddb649c Clarify repeated bootstrap for prepared sources 2026-11-18 15:17:17 +00:00
a33522ddca Draft ConfigKit v1.3.0 release notes 2026-11-18 15:07:41 +00:00
3f58d44e96 Remove completed secrets bootstrap plans 2026-11-18 15:06:06 +00:00
eeafc356e4 Document and validate configured secrets bootstrap 2026-11-18 01:10:24 +00:00
ab6e610fb7 Verify configured secrets startup handoff 2026-11-18 01:00:16 +00:00
60bcb6ddac Expose configured secrets bootstrap APIs 2026-11-18 00:54:42 +00:00
ea1f2a808d Prepare configured secrets before loading 2026-11-18 00:51:23 +00:00
649a63fff1 Verify captured imports and layered companions 2026-11-18 00:47:56 +00:00
e750b6d423 Preserve captured filesystem contexts during loading 2026-11-18 00:44:59 +00:00
a3c77f32f2 Capture selected host configuration sources 2026-11-18 00:41:44 +00:00
a9c72c1b67 Parse main-scoped secrets bootstrap controls 2026-11-18 00:37:16 +00:00
7b4fcf224a Support overwriting secrets from a directory 2026-11-18 00:29:56 +00:00
df6c3df67d Plan configured secrets bootstrap implementation 2026-11-18 00:26:00 +00:00
fb0560d888 Record explicit configured secrets bootstrap and refine its roadmap 2026-11-18 00:16:53 +00:00
e1336f74e5 Revise secrets roadmap around explicit configuration bootstrap 2026-11-17 22:28:16 +00:00
20a1087e25 Describe main-relative secrets directory support 2026-11-17 21:55:14 +00:00
51ef314415 Write ConfigKit v1.2.1 release notes 2026-11-17 15:54:24 +00:00
00efe90236 Upgrade ReleaseKit to v0.10.0 2026-11-17 15:48:53 +00:00
8aa91e8f0a Upgrade go-yaml to v4.0.0 2026-11-17 15:11:00 +00:00
63 changed files with 3246 additions and 294 deletions

View File

@@ -50,6 +50,8 @@ Start with one file. Optional features use the same loading and inspection model
references and choose which configuration fields to hide in inspection output.
- [Inspect a load](docs/config.md#layered-metadata): examine sources, presence,
history, safe YAML output, or [changes between two loads](docs/config.md#effective-configuration-diffs).
- [Hand settings to libraries](docs/consumers/README.md#component-handoff): share
one result and let each consumer select its own settings and reporting scope.
The [consumer guide](docs/consumers/README.md) walks through these tasks and links
to maintained examples. The [configuration reference](docs/config.md) defines the

View File

@@ -40,6 +40,10 @@ func Diff[T any](left, right *Result[T]) ([]Difference, error) {
if err != nil {
return nil, err
}
return fromEngineDifferences(values), nil
}
func fromEngineDifferences(values []engine.Difference) []Difference {
differences := make([]Difference, len(values))
for index, value := range values {
differences[index] = Difference{
@@ -49,5 +53,5 @@ func Diff[T any](left, right *Result[T]) ([]Difference, error) {
HiddenChanged: value.HiddenChanged,
}
}
return differences, nil
return differences
}

View File

@@ -1,6 +1,6 @@
# ADR 0004: Use secret references and explicit environment bootstrap
Status: accepted
Status: superseded by [ADR 0023](0023-explicit-configured-secrets-bootstrap.md).
Date: 2026-09-06

View File

@@ -2,7 +2,10 @@
## Status
Accepted and implemented. The
Accepted and implemented. Extended by
[ADR 0024](0024-compare-inspection-views-across-application-types.md) for inspection
view comparison across application Go types. The existing same-type comparison
API continues to follow this decision. The
[configuration contract](../config.md#effective-configuration-diffs) owns current
behavior. Completed planning and remediation records are preserved in Git
history at `1c2610c` under `docs/roadmap/`.

View File

@@ -0,0 +1,60 @@
# ADR 0023: Keep Configured Secrets Bootstrap Explicit
## Status
Accepted. Supersedes [ADR 0004](0004-secret-references-and-explicit-bootstrap.md).
## Date
2026-11-18
## Context
Applications may discover their main configuration file during startup and keep
secret files beside it. Requiring applications to discover and parse that file
separately duplicates ConfigKit's work. Some deployments also need secret files
to replace environment values that are already set.
## Decision
Keep secrets as typed references to environment-variable names. Resolve surviving
references and keep credential values out of configuration trees, history, and
inspection. Applications own credential use.
Directory bootstrap remains a separate startup operation that the application
must call explicitly. Ordinary configuration loading never writes the process
environment. The application may supply the directory directly or authorize
bootstrap from settings in the selected main document. Imports, underlays,
overlays, and later application processing do not choose those settings.
When bootstrap uses the main document, ConfigKit selects and captures that
document and its filesystem context for subsequent loading. This keeps bootstrap
and loading tied to the same main contents and location. It does not snapshot
later imports, resources, or the environment.
Preserve existing environment variables by default, including empty values.
Allow an explicit overwrite choice. An application-supplied choice takes
precedence over the main document's choice, including an explicit choice to
preserve existing values.
Keep bootstrap reports separate from later secret-lookup evidence. Report
writes, skips, and partial failures without credential values. Bootstrap offers
no rollback or transaction across environment variables and no protection
against concurrent environment mutation. General environment-variable
configuration overlays remain outside this model.
## Alternatives Considered
- Leave discovery and parsing to applications. This preserves duplicate startup
infrastructure and can select different main contents for bootstrap and loading.
- Run bootstrap inside ordinary loading. This hides process mutation in an
operation applications may repeat or run concurrently.
- Always preserve existing environment values. This keeps one precedence rule
but prevents deployments from explicitly choosing provisioned files instead.
## Consequences
Applications retain control of startup ordering and environment writes.
ConfigKit owns main-source capture, bounded secret-file loading, and safe
reporting. A later configuration failure leaves completed bootstrap writes in
place. Existing callers retain the preservation default.

View File

@@ -0,0 +1,51 @@
# ADR 0024: Compare Inspection Views Across Application Types
## Status
Accepted.
## Date
2026-11-20
## Context
An application can load configuration once and share the result with libraries.
Each library needs to inspect its own section while the application chooses the
Go type that holds the complete configuration.
[ADR 0010](0010-effective-configuration-diff.md) provides comparison between
results with the same Go configuration type. A shared inspection view lets a
library compare configurations without knowing that application type.
## Decision
Provide inspection views that compare saved configuration values from successful
loads regardless of the original application Go types. Views being compared
select the same location within their respective configurations.
ConfigKit owns comparison and redaction. Use the saved load snapshots and the
equality, sequence comparison, and sensitive-value handling established by
ADR 0010. Report changes that overlap the selected location, retaining original
application paths and any containing changes.
This decision extends ADR 0010. The existing same-type comparison API continues
to follow that decision.
## Alternatives Considered
- **Require matching application Go types.** This follows the existing API's
restriction but adds type checks or application-specific adapters to a shared
inspection view.
- **Let libraries implement comparison.** This gives libraries control but
duplicates ConfigKit's comparison and redaction rules.
## Consequences
Libraries can offer configuration comparison through one inspection interface
across applications. Applications retain ownership of their Go configuration
types and presentation.
A reported change to a containing value may include configuration outside the
selected section. The view provides a reporting focus, with the existing
redaction rules applied to all returned values.

View File

@@ -226,6 +226,13 @@ describe the configuration as it was when the load finished. Returned source,
diagnostic, and metadata records are copies; changing them cannot change later
queries. Separate loads return independently owned configuration and records.
`Result.Value` selects trusted current Go values by configuration path, including
resolved secrets and zero values without input. It uses ordinary Go assignment:
maps, slices, and pointers can share state with `Config`. Availability does not
establish input presence; use metadata for that distinction. Capture owned
runtime settings before later mutations invalidate the relationship to saved
inspection evidence. A manually constructed result also supports value lookup.
Every source, options, schema, version, defaults, decode, resolution, or
validation failure returns a nil result and a `*LoadError`. Successful results
contain caller-owned `Config`, detached `Metadata`, a defensive source list,
@@ -750,6 +757,7 @@ Use inspection to understand a completed load without reading the files again:
| Inspect earlier values as safe YAML | `Explain` or `WriteExplanation` |
| Show the saved final configuration as safe YAML | `WriteEffective` |
| Compare final values from two loads | `Diff` |
| Focus reporting on one location | `InspectSubtree` |
For example, suppose a typed default sets `workers` to `2`, the main input
supplies `workers: 3`, and an overlay supplies `workers: 4`. The final value is
@@ -758,6 +766,16 @@ earlier default and main contributions. `History` returns attribution records;
`Explain` adds their before/after values. Changing `result.Config.Workers` later
does not change any of these saved inspection results.
An `Inspection` view focuses reporting on a canonical JSON Pointer location.
Its `HistoricalPaths` includes observed paths at or below that location and
`WriteEffective` renders the selected frozen value with original sensitivity.
An absent scope can be selected, but has no effective output. Explicit metadata
and explanation queries keep native application paths and may address values
outside the focus; source catalogs and resource contexts remain available for
the whole load. This is a reporting focus, not a confidentiality boundary. Numeric
key and index spellings with the same pointer select the same focus, while
explicit queries preserve their normal path intent.
#### Presence, origins, and historical paths
`Result.Metadata()` describes every final configuration path. Queries retain explicit
@@ -1011,6 +1029,14 @@ uninitialized results return an error with no records. A failed `Load` retains
its normal nil-result/`LoadError` behavior, which callers handle before invoking
`Diff`.
`Inspection.Diff` compares focused views at the same canonical location, even
when their application root Go types differ. It compares the complete frozen
snapshots with the same paired redaction and retains records at, below, or above
the focus. Because sequences and structural replacements can be atomic, an
ancestor record may reflect a change outside the selected value. Different
scopes or unavailable views return an error and no records. Whole-result
`Diff[T]` remains restricted to results of the same Go type.
## Typed secret references
There are three separate tasks when working with credentials:
@@ -1019,7 +1045,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 +1077,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 +1104,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 +1190,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 +1211,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 +1230,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 +1769,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;

View File

@@ -26,10 +26,26 @@ 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) |
| Hand one result to library consumers | [Component handoff](#component-handoff) |
| Upgrade an existing consumer | [Migration guidance](#intentional-migration-changes) |
## Component handoff
Register application and library rules in one definition, then load once and
pass the whole result to each consumer. A consumer can select its named settings
with `Value`, assert its own type, and follow effective field origins through
`Metadata` and `SourceContext` to capture resources. It owns any runtime copy it
needs. The maintained [one-library example](../../examples/consumers/result_component.go)
shows registration, underlay defaults, handoff, and a focused inspection facade;
the [two-library example](../../examples/consumers/result_composition.go) composes
callbacks and identity registrations for two consumers.
Views focus reports while explicit metadata and explanation queries retain native
application-root paths. See the [configuration contract](../config.md#layered-metadata)
for ownership, scope, and frozen inspection behavior.
## Choosing a loading entry point
- Use [`Load`](../../lifecycle.go) with one source for an ordinary configuration.
@@ -57,6 +73,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 +547,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` |

View File

@@ -54,10 +54,11 @@ Accepted decisions:
- [Check source versions with one shared policy](adr/0013-shared-source-version-checks.md)
- [Own YAML semantics behind a private parser boundary](adr/0002-own-yaml-semantics.md)
- [Preserve presence and record application resolution](adr/0003-preserve-presence-and-resolution-history.md)
- [Secret references and explicit bootstrap](adr/0004-secret-references-and-explicit-bootstrap.md)
- [Explicit configured secrets bootstrap](adr/0023-explicit-configured-secrets-bootstrap.md)
- [Explicit overrides and safe explanation](adr/0005-explicit-overrides-and-safe-explanation.md)
- [Keep the public facade root-owned](adr/0006-public-facade.md)
- [Compare frozen effective configuration snapshots](adr/0010-effective-configuration-diff.md)
- [Compare inspection views across application types](adr/0024-compare-inspection-views-across-application-types.md)
- [Place inputs at literal application mapping paths](adr/0011-input-destinations.md)
- [Share dependency-ready ordering](adr/0015-shared-dependency-ready-ordering.md)
- [Separate import selection controls](adr/0016-independent-import-controls.md)
@@ -68,186 +69,16 @@ Accepted decisions:
- [Match registered records during resolution inspection](adr/0021-sequence-resolution-correspondence.md)
- [Bind companion contexts after main selection](adr/0022-main-relative-context.md)
For cross-cutting changes, follow every applicable row. Completed implementation
and remediation plans are preserved in Git history at `cb5b435`; use current
contracts and the component overview for ongoing work. For example:
```sh
git show cb5b435:docs/roadmap/remediation.md
```
For cross-cutting changes, follow every applicable row. Use current contracts
and the component overview for ongoing work.
Release-candidate, publication, and verification work follows the operational
[release procedure](release.md). Its module-selected ReleaseKit `publish`
invocation validates the committed candidate and publishes only the intended
tag; those release checks remain distinct from the everyday development check.
The completed string-and-integer schema-version implementation and remediation
records are preserved in Git history at `244104f`. The
[configuration contract](config.md#application-schema-versions) owns current behavior.
The completed source-origins and public-facade roadmaps, implementation plan, and
resolved review findings are preserved in Git history at `5760614`, for example
`git show 5760614:docs/roadmap/remediation.md`. The earlier source-origins staged
plan remains at `28e7fc5:docs/roadmap/implementation.md`. Current resolution
behavior belongs to the [configuration contract](config.md#recorded-application-resolution),
and current facade ownership belongs to the [component overview](internal/overview.md).
## Baseline validation
The completed main-relative companion roadmap, Audita request, implementation
plan, and remediation report are preserved in Git history at `47547bc` under
`docs/roadmap/`. The [layered loading contract](config.md#layered-loading)
describes current behavior, and [ADR 0022](adr/0022-main-relative-context.md)
records the context binding decision.
The completed field-level sequence resolution roadmap, implementation plan, and
resolved audit findings are preserved in Git history at `7e53863` under
`docs/roadmap/`. For example:
```sh
git show 7e53863:docs/roadmap/implementation.md
git show 7e53863:docs/roadmap/remediation.md
```
The [configuration contract](config.md#recorded-application-resolution) owns
current resolution behavior, and [ADR 0021](adr/0021-sequence-resolution-correspondence.md)
records the correspondence decision.
The completed filesystem-source and underlay roadmap, original feature request,
implementation plan, and resolved remediation record are preserved in Git history
at `b604aa1` under `docs/roadmap/`. Current behavior belongs to the
[configuration contract](config.md#layered-loading). Built-in sibling
inheritance is now part of the [configuration contract](config.md#sibling-inheritance).
The completed request, roadmap, plan, and resolved review findings are preserved
in Git history at `83c59ea` under `docs/roadmap/`.
The completed overlay rename plan and release-workflow simplification record are
preserved in Git history at `73ce6e9` under `docs/roadmap/`. Current overlay
behavior belongs to the [configuration contract](config.md#selected-overlays),
and release operations belong to the [release procedure](release.md).
The completed ReleaseKit adoption, startup performance request and experiments,
benchmark evidence, performance audit, implementation plan, and remediation
record are preserved in Git history at `8e91a2b` under `docs/roadmap/`. For example:
```sh
git show 8e91a2b:docs/roadmap/startup-benchmark.md
```
Remaining optimization candidates belong to
[future performance experiments](roadmap/future.md#3-performance-experiments).
The completed effective-configuration diff roadmap, implementation plan, and
resolved review findings are preserved in Git history at `1c2610c` under
`docs/roadmap/`. The
[configuration contract](config.md#effective-configuration-diffs) owns current
comparison and disclosure behavior, and
[ADR 0010](adr/0010-effective-configuration-diff.md) records the decision.
The completed input-destination, relative-import-destination, and shared
source-version roadmaps, associated consumer request, implementation plan, and
resolved review findings are preserved in Git history at `e4270c9` under
`docs/roadmap/`. For example:
```sh
git show e4270c9:docs/roadmap/implementation.md
git show e4270c9:docs/roadmap/remediation.md
```
Current behavior belongs to the configuration contract's
[input destinations](config.md#input-destinations),
[imports](config.md#explicit-imports), and
[shared source-version checks](config.md#shared-source-version-checks) sections.
Explicit sequence-item placement, collection operations, identity registration,
and final registered-identity validation are owned by the
[strict composition](config.md#strict-document-composition) section;
[imports](config.md#explicit-imports) owns acquisition and scheduling. The
[maintained sequence catalog](consumers/README.md#identified-prompt-sequences)
shows the consumer boundary, and [ADR 0017](adr/0017-collection-sequence-policy.md)
records the collection decision.
The completed sequence-composition roadmap, implementation plan, and resolved
remediation record are preserved in Git history at `008d2ba` under
`docs/roadmap/`. For example:
```sh
git show 008d2ba:docs/roadmap/sequence-composition.md
git show 008d2ba:docs/roadmap/implementation.md
git show 008d2ba:docs/roadmap/remediation.md
```
The completed import-discovery roadmap, implementation plan, and resolved
remediation record are preserved in Git history at `5747ec4` under
`docs/roadmap/`. For example:
```sh
git show 5747ec4:docs/roadmap/imports.md
git show 5747ec4:docs/roadmap/implementation.md
git show 5747ec4:docs/roadmap/remediation.md
```
The subsequent import-integration audit and completed remediation record are
preserved at `6903c9e:docs/roadmap/remediation.md`; retrieve them with
`git show 6903c9e:docs/roadmap/remediation.md`.
The completed sequence-identity/collection-policy roadmap and implementation
plan are preserved in Git history at `d0a605a`:
```sh
git show d0a605a:docs/roadmap/sequences.md
git show d0a605a:docs/roadmap/implementation.md
```
Current behavior belongs to the configuration contract's
[strict composition](config.md#strict-document-composition),
[sibling inheritance](config.md#sibling-inheritance), and
[CLI overrides](config.md#explicit-cli-overrides) sections.
The completed remediation record, including the algorithm-audit findings, is
preserved at `ea46001:docs/roadmap/remediation.md`.
The completed configuration-discovery roadmap, implementation plan, and
remediation record are preserved in Git history at `0369111`, for example
`git show 0369111:docs/roadmap/remediation.md`. Current behavior belongs to
[configuration discovery](config.md#configuration-discovery); the public
[discovery declarations](../discovery.go) own the Go API.
The completed consolidation proposal, implementation plan, and resolved audit
findings are preserved in Git history at `34cbc0d` under `docs/roadmap/`. For
example:
```sh
git show 34cbc0d:docs/roadmap/implementation.md
git show 34cbc0d:docs/roadmap/remediation.md
```
Potential enhancements are tracked in [future features](roadmap/future.md).
The completed audit-remediation, internal-boundary simplification, shared-history,
and public API cleanup roadmaps, reviews, and resolved findings are preserved at
`68400ff` under `docs/roadmap/`. For example:
```sh
git show 68400ff:docs/roadmap/api.md
git show 68400ff:docs/roadmap/remediation.md
```
Their earlier completed implementation plans are preserved at
`bb5540b:docs/roadmap/implementation.md` (audit remediation),
`f6d54a0:docs/roadmap/implementation.md` (internal-boundary simplification), and
`07e4ae5:docs/roadmap/implementation.md` (shared history). The plan at
`68400ff:docs/roadmap/implementation.md` records the public API cleanup.
Current behavior and migration information belong to the
[configuration contract](config.md), public declaration comments, and
[consumer guide](consumers/README.md#pre-v1-public-api-cleanup).
The consolidated audit, including
findings, evidence, and settled scope decisions, is preserved at
`453da68:docs/roadmap/audit.md`; the original nine reports are preserved at
`ecd5d5d` under `docs/roadmap/`. Retrieve the consolidated record with:
```sh
git show 453da68:docs/roadmap/audit.md
```
Install the Go version required by `go.mod` or a compatible newer toolchain.
Acquire declared dependencies explicitly before entering an offline
development or validation environment:
@@ -309,11 +140,12 @@ code changes. Use the component overview to find the corresponding implementatio
| Input and relative-import destinations, mounted sources, and source ownership | [Destination engine tests](../internal/engine/destination_test.go), [tier tests](../internal/engine/destination_tiers_test.go), [import traversal and version tests](../internal/engine/destination_import_test.go), [accounting tests](../internal/engine/destination_accounting_test.go), [lifecycle inspection tests](../internal/engine/destination_import_lifecycle_test.go), [public source/error tests](../facade_destination_test.go), [resource contexts](../facade_resource_context_test.go), and [consumer examples](../examples/consumers/destinations_test.go) | `go test ./internal/engine -run 'Destination\|Import\|Glob\|Mounted'`, `go test . -run 'Destination\|Import\|SourceContext\|FacadeMounted'`, and `go test ./examples/consumers` |
| Shared source-version modes and evidence | [Engine source-version tests](../internal/engine/source_version_test.go), [public facade tests](../facade_source_version_mode_test.go), and [consumer example tests](../examples/consumers/layered_test.go) | `go test ./internal/engine -run 'SourceVersion'`, `go test . -run 'SourceVersion'`, and `go test ./examples/consumers` |
| Schema, defaults, projection, cloning | [Implementation flow](internal/overview.md#implementation-flow), [schema](../internal/engine/schema_test.go), [decoding](../internal/engine/decode_test.go), [projection and typed cloning](../internal/engine/projection_test.go) | `go test ./internal/engine -run 'Schema\|Decode\|Projection\|Clone\|Inline\|CompareDocument'` |
| Current values and focused inspection | [Value tests](../facade_result_value_test.go), [view tests](../facade_inspection_view_test.go), [comparison tests](../facade_inspection_diff_test.go), and [history integration](../facade_inspection_history_test.go) | `go test . -run 'TestResultValue\|TestInspectionView'` and `go test ./internal/engine -run 'TestResultValue\|Diff\|History'` |
| Lifecycle, resolution, validation, callback ownership | [Loading](../internal/engine/load_test.go), [resolution](../internal/engine/resolution_test.go), [validation](../internal/engine/validation_test.go), [ownership](../internal/engine/callback_ownership_test.go), [independence](../internal/engine/independence_test.go) | `go test ./internal/engine -run 'Load\|Resolution\|Validation\|Validator\|Hook\|Callback\|Parallel'` |
| 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` |

View File

@@ -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

View File

@@ -45,6 +45,10 @@ Implemented component owners:
- Root `Diff` and `Difference` provide the public comparison boundary and
convert detached engine records to root-owned paths and snapshots; consumer
examples own presentation of the safe changed regions.
- `Result.Value` delegates current Go-value navigation to an operation-local
engine schema builder and existing field/path bindings. Root `Inspection`
wraps an engine view borrowing the frozen inspection and canonical scope;
it reuses history enumeration, document redaction, and whole-result diff.
- `internal/document` owns the parser-independent ordered tree and cloning.
`internal/yaml` is the sole upstream YAML adapter and parser/dumper boundary.
- Engine mechanism tests own source, composition, inheritance, decoding,
@@ -125,6 +129,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

View File

@@ -25,7 +25,7 @@ License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) |
## go-yaml v4
Selected module: `go.yaml.in/yaml/v4` at `v4.0.0-rc.6`.
Selected module: `go.yaml.in/yaml/v4` at `v4.0.0`.
Copyright 2011-2019 Canonical Ltd
@@ -37,7 +37,7 @@ SPDX-License-Identifier: Apache-2.0 AND MIT
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
[MIT](licenses/MIT.txt) |
[NOTICE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/NOTICE) |
[LICENSE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/LICENSE).
[NOTICE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/NOTICE) |
[LICENSE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/LICENSE).
[Source](https://github.com/yaml/go-yaml/tree/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125).
[Source](https://github.com/yaml/go-yaml/tree/f2f9563503f11b7a60da0c532175dcc693ce8d5a).

View File

@@ -316,12 +316,14 @@ See [ADR 0005](../adr/0005-explicit-overrides-and-safe-explanation.md).
Detailed syntax and operation tables belong to the
[current configuration contract](../config.md).
The frozen inspection boundary also supports comparing completed same-type
results without reopening sources or rerunning the load lifecycle. The
The frozen inspection boundary supports comparing completed same-type results
and focused views across application root types without reopening sources or
rerunning the load lifecycle. The
[configuration contract](../config.md#effective-configuration-diffs) owns
comparison and disclosure behavior, the [component overview](../internal/overview.md)
owns implementation responsibility, and [ADR 0010](../adr/0010-effective-configuration-diff.md)
records the accepted decision.
and [ADR 0024](../adr/0024-compare-inspection-views-across-application-types.md)
record the accepted decisions.
## Collection Identity And Combination
@@ -405,9 +407,14 @@ Secret values enter configuration through typed environment-name references;
literal credentials are not a supported configuration convention. Only an explicit
accessor exposes a resolved credential to application code. Credential bytes must
never enter composition trees, history, or inspection. General environment-variable
configuration overlays are an explicit non-goal. Bootstrap must preserve already
set variables, including empty ones, and report blocked files without contents.
See [ADR 0004](../adr/0004-secret-references-and-explicit-bootstrap.md).
configuration overlays are an explicit non-goal. Bootstrap preserves already
set variables by default, including empty ones, and reports blocked files without
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
renderers must apply secret classification, and parser errors must not be

View File

@@ -103,12 +103,23 @@ go list -m go.maximumdirect.net/releasekit
go tool releasekit version
```
This repository selects ReleaseKit v0.8.0. `go tool releasekit` preserves the
This repository selects ReleaseKit v0.10.0. `go tool releasekit` preserves the
tool's exit status and publication report; `go run` maps a nonzero child exit
status to 1. ReleaseKit's child Go commands
use the `go` found on `PATH` with `GOTOOLCHAIN=local`; keep the selected
executable first on `PATH` through the publication command.
If Go is configured for cross-compilation, select the host for the release
session before preparing or running the CLI:
```sh
release_host_os=$(go env GOHOSTOS)
release_host_arch=$(go env GOHOSTARCH)
export GOOS="$release_host_os" GOARCH="$release_host_arch"
```
ReleaseKit still selects the Linux compilation targets from the profile.
For hosted delivery, save the Gitea API token in the ignored local file
`.releasekit/gitea-token` with owner-only permissions. The profile uses it when
`RELEASEKIT_GITEA_TOKEN` is unset or blank; a nonblank environment value takes
@@ -257,10 +268,11 @@ available locally:
```sh
release_version=v1.0.0
git switch --detach "$release_version"
git switch --detach "$release_version" && git status --short
```
After preparing the tool in that tagged checkout:
Proceed once the switch succeeds and the status output is empty. After
preparing the tool in that tagged checkout:
```sh
go tool releasekit deliver "$release_version"

11
docs/releases/v1.2.1.md Normal file
View File

@@ -0,0 +1,11 @@
# ConfigKit v1.2.1
ConfigKit now uses the stable go-yaml v4.0.0 release in place of v4.0.0-rc.6.
Existing Go code and configuration files require no changes. The minimum
consumer Go version remains 1.27.0.
The maintainer release workflow now uses ReleaseKit v0.10.0, which updates
Markdown validation dependencies and includes fixes for publication recovery
and hosted release retries.
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.1/COPYRIGHT) | [LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.1/LICENSE) | [ATTRIBUTION](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.1/docs/oss/attribution.md)

50
docs/releases/v1.3.0.md Normal file
View File

@@ -0,0 +1,50 @@
# ConfigKit v1.3.0
Applications can now bootstrap secrets from a directory declared in a discovered
main configuration file, then load that same captured document. Explicit
overwrite options support deployments that give provisioned secret files
priority over existing environment variables.
## Configured secrets startup
Call `LoadSecretsIntoEnvironmentFromConfig` with a host `File` or `SearchConfig`
source. The selected main file can declare:
```yaml
config:
secrets_dir: secrets
secrets_overwrite: true
```
The helper resolves the directory relative to the main file's canonical
directory, within its filesystem root, and bootstraps all eligible entries.
It returns a secrets report and a prepared source. Pass that source to `Load`,
or use it as the main `Input.Source` for `LoadLayered`.
The prepared source retains the selected main contents and filesystem context
for reuse. Later loads acquire imports and look up environment values at their
normal lifecycle points. `SecretsFromConfigOptions.Filesystem` can select a
wider host root during preparation. An explicit context supplied to a later
load must resolve to the captured context. [Startup example](../../examples/consumers/secrets.go) · [Configuration contract](../config.md#explicit-secrets-directory-bootstrap)
## Explicit overwrite policy
Overwrite defaults to false, preserving existing variables including empty
ones. YAML `secrets_overwrite: true` enables replacement during configured
bootstrap. A non-nil `SecretsFromConfigOptions.Overwrite` takes precedence over
YAML, including an explicit false.
For an application-supplied directory, use
`LoadSecretsIntoEnvironmentWithOptions` with `SecretsOptions{Overwrite: true}`.
Existing `LoadSecretsIntoEnvironment(directory)` calls retain their preservation
behavior and exact Go function signature.
Bootstrap runs through an explicit helper call before configuration loading.
Reports describe writes, skips, and partial failures without credential contents.
A later configuration failure leaves completed environment writes in place.
Ordinary `Load` and `LoadLayered` consume the main controls and resolve typed
secret references from the environment. [Bootstrap and failure handling](../config.md#preflight-limits-and-partial-writes)
Consumers require Go 1.27.0 or later.
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.3.0/COPYRIGHT) | [LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.3.0/LICENSE) | [ATTRIBUTION](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.3.0/docs/oss/attribution.md)

58
docs/releases/v1.4.0.md Normal file
View File

@@ -0,0 +1,58 @@
# ConfigKit v1.4.0
Applications can now load configuration once and pass the complete result to
libraries that select their own typed settings and reporting scope. The new APIs
reuse the original load's provenance, resource contexts, and frozen inspection
state.
## Current typed values
`Result.Value(path)` selects a current Go value without requiring the consumer
to know the application's root configuration type. It uses ConfigKit's existing
field bindings and semantic paths, preserving named types, terminal pointers,
and resolved `Secret` values. A present nil value succeeds; unavailable paths
return false. Lookup also works with manually constructed results and returns
terminal values without conversion or revalidation.
This is trusted access with ordinary Go assignment semantics: maps, slices, and
pointers can share state with `Result.Config`. Later caller changes are visible
to lookup, while inspection continues to describe the completed load. Consumers
remain responsible for capturing any owned runtime settings they need.
[Value API](../../result_value.go) · [Ownership contract](../config.md#completion-and-resource-lifetime)
## Focused inspection
`Result.InspectSubtree(path)` returns a non-generic `Inspection` view. It renders
the selected frozen value with existing redaction, enumerates observed paths
within the scope, and forwards explanations, metadata, source records, and
resource contexts using native application paths.
A valid absent scope can be selected for history and comparison. Rendering an
absent effective value returns an error without output; explicit null renders
normally. Numeric key and index spellings with the same canonical JSON Pointer
select the same reporting location. Explicit queries retain their normal path
intent and can address values outside the focus. Source catalogs and ancestor
evidence remain available: the view is a reporting focus, not an isolation
boundary. Scoped path enumeration avoids copying unrelated effective metadata.
[Inspection API](../../inspection_view.go) · [Inspection contract](../config.md#layered-metadata)
`Inspection.Diff` compares views selecting the same location, including views
from different application root Go types. It uses the existing whole-snapshot
comparison and paired redaction, then retains differences at, below, or above
the focus. Sequences remain atomic: a retained ancestor difference can reflect
changes outside the selected descendant. Uninitialized views and mismatched
scopes return an error without records. Existing same-type `Diff[T]` is unchanged.
[Comparison contract](../config.md#effective-configuration-diffs)
The maintained [one-library](../../examples/consumers/result_component.go) and
[two-library](../../examples/consumers/result_composition.go) examples demonstrate
registration, one-load handoff, owned settings capture, and resource lookup from
effective source origins. [Consumer guidance](../consumers/README.md#component-handoff)
## Compatibility
These APIs are additive. Existing loading, composition, inspection, and shared
source-version behavior remains unchanged; existing callers need no migration.
The Go consumer minimum remains 1.27.0.
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/COPYRIGHT) | [LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/LICENSE) | [ATTRIBUTION](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/oss/attribution.md)

View File

@@ -0,0 +1,122 @@
package consumers
import (
"errors"
"io"
"io/fs"
"path"
"slices"
"strings"
configkit "go.maximumdirect.net/configkit"
)
// ComponentSettings is a library-owned configuration type embedded by an application.
type ComponentSettings struct {
Name string `yaml:"name"`
Resource string `yaml:"resource"`
Token string `yaml:"token"`
Entries []ComponentItem `yaml:"entries"`
}
// ComponentItem is one identified library setting.
type ComponentItem struct {
ID string `yaml:"id"`
Resource string `yaml:"resource"`
}
// ComponentApplication is the application-owned root for this example.
type ComponentApplication struct {
Component ComponentSettings `yaml:"component"`
}
// ComponentResult is the small interface required by the library at handoff.
type ComponentResult interface {
Value(configkit.Path) (any, bool)
Metadata() configkit.Metadata
SourceContext(string) (configkit.ResourceContext, bool)
}
// ComponentRuntime contains settings and captured resource data owned by the library.
type ComponentRuntime struct {
Settings ComponentSettings
Resource []byte
}
// ComponentDefinition registers library behavior through an application field selector.
func ComponentDefinition[T any](selectSettings func(*T) *ComponentSettings) configkit.Definition[T] {
component := configkit.Keys("component")
return configkit.Definition[T]{
SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(component.Key("entries"), "id")},
Resolve: func(root *T, resolution *configkit.Resolution) error {
settings := selectSettings(root)
configkit.Default(resolution, component.Key("name"), &settings.Name, "default component", "use component default")
configkit.Normalize(resolution, component.Key("name"), &settings.Name, strings.TrimSpace(settings.Name), "trim component name")
return nil
},
Validate: func(root *T, validation *configkit.Validation) {
if selectSettings(root).Name == "" {
validation.Error(component.Key("name"), "component name is required")
}
},
Sensitive: func(path configkit.Path) bool { return path.String() == "/component/token" },
}
}
// LoadComponentApplication assembles one application load with bundled underlay defaults.
func LoadComponentApplication(source configkit.Source) (*configkit.Result[ComponentApplication], error) {
return configkit.LoadLayered(configkit.Input{Source: source}, configkit.LayeredOptions[ComponentApplication]{
Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{Source: configkit.Bytes("component defaults", []byte("component: {entries: [{id: default}]}\n"))}}}},
Definition: ComponentDefinition(func(root *ComponentApplication) *ComponentSettings { return &root.Component }),
})
}
// NewComponent accepts the entire result, selects library settings, and captures
// a resource relative to the effective field's original source.
func NewComponent(result ComponentResult) (ComponentRuntime, error) {
value, ok := result.Value(configkit.Keys("component"))
settings, typed := value.(ComponentSettings)
if !ok || !typed {
return ComponentRuntime{}, errors.New("component settings unavailable")
}
settings.Entries = slices.Clone(settings.Entries)
info, ok := result.Metadata().Lookup(configkit.Keys("component", "resource"))
if !ok || len(info.Origin.Locations) != 1 {
return ComponentRuntime{}, errors.New("component resource origin unavailable")
}
context, ok := result.SourceContext(info.Origin.Locations[0].SourceID)
if !ok {
return ComponentRuntime{}, errors.New("component resource context unavailable")
}
data, err := fs.ReadFile(context.FS, path.Join(context.BaseDir, settings.Resource))
if err != nil {
return ComponentRuntime{}, err
}
return ComponentRuntime{Settings: settings, Resource: data}, nil
}
// ComponentInspection is a library-owned facade over one selected reporting view.
type ComponentInspection struct{ view configkit.Inspection }
// InspectComponent selects the library's conventional reporting scope once.
func InspectComponent(result interface {
InspectSubtree(configkit.Path) (configkit.Inspection, bool)
}) (ComponentInspection, bool) {
view, ok := result.InspectSubtree(configkit.Keys("component"))
return ComponentInspection{view: view}, ok
}
// WriteEffective renders the frozen component safely.
func (i ComponentInspection) WriteEffective(output io.Writer) error {
return i.view.WriteEffective(output)
}
// Explain forwards native application paths without changing their meaning.
func (i ComponentInspection) Explain(path configkit.Path) (configkit.Explanation, bool) {
return i.view.Explain(path)
}
// Diff compares two frozen component views.
func (i ComponentInspection) Diff(other ComponentInspection) ([]configkit.Difference, error) {
return i.view.Diff(other.view)
}

View File

@@ -0,0 +1,57 @@
package consumers
import (
"bytes"
"strings"
"testing"
"testing/fstest"
configkit "go.maximumdirect.net/configkit"
)
func TestComponentHandoff(t *testing.T) {
filesystem := configkit.NewFilesystem("application", fstest.MapFS{
"config/main.yml": &fstest.MapFile{Data: []byte("component: {name: ' example ', resource: asset.txt, token: disposable-canary}\n")},
"config/asset.txt": &fstest.MapFile{Data: []byte("resource data")},
})
result, err := LoadComponentApplication(filesystem.File("config/main.yml"))
if err != nil {
t.Fatal(err)
}
runtime, err := NewComponent(result)
if err != nil {
t.Fatal(err)
}
if runtime.Settings.Name != "example" || len(runtime.Settings.Entries) != 1 || runtime.Settings.Entries[0].ID != "default" || string(runtime.Resource) != "resource data" {
t.Fatalf("component runtime = %#v", runtime)
}
runtime.Settings.Entries[0].ID = "runtime change"
if result.Config.Component.Entries[0].ID != "default" {
t.Fatal("runtime settings share the result's slice")
}
entries, found := result.Metadata().Lookup(configkit.Keys("component", "entries"))
if !result.Metadata().IsExplicit(configkit.Keys("component", "resource")) || !found || entries.Origin.Layer != configkit.LayerUnderlay {
t.Fatal("presence did not retain source distinction")
}
view, ok := InspectComponent(result)
if !ok {
t.Fatal("component view unavailable")
}
var output bytes.Buffer
if err := view.WriteEffective(&output); err != nil {
t.Fatal(err)
}
if strings.Contains(output.String(), "disposable-canary") || !strings.Contains(output.String(), "example") {
t.Fatalf("unsafe report: %s", output.String())
}
if _, ok := view.Explain(configkit.Keys("component", "resource")); !ok {
t.Fatal("resource explanation unavailable")
}
if diff, err := view.Diff(view); err != nil || len(diff) != 0 {
t.Fatalf("view diff = %#v, %v", diff, err)
}
_, err = LoadComponentApplication(configkit.Bytes("invalid.yml", []byte("component: {name: ' '}\n")))
if err == nil {
t.Fatal("component validation did not fail")
}
}

View File

@@ -0,0 +1,86 @@
package consumers
import (
"errors"
"strings"
configkit "go.maximumdirect.net/configkit"
)
// AuditSettings is a second library's independent configuration type.
type AuditSettings struct {
Enabled bool `yaml:"enabled"`
Rules []AuditRule `yaml:"rules"`
}
// AuditRule has an identity used by the application's assembly policy.
type AuditRule struct {
ID string `yaml:"id"`
}
// ComposedApplication combines application and two library settings.
type ComposedApplication struct {
Label string `yaml:"label"`
Component ComponentSettings `yaml:"component"`
Audit AuditSettings `yaml:"audit"`
}
// AuditResult is the smaller interface needed by the audit consumer.
type AuditResult interface {
Value(configkit.Path) (any, bool)
}
// NewAuditSettings takes a copy of the second library's settings.
func NewAuditSettings(result AuditResult) (AuditSettings, error) {
value, ok := result.Value(configkit.Keys("audit"))
settings, typed := value.(AuditSettings)
if !ok || !typed {
return AuditSettings{}, errors.New("audit settings unavailable")
}
settings.Rules = append([]AuditRule(nil), settings.Rules...)
return settings, nil
}
func auditDefinition[T any](selectSettings func(*T) *AuditSettings) configkit.Definition[T] {
audit := configkit.Keys("audit")
return configkit.Definition[T]{
SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(audit.Key("rules"), "id")},
Resolve: func(root *T, resolution *configkit.Resolution) error {
configkit.Default(resolution, audit.Key("enabled"), &selectSettings(root).Enabled, true, "enable audit by default")
return nil
},
Validate: func(root *T, validation *configkit.Validation) {
if selectSettings(root).Enabled && len(selectSettings(root).Rules) == 0 {
validation.Error(audit.Key("rules"), "enabled audit requires a rule")
}
},
}
}
// LoadComposedApplication applies application and library callbacks in order in
// one load. A placed component input remains an ordinary underlay.
func LoadComposedApplication(main, component configkit.Input) (*configkit.Result[ComposedApplication], error) {
componentRules := ComponentDefinition(func(root *ComposedApplication) *ComponentSettings { return &root.Component })
auditRules := auditDefinition(func(root *ComposedApplication) *AuditSettings { return &root.Audit })
identities := append(componentRules.SequenceIdentities, auditRules.SequenceIdentities...)
definition := configkit.Definition[ComposedApplication]{
SequenceIdentities: identities,
Sensitive: componentRules.Sensitive,
Resolve: func(root *ComposedApplication, resolution *configkit.Resolution) error {
configkit.Normalize(resolution, configkit.Keys("label"), &root.Label, strings.TrimSpace(root.Label), "trim application label")
if err := componentRules.Resolve(root, resolution); err != nil {
return err
}
return auditRules.Resolve(root, resolution)
},
Validate: func(root *ComposedApplication, validation *configkit.Validation) {
if root.Label == "" {
validation.Error(configkit.Keys("label"), "application label is required")
}
componentRules.Validate(root, validation)
auditRules.Validate(root, validation)
},
}
component.Destination = configkit.Keys("component")
return configkit.LoadLayered(main, configkit.LayeredOptions[ComposedApplication]{Underlays: []configkit.Underlay{{Inputs: []configkit.Input{component}}}, Definition: definition})
}

View File

@@ -0,0 +1,69 @@
package consumers
import (
"io/fs"
"path"
"testing"
"testing/fstest"
configkit "go.maximumdirect.net/configkit"
)
func TestComposedConsumersShareOneLoad(t *testing.T) {
filesystem := configkit.NewFilesystem("components", fstest.MapFS{
"config/component.yml": &fstest.MapFile{Data: []byte("name: ' component '\nresource: asset.txt\nentries:\n - {id: parent, resource: asset.txt}\n - {id: child, extends: {id: parent}}\n")},
"config/asset.txt": &fstest.MapFile{Data: []byte("shared asset")},
})
component := configkit.Input{Source: filesystem.File("config/component.yml")}
load := func(main string) *configkit.Result[ComposedApplication] {
t.Helper()
result, err := LoadComposedApplication(configkit.Input{Source: configkit.Bytes("app.yml", []byte(main))}, component)
if err != nil {
t.Fatal(err)
}
return result
}
first := load("label: ' app '\naudit: {enabled: false, rules: [{id: first}]}\n")
second := load("label: second\naudit: {rules: [{id: second}]}\n")
componentRuntime, err := NewComponent(first)
if err != nil {
t.Fatal(err)
}
audit, err := NewAuditSettings(first)
if err != nil {
t.Fatal(err)
}
if first.Config.Label != "app" || componentRuntime.Settings.Name != "component" || string(componentRuntime.Resource) != "shared asset" || audit.Enabled || audit.Rules[0].ID != "first" {
t.Fatalf("first result = %#v %#v", componentRuntime, audit)
}
secondAudit, err := NewAuditSettings(second)
if err != nil || !secondAudit.Enabled || secondAudit.Rules[0].ID != "second" || audit.Enabled {
t.Fatalf("second audit = %#v, %v", secondAudit, err)
}
resource := configkit.Keys("component", "entries").Index(1).Key("resource")
info, ok := first.Metadata().Lookup(resource)
if !ok || len(info.Origin.Inheritance) == 0 || len(info.Origin.Locations) == 0 {
t.Fatalf("inherited origin = %#v, %v", info, ok)
}
context, ok := first.SourceContext(info.Origin.Locations[0].SourceID)
if !ok {
t.Fatal("resource context unavailable")
}
data, err := fs.ReadFile(context.FS, path.Join(context.BaseDir, first.Config.Component.Entries[1].Resource))
if err != nil || string(data) != "shared asset" {
t.Fatalf("inherited resource = %q, %v", data, err)
}
_, err = LoadComposedApplication(configkit.Input{Source: configkit.Bytes("invalid.yml", []byte("label: app\naudit: {rules: [{id: same}, {id: same}]}\n"))}, component)
if err == nil {
t.Fatal("duplicate audit identities accepted")
}
badComponent := configkit.Input{Source: configkit.Bytes("bad-component.yml", []byte("name: good\nentries: [{id: duplicate}, {id: duplicate}]\n"))}
_, err = LoadComposedApplication(configkit.Input{Source: configkit.Bytes("app.yml", []byte("label: app\naudit: {rules: [{id: valid}]}\n"))}, badComponent)
if err == nil {
t.Fatal("duplicate component identities accepted")
}
_, err = LoadComposedApplication(configkit.Input{Source: configkit.Bytes("invalid.yml", []byte("label: ' '\naudit: {rules: [{id: valid}]}\n"))}, component)
if err == nil {
t.Fatal("application validation did not run")
}
}

View File

@@ -0,0 +1,18 @@
package consumers
import configkit "go.maximumdirect.net/configkit"
// StartupConfig demonstrates an environment-backed credential and ordinary data.
type StartupConfig struct {
Name string `yaml:"name"`
Token configkit.Secret `yaml:"token"`
}
// PrepareStartup performs the explicit bootstrap once and returns a captured
// main that can be passed to either Load or LoadLayered as its main source.
// The caller should handle a non-nil report even if preparation fails.
func PrepareStartup(main configkit.Source, root string) (*configkit.SecretsReport, configkit.Source, error) {
return configkit.LoadSecretsIntoEnvironmentFromConfig(main, configkit.SecretsFromConfigOptions{
Filesystem: &configkit.FilesystemContext{Root: root},
})
}

View File

@@ -0,0 +1,41 @@
package consumers_test
import (
"os"
"path/filepath"
"testing"
configkit "go.maximumdirect.net/configkit"
"go.maximumdirect.net/configkit/examples/consumers"
)
func TestConfiguredSecretsStartup(t *testing.T) {
root := t.TempDir()
if err := os.Mkdir(filepath.Join(root, "secrets"), 0o700); err != nil {
t.Fatal(err)
}
const name = "CONFIGKIT_EXAMPLE_STARTUP_SECRET"
t.Setenv(name, "")
if err := os.WriteFile(filepath.Join(root, "secrets", name), []byte("example-value\n"), 0o600); err != nil {
t.Fatal(err)
}
main := filepath.Join(root, "main.yml")
if err := os.WriteFile(main, []byte("config: {secrets_dir: secrets, secrets_overwrite: true}\nname: app\ntoken: "+name+"\n"), 0o600); err != nil {
t.Fatal(err)
}
search := configkit.SearchConfig("app", configkit.SearchPaths(main))
report, prepared, err := consumers.PrepareStartup(search, root)
if err != nil || len(report.Entries()) != 1 || report.Entries()[0].Status != configkit.SecretFileLoaded {
t.Fatalf("prepare = %#v, %v", report, err)
}
ordinary, err := configkit.Load[consumers.StartupConfig](prepared)
if err != nil || ordinary.Config.Name != "app" || ordinary.Config.Token.Value() != "example-value" {
t.Fatalf("ordinary load = %#v, %v", ordinary, err)
}
layered, err := configkit.LoadLayered(configkit.Input{Source: prepared}, configkit.LayeredOptions[consumers.StartupConfig]{
Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{Source: configkit.Bytes("defaults", []byte("name: default\n"))}}}},
})
if err != nil || layered.Config.Name != "app" || layered.Config.Token.Value() != "example-value" {
t.Fatalf("layered load = %#v, %v", layered, err)
}
}

View File

@@ -1,6 +1,8 @@
package configkit_test
import (
"errors"
"os"
"strings"
"testing"
"testing/fstest"
@@ -8,6 +10,72 @@ import (
configkit "go.maximumdirect.net/configkit"
)
func TestMainBootstrapControlsAreConsumedWithoutEnvironmentWrites(t *testing.T) {
t.Setenv("CONFIGKIT_CONTROL_SENTINEL", "unchanged")
type nested struct {
Config struct {
Directory string `yaml:"secrets_dir"`
} `yaml:"config"`
}
type app struct {
Service nested `yaml:"service"`
}
for _, imports := range []bool{false, true} {
body := "config: {secrets_dir: missing, secrets_overwrite: true}\nservice: {config: {secrets_dir: ordinary}}\n"
fs := configkit.NewFilesystem("bundle", fstest.MapFS{"main.yml": {Data: []byte(body)}})
result, err := configkit.Load[app](fs.File("main.yml"), configkit.Options[app]{Imports: imports})
if err != nil || result.Config.Service.Config.Directory != "ordinary" || os.Getenv("CONFIGKIT_CONTROL_SENTINEL") != "unchanged" {
t.Fatalf("imports %v: result = %#v, error = %v", imports, result, err)
}
}
}
func TestBootstrapControlsRejectMisplacedAndMalformedValues(t *testing.T) {
for _, test := range []struct {
name, body string
code configkit.Code
path string
}{
{"directory", "config: {secrets_dir: null}\n", configkit.CodeSecretsInvalidPath, "/config/secrets_dir"},
{"overwrite", "config: {secrets_overwrite: 'false'}\n", configkit.CodeSecretsInvalidValue, "/config/secrets_overwrite"},
} {
t.Run(test.name, func(t *testing.T) {
_, err := configkit.Load[struct{}](configkit.Bytes("main", []byte(test.body)))
var loadErr *configkit.LoadError
if !errors.As(err, &loadErr) || len(loadErr.Diagnostics()) != 1 || loadErr.Diagnostics()[0].Code != test.code || loadErr.Diagnostics()[0].Path.String() != test.path || loadErr.Diagnostics()[0].Primary == nil {
t.Fatalf("error = %#v", err)
}
})
}
fs := configkit.NewFilesystem("bundle", fstest.MapFS{
"main.yml": {Data: []byte("config: {imports: [{path: other.yml}]}\n")},
"other.yml": {Data: []byte("config: {secrets_overwrite: false}\n")},
})
_, err := configkit.Load[struct{}](fs.File("main.yml"), configkit.Options[struct{}]{Imports: true})
var loadErr *configkit.LoadError
if !errors.As(err, &loadErr) || len(loadErr.Diagnostics()) != 1 || loadErr.Diagnostics()[0].Code != configkit.CodeImportInvalid || loadErr.Diagnostics()[0].Path.String() != "/config/secrets_overwrite" {
t.Fatalf("import error = %#v", err)
}
_, err = configkit.LoadLayered(configkit.Input{Source: configkit.Bytes("main", []byte("{}\n"))}, configkit.LayeredOptions[struct{}]{
Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{Source: configkit.Bytes("underlay", []byte("config: {secrets_dir: secrets}\n"))}}}},
})
if !errors.As(err, &loadErr) || len(loadErr.Diagnostics()) != 1 || loadErr.Diagnostics()[0].Code != configkit.CodeImportInvalid {
t.Fatalf("underlay error = %#v", err)
}
overlays := configkit.NewFilesystem("overlays", fstest.MapFS{
"main.yml": {Data: []byte("{}\n")},
"overlays/dev.yml": {Data: []byte("config: {secrets_overwrite: false}\n")},
})
_, err = configkit.Load[struct{}](overlays.File("main.yml"), configkit.Options[struct{}]{Overlay: "dev"})
if !errors.As(err, &loadErr) || len(loadErr.Diagnostics()) != 1 || loadErr.Diagnostics()[0].Code != configkit.CodeOverlayDirective || loadErr.Diagnostics()[0].Primary == nil {
t.Fatalf("overlay error = %#v", err)
}
_, err = configkit.Load[struct{}](configkit.Bytes("main", []byte("config: {imports: [], secrets_overwrite: false}\n")))
if !errors.As(err, &loadErr) || len(loadErr.Diagnostics()) != 1 || loadErr.Diagnostics()[0].Code != configkit.CodeImportDisabled {
t.Fatalf("disabled imports error = %#v", err)
}
}
func TestDocumentRootControlsAndNestedApplicationConfig(t *testing.T) {
type settings struct {
Imports string `yaml:"imports"`

View File

@@ -0,0 +1,96 @@
package configkit_test
import (
"strings"
"testing"
configkit "go.maximumdirect.net/configkit"
)
func TestInspectionViewDiff(t *testing.T) {
type first struct {
Component map[string]any `yaml:"component"`
Sibling string `yaml:"sibling"`
Items []string `yaml:"items"`
}
type second struct {
Component map[string]any `yaml:"component"`
Sibling string `yaml:"sibling"`
Items []string `yaml:"items"`
}
left, err := configkit.Load[first](configkit.Bytes("left.yml", []byte("component: {name: before, gone: null}\nsibling: old\nitems: [a, b]\n")))
if err != nil {
t.Fatal(err)
}
right, err := configkit.Load[second](configkit.Bytes("right.yml", []byte("component: {name: after, added: null}\nsibling: new\nitems: [a, c]\n")))
if err != nil {
t.Fatal(err)
}
lv, _ := left.InspectSubtree(configkit.Keys("component"))
rv, _ := right.InspectSubtree(configkit.Keys("component"))
diff, err := lv.Diff(rv)
if err != nil || len(diff) != 3 || diff[0].Path.String() != "/component/added" || diff[1].Path.String() != "/component/gone" || diff[2].Path.String() != "/component/name" {
t.Fatalf("component diff = %#v, %v", diff, err)
}
if diff[0].Left.Present || !diff[0].Right.Present || !diff[1].Left.Present || diff[1].Right.Present {
t.Fatalf("null and absence = %#v", diff)
}
sequenceLeft, _ := left.InspectSubtree(configkit.Keys("items").Index(0))
sequenceRight, _ := right.InspectSubtree(configkit.Keys("items", "0"))
diff, err = sequenceLeft.Diff(sequenceRight)
if err != nil || len(diff) != 1 || diff[0].Path.String() != "/items" {
t.Fatalf("sequence ancestor = %#v, %v", diff, err)
}
missingLeft, _ := left.InspectSubtree(configkit.Keys("absent"))
missingRight, _ := right.InspectSubtree(configkit.Keys("absent"))
if diff, err = missingLeft.Diff(missingRight); err != nil || len(diff) != 0 {
t.Fatalf("absent diff = %#v, %v", diff, err)
}
if diff, err = lv.Diff(missingRight); err == nil || diff != nil {
t.Fatalf("mismatched diff = %#v, %v", diff, err)
}
if diff, err = (configkit.Inspection{}).Diff(lv); err == nil || diff != nil {
t.Fatalf("zero diff = %#v, %v", diff, err)
}
rootLeft, _ := left.InspectSubtree(configkit.Path{})
rootRight, _ := right.InspectSubtree(configkit.Path{})
if diff, err = rootLeft.Diff(rootRight); err != nil || len(diff) != 5 {
t.Fatalf("root diff = %#v, %v", diff, err)
}
if diff, err = lv.Diff(lv); err != nil || len(diff) != 0 {
t.Fatalf("equal diff = %#v, %v", diff, err)
}
}
func TestInspectionViewDiffRedactionAndShape(t *testing.T) {
load := func(input string, sensitive bool) *configkit.Result[map[string]any] {
t.Helper()
result, err := configkit.Load(configkit.Bytes("view.yml", []byte(input)), configkit.Options[map[string]any]{Definition: configkit.Definition[map[string]any]{Sensitive: func(path configkit.Path) bool { return sensitive && path.String() == "/component" }}})
if err != nil {
t.Fatal(err)
}
return result
}
left := load("component: {token: disposable-canary-left}\n", true)
right := load("component: {token: disposable-canary-right}\n", false)
lv, _ := left.InspectSubtree(configkit.Keys("component", "token"))
rv, _ := right.InspectSubtree(configkit.Keys("component", "token"))
diff, err := lv.Diff(rv)
if err != nil || len(diff) != 1 || !diff[0].Left.Redacted || !diff[0].Right.Redacted || !diff[0].HiddenChanged || strings.Contains(diff[0].Left.YAML+diff[0].Right.YAML, "disposable-canary") {
t.Fatalf("sensitive diff = %#v, %v", diff, err)
}
removed := load("other: public\n", false)
removedView, _ := removed.InspectSubtree(configkit.Keys("component", "token"))
diff, err = lv.Diff(removedView)
if err != nil || len(diff) != 1 || diff[0].Right.Present || !diff[0].Left.Redacted || strings.Contains(diff[0].Left.YAML, "disposable-canary") {
t.Fatalf("sensitive removal = %#v, %v", diff, err)
}
left = load("component: {'0': old}\n", false)
right = load("component: [new]\n", false)
lv, _ = left.InspectSubtree(configkit.Keys("component", "0"))
rv, _ = right.InspectSubtree(configkit.Keys("component").Index(0))
diff, err = lv.Diff(rv)
if err != nil || len(diff) != 1 || diff[0].Path.String() != "/component" {
t.Fatalf("shape diff = %#v, %v", diff, err)
}
}

View File

@@ -0,0 +1,134 @@
package configkit_test
import (
"bytes"
"io/fs"
"path"
"reflect"
"strings"
"testing"
"testing/fstest"
configkit "go.maximumdirect.net/configkit"
)
func TestInspectionViewHistoryAndResourceOwnership(t *testing.T) {
filesystem := configkit.NewFilesystem("component", fstest.MapFS{
"config/settings.yml": &fstest.MapFile{Data: []byte("entries:\n parent: {resource: asset.txt, removed: old}\n child: {extends: parent}\nsibling: retained\n")},
"config/asset.txt": &fstest.MapFile{Data: []byte("asset contents")},
})
load := func() *configkit.Result[map[string]any] {
t.Helper()
result, err := configkit.LoadLayered(configkit.Input{Source: filesystem.File("config/settings.yml"), Destination: configkit.Keys("component")}, configkit.LayeredOptions[map[string]any]{Definition: configkit.Definition[map[string]any]{
Resolve: func(current *map[string]any, resolution *configkit.Resolution) error {
child := (*current)["component"].(map[string]any)["entries"].(map[string]any)["child"].(map[string]any)
delete(child, "removed")
resolution.RecordNormalization(configkit.Keys("component", "entries", "child", "removed"), "remove old setting")
return nil
},
}})
if err != nil {
t.Fatal(err)
}
return result
}
result, other := load(), load()
scope := configkit.Keys("component", "entries", "child")
view, ok := result.InspectSubtree(scope)
if !ok {
t.Fatal("view unavailable")
}
removed := scope.Key("removed")
resource := scope.Key("resource")
paths := []string{}
for _, p := range view.HistoricalPaths() {
paths = append(paths, p.String())
}
if !strings.Contains(strings.Join(paths, ","), removed.String()) {
t.Fatalf("removed history missing: %v", paths)
}
if _, ok := view.Metadata().Lookup(removed); ok {
t.Fatal("removed value is effective")
}
explanation, ok := view.Explain(removed)
if !ok || explanation.Effective.Present || len(explanation.History) == 0 {
t.Fatalf("removed explanation = %#v, %v", explanation, ok)
}
if len(view.Metadata().History(removed)) == 0 {
t.Fatal("removed history missing")
}
info, ok := view.Metadata().Lookup(resource)
if !ok || len(info.Origin.Locations) == 0 || len(info.Origin.Inheritance) == 0 {
t.Fatalf("inherited origin = %#v, %v", info, ok)
}
id := info.Origin.Locations[0].SourceID
context, ok := view.SourceContext(id)
if !ok {
t.Fatal("source context missing")
}
data, err := fs.ReadFile(context.FS, path.Join(context.BaseDir, "asset.txt"))
if err != nil || string(data) != "asset contents" {
t.Fatalf("resource = %q, %v", data, err)
}
if _, ok := view.Source(id); !ok {
t.Fatal("source containing sibling missing")
}
before := bytes.Buffer{}
if err := view.WriteEffective(&before); err != nil {
t.Fatal(err)
}
otherView, _ := other.InspectSubtree(scope)
child := result.Config["component"].(map[string]any)["entries"].(map[string]any)["child"].(map[string]any)
child["resource"] = "changed"
if value, _ := result.Value(resource); value != "changed" {
t.Fatalf("current value = %v", value)
}
after := bytes.Buffer{}
if err := view.WriteEffective(&after); err != nil || !bytes.Equal(before.Bytes(), after.Bytes()) {
t.Fatalf("view changed = %q, %v", after.String(), err)
}
if diff, err := view.Diff(otherView); err != nil || len(diff) != 0 {
t.Fatalf("frozen diff = %#v, %v", diff, err)
}
info.Origin.Locations[0].SourceID = "changed"
again, _ := view.Metadata().Lookup(resource)
if again.Origin.Locations[0].SourceID != id {
t.Fatal("metadata was not detached")
}
explanation.Effective.YAML = "changed"
againExplanation, _ := view.Explain(removed)
if reflect.DeepEqual(explanation, againExplanation) {
t.Fatal("explanation was not detached")
}
}
func TestInspectionViewHistoricalNumericScope(t *testing.T) {
result, err := configkit.Load(configkit.Bytes("shape.yml", []byte("component: {'0': {old: value}}\n")), configkit.Options[map[string]any]{Definition: configkit.Definition[map[string]any]{
Resolve: func(current *map[string]any, resolution *configkit.Resolution) error {
(*current)["component"] = []any{map[string]any{"new": "value"}}
resolution.RecordNormalization(configkit.Keys("component"), "change shape")
return nil
},
}})
if err != nil {
t.Fatal(err)
}
key, _ := result.InspectSubtree(configkit.Keys("component", "0"))
index, _ := result.InspectSubtree(configkit.Keys("component").Index(0))
if !reflect.DeepEqual(key.HistoricalPaths(), index.HistoricalPaths()) {
t.Fatal("numeric reporting scopes differ")
}
var paths []string
for _, p := range key.HistoricalPaths() {
paths = append(paths, p.String())
}
if !strings.Contains(strings.Join(paths, ","), "/component/0/old") || !strings.Contains(strings.Join(paths, ","), "/component/0/new") {
t.Fatalf("shape history = %v", paths)
}
if _, ok := key.Metadata().Lookup(configkit.Keys("component", "0", "new")); ok {
t.Fatal("explicit key query changed intent")
}
if _, ok := key.Metadata().Lookup(configkit.Keys("component").Index(0).Key("new")); !ok {
t.Fatal("index query failed")
}
}

View File

@@ -0,0 +1,153 @@
package configkit_test
import (
"bytes"
"errors"
"reflect"
"strings"
"testing"
configkit "go.maximumdirect.net/configkit"
)
func TestInspectionViewScopeAndQueries(t *testing.T) {
result, err := configkit.Load[map[string]any](configkit.Bytes("view.yml", []byte("a: {child: one}\nab: two\nitems: [{name: first}]\n'a/b': {'': value}\n")))
if err != nil {
t.Fatal(err)
}
view, ok := result.InspectSubtree(configkit.Keys("a"))
if !ok {
t.Fatal("view unavailable")
}
var paths []string
for _, path := range view.HistoricalPaths() {
paths = append(paths, path.String())
}
if !reflect.DeepEqual(paths, []string{"/a", "/a/child"}) {
t.Fatalf("scope paths = %#v", paths)
}
if _, ok := view.Metadata().Lookup(configkit.Keys("ab")); !ok {
t.Fatal("metadata filtered")
}
if _, ok := view.Explain(configkit.Keys("ab")); !ok {
t.Fatal("native query filtered")
}
var output bytes.Buffer
if err := view.WriteExplanation(&output, configkit.Keys("ab")); err != nil {
t.Fatal(err)
}
if len(view.Sources()) != len(result.Sources()) || len(view.Sources()) == 0 {
t.Fatal("sources filtered")
}
if _, ok := view.Source(view.Sources()[0].ID); !ok {
t.Fatal("source unavailable")
}
if _, ok := result.InspectSubtree(configkit.Keys("absent")); !ok {
t.Fatal("absent scope rejected")
}
if _, ok := result.InspectSubtree(configkit.Path{}.Index(-1)); ok {
t.Fatal("invalid scope accepted")
}
keyScope, _ := result.InspectSubtree(configkit.Keys("items", "0"))
indexScope, _ := result.InspectSubtree(configkit.Keys("items").Index(0))
if !reflect.DeepEqual(keyScope.HistoricalPaths(), indexScope.HistoricalPaths()) {
t.Fatal("numeric scope differs")
}
escaped, _ := result.InspectSubtree(configkit.Keys("a/b", ""))
if got := escaped.HistoricalPaths(); len(got) != 1 || got[0].String() != "/a~1b/" {
t.Fatalf("escaped scope = %#v", got)
}
root, _ := result.InspectSubtree(configkit.Path{})
if !reflect.DeepEqual(root.HistoricalPaths(), result.Metadata().HistoricalPaths()) {
t.Fatal("root scope filtered")
}
}
type viewFailWriter struct{}
func (viewFailWriter) Write([]byte) (int, error) { return 0, errors.New("write failed") }
func TestInspectionViewWriteEffective(t *testing.T) {
options := configkit.Options[map[string]any]{Definition: configkit.Definition[map[string]any]{
Sensitive: func(path configkit.Path) bool { return path.String() == "/private" || path.String() == "/nested/token" },
Resolve: func(current *map[string]any, resolution *configkit.Resolution) error {
delete(*current, "removed")
resolution.RecordNormalization(configkit.Keys("removed"), "remove")
return nil
},
}}
result, err := configkit.Load(configkit.Bytes("view.yml", []byte("private: {child: canary-private}\nnested: {token: canary-token, name: public}\nitems: [zero, one]\n'0': numeric\n'null': null\nremoved: earlier\n")), options)
if err != nil {
t.Fatal(err)
}
for _, tc := range []struct {
path configkit.Path
contains string
absent string
fails bool
}{
{configkit.Path{}, "public", "canary-token", false},
{configkit.Keys("nested"), "public", "canary-token", false},
{configkit.Keys("private", "child"), "REDACTED", "canary-private", false},
{configkit.Keys("items"), "one", "", false},
{configkit.Keys("items").Index(1), "one", "", false},
{configkit.Path{}.Index(0), "numeric", "", false},
{configkit.Keys("null"), "null", "", false},
{configkit.Keys("removed"), "", "", true},
{configkit.Keys("missing"), "", "", true},
} {
view, ok := result.InspectSubtree(tc.path)
if !ok {
t.Fatal("view unavailable")
}
var out bytes.Buffer
err := view.WriteEffective(&out)
if (err != nil) != tc.fails || (tc.fails && out.Len() != 0) || (tc.contains != "" && !strings.Contains(out.String(), tc.contains)) || (tc.absent != "" && strings.Contains(out.String(), tc.absent)) {
t.Errorf("%s: %q, %v", tc.path.String(), out.String(), err)
}
}
view, _ := result.InspectSubtree(configkit.Keys("nested"))
result.Config["nested"] = "changed"
var out bytes.Buffer
if err := view.WriteEffective(&out); err != nil || !strings.Contains(out.String(), "public") {
t.Fatalf("frozen output = %q, %v", out.String(), err)
}
if err := view.WriteEffective(viewFailWriter{}); err == nil {
t.Fatal("writer error lost")
}
if err := view.WriteEffective(nil); err == nil {
t.Fatal("nil writer accepted")
}
if err := (configkit.Inspection{}).WriteEffective(&bytes.Buffer{}); err == nil {
t.Fatal("zero view accepted")
}
}
func TestInspectionViewUnavailable(t *testing.T) {
var result *configkit.Result[map[string]any]
if _, ok := result.InspectSubtree(configkit.Path{}); ok {
t.Fatal("nil result accepted")
}
if _, ok := (&configkit.Result[map[string]any]{}).InspectSubtree(configkit.Path{}); ok {
t.Fatal("manual result accepted")
}
var view configkit.Inspection
if len(view.HistoricalPaths()) != 0 || view.Sources() != nil {
t.Fatal("zero view returned records")
}
if _, ok := view.Metadata().Lookup(configkit.Path{}); ok {
t.Fatal("zero metadata")
}
if _, ok := view.Source("source-1"); ok {
t.Fatal("zero source")
}
if _, ok := view.SourceContext("source-1"); ok {
t.Fatal("zero source context")
}
if _, ok := view.Explain(configkit.Path{}); ok {
t.Fatal("zero explanation")
}
if err := view.WriteExplanation(&bytes.Buffer{}, configkit.Path{}); err == nil {
t.Fatal("zero explanation rendering")
}
}

187
facade_result_value_test.go Normal file
View File

@@ -0,0 +1,187 @@
package configkit_test
import (
"bytes"
"reflect"
"strings"
"testing"
configkit "go.maximumdirect.net/configkit"
)
type valueName string
type valueKey string
type valueEmbedded struct{ Label valueName }
type valueCodec struct{ Text string }
func (valueCodec) MarshalText() ([]byte, error) { panic("codec called during lookup") }
func (*valueCodec) UnmarshalText([]byte) error { panic("codec called during lookup") }
type valueConfig struct {
Embedded *valueEmbedded `yaml:",inline"`
Extra map[valueKey]any `yaml:",inline"`
List []string `yaml:"list"`
Array [2]int `yaml:"array"`
Dynamic any `yaml:"dynamic"`
Codec valueCodec `yaml:"codec"`
Pointer *valueEmbedded `yaml:"pointer"`
Nil *valueEmbedded `yaml:"nil"`
Ignored string `yaml:"-"`
private string
}
func TestResultValueCurrentNavigation(t *testing.T) {
var missing *configkit.Result[valueConfig]
if _, ok := missing.Value(configkit.Path{}); ok {
t.Fatal("nil result")
}
var nilMap map[string]int
result := &configkit.Result[valueConfig]{Config: valueConfig{
Embedded: &valueEmbedded{Label: "named"}, Extra: map[valueKey]any{"a/b": nil, "": nilMap, "0": 7},
List: []string{"first"}, Array: [2]int{1, 2}, Dynamic: map[string]any{"list": []any{valueEmbedded{Label: "dynamic"}}}, Pointer: &valueEmbedded{Label: "pointer"},
}}
parsed, _ := configkit.ParsePath("/dynamic/list/0/label")
parsedKey, _ := configkit.ParsePath("/0")
if got, ok := result.Value(configkit.Path{}); !ok || !reflect.DeepEqual(got, result.Config) {
t.Fatalf("root = %#v, %v", got, ok)
}
pointer, ok := result.Value(configkit.Keys("dynamic", "list").Index(0))
if !ok || pointer.(valueEmbedded).Label != "dynamic" {
t.Fatalf("struct terminal = %#v, %v", pointer, ok)
}
for _, tc := range []struct {
path configkit.Path
want any
ok bool
}{
{configkit.Keys("label"), valueName("named"), true},
{configkit.Keys("a/b"), nil, true}, {configkit.Keys(""), nilMap, true},
{parsedKey, 7, true}, {configkit.Path{}.Index(0), nil, false},
{configkit.Keys("list").Index(0), "first", true}, {configkit.Keys("list", "0"), nil, false},
{configkit.Keys("list").Index(1), nil, false}, {configkit.Keys("list").Index(-1), nil, false},
{parsed, valueName("dynamic"), true}, {configkit.Keys("ignored"), nil, false}, {configkit.Keys("private"), nil, false},
{configkit.Keys("codec"), valueCodec{}, true}, {configkit.Keys("codec", "text"), nil, false},
{configkit.Keys("nil"), (*valueEmbedded)(nil), true}, {configkit.Keys("nil", "label"), nil, false},
{configkit.Keys("pointer", "label"), valueName("pointer"), true},
} {
got, ok := result.Value(tc.path)
if ok != tc.ok || !reflect.DeepEqual(got, tc.want) {
t.Errorf("%s: got %#v, %v; want %#v, %v", tc.path.String(), got, ok, tc.want, tc.ok)
}
}
copyValue, _ := result.Value(configkit.Keys("array"))
array := copyValue.([2]int)
array[0] = 9
listValue, _ := result.Value(configkit.Keys("list"))
listValue.([]string)[0] = "changed"
mapValue, _ := result.Value(configkit.Keys("dynamic"))
mapValue.(map[string]any)["added"] = true
pointerValue, _ := result.Value(configkit.Keys("pointer"))
pointerValue.(*valueEmbedded).Label = "changed"
if result.Config.Array[0] != 1 || result.Config.List[0] != "changed" {
t.Fatal("assignment ownership differs")
}
if result.Config.Dynamic.(map[string]any)["added"] != true {
t.Fatal("map assignment did not preserve alias")
}
if result.Config.Pointer.Label != "changed" {
t.Fatal("pointer assignment did not preserve alias")
}
result.Config.Embedded = nil
if _, ok := result.Value(configkit.Keys("label")); ok {
t.Fatal("nil inline pointer")
}
result.Config.Dynamic = make(chan int)
if _, ok := result.Value(configkit.Keys("dynamic")); !ok {
t.Fatal("unsupported terminal unavailable")
}
if _, ok := result.Value(configkit.Keys("dynamic", "x")); ok {
t.Fatal("unsupported value traversed")
}
}
func TestResultValueFrozenInspectionAndSecret(t *testing.T) {
t.Setenv("CONFIGKIT_VALUE_TEST_SECRET", "disposable-value-canary")
type settings struct {
Name string `yaml:"name"`
Count int `yaml:"count"`
Token configkit.Secret `yaml:"token"`
}
result, err := configkit.Load[settings](configkit.Bytes("settings.yml", []byte("name: before\ntoken: CONFIGKIT_VALUE_TEST_SECRET\n")))
if err != nil {
t.Fatal(err)
}
if got, ok := result.Value(configkit.Keys("count")); !ok || got != 0 || result.Metadata().IsExplicit(configkit.Keys("count")) {
t.Fatalf("default = %#v, %v", got, ok)
}
secret, ok := result.Value(configkit.Keys("token"))
if !ok || secret.(configkit.Secret).Value() != "disposable-value-canary" {
t.Fatal("resolved secret unavailable")
}
result.Config.Name = "after"
if got, _ := result.Value(configkit.Keys("name")); got != "after" {
t.Fatalf("current value = %v", got)
}
var output bytes.Buffer
if err := result.WriteEffective(&output); err != nil {
t.Fatal(err)
}
if !strings.Contains(output.String(), "before") || strings.Contains(output.String(), "after") || strings.Contains(output.String(), "disposable-value-canary") {
t.Fatalf("frozen output = %s", output.String())
}
}
func TestResultValueReturnsTerminalsWithoutSchemaValidation(t *testing.T) {
type terminal struct {
A int `yaml:"same"`
B int `yaml:"same"`
}
want := terminal{A: 1, B: 2}
cases := []struct {
name string
lookup func(configkit.Path) (any, bool)
path configkit.Path
}{
{"map", (&configkit.Result[map[string]terminal]{Config: map[string]terminal{"item": want}}).Value, configkit.Keys("item")},
{"slice", (&configkit.Result[[]terminal]{Config: []terminal{want}}).Value, configkit.Path{}.Index(0)},
{"array", (&configkit.Result[[1]terminal]{Config: [1]terminal{want}}).Value, configkit.Path{}.Index(0)},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
got, ok := tc.lookup(tc.path)
if !ok || got != want {
t.Fatalf("terminal = %#v, %v", got, ok)
}
if _, ok := tc.lookup(tc.path.Key("same")); ok {
t.Fatal("ambiguous containing bindings accepted")
}
})
}
// A post-load replacement need not itself satisfy the load-time schema.
result, err := configkit.Load[map[string]any](configkit.Bytes("dynamic.yml", []byte("{}")))
if err != nil {
t.Fatal(err)
}
result.Config["dynamic"] = struct {
Child terminal `yaml:"child"`
Good int `yaml:"good"`
}{Child: want, Good: 3}
for _, tc := range []struct {
path configkit.Path
want any
}{
{configkit.Keys("dynamic", "child"), want},
{configkit.Keys("dynamic", "good"), 3},
} {
got, ok := result.Value(tc.path)
if !ok || got != tc.want {
t.Fatalf("%s = %#v, %v", tc.path.String(), got, ok)
}
}
if _, ok := result.Value(configkit.Keys("dynamic", "child", "same")); ok {
t.Fatal("ambiguous dynamic child accepted navigation")
}
if _, err := configkit.Load[map[string]terminal](configkit.NoSource()); err == nil {
t.Fatal("Load accepted an invalid element schema")
}
}

View File

@@ -0,0 +1,103 @@
package configkit_test
import (
"errors"
"os"
"path/filepath"
"testing"
configkit "go.maximumdirect.net/configkit"
)
var _ func(string) (*configkit.SecretsReport, error) = configkit.LoadSecretsIntoEnvironment
func TestFacadeSecretsOptionsAndConfiguredPrecedence(t *testing.T) {
root := t.TempDir()
directory := filepath.Join(root, "secrets")
if err := os.Mkdir(directory, 0o700); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(directory, "CONFIGKIT_FACADE_SECRET"), []byte("replacement\n"), 0o600); err != nil {
t.Fatal(err)
}
t.Setenv("CONFIGKIT_FACADE_SECRET", "old")
report, err := configkit.LoadSecretsIntoEnvironmentWithOptions(directory, configkit.SecretsOptions{Overwrite: true})
if err != nil || len(report.Entries()) != 1 || report.Entries()[0].Status != configkit.SecretFileLoaded || os.Getenv("CONFIGKIT_FACADE_SECRET") != "replacement" {
t.Fatalf("direct report = %#v, error = %v", report, err)
}
for _, test := range []struct {
name, setting, want string
overwrite *bool
}{
{"default", "", "old", nil},
{"yaml true", " secrets_overwrite: true\n", "replacement", nil},
{"false overrides true", " secrets_overwrite: true\n", "old", facadeBool(false)},
{"true overrides false", " secrets_overwrite: false\n", "replacement", facadeBool(true)},
} {
t.Run(test.name, func(t *testing.T) {
t.Setenv("CONFIGKIT_FACADE_SECRET", "old")
main := filepath.Join(root, "main.yml")
if err := os.WriteFile(main, []byte("config:\n secrets_dir: secrets\n"+test.setting+"value: original\n"), 0o600); err != nil {
t.Fatal(err)
}
var report *configkit.SecretsReport
var prepared configkit.Source
var err error
if test.overwrite == nil {
report, prepared, err = configkit.LoadSecretsIntoEnvironmentFromConfig(configkit.File(main))
} else {
report, prepared, err = configkit.LoadSecretsIntoEnvironmentFromConfig(configkit.File(main), configkit.SecretsFromConfigOptions{Overwrite: test.overwrite})
}
if err != nil || report == nil || len(report.Entries()) != 1 || os.Getenv("CONFIGKIT_FACADE_SECRET") != test.want {
t.Fatalf("report = %#v, error = %v", report, err)
}
if err := os.WriteFile(main, []byte("value: changed\n"), 0o600); err != nil {
t.Fatal(err)
}
loaded, err := configkit.Load[struct {
Value string `yaml:"value"`
}](prepared)
if err != nil || loaded.Config.Value != "original" {
t.Fatalf("prepared load = %#v, error = %v", loaded, err)
}
})
}
}
func facadeBool(value bool) *bool { return &value }
func TestFacadeSecretsFromConfigErrorsKeepPublicEvidence(t *testing.T) {
root := t.TempDir()
directReport, directErr := configkit.LoadSecretsIntoEnvironmentWithOptions(filepath.Join(root, "missing"), configkit.SecretsOptions{Overwrite: true})
var directFailure *configkit.SecretsError
if directReport == nil || !errors.As(directErr, &directFailure) || len(directFailure.Diagnostics()) != 1 || directFailure.Diagnostics()[0].Code != configkit.CodeSecretsMissing {
t.Fatalf("direct report = %#v, error = %#v", directReport, directErr)
}
main := filepath.Join(root, "main.yml")
if err := os.WriteFile(main, []byte("config: {secrets_overwrite: invalid}\n"), 0o600); err != nil {
t.Fatal(err)
}
report, prepared, err := configkit.LoadSecretsIntoEnvironmentFromConfig(configkit.File(main), configkit.SecretsFromConfigOptions{Overwrite: facadeBool(false)})
var loadErr *configkit.LoadError
if report == nil || len(report.Entries()) != 0 || !errors.As(err, &loadErr) || len(loadErr.Sources()) != 1 || len(loadErr.Diagnostics()) != 1 || loadErr.Diagnostics()[0].Code != configkit.CodeSecretsInvalidValue || loadErr.Diagnostics()[0].Primary == nil || loadErr.Diagnostics()[0].Primary.SourceID != loadErr.Sources()[0].ID {
t.Fatalf("preparation report = %#v, error = %#v", report, err)
}
if _, err := configkit.Load[struct{}](prepared); err == nil {
t.Fatal("failed preparation returned a usable source")
}
report, _, err = configkit.LoadSecretsIntoEnvironmentFromConfig(configkit.File(main), configkit.SecretsFromConfigOptions{}, configkit.SecretsFromConfigOptions{})
if report == nil || !errors.As(err, &loadErr) || len(loadErr.Diagnostics()) != 1 || loadErr.Diagnostics()[0].Code != configkit.CodeOptionsInvalid || len(loadErr.Sources()) != 0 {
t.Fatalf("multiple options report = %#v, error = %#v", report, err)
}
if err := os.WriteFile(main, []byte("config: {secrets_dir: missing}\n"), 0o600); err != nil {
t.Fatal(err)
}
report, prepared, err = configkit.LoadSecretsIntoEnvironmentFromConfig(configkit.File(main))
var secretsErr *configkit.SecretsError
if report == nil || !errors.As(err, &secretsErr) || len(secretsErr.Diagnostics()) != 1 || secretsErr.Diagnostics()[0].Code != configkit.CodeSecretsMissing {
t.Fatalf("directory report = %#v, error = %#v", report, err)
}
if _, err := configkit.Load[struct{}](prepared); err == nil {
t.Fatal("failed bootstrap returned a usable source")
}
}

View File

@@ -0,0 +1,180 @@
package configkit_test
import (
"errors"
"io/fs"
"os"
"path/filepath"
"sync"
"testing"
configkit "go.maximumdirect.net/configkit"
)
type startupHandoffConfig struct {
Main string `yaml:"main"`
Imported string `yaml:"imported"`
Underlay string `yaml:"underlay"`
Overlay string `yaml:"overlay"`
Asset string `yaml:"asset"`
Token configkit.Secret `yaml:"token"`
}
func TestConfiguredSecretsStartupHandoff(t *testing.T) {
root := t.TempDir()
other := t.TempDir()
t.Chdir(other)
write := func(name, contents string) string {
t.Helper()
file := filepath.Join(root, name)
if err := os.MkdirAll(filepath.Dir(file), 0o700); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(file, []byte(contents), 0o600); err != nil {
t.Fatal(err)
}
return file
}
const tokenName = "CONFIGKIT_HANDOFF_TOKEN"
const sdkName = "CONFIGKIT_HANDOFF_SDK_ONLY"
const emptyName = "CONFIGKIT_HANDOFF_EMPTY"
t.Setenv(tokenName, "previous")
t.Setenv(sdkName, "previous-sdk")
t.Setenv(emptyName, "")
write("app/secrets/"+tokenName, "bootstrap-token\n")
write("app/secrets/"+sdkName, "bootstrap-sdk\n")
write("app/secrets/"+emptyName, "bootstrap-empty\n")
write("app/fragment.yml", "imported: before\n")
write("app/lower.yml", "underlay: companion\n")
write("app/overlays/dev.yml", "overlay: selected\n")
write("app/asset.txt", "resource-data")
main := write("app/main.yml", "config: {secrets_dir: secrets, secrets_overwrite: true, imports: [{path: fragment.yml}]}\nmain: captured\nasset: asset.txt\ntoken: "+tokenName+"\n")
candidate := filepath.Join(root, "app", "earlier.yml")
search := configkit.SearchConfig("app", configkit.SearchPaths(candidate, main))
report, prepared, err := configkit.LoadSecretsIntoEnvironmentFromConfig(search, configkit.SecretsFromConfigOptions{Filesystem: &configkit.FilesystemContext{Root: root}})
if err != nil || report == nil || len(report.Entries()) != 3 || os.Getenv(tokenName) != "bootstrap-token" || os.Getenv(sdkName) != "bootstrap-sdk" || os.Getenv(emptyName) != "bootstrap-empty" {
t.Fatalf("prepare report = %#v, error = %v", report, err)
}
for _, entry := range report.Entries() {
if entry.Status != configkit.SecretFileLoaded {
t.Fatalf("bootstrap entry = %#v", entry)
}
}
options := configkit.Options[startupHandoffConfig]{Imports: true}
first, err := configkit.Load[startupHandoffConfig](prepared, options)
if err != nil || first.Config.Main != "captured" || first.Config.Imported != "before" || first.Config.Token.Value() != "bootstrap-token" {
t.Fatalf("first load = %#v, %v", first, err)
}
write("app/main.yml", "main: changed\n")
write("app/earlier.yml", "main: different-candidate\n")
write("app/fragment.yml", "imported: after\n")
if err := os.Setenv(tokenName, "later-token"); err != nil {
t.Fatal(err)
}
second, err := configkit.Load[startupHandoffConfig](prepared, options)
if err != nil || second.Config.Main != "captured" || second.Config.Imported != "after" || second.Config.Token.Value() != "later-token" || first.Config.Imported != "before" || first.Config.Token.Value() != "bootstrap-token" {
t.Fatalf("subsequent load = %#v, %v", second, err)
}
sources := second.Sources()
canonicalMain, err := filepath.EvalSymlinks(main)
if err != nil {
t.Fatal(err)
}
if len(sources) != 2 || sources[0].Kind != configkit.SourceKindFile || sources[0].Path != canonicalMain || sources[0].ID != "source-1" || sources[1].ID != "source-2" {
t.Fatalf("sources = %#v", sources)
}
sources[0].Label = "modified"
if second.Sources()[0].Label == "modified" || first.Sources()[0].Label == "modified" {
t.Fatal("source evidence is shared")
}
context, ok := second.SourceContext("source-1")
if !ok || context.BaseDir != "app" {
t.Fatalf("source context = %#v, %v", context, ok)
}
if data, err := fs.ReadFile(context.FS, "app/asset.txt"); err != nil || string(data) != "resource-data" {
t.Fatalf("resource = %q, %v", data, err)
}
underlay := configkit.Input{Source: configkit.Bytes("companion", []byte("config: {imports: [{path: lower.yml}]}\n")), Imports: true, MainRelative: configkit.MainRelative()}
layered, err := configkit.LoadLayered(configkit.Input{Source: prepared, Imports: true, Filesystem: &configkit.FilesystemContext{Root: root}}, configkit.LayeredOptions[startupHandoffConfig]{
Underlays: []configkit.Underlay{{Inputs: []configkit.Input{underlay}}}, Overlay: "dev",
})
if err != nil || layered.Config.Underlay != "companion" || layered.Config.Overlay != "selected" || layered.Config.Imported != "after" {
t.Fatalf("layered load = %#v, %v", layered, err)
}
_, err = configkit.LoadLayered(configkit.Input{Source: prepared, Filesystem: &configkit.FilesystemContext{Root: filepath.Join(root, "app")}}, configkit.LayeredOptions[startupHandoffConfig]{})
var loadErr *configkit.LoadError
if !errors.As(err, &loadErr) || len(loadErr.Diagnostics()) == 0 || loadErr.Diagnostics()[0].Code != configkit.CodeOptionsInvalid || os.Getenv(tokenName) != "later-token" {
t.Fatalf("incompatible context error = %v", err)
}
_, err = configkit.Load[startupHandoffConfig](prepared, configkit.Options[startupHandoffConfig]{Imports: true, Definition: configkit.Definition[startupHandoffConfig]{Validate: func(_ *startupHandoffConfig, validation *configkit.Validation) {
validation.Error(configkit.Keys("main"), "invalid startup setting")
}}})
if !errors.As(err, &loadErr) || os.Getenv(tokenName) != "later-token" || os.Getenv(sdkName) != "bootstrap-sdk" || len(report.Entries()) != 3 {
t.Fatalf("later validation error = %v, report = %#v", err, report)
}
var group sync.WaitGroup
errorsFound := make(chan error, 8)
for range 8 {
group.Go(func() {
loaded, err := configkit.Load[startupHandoffConfig](prepared, options)
if err != nil {
errorsFound <- err
} else if loaded.Config.Main != "captured" || loaded.Config.Token.Value() != "later-token" {
errorsFound <- errors.New("captured source produced unexpected values")
}
})
}
group.Wait()
close(errorsFound)
for err := range errorsFound {
t.Error(err)
}
}
func TestConfiguredSecretsPreservesExistingEmptyValue(t *testing.T) {
root := t.TempDir()
if err := os.Mkdir(filepath.Join(root, "secrets"), 0o700); err != nil {
t.Fatal(err)
}
const name = "CONFIGKIT_HANDOFF_PRESERVED_EMPTY"
t.Setenv(name, "")
if err := os.WriteFile(filepath.Join(root, "secrets", name), []byte("replacement"), 0o600); err != nil {
t.Fatal(err)
}
main := filepath.Join(root, "main.yml")
if err := os.WriteFile(main, []byte("config: {secrets_dir: secrets}\nmain: value\n"), 0o600); err != nil {
t.Fatal(err)
}
report, _, err := configkit.LoadSecretsIntoEnvironmentFromConfig(configkit.File(main))
if err != nil || len(report.Entries()) != 1 || report.Entries()[0].Status != configkit.SecretFileSkippedExisting || !report.Entries()[0].ExistingEmpty || os.Getenv(name) != "" {
t.Fatalf("report = %#v, error = %v", report, err)
}
}
func TestOrdinaryLoadingNeverBootstrapsSecrets(t *testing.T) {
root := t.TempDir()
if err := os.Mkdir(filepath.Join(root, "secrets"), 0o700); err != nil {
t.Fatal(err)
}
const name = "CONFIGKIT_NO_AUTOMATIC_BOOTSTRAP"
t.Setenv(name, "existing")
if err := os.WriteFile(filepath.Join(root, "secrets", name), []byte("replacement"), 0o600); err != nil {
t.Fatal(err)
}
main := filepath.Join(root, "main.yml")
if err := os.WriteFile(main, []byte("config: {secrets_dir: secrets, secrets_overwrite: true}\nmain: ordinary\n"), 0o600); err != nil {
t.Fatal(err)
}
type ordinaryConfig struct {
Main string `yaml:"main"`
}
if _, err := configkit.Load[ordinaryConfig](configkit.File(main)); err != nil {
t.Fatal(err)
}
if _, err := configkit.LoadLayered(configkit.Input{Source: configkit.File(main)}, configkit.LayeredOptions[ordinaryConfig]{}); err != nil {
t.Fatal(err)
}
if os.Getenv(name) != "existing" {
t.Fatal("ordinary loading changed the environment")
}
}

8
go.mod
View File

@@ -2,12 +2,12 @@ module go.maximumdirect.net/configkit
go 1.27.0
require go.yaml.in/yaml/v4 v4.0.0-rc.6
require go.yaml.in/yaml/v4 v4.0.0
require (
github.com/yuin/goldmark/v2 v2.1.6 // indirect
go.maximumdirect.net/releasekit v0.8.0 // indirect
golang.org/x/mod v0.40.0 // indirect
github.com/yuin/goldmark/v2 v2.1.16 // indirect
go.maximumdirect.net/releasekit v0.10.0 // indirect
golang.org/x/mod v0.43.0 // indirect
)
tool go.maximumdirect.net/releasekit/cmd/releasekit

16
go.sum
View File

@@ -1,8 +1,8 @@
github.com/yuin/goldmark/v2 v2.1.6 h1:igy0q9JcqovoFXFx/XjtU8sHVhcUHavPj2sA3EoKJUE=
github.com/yuin/goldmark/v2 v2.1.6/go.mod h1:G6M4/qOFtfn01/o14BU1UR2Lo5N3S9Qo7xCuz/sHjGQ=
go.maximumdirect.net/releasekit v0.8.0 h1:hSaHPbUI7tAhnolfbu7UMj2fvmm9FGBY+jhkygdbxR0=
go.maximumdirect.net/releasekit v0.8.0/go.mod h1:QE4BLrAhVJTzi+/YTcVl21K/qZp9ojRLg5kuoy3Zb44=
go.yaml.in/yaml/v4 v4.0.0-rc.6 h1:1h7H1ohdUh93/FyE4YaDa1Zh64K6VVbjF4K6WUxMtH4=
go.yaml.in/yaml/v4 v4.0.0-rc.6/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
golang.org/x/mod v0.40.0 h1:hUv+3cXcdRHz08UmSiOob7sadHig73uo5bkXxQ/tvUs=
golang.org/x/mod v0.40.0/go.mod h1:0/weTWkPWGBikyTWAX3dkjVztMmBA5hM0DH6BElSupE=
github.com/yuin/goldmark/v2 v2.1.16 h1:MXvCVo+Cb2SVJ5cwJUzXetDjI7HECRJCkcqylEQtcJo=
github.com/yuin/goldmark/v2 v2.1.16/go.mod h1:G6M4/qOFtfn01/o14BU1UR2Lo5N3S9Qo7xCuz/sHjGQ=
go.maximumdirect.net/releasekit v0.10.0 h1:3GOgaIigXTkvYaRkntWZASE//2NTR1+IhkoKmt64aJo=
go.maximumdirect.net/releasekit v0.10.0/go.mod h1:cT5NZNEcf7SKDx4MPG40YNK9V4bNyIxcLLFuNlbGQ90=
go.yaml.in/yaml/v4 v4.0.0 h1:/LG1pNO84Z4l603j/xMn69CcS5OYhMQ/f7l2LoQUGuw=
go.yaml.in/yaml/v4 v4.0.0/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
golang.org/x/mod v0.43.0 h1:MFuq5J6s35W9D3IjkwyWc9vHh0nENOrt5K8Iof4ofmg=
golang.org/x/mod v0.43.0/go.mod h1:4ec1JnuyBz5+FIVhg86UsA39YG8BpnrZdJYSNHmGzHY=

88
inspection_view.go Normal file
View File

@@ -0,0 +1,88 @@
package configkit
import (
"io"
"go.maximumdirect.net/configkit/internal/engine"
)
// Inspection is a reporting view of a completed load. Its scope filters
// enumeration; explicit queries and source records retain their native paths.
type Inspection struct{ view engine.InspectionView }
// InspectSubtree selects a canonical JSON Pointer reporting location, including
// an absent location. Equivalent key and index spellings select the same scope.
// Nil, manually constructed results and invalid paths cannot produce a view.
func (r *Result[T]) InspectSubtree(path Path) (Inspection, bool) {
if r == nil {
return Inspection{}, false
}
view, ok := engine.NewInspectionView(r.inspection, toEnginePath(path))
return Inspection{view: view}, ok
}
// Metadata returns the unfiltered metadata of the completed load.
func (i Inspection) Metadata() Metadata { return Metadata{value: i.view.Inspection().Metadata()} }
// HistoricalPaths returns observed paths at or beneath the reporting scope.
func (i Inspection) HistoricalPaths() []Path {
values := i.view.HistoricalPaths()
paths := make([]Path, len(values))
for index := range values {
paths[index] = fromEnginePath(values[index])
}
return paths
}
// WriteEffective renders the saved value at the reporting scope with its
// original sensitivity. Unavailable values and nil writers return an error;
// writer errors can leave partial output.
func (i Inspection) WriteEffective(output io.Writer) error { return i.view.WriteEffective(output) }
// Diff compares frozen views at the same canonical scope, including differences
// at an ancestor when the existing comparison treats that ancestor atomically.
// Views may come from different root Go types. Unavailable or mismatched views
// return an error without records.
func (i Inspection) Diff(other Inspection) ([]Difference, error) {
values, err := i.view.Diff(other.view)
if err != nil {
return nil, err
}
return fromEngineDifferences(values), nil
}
// Sources returns the full detached source catalog.
func (i Inspection) Sources() []SourceInfo {
values := i.view.Inspection().Sources()
if values == nil {
return nil
}
result := make([]SourceInfo, len(values))
for index := range values {
result[index] = fromEngineSourceInfo(values[index])
}
return result
}
// Source returns a detached record from the full source catalog.
func (i Inspection) Source(id string) (SourceInfo, bool) {
value, ok := i.view.Inspection().Source(id)
return fromEngineSourceInfo(value), ok
}
// SourceContext returns the borrowed resource context for an acquired source.
func (i Inspection) SourceContext(id string) (ResourceContext, bool) {
value, ok := i.view.Inspection().SourceContext(id)
return ResourceContext{FS: value.FS, BaseDir: value.BaseDir}, ok
}
// Explain queries a native path, whether or not it lies within the scope.
func (i Inspection) Explain(path Path) (Explanation, bool) {
value, ok := i.view.Inspection().Explain(toEnginePath(path))
return fromEngineExplanation(value), ok
}
// WriteExplanation renders an explicit native path using the frozen load.
func (i Inspection) WriteExplanation(output io.Writer, path Path) error {
return i.view.Inspection().WriteExplanation(output, toEnginePath(path))
}

View File

@@ -43,22 +43,15 @@ func acquireInput(request inputAcquisitionRequest, policy acquisitionPolicy, sta
accounting := state.accounting
versionState := state.versionState
sourceID := "source-" + strconv.Itoa(accounting.sources+1)
selectedSource := source
if source.kind == sourceSearch {
resolved, failedSource, diagnostics := resolveSearchInput(source, sourceID, defaultDiscoveryDirectoryHelpers(), defaultDiscoveryHostProbe())
if len(diagnostics) != 0 {
selectedSource, failedSource, selectionDiagnostics := selectInputSource(source, sourceID, request.input.filesystem)
if len(selectionDiagnostics) != 0 {
if failedSource != nil {
failedSource.Destination = destination.clone()
failedSource.placementMode = request.input.placementMode
}
return assembledInput{source: resolved, sources: sourceInfos(failedSource), versionState: versionState, accounting: accounting}, diagnostics
}
selectedSource = resolved
if request.input.filesystem != nil {
if diagnostics := filesystemOptionDiagnostics(selectedSource, request.input.filesystem); len(diagnostics) != 0 {
return assembledInput{source: selectedSource, versionState: versionState, accounting: accounting}, diagnostics
}
return assembledInput{source: selectedSource, sources: sourceInfos(failedSource), versionState: versionState, accounting: accounting}, selectionDiagnostics
}
if source.kind == sourceSearch {
if selectedSource.kind == sourceNone && activeOverlay(request.ordinaryOverlay) && request.input.filesystem == nil {
return assembledInput{source: selectedSource, versionState: versionState, accounting: accounting}, []Diagnostic{optionDiagnostic(CodeOptionsInvalid, "NoSource overlays require explicit filesystem context")}
}
@@ -85,6 +78,13 @@ func acquireInput(request inputAcquisitionRequest, policy acquisitionPolicy, sta
}
return input, diagnostics
}
if selectedSource.captured != nil {
resolved, diagnostic := resolveFilesystemContext(selectedSource, request.input.filesystem, parsed, tier.hostToken)
if diagnostic != nil {
return input, []Diagnostic{*diagnostic}
}
request.resolved = &resolved
}
directiveContext := request.directiveContext
if directiveContext == 0 {
directiveContext = rootDirectiveContextImportsOnly
@@ -137,9 +137,11 @@ func acquireStandaloneInput(input assembledInput, request inputAcquisitionReques
input.document = processing.payload
}
if request.resolved != nil {
if input.source.captured == nil || request.input.filesystem != nil {
if diagnostic := validateResolvedFilesystemContext(*request.resolved); diagnostic != nil {
return input, []Diagnostic{*diagnostic}
}
}
input.resolvedFilesystem = request.resolved
}
if request.input.filesystem != nil && (input.source.kind == sourceNone || !activeOverlay(request.ordinaryOverlay)) {

View File

@@ -12,7 +12,7 @@ func acquireContextlessInput(input assembledInput, request inputAcquisitionReque
body, declarations = processing.payload, processing.imports
sequences = cloneSequenceDeclarations(processing.sequences)
} else {
body, declarations, diagnostics = splitImportDirectives(parsed.document)
body, declarations, diagnostics = splitImportDirectives(parsed.document, request.role)
}
destination := request.input.destination
localDestination := destination

View File

@@ -129,7 +129,7 @@ parent: true
betaPath := writeImportFile(t, directory, "fragments/b.yml", "beta: true\n")
main := parseImportMain(t, mainPath)
_, declarations, diagnostics := splitImportDirectives(main.document)
_, declarations, diagnostics := splitImportDirectives(main.document, sourceVersionMain)
if len(diagnostics) != 0 {
t.Fatalf("main directive diagnostics = %#v", diagnostics)
}

View File

@@ -2,6 +2,7 @@ package engine
import (
"reflect"
"runtime"
"testing"
"go.maximumdirect.net/configkit/internal/document"
@@ -18,7 +19,7 @@ records:
configkit: {imports: [{path: absent.yaml}]}
_configkit: ordinary
`)
extracted, diagnostics := extractRootDirectives(root, rootDirectiveContextSource)
extracted, diagnostics := extractRootDirectives(root, rootDirectiveContextSource, sourceVersionContribution)
if len(diagnostics) != 0 || len(extracted.imports) != 1 {
t.Fatalf("extraction = %#v, diagnostics = %#v", extracted, diagnostics)
}
@@ -59,7 +60,7 @@ func TestDocumentRootControlValidation(t *testing.T) {
{"bad imports", "config: {imports: wrong}\n", CodeImportInvalid, "/config/imports"},
} {
t.Run(test.name, func(t *testing.T) {
_, diagnostics := extractRootDirectives(parseRootDirectiveDocument(t, test.input), rootDirectiveContextSource)
_, diagnostics := extractRootDirectives(parseRootDirectiveDocument(t, test.input), rootDirectiveContextSource, sourceVersionContribution)
if len(diagnostics) == 0 || diagnostics[0].Code != test.code || diagnostics[0].Path.String() != test.path {
t.Fatalf("diagnostics = %#v", diagnostics)
}
@@ -87,7 +88,101 @@ func TestDocumentRootControlGuards(t *testing.T) {
if got := overlayDirectiveDiagnostics(sequences, Path{}, true); len(got) != 0 {
t.Fatalf("overlay sequences diagnostics = %#v", got)
}
if _, got := extractRootDirectives(sequences, rootDirectiveContextImportsOnly); len(got) == 0 || got[0].Code != CodeSequenceInvalid {
if _, got := extractRootDirectives(sequences, rootDirectiveContextImportsOnly, sourceVersionContribution); len(got) == 0 || got[0].Code != CodeSequenceInvalid {
t.Fatalf("imports-only extraction diagnostics = %#v", got)
}
}
func TestBootstrapControlExtraction(t *testing.T) {
root := parseRootDirectiveDocument(t, "config:\n imports: invalid\n secrets_dir: ../secrets\n secrets_overwrite: false\n")
settings, diagnostics := extractBootstrapSettings(root)
if len(diagnostics) != 0 || !settings.directoryDeclared || settings.directory != "../secrets" || !settings.overwriteDeclared || settings.overwrite || settings.directoryLocation.Line != 3 || settings.overwriteLocation.Line != 4 {
t.Fatalf("settings = %#v, diagnostics = %#v", settings, diagnostics)
}
if _, diagnostics := extractRootDirectives(root, rootDirectiveContextSource, sourceVersionMain); len(diagnostics) == 0 {
t.Fatal("normal extraction did not validate unrelated import grammar")
}
for _, test := range []struct {
input string
code Code
path string
}{
{"config: {secrets_dir: ''}", CodeSecretsInvalidPath, "/config/secrets_dir"},
{"config: {secrets_dir: /absolute}", CodeSecretsInvalidPath, "/config/secrets_dir"},
{"config: {secrets_dir: null}", CodeSecretsInvalidPath, "/config/secrets_dir"},
{"config: {secrets_dir: 123}", CodeSecretsInvalidPath, "/config/secrets_dir"},
{"config: {secrets_overwrite: null}", CodeSecretsInvalidValue, "/config/secrets_overwrite"},
{"config: {secrets_overwrite: 'true'}", CodeSecretsInvalidValue, "/config/secrets_overwrite"},
{"config: invalid", CodeImportInvalid, "/config"},
} {
t.Run(test.input, func(t *testing.T) {
root := parseRootDirectiveDocument(t, test.input+"\n")
_, preparation := extractBootstrapSettings(root)
_, normal := extractRootDirectives(root, rootDirectiveContextSource, sourceVersionMain)
for _, got := range [][]Diagnostic{preparation, normal} {
if len(got) != 1 || got[0].Code != test.code || got[0].Path.String() != test.path || got[0].Primary == nil || got[0].Primary.Line != 1 {
t.Fatalf("diagnostics = %#v", got)
}
}
})
}
}
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} {
main, diagnostics := extractRootDirectives(root, context, sourceVersionMain)
if len(diagnostics) != 0 || len(main.body.Mapping) != 1 || main.body.Mapping[0].Key != "value" {
t.Fatalf("main extraction = %#v, diagnostics = %#v", main, diagnostics)
}
_, diagnostics = extractRootDirectives(root, context, sourceVersionContribution)
if len(diagnostics) != 2 || diagnostics[0].Code != CodeImportInvalid || diagnostics[1].Code != CodeImportInvalid {
t.Fatalf("contribution diagnostics = %#v", diagnostics)
}
}
_, diagnostics := extractRootDirectives(root, rootDirectiveContextOverlay, sourceVersionContribution)
if len(diagnostics) != 2 || diagnostics[0].Code != CodeOverlayDirective || diagnostics[1].Code != CodeOverlayDirective {
t.Fatalf("overlay diagnostics = %#v", diagnostics)
}
for _, name := range []string{"secrets_dir", "secrets_overwrite"} {
if !sourceVersionControlOverlap(root, Keys("config", name)) {
t.Errorf("version overlap not detected for %s", name)
}
}
}
func TestBootstrapControlsKeepSourceVersionChecksInLoad(t *testing.T) {
root := parseRootDirectiveDocument(t, "config: {secrets_dir: secrets, secrets_overwrite: false}\nversion: 1\n")
called := false
rule := &VersionRule{Path: Keys("version"), Check: func(Version, *Validation) error {
called = true
return nil
}}
if _, diagnostics := extractBootstrapSettings(root); len(diagnostics) != 0 || called {
t.Fatalf("preparation diagnostics = %#v, checker called = %v", diagnostics, called)
}
result := processSourceVersionWithDirectiveContext(root, rule, sourceVersionMain, Path{}, sourceVersionModeRequired, rootDirectiveContextSource)
if len(result.diagnostics) != 0 || !called {
t.Fatalf("load diagnostics = %#v, checker called = %v", result.diagnostics, called)
}
for _, name := range []string{"secrets_dir", "secrets_overwrite"} {
rule.Path = Keys("config", name)
result = processSourceVersionWithDirectiveContext(root, rule, sourceVersionMain, Path{}, sourceVersionModeRequired, rootDirectiveContextSource)
if len(result.diagnostics) != 1 || result.diagnostics[0].Code != CodeVersionError {
t.Errorf("overlap %s diagnostics = %#v", name, result.diagnostics)
}
}
}

View File

@@ -1,7 +1,9 @@
package engine
import (
"os"
"path"
"path/filepath"
"strings"
"go.maximumdirect.net/configkit/internal/document"
@@ -24,15 +26,71 @@ type rootDirectiveExtraction struct {
sequences []sequenceDeclarationSpec
}
func splitImportDirectives(root *document.Node) (*document.Node, []importDeclarationSpec, []Diagnostic) {
extracted, diagnostics := extractRootDirectives(root, rootDirectiveContextImportsOnly)
// bootstrapSettings retains only source-local control facts, never credentials.
type bootstrapSettings struct {
directoryDeclared bool
directory string
directoryLocation document.Location
overwriteDeclared bool
overwrite bool
overwriteLocation document.Location
}
// extractBootstrapSettings validates only the controls needed for preparation;
// normal loading remains responsible for the rest of the directive grammar.
func extractBootstrapSettings(root *document.Node) (bootstrapSettings, []Diagnostic) {
var settings bootstrapSettings
if root == nil || root.Kind != document.Mapping {
return settings, nil
}
for _, entry := range root.Mapping {
if entry.Key != directiveKey {
continue
}
if entry.Value == nil || entry.Value.Kind != document.Mapping {
return settings, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, Keys(directiveKey), "configuration directive must be a mapping", entry.Value)}
}
var diagnostics []Diagnostic
for _, field := range entry.Value.Mapping {
if field.Key == "secrets_dir" || field.Key == "secrets_overwrite" {
if diagnostic := parseBootstrapField(&settings, field); diagnostic != nil {
diagnostics = append(diagnostics, *diagnostic)
}
}
}
return settings, canonicalDiagnostics(diagnostics)
}
return settings, nil
}
func parseBootstrapField(settings *bootstrapSettings, entry document.Entry) *Diagnostic {
value := entry.Value
fieldPath := Keys(directiveKey, entry.Key)
if entry.Key == "secrets_dir" {
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
}
settings.directoryDeclared, settings.directory, settings.directoryLocation = true, value.Text, value.Location
return nil
}
if value == nil || value.Kind != document.Boolean {
diagnostic := nodeImportDiagnostic(CodeSecretsInvalidValue, fieldPath, "secrets overwrite setting must be a Boolean", value)
return &diagnostic
}
settings.overwriteDeclared, settings.overwrite, settings.overwriteLocation = true, value.Text == "true", value.Location
return nil
}
func splitImportDirectives(root *document.Node, role sourceVersionRole) (*document.Node, []importDeclarationSpec, []Diagnostic) {
extracted, diagnostics := extractRootDirectives(root, rootDirectiveContextImportsOnly, role)
if len(diagnostics) != 0 {
return nil, nil, diagnostics
}
return extracted.body, extracted.imports, nil
}
func extractRootDirectives(root *document.Node, context rootDirectiveContext) (rootDirectiveExtraction, []Diagnostic) {
func extractRootDirectives(root *document.Node, context rootDirectiveContext, role sourceVersionRole) (rootDirectiveExtraction, []Diagnostic) {
if root == nil {
return rootDirectiveExtraction{}, nil
}
@@ -43,7 +101,7 @@ func extractRootDirectives(root *document.Node, context rootDirectiveContext) (r
continue
}
directiveIndex = index
extracted, diagnostics := parseRootDirectiveBlock(entry.Value, Keys(directiveKey), context)
extracted, diagnostics := parseRootDirectiveBlock(entry.Value, Keys(directiveKey), context, role)
if len(diagnostics) != 0 {
return rootDirectiveExtraction{}, diagnostics
}
@@ -56,7 +114,7 @@ func extractRootDirectives(root *document.Node, context rootDirectiveContext) (r
return rootDirectiveExtraction{body: body}, nil
}
func parseRootDirectiveBlock(node *document.Node, directivePath Path, context rootDirectiveContext) (rootDirectiveExtraction, []Diagnostic) {
func parseRootDirectiveBlock(node *document.Node, directivePath Path, context rootDirectiveContext, role sourceVersionRole) (rootDirectiveExtraction, []Diagnostic) {
if node == nil || node.Kind != document.Mapping {
return rootDirectiveExtraction{}, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, directivePath, "configuration directive must be a mapping", node)}
}
@@ -89,6 +147,19 @@ func parseRootDirectiveBlock(node *document.Node, directivePath Path, context ro
parsed, issues := parseSequenceDeclarationDirective(entry.Value, fieldPath)
extracted.sequences = append(extracted.sequences, parsed...)
diagnostics = append(diagnostics, issues...)
case "secrets_dir", "secrets_overwrite":
if role != sourceVersionMain || context == rootDirectiveContextOverlay {
code := CodeImportInvalid
if context == rootDirectiveContextOverlay {
code = CodeOverlayDirective
}
diagnostics = append(diagnostics, nodeImportDiagnostic(code, fieldPath, "secrets bootstrap controls are only permitted in the main document", entry.Value))
continue
}
var settings bootstrapSettings
if diagnostic := parseBootstrapField(&settings, entry); diagnostic != nil {
diagnostics = append(diagnostics, *diagnostic)
}
default:
diagnostics = append(diagnostics, nodeImportDiagnostic(CodeImportInvalid, fieldPath, "configuration directive field is not recognized", entry.Value))
}

View File

@@ -17,6 +17,9 @@ type resolvedFilesystemContext struct {
}
func resolveFilesystemContext(source Source, context *FilesystemContext, main parsedSource, hostToken *namespaceToken) (resolvedFilesystemContext, *Diagnostic) {
if source.captured != nil {
return resolveCapturedFilesystemContext(source, context, main, hostToken)
}
if source.kind == sourceNone && context != nil {
return resolveAbsentFilesystemContext(context)
}
@@ -26,6 +29,30 @@ func resolveFilesystemContext(source Source, context *FilesystemContext, main pa
return resolveHostFilesystemContext(source, context, main, hostToken)
}
func resolveCapturedFilesystemContext(source Source, context *FilesystemContext, main parsedSource, hostToken *namespaceToken) (resolvedFilesystemContext, *Diagnostic) {
captured := source.captured
resolved := resolvedFilesystemContext{hostToken: hostToken, rootPath: captured.rootPath, basePath: captured.basePath, mainPath: captured.mainPath}
if context == nil {
return resolved, nil
}
if context.FS != nil || context.BaseDir != "" {
value := optionDiagnostic(CodeOptionsInvalid, "prepared source requires a compatible host filesystem context")
return resolvedFilesystemContext{}, &value
}
// The source record carries the captured canonical main path, so this does
// not follow the original filename again after preparation.
explicit, diagnostic := resolveHostFilesystemContext(source, context, main, hostToken)
if diagnostic != nil || !sameHostPath(explicit.rootPath, resolved.rootPath) || !sameHostPath(explicit.basePath, resolved.basePath) || !sameHostPath(explicit.mainPath, resolved.mainPath) {
value := optionDiagnostic(CodeOptionsInvalid, "prepared source requires a compatible host filesystem context")
return resolvedFilesystemContext{}, &value
}
return resolved, nil
}
func sameHostPath(left, right string) bool {
return containedPath(left, right) && containedPath(right, left)
}
func resolveAbsentFilesystemContext(context *FilesystemContext) (resolvedFilesystemContext, *Diagnostic) {
if context.FS != nil {
return resolveNativeFilesystemContext(Source{kind: sourceNone}, context)

View File

@@ -156,7 +156,7 @@ func acquireImportedWithAccess(request importAcquisitionRequest, policy *acquisi
declarations = processing.imports
sequenceDeclarations = cloneSequenceDeclarations(processing.sequences)
} else {
body, declarations, diagnostics = splitImportDirectives(main.document)
body, declarations, diagnostics = splitImportDirectives(main.document, request.input.role)
}
root := acquiredContribution{
source: cloneSourceInfo(mainInfo), payload: body, identity: mainNodeKey,

View File

@@ -232,7 +232,7 @@ func parseImportSpecsYAML(t *testing.T, declarations string) ([]importDeclaratio
if len(diagnostics) != 0 {
return nil, diagnostics
}
extracted, diagnostics := extractRootDirectives(parsed.document, rootDirectiveContextSource)
extracted, diagnostics := extractRootDirectives(parsed.document, rootDirectiveContextSource, sourceVersionContribution)
if len(diagnostics) != 0 {
return nil, diagnostics
}

View File

@@ -1558,6 +1558,6 @@ func parseImportSpecificationYAML(input string) ([]importDeclarationSpec, []Diag
if len(diagnostics) != 0 {
return nil, diagnostics
}
_, declarations, diagnostics := splitImportDirectives(parsed.document)
_, declarations, diagnostics := splitImportDirectives(parsed.document, sourceVersionMain)
return declarations, diagnostics
}

View File

@@ -0,0 +1,68 @@
package engine
import (
"errors"
"io"
yamladapter "go.maximumdirect.net/configkit/internal/yaml"
)
// InspectionView borrows an inspection and selects a canonical reporting scope.
type InspectionView struct {
inspection *Inspection
scope Path
}
func NewInspectionView(inspection *Inspection, scope Path) (InspectionView, bool) {
if inspection == nil || !scope.valid() {
return InspectionView{}, false
}
normalized, err := ParsePath(scope.String())
if err != nil {
return InspectionView{}, false
}
return InspectionView{inspection: inspection, scope: normalized}, true
}
func (v InspectionView) Inspection() *Inspection { return v.inspection }
func (v InspectionView) Diff(other InspectionView) ([]Difference, error) {
if v.inspection == nil || other.inspection == nil || v.scope.String() != other.scope.String() {
return nil, errors.New("configkit: diff inspection scope unavailable or mismatched")
}
values, err := Diff(v.inspection, other.inspection)
if err != nil {
return nil, err
}
var result []Difference
for _, value := range values {
if pathContains(v.scope, value.Path) || pathContains(value.Path, v.scope) {
result = append(result, value)
}
}
return result, nil
}
func (v InspectionView) WriteEffective(output io.Writer) error {
if v.inspection == nil || v.inspection.final == nil || output == nil {
return errEffectiveUnavailable
}
node, ok := documentAtPathWithLookup(v.inspection.final, v.scope, v.inspection.documentLookup())
if !ok {
return errEffectiveUnavailable
}
return yamladapter.Write(output, redactedDocument(node, v.inspection.secrets, v.scope))
}
func (v InspectionView) HistoricalPaths() []Path {
if v.inspection == nil {
return nil
}
var paths []Path
for _, path := range v.inspection.metadata.HistoricalPaths() {
if pathContains(v.scope, path) {
paths = append(paths, path)
}
}
return paths
}

View File

@@ -0,0 +1,103 @@
package engine
import (
"errors"
"io/fs"
"os"
"path/filepath"
"reflect"
"runtime"
"testing"
"testing/fstest"
)
func TestCapturedMainUsesItsContextDuringOrdinaryLoad(t *testing.T) {
root := t.TempDir()
main := writeImportFile(t, root, "app/main.yml", "settings: {main: retained}\n")
writeImportFile(t, root, "app/resource.txt", "resource")
writeImportFile(t, root, "overlays/dev.yml", "settings: {overlay: applied}\n")
context := &FilesystemContext{Root: root}
prepared, _, diagnostics := captureHostMain(File(main), context)
if len(diagnostics) != 0 {
t.Fatal(diagnostics)
}
options := Options[discoveryLoadConfig]{Filesystem: context, Destination: Keys("service"), Overlay: "dev"}
ordinary, err := testLoad(File(main), options)
if err != nil {
t.Fatal(err)
}
options.Filesystem = nil
captured, err := testLoad(prepared, options)
if err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(captured.Config, ordinary.Config) || !reflect.DeepEqual(captured.Sources(), ordinary.Sources()) {
t.Fatalf("ordinary = %#v, captured = %#v, sources = %#v / %#v", ordinary.Config, captured.Config, ordinary.Sources(), captured.Sources())
}
resource, ok := captured.Inspection.SourceContext("source-1")
if !ok || resource.BaseDir != "app" {
t.Fatalf("resource context = %#v, %v", resource, ok)
}
data, err := fs.ReadFile(resource.FS, "app/resource.txt")
if err != nil || string(data) != "resource" {
t.Fatalf("resource = %q, %v", data, err)
}
if err := os.Remove(main); err != nil {
t.Fatal(err)
}
for _, filesystem := range []*FilesystemContext{nil, {Root: root}} {
options.Filesystem = filesystem
loaded, err := testLoad(prepared, options)
if err != nil || !reflect.DeepEqual(loaded.Config, captured.Config) {
t.Fatalf("load after main removal: %#v, %v", loaded, err)
}
}
for _, filesystem := range []*FilesystemContext{{Root: filepath.Join(root, "app")}, {Root: root, BaseDir: root}, {Root: ".", FS: filesystemPointer(NewFilesystem("native", fstest.MapFS{}))}} {
for _, imports := range []bool{false, true} {
options.Filesystem, options.Imports = filesystem, imports
_, err := testLoad(prepared, options)
var loadErr *LoadError
if !errors.As(err, &loadErr) || len(loadErr.Diagnostics()) == 0 || loadErr.Diagnostics()[0].Code != CodeOptionsInvalid {
t.Fatalf("incompatible context %#v, imports %v: %v", filesystem, imports, err)
}
}
}
_, err = LoadLayered(Input{Source: prepared, Filesystem: &FilesystemContext{Root: filepath.Join(root, "app")}}, testSecretBinding(), LayeredOptions[discoveryLoadConfig]{Overlay: "missing"})
var loadErr *LoadError
if !errors.As(err, &loadErr) || len(loadErr.Diagnostics()) == 0 || loadErr.Diagnostics()[0].Code != CodeOptionsInvalid {
t.Fatalf("incompatible layered context: %v", err)
}
}
func filesystemPointer(filesystem Filesystem) *Filesystem { return &filesystem }
func TestCapturedMainUsesCanonicalTargetAfterSymlinkChanges(t *testing.T) {
if runtime.GOOS == "windows" {
t.Skip("symlink creation may require privileges")
}
root := t.TempDir()
main := writeImportFile(t, root, "actual/main.yml", "value: original\n")
other := writeImportFile(t, root, "other.yml", "value: changed\n")
link := filepath.Join(root, "link.yml")
if err := os.Symlink(main, link); err != nil {
t.Fatal(err)
}
prepared, _, diagnostics := captureHostMain(File(link), &FilesystemContext{Root: root})
if len(diagnostics) != 0 {
t.Fatal(diagnostics)
}
if err := os.Remove(link); err != nil {
t.Fatal(err)
}
if err := os.Symlink(other, link); err != nil {
t.Fatal(err)
}
rootAlias := filepath.Join(t.TempDir(), "root-link")
if err := os.Symlink(root, rootAlias); err != nil {
t.Fatal(err)
}
loaded, err := testLoad(prepared, Options[discoveryLoadConfig]{Filesystem: &FilesystemContext{Root: rootAlias}})
if err != nil || loaded.Config.Value != "original" || loaded.Sources()[0].Path != canonicalTestPath(t, main) {
t.Fatalf("load = %#v, %v", loaded, err)
}
}

View File

@@ -0,0 +1,121 @@
package engine
import (
"errors"
"os"
"path/filepath"
"testing"
)
func TestCapturedMainLoadsLiveImportsWithIndependentEvidence(t *testing.T) {
root := t.TempDir()
mainBody := "version: 1\nconfig: {imports: [{path: ../shared.yml}]}\nsettings: {main: captured}\n"
main := writeImportFile(t, root, "app/main.yml", mainBody)
child := writeImportFile(t, root, "shared.yml", "version: 2\nsettings: {child: original}\n")
prepared, _, diagnostics := captureHostMain(File(main), &FilesystemContext{Root: root})
if len(diagnostics) != 0 {
t.Fatal(diagnostics)
}
if err := os.WriteFile(main, []byte("settings: {main: changed}\n"), 0o600); err != nil {
t.Fatal(err)
}
type config struct {
Version int `yaml:"version"`
Settings map[string]string `yaml:"settings"`
}
options := Options[config]{Imports: true, SourceVersionMode: sourceVersionModeRequired,
Definition: Definition[config]{Version: &VersionRule{Path: Keys("version"), Check: func(Version, *Validation) error { return nil }}},
}
for _, value := range []string{"first", "second"} {
if err := os.WriteFile(child, []byte("version: 2\nsettings: {child: "+value+"}\n"), 0o600); err != nil {
t.Fatal(err)
}
loaded, err := testLoad(prepared, options)
if err != nil {
t.Fatal(err)
}
if loaded.Config.Settings["main"] != "captured" || loaded.Config.Settings["child"] != value {
t.Fatalf("configuration = %#v", loaded.Config)
}
sources := loaded.Sources()
if len(sources) != 2 || sources[0].ID != "source-1" || sources[1].ID != "source-2" || sources[0].VersionCheck == nil || sources[0].VersionCheck.Version.Text != "1" || sources[1].VersionCheck == nil || sources[1].VersionCheck.Version.Text != "2" {
t.Fatalf("source evidence = %#v", sources)
}
sources[0].Label = "mutated"
if loaded.Sources()[0].Label == "mutated" {
t.Fatal("source evidence aliases returned records")
}
}
}
func TestCapturedMainImportIdentityAndAccounting(t *testing.T) {
root := t.TempDir()
mainBody := "config: {imports: [{path: child.yml}]}\nsettings: {main: captured}\n"
childBody := "settings: {child: value}\n"
main := writeImportFile(t, root, "main.yml", mainBody)
child := writeImportFile(t, root, "child.yml", childBody)
prepared, _, diagnostics := captureHostMain(File(main), nil)
if len(diagnostics) != 0 {
t.Fatal(diagnostics)
}
accounting := &importAccounting{}
state := &acquisitionState{accounting: accounting}
policy := acquisitionPolicy{importLimits: defaultImportLimits()}
input, diagnostics := acquireInput(inputAcquisitionRequest{
input: loadInput{source: prepared, imports: true, destination: Keys("service")},
role: sourceVersionMain, directiveContext: rootDirectiveContextSource,
}, policy, state, &tierAcquisitionState{visited: make(map[resourceIdentity]importRoute)})
mainParsed, _ := parseSource(Bytes("main", []byte(mainBody)), "main", defaultParseLimits())
childParsed, _ := parseSource(Bytes("child", []byte(childBody)), "child", defaultParseLimits())
wantNodes := countInputNodes(mainParsed.document) + countInputNodes(childParsed.document) + destinationWrapperNodeCount(Keys("service"))*2
if len(diagnostics) != 0 || len(input.sources) != 2 || accounting.sources != 2 || accounting.bytes != int64(len(mainBody)+len(childBody)) || accounting.nodes != wantNodes {
t.Fatalf("acquisition = %#v, diagnostics = %#v, accounting = %#v, want nodes %d", input, diagnostics, accounting, wantNodes)
}
if err := os.WriteFile(child, []byte("config: {imports: [{path: main.yml}]}\n"), 0o600); err != nil {
t.Fatal(err)
}
requireLoadCode(t, prepared, Options[importTestConfig]{Imports: true}, CodeImportCycle)
if err := os.WriteFile(child, []byte("settings: {child: value}\n"), 0o600); err != nil {
t.Fatal(err)
}
_, err := LoadLayered(Input{Source: NoSource()}, testSecretBinding(), LayeredOptions[importTestConfig]{
Underlays: []Underlay{{Inputs: []Input{{Source: prepared, Imports: true}, {Source: prepared, Imports: true}}}},
})
var loadErr *LoadError
if !errors.As(err, &loadErr) || len(loadErr.Diagnostics()) == 0 || loadErr.Diagnostics()[0].Code != CodeImportRepeated {
t.Fatalf("repeated captured file: %v", err)
}
if err := os.WriteFile(main, []byte("changed: true\n"), 0o600); err != nil {
t.Fatal(err)
}
for range 2 {
if _, err := testLoad(prepared, Options[discoveryLoadConfig]{Imports: true}); err != nil {
t.Fatalf("independent load: %v", err)
}
}
}
func TestCapturedMainBindsLayeredCompanions(t *testing.T) {
root := t.TempDir()
main := writeImportFile(t, root, "app/main.yml", "settings: {main: yes-value}\n")
writeImportFile(t, root, "app/lower.yml", "settings: {lower: underlay}\n")
writeImportFile(t, root, "app/overlays/dev.yml", "settings: {selected: overlay}\n")
prepared, _, diagnostics := captureHostMain(File(main), &FilesystemContext{Root: root})
if len(diagnostics) != 0 {
t.Fatal(diagnostics)
}
underlay := Input{Source: Bytes("companion", []byte("config: {imports: [{path: lower.yml}]}\n")), Imports: true, MainRelative: &MainRelativeContext{RequireBase: true}}
loaded, err := LoadLayered(Input{Source: prepared}, testSecretBinding(), LayeredOptions[discoveryLoadConfig]{
Underlays: []Underlay{{Inputs: []Input{underlay}}}, Overlay: "dev",
})
if err != nil {
t.Fatal(err)
}
if loaded.Config.Settings["main"] != "yes-value" || loaded.Config.Settings["lower"] != "underlay" || loaded.Config.Settings["selected"] != "overlay" {
t.Fatalf("layered configuration = %#v", loaded.Config)
}
sources := loaded.Inspection.Sources()
if len(sources) != 4 || sources[0].Path != canonicalTestPath(t, main) || sources[2].Path != canonicalTestPath(t, filepath.Join(root, "app/lower.yml")) || sources[3].Layer != LayerOverlay {
t.Fatalf("layered sources = %#v", sources)
}
}

View File

@@ -0,0 +1,73 @@
package engine
import "go.maximumdirect.net/configkit/internal/document"
// capturedHostSource contains immutable, passive facts about one selected file.
type capturedHostSource struct {
document *document.Node
bytes int64
mainPath string
basePath string
rootPath string
}
// selectInputSource shares discovery and post-selection option checks with
// preparation and ordinary acquisition.
func selectInputSource(source Source, sourceID string, context *FilesystemContext) (Source, *SourceInfo, []Diagnostic) {
if source.kind != sourceSearch {
return source, nil, nil
}
selected, failed, diagnostics := resolveSearchInput(source, sourceID, defaultDiscoveryDirectoryHelpers(), defaultDiscoveryHostProbe())
if len(diagnostics) != 0 {
return selected, failed, diagnostics
}
if context != nil {
if diagnostics := filesystemOptionDiagnostics(selected, context); len(diagnostics) != 0 {
return selected, nil, diagnostics
}
}
return selected, nil, nil
}
// captureHostMain snapshots a selected host document and canonical context.
// Diagnostics retain the same source evidence as ordinary acquisition.
func captureHostMain(source Source, context *FilesystemContext) (Source, []SourceInfo, []Diagnostic) {
const sourceID = "source-1"
if source.kind != sourceFile && source.kind != sourceSearch && source.kind != sourceNone {
return Source{}, nil, []Diagnostic{optionDiagnostic(CodeOptionsInvalid, "main preparation requires a host file, search, or absent source")}
}
if context != nil {
if context.FS != nil {
return Source{}, nil, []Diagnostic{optionDiagnostic(CodeOptionsInvalid, "main preparation requires a host filesystem context")}
}
}
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 {
return Source{}, sourceInfos(failed), diagnostics
}
if selected.kind == sourceNone {
if context != nil {
_, diagnostic := validateFilesystemContext(selected, context, parsedSource{}, nil)
if diagnostic != nil {
return Source{}, nil, []Diagnostic{*diagnostic}
}
}
return selected, nil, nil
}
parsed, diagnostics := parseSource(selected, sourceID, defaultParseLimits())
if len(diagnostics) != 0 {
return Source{}, sourceInfos(parsed.source), diagnostics
}
resolved, diagnostic := validateFilesystemContext(selected, context, parsed, nil)
if diagnostic != nil {
return Source{}, sourceInfos(parsed.source), []Diagnostic{*diagnostic}
}
selected.captured = &capturedHostSource{
document: parsed.document, bytes: parsed.bytes, mainPath: resolved.mainPath,
basePath: resolved.basePath, rootPath: resolved.rootPath,
}
return selected, sourceInfos(parsed.source), nil
}

View File

@@ -0,0 +1,85 @@
package engine
import (
"os"
"path/filepath"
"testing"
)
func TestCapturedHostSourceRetainsSelectedDocument(t *testing.T) {
dir := t.TempDir()
first := filepath.Join(dir, "first.yml")
second := filepath.Join(dir, "second.yml")
if err := os.WriteFile(second, []byte("config: {secrets_dir: secrets}\nvalue: original\n"), 0o600); err != nil {
t.Fatal(err)
}
search := SearchConfig("app", Paths(first, second))
prepared, sources, diagnostics := captureHostMain(search, nil)
if len(diagnostics) != 0 || len(sources) != 1 || prepared.captured == nil || prepared.captured.mainPath != canonicalTestPath(t, second) || prepared.captured.basePath != canonicalTestPath(t, dir) || prepared.captured.rootPath != canonicalTestPath(t, dir) {
t.Fatalf("prepared = %#v, sources = %#v, diagnostics = %#v", prepared, sources, diagnostics)
}
wider, _, diagnostics := captureHostMain(File(second), &FilesystemContext{Root: filepath.Dir(dir)})
if len(diagnostics) != 0 || wider.captured == nil || wider.captured.rootPath != canonicalTestPath(t, filepath.Dir(dir)) {
t.Fatalf("wider context = %#v, diagnostics = %#v", wider, diagnostics)
}
if err := os.WriteFile(first, []byte("value: newer-candidate\n"), 0o600); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(second, []byte("value: changed\n"), 0o600); err != nil {
t.Fatal(err)
}
for _, source := range []Source{prepared, prepared} {
parsed, diagnostics := parseSource(source, "another-source", defaultParseLimits())
if len(diagnostics) != 0 || parsed.source.Path != canonicalTestPath(t, second) || len(parsed.document.Mapping) != 2 || parsed.document.Mapping[1].Value.Text != "original" || parsed.document.Mapping[0].Value.Location.SourceID != "another-source" {
t.Fatalf("parsed = %#v, diagnostics = %#v", parsed, diagnostics)
}
parsed.document.Mapping[1].Value.Text = "mutated"
}
ordinary, diagnostics := parseSource(File(second), "ordinary", defaultParseLimits())
if len(diagnostics) != 0 || ordinary.document.Mapping[0].Value.Text != "changed" {
t.Fatalf("ordinary file after modification = %#v, diagnostics = %#v", ordinary, diagnostics)
}
if err := os.Remove(second); err != nil {
t.Fatal(err)
}
parsed, diagnostics := parseSource(prepared, "after-removal", defaultParseLimits())
if len(diagnostics) != 0 || parsed.document.Mapping[1].Value.Text != "original" {
t.Fatalf("after removal: parsed = %#v, diagnostics = %#v", parsed, diagnostics)
}
selected, _, diagnostics := selectInputSource(search, "source-1", nil)
if len(diagnostics) != 0 || selected.path != first {
t.Fatalf("fresh discovery = %#v, diagnostics = %#v", selected, diagnostics)
}
parsed, diagnostics = parseSource(File(first), "fresh", defaultParseLimits())
if len(diagnostics) != 0 || parsed.document.Mapping[0].Value.Text != "newer-candidate" {
t.Fatalf("fresh file = %#v, diagnostics = %#v", parsed, diagnostics)
}
limits := defaultParseLimits()
limits.source.remaining = prepared.captured.bytes - 1
if _, diagnostics := parseSource(prepared, "limited", limits); len(diagnostics) != 1 || diagnostics[0].Code != CodeSourceLimitExceeded {
t.Fatalf("captured limit diagnostics = %#v", diagnostics)
}
}
func TestCaptureHostSourceReportsSelectionAndParsingFailures(t *testing.T) {
dir := t.TempDir()
invalid := filepath.Join(dir, "invalid.yml")
if err := os.WriteFile(invalid, []byte("not: [valid\n"), 0o600); err != nil {
t.Fatal(err)
}
for _, source := range []Source{File(invalid), File(filepath.Join(dir, "missing.yml"))} {
prepared, sources, diagnostics := captureHostMain(source, nil)
if prepared.kind != sourceInvalid || len(sources) != 1 || len(diagnostics) == 0 || diagnostics[0].Primary == nil {
t.Fatalf("prepared = %#v, sources = %#v, diagnostics = %#v", prepared, sources, diagnostics)
}
}
missing := Paths(filepath.Join(dir, "missing.yml"))
prepared, sources, diagnostics := captureHostMain(SearchConfig("app", missing), nil)
if prepared.kind != sourceNone || len(sources) != 0 || len(diagnostics) != 0 {
t.Fatalf("optional search: prepared = %#v, sources = %#v, diagnostics = %#v", prepared, sources, diagnostics)
}
prepared, _, diagnostics = captureHostMain(SearchConfig("app", missing, SearchOptions{Required: true}), nil)
if prepared.kind != sourceInvalid || len(diagnostics) == 0 {
t.Fatalf("required search: prepared = %#v, diagnostics = %#v", prepared, diagnostics)
}
}

View File

@@ -0,0 +1,99 @@
package engine
import "reflect"
// ResultValue navigates the current Go value without projecting or copying it.
func ResultValue(root any, path Path, secrets SecretBinding) (any, bool) {
if !path.valid() {
return nil, false
}
current := reflect.ValueOf(root)
if len(path.segments) == 0 {
return root, true
}
builder := schemaBuilder{cache: make(map[reflect.Type]*typeDescriptor), building: make(map[reflect.Type]bool), secrets: secrets, lookup: true}
for _, segment := range path.segments {
seen := make(map[valueVisit]bool)
for current.IsValid() && (current.Kind() == reflect.Pointer || current.Kind() == reflect.Interface) {
if current.IsNil() {
return nil, false
}
if current.Kind() == reflect.Pointer {
visit := valueVisit{typeOf: current.Type(), kind: current.Kind(), ptr: current.Pointer()}
if seen[visit] {
return nil, false
}
seen[visit] = true
}
current = current.Elem()
}
if !current.IsValid() {
return nil, false
}
descriptor, issue := builder.describe(current.Type(), Path{})
if issue != nil {
return nil, false
}
switch descriptor.kind {
case descriptorStruct:
if segment.kind == pathSegmentIndex {
return nil, false
}
if position, ok := descriptor.fieldByName[segment.key]; ok {
current = resultField(current, descriptor.fields[position].index)
} else if descriptor.inlineMap != nil {
current = resultMapEntry(resultField(current, descriptor.inlineMap.index), segment.key)
} else {
return nil, false
}
case descriptorMap:
if segment.kind == pathSegmentIndex {
return nil, false
}
current = resultMapEntry(current, segment.key)
case descriptorSlice, descriptorArray:
index, ok := schemaIndex(segment)
if !ok || index >= current.Len() {
return nil, false
}
current = current.Index(index)
default:
return nil, false
}
if !current.IsValid() {
return nil, false
}
}
if !current.CanInterface() {
return nil, false
}
return current.Interface(), true
}
func resultField(root reflect.Value, index []int) reflect.Value {
current := root
for position, field := range index {
if current.Kind() != reflect.Struct {
return reflect.Value{}
}
current = current.Field(field)
if position < len(index)-1 {
for current.Kind() == reflect.Pointer {
if current.IsNil() {
return reflect.Value{}
}
current = current.Elem()
}
}
}
return current
}
func resultMapEntry(value reflect.Value, name string) reflect.Value {
if !value.IsValid() || value.Kind() != reflect.Map {
return reflect.Value{}
}
key := reflect.New(value.Type().Key()).Elem()
key.SetString(name)
return value.MapIndex(key)
}

View File

@@ -0,0 +1,67 @@
package engine
import (
"reflect"
"testing"
)
func TestResultValueNavigation(t *testing.T) {
type key string
type embedded struct{ Name string }
type root struct {
Embedded *embedded `yaml:",inline"`
Extra map[key]any `yaml:",inline"`
List []int `yaml:"list"`
Any any `yaml:"any"`
}
value := root{Embedded: &embedded{Name: "named"}, Extra: map[key]any{"a/b": nil}, List: []int{3}, Any: map[string]any{"n": []any{"ok"}}}
parsed, _ := ParsePath("/any/n/0")
for _, tc := range []struct {
path Path
want any
ok bool
}{
{Keys("name"), "named", true},
{Keys("a/b"), nil, true},
{Keys("missing"), nil, false},
{Keys("list").Index(0), 3, true},
{Keys("list").Key("0"), nil, false},
{parsed, "ok", true},
{Keys("list").Index(2), nil, false},
{Path{}.Index(-1), nil, false},
} {
got, ok := ResultValue(value, tc.path, SecretBinding{})
if ok != tc.ok || !reflect.DeepEqual(got, tc.want) {
t.Errorf("%s: got %#v, %v; want %#v, %v", tc.path.String(), got, ok, tc.want, tc.ok)
}
}
value.Embedded = nil
if _, ok := ResultValue(value, Keys("name"), SecretBinding{}); ok {
t.Fatal("nil inline pointer was traversed")
}
}
func TestResultValueTerminalAndPointerCycle(t *testing.T) {
type pointer *pointer
var cycle pointer
cycle = &cycle
var nilSlice []string
for _, value := range []any{nil, nilSlice, make(chan int), cycle} {
got, ok := ResultValue(value, Path{}, SecretBinding{})
if !ok || reflect.TypeOf(got) != reflect.TypeOf(value) {
t.Fatalf("terminal %#v: got %#v, %v", value, got, ok)
}
}
if _, ok := ResultValue(cycle, Keys("x"), SecretBinding{}); ok {
t.Fatal("pointer cycle was traversed")
}
channel := make(chan int)
value := struct{ Channel chan int }{Channel: channel}
got, ok := ResultValue(value, Keys("channel"), SecretBinding{})
if !ok || got != channel {
t.Fatalf("unsupported terminal: got %#v, %v", got, ok)
}
if _, ok := ResultValue(value, Keys("channel", "x"), SecretBinding{}); ok {
t.Fatal("unsupported terminal accepted navigation")
}
}

View File

@@ -115,6 +115,9 @@ type schemaBuilder struct {
building map[reflect.Type]bool
journal []reflect.Type
secrets SecretBinding
// lookup describes only the current container and its flattened inline fields.
// Ordinary descendants are described only when navigation continues into them.
lookup bool
}
func (b *schemaBuilder) describe(current reflect.Type, path Path) (*typeDescriptor, *schemaIssue) {
@@ -134,6 +137,9 @@ func (b *schemaBuilder) describe(current reflect.Type, path Path) (*typeDescript
if current.Kind() == reflect.Pointer {
descriptor.kind = descriptorPointer
if b.lookup {
return descriptor, nil
}
element, issue := b.describe(current.Elem(), path)
if issue != nil {
return nil, issue
@@ -171,6 +177,9 @@ func (b *schemaBuilder) describe(current reflect.Type, path Path) (*typeDescript
return fail(CodeSchemaUnsupportedType, "configuration maps must have string keys")
}
descriptor.kind = descriptorMap
if b.lookup {
return descriptor, nil
}
element, issue := b.describe(current.Elem(), path)
if issue != nil {
return nil, issue
@@ -178,6 +187,9 @@ func (b *schemaBuilder) describe(current reflect.Type, path Path) (*typeDescript
descriptor.element = element
case reflect.Slice:
descriptor.kind = descriptorSlice
if b.lookup {
return descriptor, nil
}
element, issue := b.describe(current.Elem(), path.Index(0))
if issue != nil {
return nil, issue
@@ -186,6 +198,9 @@ func (b *schemaBuilder) describe(current reflect.Type, path Path) (*typeDescript
case reflect.Array:
descriptor.kind = descriptorArray
descriptor.length = current.Len()
if b.lookup {
return descriptor, nil
}
element, issue := b.describe(current.Elem(), path.Index(0))
if issue != nil {
return nil, issue

View File

@@ -4,10 +4,14 @@ import "reflect"
func (b *schemaBuilder) describeOrdinaryField(owner *typeDescriptor, field reflect.StructField, index int, name string, secret bool, path Path) *schemaIssue {
fieldPath := path.Key(name)
fieldType, issue := b.describe(field.Type, fieldPath)
var fieldType *typeDescriptor
if !b.lookup {
var issue *schemaIssue
fieldType, issue = b.describe(field.Type, fieldPath)
if issue != nil {
return issue
}
}
if issue := addField(owner, fieldDescriptor{name: name, index: []int{index}, descriptor: fieldType, secret: secret}, path); issue != nil {
return issue
}

View File

@@ -132,14 +132,25 @@ type stagedSecret struct {
// once during startup, before concurrent work; Load never calls it.
// Dot-prefixed entries are ignored and omitted from the report.
func LoadSecretsDir(directory string) (*SecretsReport, error) {
return loadSecretsDir(directory, secretsEnvironment{lookup: os.LookupEnv, set: os.Setenv}, secretsAccess{
return LoadSecretsDirWithOptions(directory, SecretsDirOptions{})
}
// SecretsDirOptions controls how directory values are applied.
type SecretsDirOptions struct {
Overwrite bool
containmentRoot string
}
// LoadSecretsDirWithOptions loads directory values with the selected policy.
func LoadSecretsDirWithOptions(directory string, options SecretsDirOptions) (*SecretsReport, error) {
return loadSecretsDir(directory, options, secretsEnvironment{lookup: os.LookupEnv, set: os.Setenv}, secretsAccess{
openDirectory: os.Open,
lstat: os.Lstat,
openFile: os.Open,
})
}
func loadSecretsDir(directory string, environment secretsEnvironment, access secretsAccess) (*SecretsReport, error) {
func loadSecretsDir(directory string, options SecretsDirOptions, environment secretsEnvironment, access secretsAccess) (*SecretsReport, error) {
report := &SecretsReport{}
if strings.TrimSpace(directory) == "" {
return report, secretsFailure(CodeSecretsInvalidPath, "secrets directory path is required")
@@ -149,6 +160,9 @@ func loadSecretsDir(directory string, environment secretsEnvironment, access sec
if err != nil {
return report, secretsFailure(classifySecretsFilesystemError(err), "secrets directory could not be canonicalized: "+strconv.Quote(cleanAbsolutePath(directory)))
}
if options.containmentRoot != "" && !containedPath(options.containmentRoot, canonical) {
return report, secretsFailure(CodeSecretsInvalidPath, "secrets directory is outside the configuration root")
}
info, err := os.Stat(canonical)
if err != nil {
return report, secretsFailure(classifySecretsFilesystemError(err), "secrets directory could not be inspected: "+strconv.Quote(canonical))
@@ -204,7 +218,7 @@ func loadSecretsDir(directory string, environment secretsEnvironment, access sec
var consumed int64
for index := range report.entries {
entry := &report.entries[index]
if existing, present := environment.lookup(entry.Name); present {
if existing, present := environment.lookup(entry.Name); present && !options.Overwrite {
entry.Status = SecretFileSkippedExisting
entry.ExistingEmpty = existing == ""
continue
@@ -221,7 +235,7 @@ func loadSecretsDir(directory string, environment secretsEnvironment, access sec
for _, secret := range staged {
entry := &report.entries[secret.entry]
if existing, present := environment.lookup(entry.Name); present {
if existing, present := environment.lookup(entry.Name); present && !options.Overwrite {
entry.Status = SecretFileSkippedExisting
entry.ExistingEmpty = existing == ""
continue

View File

@@ -0,0 +1,67 @@
package engine
import (
"os"
"path/filepath"
)
// SecretsFromConfigOptions controls main preparation and bootstrap precedence.
type SecretsFromConfigOptions struct {
Filesystem *FilesystemContext
Overwrite *bool
}
// LoadSecretsDirFromConfig prepares a host main source and explicitly loads
// its declared secrets directory before a later configuration load.
func LoadSecretsDirFromConfig(main Source, supplied ...SecretsFromConfigOptions) (*SecretsReport, Source, error) {
return loadSecretsFromConfig(main, supplied, secretsEnvironment{lookup: os.LookupEnv, set: os.Setenv}, secretsAccess{
openDirectory: os.Open, lstat: os.Lstat, openFile: os.Open,
})
}
func loadSecretsFromConfig(main Source, supplied []SecretsFromConfigOptions, environment secretsEnvironment, access secretsAccess) (*SecretsReport, Source, error) {
emptyReport := &SecretsReport{}
if len(supplied) > 1 {
return emptyReport, Source{}, (&diagnosticAccumulator{diagnostics: []Diagnostic{optionDiagnostic(CodeOptionsInvalid, "secrets preparation accepts at most one options value")}}).loadError()
}
var context *FilesystemContext
var overwrite *bool
if len(supplied) == 1 {
if supplied[0].Filesystem != nil {
snapshot := *supplied[0].Filesystem
if snapshot.FS != nil {
filesystem := *snapshot.FS
snapshot.FS = &filesystem
}
context = &snapshot
}
if supplied[0].Overwrite != nil {
value := *supplied[0].Overwrite
overwrite = &value
}
}
prepared, sources, diagnostics := captureHostMain(main, context)
if len(diagnostics) != 0 {
return emptyReport, Source{}, (&diagnosticAccumulator{sources: sources, diagnostics: diagnostics}).loadError()
}
if prepared.kind == sourceNone {
return emptyReport, prepared, nil
}
settings, diagnostics := extractBootstrapSettings(prepared.captured.document)
if len(diagnostics) != 0 {
return emptyReport, Source{}, (&diagnosticAccumulator{sources: sources, diagnostics: diagnostics}).loadError()
}
if !settings.directoryDeclared {
return emptyReport, prepared, nil
}
selectedOverwrite := settings.overwrite
if overwrite != nil {
selectedOverwrite = *overwrite
}
directory := filepath.Join(prepared.captured.basePath, settings.directory)
report, err := loadSecretsDir(directory, SecretsDirOptions{Overwrite: selectedOverwrite, containmentRoot: prepared.captured.rootPath}, environment, access)
if err != nil {
return report, Source{}, err
}
return report, prepared, nil
}

View File

@@ -0,0 +1,225 @@
package engine
import (
"errors"
"fmt"
"os"
"path/filepath"
"runtime"
"strings"
"testing"
"testing/fstest"
)
func TestSecretsFromConfigPreparesWithoutDirectory(t *testing.T) {
root := t.TempDir()
for _, body := range []string{"value: retained\n", "config: {secrets_overwrite: true, imports: invalid}\nvalue: retained\n"} {
main := writeImportFile(t, root, "main.yml", body)
values := map[string]string{"EXISTING": "kept"}
report, prepared, err := loadSecretsFromConfig(File(main), nil, mapSecretsEnvironment(values), testSecretsAccess())
if err != nil || report == nil || len(report.Entries()) != 0 || prepared.captured == nil || values["EXISTING"] != "kept" {
t.Fatalf("report = %#v, source = %#v, error = %v", report, prepared, err)
}
}
for _, source := range []Source{NoSource(), SearchConfig("app", Paths(filepath.Join(root, "missing.yml")))} {
report, prepared, err := loadSecretsFromConfig(source, nil, mapSecretsEnvironment(nil), testSecretsAccess())
if err != nil || report == nil || len(report.Entries()) != 0 || prepared.kind != sourceNone {
t.Fatalf("absent: report = %#v, source = %#v, error = %v", report, prepared, err)
}
}
}
func TestSecretsFromConfigSelectsOverwritePolicy(t *testing.T) {
root := t.TempDir()
writeImportFile(t, root, "secrets/EXISTING", "replacement\n")
writeImportFile(t, root, "secrets/NEW", "new\n")
for _, test := range []struct {
name, yaml, want string
overwrite *bool
}{
{"default preserves", "", "old", nil},
{"yaml enables", " secrets_overwrite: true\n", "replacement", nil},
{"explicit false wins", " secrets_overwrite: true\n", "old", boolPointer(false)},
{"explicit true wins", " secrets_overwrite: false\n", "replacement", boolPointer(true)},
} {
t.Run(test.name, func(t *testing.T) {
main := writeImportFile(t, root, "main.yml", "config:\n secrets_dir: secrets\n"+test.yaml+"value: fixed\n")
values := map[string]string{"EXISTING": "old", "OTHER": "kept"}
report, prepared, err := loadSecretsFromConfig(File(main), []SecretsFromConfigOptions{{Overwrite: test.overwrite}}, mapSecretsEnvironment(values), testSecretsAccess())
if err != nil || prepared.captured == nil || report == nil || len(report.Entries()) != 2 || values["EXISTING"] != test.want || values["NEW"] != "new" || values["OTHER"] != "kept" {
t.Fatalf("report = %#v, source = %#v, values = %#v, error = %v", report, prepared, values, err)
}
})
}
}
func TestSecretsFromConfigAcceptsPreparedMainAgain(t *testing.T) {
root := t.TempDir()
main := writeImportFile(t, root, "main.yml", "config: {secrets_dir: secrets}\nvalue: captured\n")
writeImportFile(t, root, "secrets/SECRET", "value")
values := map[string]string{}
_, prepared, err := loadSecretsFromConfig(File(main), nil, mapSecretsEnvironment(values), testSecretsAccess())
if err != nil {
t.Fatal(err)
}
if err := os.WriteFile(main, []byte("config: {secrets_dir: missing}\n"), 0o600); err != nil {
t.Fatal(err)
}
delete(values, "SECRET")
report, again, err := loadSecretsFromConfig(prepared, nil, mapSecretsEnvironment(values), testSecretsAccess())
if err != nil || again.captured == nil || len(report.Entries()) != 1 || values["SECRET"] != "value" {
t.Fatalf("report = %#v, source = %#v, error = %v", report, again, err)
}
}
func TestSecretsFromConfigReportsPreparationFailures(t *testing.T) {
root := t.TempDir()
malformed := writeImportFile(t, root, "bad.yml", "config: {secrets_overwrite: wrong}\n")
badRoot := writeImportFile(t, root, "bad-root.yml", "config: invalid\n")
missing := filepath.Join(root, "missing.yml")
native := NewFilesystem("native", fstest.MapFS{})
for _, test := range []struct {
name string
main Source
opts []SecretsFromConfigOptions
code Code
}{
{"malformed even with override", File(malformed), []SecretsFromConfigOptions{{Overwrite: boolPointer(true)}}, CodeSecretsInvalidValue},
{"malformed root", File(badRoot), nil, CodeImportInvalid},
{"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},
} {
t.Run(test.name, func(t *testing.T) {
report, prepared, err := loadSecretsFromConfig(test.main, test.opts, mapSecretsEnvironment(nil), testSecretsAccess())
var failure *LoadError
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())
}
})
}
}
func TestSecretsFromConfigChecksDirectoryContainment(t *testing.T) {
parent := t.TempDir()
root := filepath.Join(parent, "root")
writeImportFile(t, root, "inside/SECRET", "safe")
writeImportFile(t, parent, "outside/SECRET", "outside")
main := writeImportFile(t, root, "main.yml", "config: {secrets_dir: ../outside}\n")
values := map[string]string{}
report, prepared, err := loadSecretsFromConfig(File(main), nil, mapSecretsEnvironment(values), testSecretsAccess())
requireSecretsCode(t, err, CodeSecretsInvalidPath)
if report == nil || len(report.Entries()) != 0 || prepared.kind != sourceInvalid || len(values) != 0 {
t.Fatalf("outside: report = %#v, source = %#v, values = %#v", report, prepared, values)
}
if err := os.WriteFile(main, []byte("config: {secrets_dir: missing}\n"), 0o600); err != nil {
t.Fatal(err)
}
report, prepared, err = loadSecretsFromConfig(File(main), nil, mapSecretsEnvironment(values), testSecretsAccess())
requireSecretsCode(t, err, CodeSecretsMissing)
if report == nil || prepared.kind != sourceInvalid || len(values) != 0 {
t.Fatalf("missing: report = %#v, source = %#v, values = %#v", report, prepared, values)
}
if runtime.GOOS == "windows" {
return
}
if err := os.Symlink(filepath.Join(root, "inside"), filepath.Join(root, "linked")); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(main, []byte("config: {secrets_dir: linked}\n"), 0o600); err != nil {
t.Fatal(err)
}
report, prepared, err = loadSecretsFromConfig(File(main), nil, mapSecretsEnvironment(values), testSecretsAccess())
if err != nil || prepared.captured == nil || len(report.Entries()) != 1 || values["SECRET"] != "safe" {
t.Fatalf("contained link: report = %#v, source = %#v, error = %v", report, prepared, err)
}
if err := os.Remove(filepath.Join(root, "linked")); err != nil {
t.Fatal(err)
}
if err := os.Symlink(filepath.Join(parent, "outside"), filepath.Join(root, "linked")); err != nil {
t.Fatal(err)
}
report, prepared, err = loadSecretsFromConfig(File(main), nil, mapSecretsEnvironment(map[string]string{}), testSecretsAccess())
requireSecretsCode(t, err, CodeSecretsInvalidPath)
if report == nil || len(report.Entries()) != 0 || prepared.kind != sourceInvalid {
t.Fatalf("outside link: report = %#v, source = %#v", report, prepared)
}
}
func TestSecretsFromConfigKeepsPartialReportSafe(t *testing.T) {
root := t.TempDir()
main := writeImportFile(t, root, "main.yml", "config: {secrets_dir: secrets}\n")
writeImportFile(t, root, "secrets/A", "FIRST-CANARY")
writeImportFile(t, root, "secrets/B", "SECOND-CANARY")
writeImportFile(t, root, "secrets/C", "THIRD-CANARY")
values := map[string]string{}
environment := mapSecretsEnvironment(values)
environment.set = func(name, value string) error {
if name == "B" {
return errors.New("unsafe canary failure")
}
values[name] = value
return nil
}
report, prepared, err := loadSecretsFromConfig(File(main), nil, environment, testSecretsAccess())
requireSecretsCode(t, err, CodeSecretsApplyFailed)
entries := report.Entries()
if prepared.kind != sourceInvalid || len(entries) != 3 || entries[0].Status != SecretFileLoaded || entries[1].Status != SecretFileFailed || entries[2].Status != SecretFileNotApplied || values["A"] != "FIRST-CANARY" || strings.Contains(err.Error()+fmt.Sprintf("%#v", entries), "CANARY") {
t.Fatalf("report = %#v, source = %#v, error = %v", report, prepared, err)
}
}
func TestSecretsFromConfigClosesOpenedFiles(t *testing.T) {
for _, test := range []struct {
name, contents string
fails bool
}{
{"success", "value", false},
{"read failure", "bad\x00value", true},
} {
t.Run(test.name, func(t *testing.T) {
root := t.TempDir()
main := writeImportFile(t, root, "main.yml", "config: {secrets_dir: secrets}\n")
writeImportFile(t, root, "secrets/SECRET", test.contents)
var opened []*os.File
open := func(name string) (*os.File, error) {
file, err := os.Open(name)
if err == nil {
opened = append(opened, file)
}
return file, err
}
access := testSecretsAccess()
access.openDirectory, access.openFile = open, open
_, prepared, err := loadSecretsFromConfig(File(main), nil, mapSecretsEnvironment(map[string]string{}), access)
if (err != nil) != test.fails || (prepared.kind == sourceInvalid) != test.fails || len(opened) != 2 {
t.Fatalf("source = %#v, error = %v, opened = %d", prepared, err, len(opened))
}
for _, file := range opened {
if _, err := file.Stat(); !errors.Is(err, os.ErrClosed) {
t.Fatalf("file %q remains open: %v", file.Name(), err)
}
}
// On systems exposing process descriptors, also check the main file,
// whose normal acquisition uses the shared regular-file reader.
entries, err := os.ReadDir("/proc/self/fd")
if err != nil {
return
}
canonical := canonicalTestPath(t, main)
canonicalRoot := canonicalTestPath(t, root)
for _, entry := range entries {
target, err := os.Readlink(filepath.Join("/proc/self/fd", entry.Name()))
if err == nil && (target == canonical || target == canonicalRoot) {
t.Fatalf("main or root remains open through descriptor %s", entry.Name())
}
}
})
}
}

View File

@@ -84,12 +84,12 @@ func TestLoadSecretsDirIgnoresDotEntries(t *testing.T) {
return os.Lstat(path)
}
environment := map[string]string{}
report, err := loadSecretsDir(directory, mapSecretsEnvironment(environment), access)
report, err := loadSecretsDir(directory, SecretsDirOptions{}, mapSecretsEnvironment(environment), access)
if err != nil || len(report.Entries()) != 0 || len(environment) != 0 {
t.Fatalf("hidden-only directory: error = %v, report = %#v, environment = %#v", err, report.Entries(), environment)
}
writeSecretTestFile(t, directory, "SECRET", "value\n")
report, err = loadSecretsDir(directory, mapSecretsEnvironment(environment), access)
report, err = loadSecretsDir(directory, SecretsDirOptions{}, mapSecretsEnvironment(environment), access)
if err != nil {
t.Fatal(err)
}
@@ -111,7 +111,7 @@ func TestLoadSecretsDirPreservesExistingWithoutReading(t *testing.T) {
return nil, errors.New("must not open")
}
report, err := loadSecretsDir(directory, mapSecretsEnvironment(environment), access)
report, err := loadSecretsDir(directory, SecretsDirOptions{}, mapSecretsEnvironment(environment), access)
if err != nil {
t.Fatalf("loadSecretsDir() error = %v", err)
}
@@ -157,7 +157,7 @@ func TestLoadSecretsDirValidatesAllMetadataBeforeReadingOrWriting(t *testing.T)
access := testSecretsAccess()
opened := 0
access.openFile = func(path string) (*os.File, error) { opened++; return os.Open(path) }
report, err := loadSecretsDir(directory, secretsEnvironment{
report, err := loadSecretsDir(directory, SecretsDirOptions{}, secretsEnvironment{
lookup: func(string) (string, bool) { return "", false },
set: func(string, string) error { writes++; return nil },
}, access)
@@ -186,7 +186,7 @@ func TestLoadSecretsDirPreflightFailuresDoNotWrite(t *testing.T) {
writeSecretTestFile(t, directory, "A_FIRST", "first")
writeSecretTestFile(t, directory, "Z_FAILED", test.body)
writes := 0
report, err := loadSecretsDir(directory, secretsEnvironment{
report, err := loadSecretsDir(directory, SecretsDirOptions{}, secretsEnvironment{
lookup: func(string) (string, bool) { return "", false },
set: func(string, string) error { writes++; return nil },
}, testSecretsAccess())
@@ -218,7 +218,7 @@ func TestLoadSecretsDirClassifiesReadFailuresWithoutLeakingThem(t *testing.T) {
access := testSecretsAccess()
access.openFile = func(string) (*os.File, error) { return nil, test.err }
writes := 0
report, err := loadSecretsDir(directory, secretsEnvironment{
report, err := loadSecretsDir(directory, SecretsDirOptions{}, secretsEnvironment{
lookup: func(string) (string, bool) { return "", false },
set: func(string, string) error { writes++; return nil },
}, access)
@@ -239,7 +239,7 @@ func TestLoadSecretsDirEnforcesEnumerationAndTotalBounds(t *testing.T) {
for index := 0; index <= secretsEntryLimit; index++ {
writeSecretTestFile(t, directory, fmt.Sprintf("SECRET_%04d", index), "")
}
report, err := loadSecretsDir(directory, mapSecretsEnvironment(map[string]string{}), testSecretsAccess())
report, err := loadSecretsDir(directory, SecretsDirOptions{}, mapSecretsEnvironment(map[string]string{}), testSecretsAccess())
requireSecretsCode(t, err, CodeSecretsLimitExceeded)
if len(report.Entries()) != secretsEntryLimit+1 {
t.Fatalf("entries = %d, want %d bounded enumerated entries", len(report.Entries()), secretsEntryLimit+1)
@@ -252,7 +252,7 @@ func TestLoadSecretsDirEnforcesEnumerationAndTotalBounds(t *testing.T) {
writeSecretTestFile(t, directory, fmt.Sprintf("SECRET_%02d", index), strings.Repeat("x", int(secretFileByteLimit)))
}
writes := 0
report, err := loadSecretsDir(directory, secretsEnvironment{
report, err := loadSecretsDir(directory, SecretsDirOptions{}, secretsEnvironment{
lookup: func(string) (string, bool) { return "", false },
set: func(string, string) error { writes++; return nil },
}, testSecretsAccess())
@@ -288,7 +288,7 @@ func TestLoadSecretsDirApplyReportsPartialFailureAndPresenceRace(t *testing.T) {
},
}
report, err := loadSecretsDir(directory, environment, testSecretsAccess())
report, err := loadSecretsDir(directory, SecretsDirOptions{}, environment, testSecretsAccess())
requireSecretsCode(t, err, CodeSecretsApplyFailed)
entries := report.Entries()
wantStatuses := []SecretFileStatus{SecretFileLoaded, SecretFileSkippedExisting, SecretFileFailed, SecretFileNotApplied}
@@ -305,10 +305,79 @@ func TestLoadSecretsDirApplyReportsPartialFailureAndPresenceRace(t *testing.T) {
}
}
func TestLoadSecretsDirOverwrite(t *testing.T) {
directory := t.TempDir()
writeSecretTestFile(t, directory, "CK_OVERWRITE_NONEMPTY", "replacement\n")
writeSecretTestFile(t, directory, "CK_OVERWRITE_EMPTY", "filled")
writeSecretTestFile(t, directory, "CK_OVERWRITE_WITH_EMPTY", "")
t.Setenv("CK_OVERWRITE_NONEMPTY", "old")
t.Setenv("CK_OVERWRITE_EMPTY", "")
t.Setenv("CK_OVERWRITE_WITH_EMPTY", "old")
t.Setenv("CK_OVERWRITE_UNRELATED", "untouched")
report, err := LoadSecretsDirWithOptions(directory, SecretsDirOptions{Overwrite: true})
if err != nil {
t.Fatal(err)
}
for name, want := range map[string]string{
"CK_OVERWRITE_NONEMPTY": "replacement", "CK_OVERWRITE_EMPTY": "filled",
"CK_OVERWRITE_WITH_EMPTY": "", "CK_OVERWRITE_UNRELATED": "untouched",
} {
if got, ok := os.LookupEnv(name); !ok || got != want {
t.Errorf("%s = %q, present %v; want %q", name, got, ok, want)
}
}
for _, entry := range report.Entries() {
if entry.Status != SecretFileLoaded || entry.ExistingEmpty {
t.Errorf("unexpected result: %#v", entry)
}
}
}
func TestLoadSecretsDirOverwritePresenceRaceAndPartialFailure(t *testing.T) {
directory := t.TempDir()
for _, name := range []string{"A_LOADED", "B_RACED", "C_FAILED", "D_WAITING"} {
writeSecretTestFile(t, directory, name, "value-"+name)
}
values := map[string]string{"A_LOADED": "old"}
lookups := map[string]int{}
environment := secretsEnvironment{
lookup: func(name string) (string, bool) {
lookups[name]++
if name == "B_RACED" && lookups[name] == 2 {
values[name] = "raced"
}
value, present := values[name]
return value, present
},
set: func(name, value string) error {
if name == "C_FAILED" {
return errors.New("set failure")
}
values[name] = value
return nil
},
}
report, err := loadSecretsDir(directory, SecretsDirOptions{Overwrite: true}, environment, testSecretsAccess())
requireSecretsCode(t, err, CodeSecretsApplyFailed)
want := []SecretFileStatus{SecretFileLoaded, SecretFileLoaded, SecretFileFailed, SecretFileNotApplied}
for i, entry := range report.Entries() {
if entry.Status != want[i] || entry.ExistingEmpty {
t.Errorf("entry %d = %#v, want status %s", i, entry, want[i])
}
}
if values["A_LOADED"] != "value-A_LOADED" || values["B_RACED"] != "value-B_RACED" {
t.Fatalf("unexpected applied values: %#v", values)
}
if _, present := values["D_WAITING"]; present {
t.Fatal("entry after apply failure was written")
}
}
func TestLoadSecretsDirFailuresAreSafeAndDetached(t *testing.T) {
directory := t.TempDir()
writeSecretTestFile(t, directory, "SECRET", "CREDENTIAL-CANARY\x00")
report, err := loadSecretsDir(directory, mapSecretsEnvironment(map[string]string{}), testSecretsAccess())
report, err := loadSecretsDir(directory, SecretsDirOptions{}, mapSecretsEnvironment(map[string]string{}), testSecretsAccess())
secretsErr := requireSecretsCode(t, err, CodeSecretsInvalidValue)
diagnostics := secretsErr.Diagnostics()
diagnostics[0].Message = "mutated"

View File

@@ -81,14 +81,14 @@ func TestExtractRootDirectivesAllowsSequencesButRejectsOverlayImports(t *testing
_, diagnostics := extractRootDirectives(parseRootDirectiveDocument(t, `config:
imports: [{path: fragments/base.yaml}]
sequences: [{destination: [prompts], key: id}]
`), rootDirectiveContextOverlay)
`), rootDirectiveContextOverlay, sourceVersionContribution)
if len(diagnostics) != 1 || diagnostics[0].Code != CodeOverlayDirective || diagnostics[0].Path.String() != "/config/imports" {
t.Fatalf("overlay diagnostics = %#v, want imports-only rejection", diagnostics)
}
extracted, diagnostics := extractRootDirectives(parseRootDirectiveDocument(t, `config:
sequences: [{destination: [prompts], key: id}]
`), rootDirectiveContextOverlay)
`), rootDirectiveContextOverlay, sourceVersionContribution)
if len(diagnostics) != 0 || len(extracted.sequences) != 1 {
t.Fatalf("overlay sequence extraction = %#v, %#v", extracted, diagnostics)
}
@@ -114,7 +114,7 @@ func TestParseSequenceDeclarationRejectsMalformedForms(t *testing.T) {
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
_, diagnostics := extractRootDirectives(parseRootDirectiveDocument(t, test.body), rootDirectiveContextSource)
_, diagnostics := extractRootDirectives(parseRootDirectiveDocument(t, test.body), rootDirectiveContextSource, sourceVersionContribution)
if len(diagnostics) == 0 || diagnostics[0].Code != CodeSequenceInvalid || diagnostics[0].Path.String() != test.path {
t.Fatalf("diagnostics = %#v, want %s at %s", diagnostics, CodeSequenceInvalid, test.path)
}
@@ -155,7 +155,7 @@ version: v1
func extractSequenceDeclarationsYAML(t *testing.T, input string, context rootDirectiveContext) rootDirectiveExtraction {
t.Helper()
extracted, diagnostics := extractRootDirectives(parseRootDirectiveDocument(t, input), context)
extracted, diagnostics := extractRootDirectives(parseRootDirectiveDocument(t, input), context, sourceVersionContribution)
if len(diagnostics) != 0 {
t.Fatalf("root directive diagnostics = %#v", diagnostics)
}

View File

@@ -36,6 +36,7 @@ type Source struct {
searchApp string
searchRequired bool
searchIssues []string
captured *capturedHostSource
}
type sourceKind uint8
@@ -227,6 +228,15 @@ func readSource(source Source, sourceID string, limits sourceLimits) (sourceRead
var input io.Reader
switch source.kind {
case sourceFile:
if source.captured != nil {
info.Path = source.captured.mainPath
if source.captured.bytes > limit {
return sourceRead{info: info}, []Diagnostic{sourceDiagnostic(CodeSourceLimitExceeded, sourceID, "source exceeds the configured byte limit")}
}
owned := document.Clone(source.captured.document)
setDocumentSourceID(owned, sourceID)
return sourceRead{document: owned, bytes: source.captured.bytes, info: info}, nil
}
absolute, err := filepath.Abs(source.path)
if err != nil {
return sourceRead{info: info}, []Diagnostic{sourceDiagnostic(CodeSourceRead, sourceID, "source path could not be resolved")}

View File

@@ -220,7 +220,7 @@ func processSourceVersionWithDirectiveContext(root *document.Node, rule *Version
return sourceVersionProcessingResult{}
}
extracted, diagnostics := extractRootDirectives(root, directiveContext)
extracted, diagnostics := extractRootDirectives(root, directiveContext, role)
if len(diagnostics) != 0 {
return sourceVersionProcessingResult{diagnostics: diagnostics}
}

View File

@@ -8,7 +8,7 @@ import (
"strings"
"go.yaml.in/yaml/v4"
"go.yaml.in/yaml/v4/plugin/limit"
"go.yaml.in/yaml/v4/plugin/loaderlimits"
"go.maximumdirect.net/configkit/internal/document"
)
@@ -60,7 +60,7 @@ func Parse(input io.Reader, sourceID string, limits Limits) (*document.Node, []I
parserDepth = limits.Depth + 2
}
depthExceeded := false
plugin := limit.New(limit.DepthFunc(func(depth int, _ *limit.DepthContext) error {
plugin := loaderlimits.New(loaderlimits.DepthFunc(func(depth int, _ *loaderlimits.DepthContext) error {
if depth > parserDepth {
depthExceeded = true
return errParserDepth

View File

@@ -6,7 +6,7 @@ import (
"testing"
"go.yaml.in/yaml/v4"
"go.yaml.in/yaml/v4/plugin/limit"
"go.yaml.in/yaml/v4/plugin/loaderlimits"
"go.maximumdirect.net/configkit/internal/document"
)
@@ -167,7 +167,7 @@ func TestParserDepthCalibrationForBlockAndFlow(t *testing.T) {
func observedParserDepth(t *testing.T, input string) int {
t.Helper()
maximum := 0
depthPlugin := limit.New(limit.DepthFunc(func(depth int, _ *limit.DepthContext) error {
depthPlugin := loaderlimits.New(loaderlimits.DepthFunc(func(depth int, _ *loaderlimits.DepthContext) error {
maximum = max(maximum, depth)
return nil
}))

31
result_value.go Normal file
View File

@@ -0,0 +1,31 @@
package configkit
import "go.maximumdirect.net/configkit/internal/engine"
// Value returns the current Config value at path. The root [Path] selects Config.
// A non-nil result supports lookup even when constructed manually without load
// or inspection state. Success means value availability, not input presence or
// validation; use Metadata to inspect presence in the completed load.
//
// Navigation follows the shared YAML field names, inline bindings and supported
// shapes described in docs/config.md#application-schema-binding, with [Path]'s
// key/index rules. It follows non-nil intermediate pointers and interfaces,
// checks map membership and sequence bounds, and never allocates missing values.
// Scalars, including text-codec types and Secret, remain leaves.
// A nil receiver, invalid path, missing value, or unavailable traversal returns
// (nil, false). A present nil succeeds: a nil interface returns (nil, true), while
// typed nil pointers, maps and slices retain their types in the returned any.
//
// The terminal retains its actual Go type, including named types and pointers;
// terminal pointers are not dereferenced. Lookup performs no conversion or
// revalidation of the terminal and does not invoke codecs or resolve secrets.
// Values are trusted application data and may include resolved Secret values.
// Ordinary Go assignment applies: structs and arrays are copied, while maps,
// slices and pointers can alias Config. Inspection methods continue to report
// the frozen completed load, not later caller mutations.
func (r *Result[T]) Value(path Path) (any, bool) {
if r == nil {
return nil, false
}
return engine.ResultValue(r.Config, toEnginePath(path), secretBinding())
}

View File

@@ -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 (
@@ -92,13 +92,75 @@ func (e *SecretsError) Diagnostics() []Diagnostic {
// roll back values already applied.
func LoadSecretsIntoEnvironment(directory string) (*SecretsReport, error) {
report, err := engine.LoadSecretsDir(directory)
return &SecretsReport{value: report}, fromEngineSecretsError(err)
}
// SecretsOptions selects the policy for an explicit directory bootstrap.
type SecretsOptions struct {
// Overwrite replaces existing environment variables, including empty values.
Overwrite bool
}
// LoadSecretsIntoEnvironmentWithOptions loads immediate regular files into the
// 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)
}
// SecretsFromConfigOptions configures preparation of a host main source.
type SecretsFromConfigOptions struct {
// Filesystem selects the main file's host containment root when supplied.
Filesystem *FilesystemContext
// Overwrite, when non-nil, overrides the main document's Boolean setting.
// A nil value uses that setting, or false when it is absent.
Overwrite *bool
}
// LoadSecretsIntoEnvironmentFromConfig explicitly prepares a host File or
// SearchConfig main and loads its declared secrets directory before loading.
// Passing a previously prepared source reuses its captured main document and
// explicitly repeats bootstrap. Loading that source with Load or LoadLayered
// does not repeat bootstrap.
// 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
// roll back prior environment writes.
func LoadSecretsIntoEnvironmentFromConfig(main Source, supplied ...SecretsFromConfigOptions) (*SecretsReport, Source, error) {
options := make([]engine.SecretsFromConfigOptions, len(supplied))
for index, option := range supplied {
options[index].Filesystem = toEngineFilesystemContext(option.Filesystem)
if option.Overwrite != nil {
value := *option.Overwrite
options[index].Overwrite = &value
}
}
report, prepared, err := engine.LoadSecretsDirFromConfig(main.toEngine(), options...)
result := &SecretsReport{value: report}
if err == nil {
return result, nil
return result, Source{value: prepared}, nil
}
var loadError *engine.LoadError
if errors.As(err, &loadError) {
return result, Source{}, &LoadError{value: loadError}
}
return result, Source{}, fromEngineSecretsError(err)
}
func fromEngineSecretsError(err error) error {
if err == nil {
return nil
}
var secretsError *engine.SecretsError
if errors.As(err, &secretsError) {
return result, &SecretsError{value: secretsError}
return &SecretsError{value: secretsError}
}
return result, &SecretsError{}
return &SecretsError{}
}

View File

@@ -10,6 +10,10 @@ import (
// Source is an opaque configuration input. Construct sources with File,
// Filesystem.File, SearchConfig, Bytes, Reader, Mapping, or NoSource; the zero
// value is invalid. SearchConfig selects a host file when a load consumes it.
// LoadSecretsIntoEnvironmentFromConfig returns a reusable source that retains
// the selected main document and context: later loads neither rediscover nor
// reread that main or repeat bootstrap. Reusing File or SearchConfig selects
// and reads the main again. Imports and resources remain live on each load.
type Source struct{ value engine.Source }
// Filesystem is a reusable opaque namespace for a caller-owned fs.FS. Copies