configfile

package
v0.17.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 30, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package configfile loads YAML configuration files with strict environment interpolation.

Index

Constants

View Source 
const (
	// EnvSchemaBase64Bytes32 validates base64-encoded 32-byte secrets.
	EnvSchemaBase64Bytes32 = "base64-32-byte"
	// EnvSchemaBool validates boolean strings.
	EnvSchemaBool = "bool"
	// EnvSchemaDuration validates Go duration strings.
	EnvSchemaDuration = "duration"
	// EnvSchemaEmail validates plain email addresses.
	EnvSchemaEmail = "email"
	// EnvSchemaHexBytes32 validates hex-encoded 32-byte secrets.
	EnvSchemaHexBytes32 = "hex-32-byte"
	// EnvSchemaHostPort validates host:port addresses.
	EnvSchemaHostPort = "hostport"
	// EnvSchemaJSON validates JSON payloads.
	EnvSchemaJSON = "json"
	// EnvSchemaPositiveInteger validates integers greater than zero.
	EnvSchemaPositiveInteger = "positive-int"
	// EnvSchemaURL validates absolute URLs.
	EnvSchemaURL = "url"
)

Variables

View Source 
var (
	// ErrInvalidEnvironmentReference reports unsupported environment syntax in a
	// YAML scalar.
	ErrInvalidEnvironmentReference = errors.New("configfile.invalid_environment_reference")

	// ErrMissingEnvironmentVariables reports YAML references to unset
	// environment variables.
	ErrMissingEnvironmentVariables = errors.New("configfile.missing_environment_variables")

	// ErrMissingPath reports an empty config file path.
	ErrMissingPath = errors.New("configfile.missing_path")

	// ErrNilTarget reports a nil or non-pointer decode target.
	ErrNilTarget = errors.New("configfile.nil_target")

	// ErrParse reports malformed YAML or target decode failures.
	ErrParse = errors.New("configfile.parse")

	// ErrRead reports config file read failures.
	ErrRead = errors.New("configfile.read")
)
View Source 
var (
	// ErrEnvironmentValidation reports invalid environment values for a config
	// registry.
	ErrEnvironmentValidation = errors.New("configfile.environment_validation")

	// ErrInvalidEnvironmentRequirement reports an invalid environment contract
	// declaration.
	ErrInvalidEnvironmentRequirement = errors.New("configfile.invalid_environment_requirement")
)

Functions

func InterpolateYAML 

func InterpolateYAML(configPayload []byte) ([]byte, error)

InterpolateYAML expands environment variables only inside YAML scalar nodes.

func InterpolateYAMLWithOptions added in v0.17.0 

func InterpolateYAMLWithOptions(configPayload []byte, options EnvironmentOptions) ([]byte, error)

InterpolateYAMLWithOptions validates the supplied environment registry and expands environment variables only inside YAML scalar nodes.

func LoadYAML 

func LoadYAML(path string, target any) error

LoadYAML reads a YAML config file, expands environment variables only inside YAML scalar nodes, and decodes the result with KnownFields enabled.

func LoadYAMLBytes 

func LoadYAMLBytes(configPayload []byte, target any) error

LoadYAMLBytes expands environment variables only inside YAML scalar nodes and decodes the result with KnownFields enabled.

func LoadYAMLBytesWithOptions added in v0.17.0 

func LoadYAMLBytesWithOptions(configPayload []byte, target any, options EnvironmentOptions) error

LoadYAMLBytesWithOptions validates the supplied environment registry, expands environment variables only inside YAML scalar nodes, and decodes the result with KnownFields enabled.

func LoadYAMLWithOptions added in v0.17.0 

func LoadYAMLWithOptions(path string, target any, options EnvironmentOptions) error

LoadYAMLWithOptions reads a YAML config file, validates the supplied environment registry, expands environment variables only inside YAML scalar nodes, and decodes the result with KnownFields enabled.

func OSEnvironmentLookup added in v0.17.0 

