Expose configured secrets bootstrap APIs

This commit is contained in:
2026-11-18 00:54:42 +00:00
parent ea1f2a808d
commit 60bcb6ddac
4 changed files with 168 additions and 3 deletions

View File

@@ -311,6 +311,8 @@ only when its own operation succeeds.
## Stage 7 — Expose root-owned APIs and convert both error families ## Stage 7 — Expose root-owned APIs and convert both error families
**Completed.**
Work in root `secrets.go`, `source.go`, and existing facade conversion owners. Work in root `secrets.go`, `source.go`, and existing facade conversion owners.
1. Add the two options types and new functions with the signatures above. Keep 1. Add the two options types and new functions with the signatures above. Keep

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

@@ -92,13 +92,69 @@ func (e *SecretsError) Diagnostics() []Diagnostic {
// roll back values already applied. // roll back values already applied.
func LoadSecretsIntoEnvironment(directory string) (*SecretsReport, error) { func LoadSecretsIntoEnvironment(directory string) (*SecretsReport, error) {
report, err := engine.LoadSecretsDir(directory) 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. 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.
// 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.
// 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} result := &SecretsReport{value: report}
if err == nil { 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 var secretsError *engine.SecretsError
if errors.As(err, &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, // Source is an opaque configuration input. Construct sources with File,
// Filesystem.File, SearchConfig, Bytes, Reader, Mapping, or NoSource; the zero // Filesystem.File, SearchConfig, Bytes, Reader, Mapping, or NoSource; the zero
// value is invalid. SearchConfig selects a host file when a load consumes it. // 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 } type Source struct{ value engine.Source }
// Filesystem is a reusable opaque namespace for a caller-owned fs.FS. Copies // Filesystem is a reusable opaque namespace for a caller-owned fs.FS. Copies