Files
configkit/secrets.go

167 lines
6.1 KiB
Go
Raw Permalink Normal View History

package configkit
import (
"errors"
"io"
"go.maximumdirect.net/configkit/internal/engine"
)
// SecretFileStatus describes the outcome for one file considered by an
// explicit secrets bootstrap helper.
type SecretFileStatus string
const (
SecretFileLoaded SecretFileStatus = "loaded"
SecretFileSkippedExisting SecretFileStatus = "skipped_existing"
SecretFileNotApplied SecretFileStatus = "not_applied"
SecretFileFailed SecretFileStatus = "failed"
)
// SecretFileResult is the safe, value-free bootstrap result for one directory
// entry. ExistingEmpty is meaningful when Status is SecretFileSkippedExisting.
type SecretFileResult struct {
Name string
Path string
Status SecretFileStatus
ExistingEmpty bool
}
// SecretsReport is a detached snapshot of an explicit secrets-directory
// bootstrap. It does not retain file contents or environment values.
2026-09-12 16:21:17 +00:00
type SecretsReport struct{ value *engine.SecretsReport }
// Entries returns a copy of the report's filename-ordered entries.
func (r *SecretsReport) Entries() []SecretFileResult {
2026-09-12 16:21:17 +00:00
if r == nil || r.value == nil {
return nil
}
values := r.value.Entries()
if values == nil {
return nil
}
2026-09-12 16:21:17 +00:00
result := make([]SecretFileResult, len(values))
for index := range values {
result[index] = fromEngineSecretFileResult(values[index])
}
return result
}
// WriteTo renders one safe, deterministic line per entry. Names and paths are
// quoted so control characters cannot affect terminal output.
func (r *SecretsReport) WriteTo(output io.Writer) (int64, error) {
2026-09-12 16:21:17 +00:00
if r == nil || r.value == nil {
return (*engine.SecretsReport)(nil).WriteTo(output)
}
2026-09-12 16:21:17 +00:00
return r.value.WriteTo(output)
}
// SecretsError reports safe structured diagnostics for a failed explicit
// secrets-directory bootstrap. It intentionally does not unwrap filesystem or
// environment errors.
2026-09-12 16:21:17 +00:00
type SecretsError struct{ value *engine.SecretsError }
// Error implements error without rendering filenames, paths, or file contents.
func (e *SecretsError) Error() string {
2026-09-12 16:21:17 +00:00
if e == nil || e.value == nil {
return "configkit: secrets bootstrap failed"
}
2026-09-12 16:21:17 +00:00
return e.value.Error()
}
// Diagnostics returns a deep copy of the bootstrap diagnostics.
func (e *SecretsError) Diagnostics() []Diagnostic {
2026-09-12 16:21:17 +00:00
if e == nil || e.value == nil {
return nil
}
2026-09-12 16:21:17 +00:00
values := e.value.Diagnostics()
if values == nil {
return nil
}
result := make([]Diagnostic, len(values))
for index := range values {
result[index] = fromEngineDiagnostic(values[index])
}
return result
}
// LoadSecretsIntoEnvironment explicitly loads immediate regular files into the
// process environment, preserving variables that are already set, including
// empty values. Dot-prefixed entries are ignored and omitted from the report.
// Load never calls it. The report accompanies any error, and an error does not
// roll back values already applied.
func LoadSecretsIntoEnvironment(directory string) (*SecretsReport, error) {
2026-09-12 16:21:17 +00:00
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...)
2026-09-12 16:21:17 +00:00
result := &SecretsReport{value: report}
if err == 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
}
2026-09-12 16:21:17 +00:00
var secretsError *engine.SecretsError
if errors.As(err, &secretsError) {
return &SecretsError{value: secretsError}
}
return &SecretsError{}
}