func OSEnvironmentLookup(name string) (string, bool)

OSEnvironmentLookup resolves values from the process environment.

func ParseYAMLDocument added in v0.17.0 

func ParseYAMLDocument(configPayload []byte) (yaml.Node, error)

ParseYAMLDocument decodes exactly one YAML document and rejects trailing documents.

Types

type EnvContract added in v0.17.0 

type EnvContract struct {
	// contains filtered or unexported fields
}

EnvContract marks environment variables as required or optional for a config file family.

func NewEnvContract added in v0.17.0 

func NewEnvContract(requirements []EnvRequirement) (EnvContract, error)

NewEnvContract creates a contract from explicit environment requirements.

func (EnvContract) RegistryForYAML added in v0.17.0 

func (contract EnvContract) RegistryForYAML(configPayload []byte) (EnvRegistry, error)

RegistryForYAML returns the environment registry implied by a YAML config and this contract. Referenced variables are required by default unless the contract explicitly marks them optional.

func (EnvContract) Requirement added in v0.17.0 

func (contract EnvContract) Requirement(name string) (EnvRequirement, bool)

Requirement returns the explicit contract requirement for an environment variable.

type EnvRegistry added in v0.17.0 

type EnvRegistry struct {
	// contains filtered or unexported fields
}

EnvRegistry exposes environment requirements for preflight validation.

func NewEnvRegistry added in v0.17.0 

func NewEnvRegistry(requirements []EnvRequirement) (EnvRegistry, error)

NewEnvRegistry creates a registry from explicit requirements.

func (EnvRegistry) Mandatory added in v0.17.0 

func (registry EnvRegistry) Mandatory() []EnvRequirement

Mandatory returns required environment variables only.

func (EnvRegistry) ReferencePaths added in v0.17.0 

func (registry EnvRegistry) ReferencePaths(name string) []string

ReferencePaths returns config paths that reference an environment variable.

func (EnvRegistry) Requirement added in v0.17.0 

func (registry EnvRegistry) Requirement(name string) (EnvRequirement, bool)

Requirement returns the registry entry for an environment variable.

func (EnvRegistry) Requirements added in v0.17.0 

func (registry EnvRegistry) Requirements() []EnvRequirement

Requirements returns every declared environment requirement.

func (EnvRegistry) Validate added in v0.17.0 

func (registry EnvRegistry) Validate(lookup EnvironmentLookup) error

Validate checks required environment values and optional values that are present.

type EnvRequirement added in v0.17.0 

type EnvRequirement struct {
	// contains filtered or unexported fields
}

EnvRequirement declares whether an environment variable is required or optional and which value schema it must satisfy when present.

func NewOptionalEnv added in v0.17.0 

func NewOptionalEnv(name string, schema EnvValueSchema) (EnvRequirement, error)

NewOptionalEnv declares an optional environment variable.

func NewRequiredEnv added in v0.17.0 

func NewRequiredEnv(name string, schema EnvValueSchema) (EnvRequirement, error)

NewRequiredEnv declares a mandatory environment variable.

func (EnvRequirement) Name added in v0.17.0 

func (requirement EnvRequirement) Name() string

Name returns the environment variable name.

func (EnvRequirement) Required added in v0.17.0 

func (requirement EnvRequirement) Required() bool

Required reports whether the environment variable must be defined with a non-empty value.

func (EnvRequirement) SchemaName added in v0.17.0 

func (requirement EnvRequirement) SchemaName() string

SchemaName returns the value schema name or an empty string when no schema is attached.

type EnvValidationError added in v0.17.0 

type EnvValidationError struct {
	// contains filtered or unexported fields
}

EnvValidationError groups environment validation issues.

func (EnvValidationError) Error added in v0.17.0 

func (validationError EnvValidationError) Error() string

func (EnvValidationError) Is added in v0.17.0 

func (validationError EnvValidationError) Is(target error) bool

Is reports compatibility with ErrEnvironmentValidation.

func (EnvValidationError) Issues added in v0.17.0 

func (validationError EnvValidationError) Issues() []EnvValidationIssue

Issues returns the individual validation issues.

type EnvValidationIssue added in v0.17.0 

type EnvValidationIssue struct {
	// contains filtered or unexported fields
}

EnvValidationIssue describes one invalid environment variable.

func (EnvValidationIssue) Detail added in v0.17.0 

func (issue EnvValidationIssue) Detail() string

Detail returns schema failure detail without the raw environment value.

func (EnvValidationIssue) Kind added in v0.17.0 

func (issue EnvValidationIssue) Kind() EnvValidationIssueKind

Kind returns the validation issue category.

func (EnvValidationIssue) Name added in v0.17.0 

func (issue EnvValidationIssue) Name() string

Name returns the environment variable name.

func (EnvValidationIssue) Required added in v0.17.0 

func (issue EnvValidationIssue) Required() bool

Required reports whether the invalid environment variable was mandatory.

func (EnvValidationIssue) SchemaName added in v0.17.0 

func (issue EnvValidationIssue) SchemaName() string

SchemaName returns the failed schema name for invalid-value issues.

type EnvValidationIssueKind added in v0.17.0 

type EnvValidationIssueKind string

EnvValidationIssueKind classifies an environment validation failure. 

const (
	// EnvValidationIssueMissing means the required key was not defined.
	EnvValidationIssueMissing EnvValidationIssueKind = "missing"
	// EnvValidationIssueEmpty means the required key was defined with an empty
	// value.
	EnvValidationIssueEmpty EnvValidationIssueKind = "empty"
	// EnvValidationIssueInvalid means the value failed its declared schema.
	EnvValidationIssueInvalid EnvValidationIssueKind = "invalid"
)

type EnvValueSchema added in v0.17.0 

type EnvValueSchema interface {
	Name() string
	Validate(value string) error
}

EnvValueSchema validates one environment value without exposing the value in error output.

func EnvValueSchemaForKind added in v0.17.0 

func EnvValueSchemaForKind(kind string) (EnvValueSchema, error)

EnvValueSchemaForKind returns a built-in environment value schema.

func NewEnvValueSchema added in v0.17.0 

func NewEnvValueSchema(name string, validate func(value string) error) (EnvValueSchema, error)

NewEnvValueSchema creates a named environment value validator.

type EnvironmentLookup added in v0.17.0 

type EnvironmentLookup func(name string) (string, bool)

EnvironmentLookup resolves an environment variable by name.

type EnvironmentOptions added in v0.17.0 

type EnvironmentOptions struct {
	Lookup   EnvironmentLookup
	Registry EnvRegistry
}

EnvironmentOptions configures YAML environment interpolation and validation.

type InvalidEnvironmentReferenceError 

type InvalidEnvironmentReferenceError struct {
	Reference string
}

InvalidEnvironmentReferenceError identifies an unsupported interpolation reference.

func (InvalidEnvironmentReferenceError) Error 

func (invalidReferenceError InvalidEnvironmentReferenceError) Error() string

Error returns a stable invalid-reference error string.

func (InvalidEnvironmentReferenceError) Is 

func (invalidReferenceError InvalidEnvironmentReferenceError) Is(target error) bool

Is reports compatibility with ErrInvalidEnvironmentReference.

type MissingEnvironmentVariablesError 

type MissingEnvironmentVariablesError struct {
	Names []string
}

MissingEnvironmentVariablesError identifies every unset environment variable referenced by a YAML document.

func (MissingEnvironmentVariablesError) Error 

func (missingVariablesError MissingEnvironmentVariablesError) Error() string

Error returns a stable missing-environment error string.

func (MissingEnvironmentVariablesError) Is 

func (missingVariablesError MissingEnvironmentVariablesError) Is(target error) bool

Is reports compatibility with ErrMissingEnvironmentVariables.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.