diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 4808b94..6c108ab 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -311,6 +311,8 @@ only when its own operation succeeds. ## Stage 7 — Expose root-owned APIs and convert both error families +**Completed.** + Work in root `secrets.go`, `source.go`, and existing facade conversion owners. 1. Add the two options types and new functions with the signatures above. Keep diff --git a/facade_secrets_config_test.go b/facade_secrets_config_test.go new file mode 100644 index 0000000..233747d --- /dev/null +++ b/facade_secrets_config_test.go @@ -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") + } +} diff --git a/secrets.go b/secrets.go index 917e081..1599364 100644 --- a/secrets.go +++ b/secrets.go @@ -92,13 +92,69 @@ 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. 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} 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{} } diff --git a/source.go b/source.go index 5c0ecc5..e500c13 100644 --- a/source.go +++ b/source.go @@ -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