Skip to content
containerooPublic

About

golang library to get variables from environment, json, yaml, ini or other files

Resources

Stars

0 stars

Watchers

1 watching

Forks

Latest commit

 

History

37 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Resolver

github.com/containeroo/resolver resolves configuration values from environment variables, files, JSON, YAML, INI and TOML with explicit source prefixes. Unknown references pass through unchanged by default.

Installation

go get github.com/containeroo/resolver

Sources

Syntax Meaning
env:NAME Environment variable NAME
secret:/run/secrets/token Whole secret file, trailing CR/LF removed
file:/path/token Entire file contents
file:/path/config.env//KEY Value of KEY from a key-value file
json:/path/config.json//service.token JSON path
yaml:/path/config.yaml//service.token YAML path
ini:/path/config.ini//Section.Key INI key
toml:/path/config.toml//service.token TOML key
literal:my:secret Literal string containing any colon
plain-secret Unprefixed literal, unchanged
value, err := resolver.ResolveVariable("env:MY_TOKEN")

An unset environment variable returns ErrNotFound; a set-but-empty variable is accepted by default. The default whole-file resolver trims surrounding whitespace. To preserve whitespace, register a KeyValueFileResolver with an explicit Whitespace policy.

Registry configuration

r := resolver.NewDefaultRegistry(
    resolver.WithEmptyValuePolicy(resolver.RejectBlank),
    resolver.WithUnknownSchemePolicy(resolver.ErrorOnUnknown),
    resolver.WithMaxDepth(8),
)

secret, err := r.ResolveVariable("env:CLOUDFLARE_TOKEN")

Empty-value policies:

  • AllowEmpty (default): accepts empty and whitespace-only strings.
  • RejectEmpty: rejects only "".
  • RejectBlank: rejects empty or whitespace-only strings, without trimming valid values.

Rejected empties produce ErrEmptyValue. Missing values still produce ErrNotFound.

Unknown-scheme policies:

  • PassThrough (default): leaves unknown schemes unchanged.
  • ErrorOnUnknown: rejects inputs starting with an unregistered scheme prefix such as evn:KEY or https:. Colons embedded in ordinary prose do not count as a scheme. To deliberately use an unknown scheme as a literal, use literal:https://example.com.

NewRegistry(options...) starts with no registered schemes; NewDefaultRegistry(options...) registers the built-in schemes. You can also use SetEmptyValuePolicy and SetUnknownSchemePolicy on a registry.

To allow only environment and file sources:

r := resolver.NewRegistry(
    resolver.WithEmptyValuePolicy(resolver.RejectBlank),
    resolver.WithUnknownSchemePolicy(resolver.ErrorOnUnknown),
)
r.Register("env:", &resolver.EnvResolver{})
r.Register("file:", &resolver.KeyValueFileResolver{Whitespace: resolver.FileTrimNewlines})
r.Register("literal:", resolver.LiteralResolver{})

File whitespace policies

  • FileTrimSpace (default) trims surrounding whitespace, including newlines.
  • FileTrimNewlines removes trailing carriage returns and line feeds only.
  • FilePreserveWhitespace preserves bytes (excluding any leading UTF-8 BOM).

These policies apply when reading an entire file; key-value file parsing retains its existing whitespace rules. Values are resolved at call time, not watched for changes.

Mounted Kubernetes secrets

Use secret: to read a mounted secret as a whole file and remove trailing LF or CRLF line endings. Leading and trailing spaces, tabs, internal newlines, and all other bytes are preserved:

value, err := resolver.ResolveVariable("secret:/var/run/secrets/my-app/token")

secret: is registered by default and appears in Prefixes(). Paths support environment variables, for example secret:${SECRETS_DIR}/token. An empty path returns ErrBadPath; a missing file returns an error matching ErrNotFound. Empty contents are governed by the registry's empty-value policy.

This source works with Kubernetes, Docker, and other mounted secret files. It reads the whole file directly without key selectors, Kubernetes API access, or base64 decoding. Values are read again on each resolution call. If trailing newlines are part of the secret, use file: with FilePreserveWhitespace instead. The default file: resolver uses FileTrimSpace, which also removes surrounding spaces and tabs.

Discover registered prefixes

Use Prefixes to discover supported prefixes instead of hardcoding built-in schemes. It returns a sorted, independent copy of the current registrations, including custom resolvers:

r := resolver.NewDefaultRegistry()
r.Register("custom:", resolver.ResolverFunc(func(value string) (string, error) {
    return value, nil
}))
prefixes := r.Prefixes() // includes "custom:"
known := r.CanResolve("custom:value") // true; does not invoke the resolver

CanResolve follows the same case-sensitive, start-of-string prefix matching as ResolveVariable. It only checks registration: env:MISSING and even env: match a registered env: prefix, but resolution can still fail. It does not read environment variables, files, or external services. Embedded references such as Bearer env:TOKEN do not match.

Package-level resolver.Prefixes() and resolver.CanResolve(value) use the default registry and immediately reflect registrations made with RegisterResolver. Registrations on a separate registry affect only that instance. Replacing a resolver does not duplicate its prefix. Schemes() remains available when registration order is needed; resolution still uses the first registered matching prefix, including when prefixes overlap.

String interpolation

Use ResolveString to interpolate ${scheme:value} tokens in a string. Expansion can run multiple passes when one resolver produces another expression. The default maximum is eight passes and can be changed with WithMaxDepth.

r := resolver.NewDefaultRegistry()
r.Register("a:", resolver.ResolverFunc(func(string) (string,error) {return "${b:x}", nil}))
r.Register("b:", resolver.ResolverFunc(func(string) (string,error) {return "OK", nil}))
value, err := r.ResolveString("${a:any}")  // "OK"

Escape a token as \${env:NAME} to leave it literal, even across multiple expansion passes. Use ResolveVariable for whole secret references rather than interpolation; interpolation is designed for assembling larger strings.

Batch resolution

ResolveSlice returns a new slice or stops at the first error. ResolveSliceBestEffort attempts all values and returns a new slice plus per-index errors.

Custom resolvers

r := resolver.NewRegistry()
r.Register("custom:", resolver.ResolverFunc(func(value string) (string, error) {
    return fetchCustomValue(value)
}))

RegisterResolver registers on the package's global default registry. Registry.Register registers on a specific registry. DefaultRegistry() returns the global registry; avoid mutating it when different components need different source restrictions.

About

golang library to get variables from environment, json, yaml, ini or other files

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages