9.2 KiB
Main-relative secrets directories
Motivation and baseline
Applications can use SearchConfig to select their main configuration file
during a load. They can also call LoadSecretsIntoEnvironment during startup,
but that helper takes a native directory path before the load begins. A relative
argument uses the process working directory. Using a directory beside the
discovered file therefore requires the application to take over main-file
selection or perform a preliminary load. Configuration discovery · Secrets bootstrap
ConfigKit already retains filesystem context for acquired main files and binds
companion inputs to that context. Typed Secret references read the environment
after application resolution and before final validation. A companion bootstrap
helper can use the main's context before loading while preserving this
processing order. Main-relative contexts · Typed secret references
Target behavior
Declaration and path resolution
An application explicitly calls a companion to
LoadSecretsIntoEnvironment before Load or LoadLayered. The selected main
document supplies the directory and overwrite policy through its root control
mapping. For example, the following declaration in /etc/demo/config.yml
selects /etc/demo/secrets and authorizes replacement of existing variables
when the companion helper is called.
config:
secrets_dir: secrets
secrets_overwrite: true
api_key: DEMO_API_KEY
Interpret these fields at the main document's root before placement and
composition. They are bootstrap settings consumed as document controls.
Load and LoadLayered recognize the controls and perform their usual
environment lookup without invoking bootstrap. The companion helper call is
the explicit authorization for environment writes.
Only the main document selects the bootstrap directory and YAML overwrite
policy. Diagnose these controls in unsupported source-control contexts.
Nested application data follows the existing config rules. Imports,
underlays, overlays, CLI overrides, and application resolution retain their
ordinary effects on application configuration. They do not redirect this
bootstrap operation.
secrets_overwrite is an optional Boolean with a default of false.
An explicitly supplied Go overwrite choice takes precedence over YAML,
including when that choice is false. If the main supplies no directory,
bootstrap is a no-op and the prepared main can still be loaded. An optional
search that finds no main preserves the existing absent-main lifecycle.
Resolve the directory from the selected main file's canonical base within its existing filesystem root. For a discovered symlink, the base is the selected file's canonical target directory. Parent-relative paths follow the same containment rule as other main-relative inputs. The declaration must be a nonempty relative path and requires a usable main-file context. Keep the declaration and any diagnostics in source-local coordinates. Document-root controls · Layered loading
Companion helper and prepared main source
The companion accepts the main Source, including a SearchConfig source,
and returns a secrets report and a prepared main source. The public name and
option type below are illustrative.
main := configkit.SearchConfig("demo", search)
report, preparedMain, err := configkit.LoadSecretsIntoEnvironmentFromConfig(main)
if err != nil {
// Handle the bootstrap failure and inspect report.
return err
}
result, err := configkit.Load[AppConfig](preparedMain)
For layered loading, supply the prepared source as the main Input.Source.
The helper resolves discovery once, reads the selected main document, extracts
the bootstrap controls, and performs bootstrap. It returns the captured main
contents with the selected file's identity and filesystem context so the later
load consumes that same main document. Keep its remaining controls, including
imports and collection declarations, available to normal loading.
The helper prepares only the main document. Composition, import acquisition, inheritance, typed decoding, application resolution, secret lookup, and validation run through the subsequent ordinary or layered load. Main preparation must retain the applicable source limits and root constraints. Source records, diagnostics, placements, imports, and main-relative companions use the selected main's identity and context.
Release library-owned file handles before the helper returns, including on error. Prepared sources retain captured document data and passive filesystem context and follow the source reuse contract without sharing mutable load state. Later imports and resources observe the filesystem when accessed. A later load reads the environment at its normal secret-resolution step. Complete-on-return loading · Source resource contexts
Shared bootstrap and overwrite behavior
Extend the existing direct-directory helper with an optional named Boolean option, keeping existing calls valid. The option type name in this example is provisional.
report, err := configkit.LoadSecretsIntoEnvironment("/etc/demo/secrets")
report, err = configkit.LoadSecretsIntoEnvironment(
"/etc/demo/secrets",
configkit.SecretsOptions{Overwrite: true},
)
Both helpers use the same directory-bootstrap implementation. With overwrite disabled, existing variables win, including empty ones, with presence checked again immediately before application as today. With overwrite enabled, eligible files are read even for existing variables and their values replace those variables. Variables without a corresponding file are left alone. An applied empty file supplies an empty value in either mode.
Bootstrap processes the directory's eligible entries, including credentials
used by SDKs or subprocesses outside typed Secret fields. Reuse the existing
dot-entry handling, file checks, content rules, limits, and filename ordering.
Validate metadata and read all content needed by the chosen overwrite policy
before beginning writes.
Directory and file failures produce the existing safe reporting behavior.
The secrets report identifies writes, skips, and partial failures without
retaining credential bytes.
Call bootstrap during startup before starting concurrent work. Successful
bootstrap precedes configuration loading and validation. A later load failure
leaves the completed environment writes in place. A bootstrap write failure
stops further writes, leaves earlier writes in place, and reports remaining
entries as not_applied. The existing lack of rollback and concurrent
environment transaction guarantees continues to apply.
Keep bootstrap reporting separate from the subsequent configuration's secret lookup evidence. Each operation describes what it observed and performed. Secrets bootstrap · Secret references and explicit bootstrap
Filesystem scope
Support discovered and explicitly selected host files, including their existing main-root options. This covers the requested deployment pattern and reuses the native secret-file checks. Caller-supplied filesystem support is a possible later extension requiring decisions about file-type and symlink capabilities.
Work needed
- Add
config.secrets_dirandconfig.secrets_overwriteto the main-document control grammar and consume them during ordinary loading without triggering bootstrap. Retain source-local positions for diagnostics. - Factor main-file selection and capture for use by the companion helper and
normal acquisition. Add a prepared-source handoff with retained main contents,
identity, context, and ownership. Select an API for supplying applicable
main-root constraints and representing an absent or explicit Go overwrite
choice, including
false. - Add the optional overwrite setting to direct-directory bootstrap and reuse that operation from the companion helper, with matching reports and failures.
- Verify discovery from a different working directory, canonical main paths, optional search exhaustion, declaration scope, default and explicit overwrite choices, Go-over-YAML precedence, and both helper interfaces. Cover empty values, dot entries, read failures before writes, and partial write failures. Verify bootstrap includes entries unused by typed fields and that later load failures preserve bootstrap effects.
- Verify prepared-source reuse, handle cleanup, normal loading without environment writes, and agreement with selected-file provenance, placement, relative imports, and main-relative companions. Use disposable credential values and deterministic failure seams in line with the testing policy.
- Document the startup workflow and add a consumer example. Record the prepared main-source handoff and optional overwrite policy in an ADR referencing ADR 0004, and update the canonical configuration contract and affected architecture and component documentation when implemented.