README
¶
gas/config
Part of the Gas monorepo · Documentation · All modules
Configuration for the Gas framework. Loads from environment variables, JSON,
.env files, and AWS Secrets Manager, and binds the result to Go structs with validation.
Implements gas.ConfigProvider.
go get github.com/gasmod/gas/config
cfg := config.New(config.WithProvider(providers.NewEnvProvider()))
if err := cfg.Load(); err != nil { log.Fatal(err) }
gas.WithServiceInstance[gas.ConfigProvider](cfg),
Nothing. Config is built and loaded before the app, so a bad configuration fails before anything else starts.
| Package | Provides |
|---|---|
config/providers |
Environment, JSON, and .env providers |
config/providers/secretsmanager |
AWS Secrets Manager |
config/extensions/gasenv |
Environment detection: development, staging, production |
config/configtest |
Mock and a real-backed fake seeded with known values |
Documentation
The full guide, with configuration, testing, and worked examples, is on the docs site. This README is deliberately a signpost: keeping a second copy here is how the docs drifted before.
- Guide: Configure an app
- API reference: pkg.go.dev/github.com/gasmod/gas/config
- Contributing: CONTRIBUTING.md
License
Documentation
¶
Overview ¶
Package config provides a flexible configuration management system that supports reading from multiple providers and binding to user-defined types.
Package config provides configuration management: env, JSON, and .env providers; struct binding; hierarchical dot-notation access; extensions with pre/post-load hooks.
See the module README for usage examples and design rationale.
SPDX-License-Identifier: MIT
Index ¶
- Variables
- type BindOption
- type BindOptions
- type Config
- func (c *Config) Bind(dest any, options ...BindOption) error
- func (c *Config) Find(key string) (value any, exist bool)
- func (c *Config) Get(key string) any
- func (c *Config) Load() error
- func (c *Config) LoadProvider(p providers.Provider) error
- func (c *Config) LoadProviderContext(ctx context.Context, p providers.Provider) error
- func (c *Config) LoadWithContext(ctx context.Context) error
- func (c *Config) Set(key string, value any)
- func (c *Config) SetDefault(key string, value any)
- func (c *Config) SetDefaults(values any) error
- func (c *Config) Values() map[string]any
- type Extension
- type Option
Constants ¶
This section is empty.
Variables ¶
var ( // ErrProviderLoadFailed indicates failure to load configuration from a provider. ErrProviderLoadFailed = errors.New("failed to load from provider") // ErrExtensionPreLoadHookFailed indicates a failure while executing the pre-load hook of an extension. ErrExtensionPreLoadHookFailed = errors.New("failed to execute extension pre-load hook") // ErrExtensionPostLoadHookFailed indicates a failure when executing the post-load hook of an extension. ErrExtensionPostLoadHookFailed = errors.New("failed to execute extension post-load hook") // ErrNilValues is returned when a nil value is provided where non-nil input is required. ErrNilValues = errors.New("values cannot be nil") )
Functions ¶
This section is empty.
Types ¶
type BindOption ¶
type BindOption func(*BindOptions)
BindOption is a functional option for configuring Bind behavior by modifying BindOptions.
func WithValidate ¶
func WithValidate(validate bool) BindOption
WithValidate sets the validation flag in the BindOptions.
type BindOptions ¶
type BindOptions struct {
// contains filtered or unexported fields
}
BindOptions defines options for binding configuration data to a struct.
type Config ¶
type Config struct {
// contains filtered or unexported fields
}
Config represents the configuration loaded from various providers.
func New ¶
New creates and returns a new Config instance, applying the provided functional options. If no providers are specified, an EnvProvider is added as the default.
func (*Config) Bind ¶
func (c *Config) Bind(dest any, options ...BindOption) error
Bind binds the configuration to the provided struct.
func (*Config) Find ¶
Find searches for and retrieves a configuration value by key. Supports hierarchical paths like "database.host".
func (*Config) Get ¶
Get retrieves a configuration value by key. Supports hierarchical paths like "database.host".
func (*Config) Load ¶
Load loads configuration from all registered providers and applies pre/post-Load hooks defined by extensions.
Returns an error if any provider or extension hook fails during the loading process.
func (*Config) LoadProvider ¶ added in v0.4.3
LoadProvider registers the provider and loads its values into the configuration, merging them over any values already present. Like the providers passed to New, a provider registered here overrides the keys it defines and leaves the rest alone, so registering the same name twice is allowed and the later values win.
Returns an error if loading fails.
func (*Config) LoadProviderContext ¶ added in v0.4.3
LoadProviderContext behaves like LoadProvider, using the provided context when the provider implements providers.ContextProvider.
func (*Config) LoadWithContext ¶
LoadWithContext loads configuration with the provided context, executing pre-Load and post-Load hooks for extensions.
func (*Config) Set ¶
Set sets a value for the specified key in the configuration, overriding any existing value. It creates nested maps if they do not exist.
func (*Config) SetDefault ¶
SetDefault sets a default value for the specified key in the configuration. It creates nested maps if they do not exist, but does not override existing values.
func (*Config) SetDefaults ¶
SetDefaults sets default configuration values from a struct or map without overriding existing values. Returns an error if the input is invalid or nil.
type Extension ¶
type Extension interface {
Name() string
PreLoad(ctx context.Context, cfg *Config) error
PostLoad(ctx context.Context, cfg *Config) error
}
Extension defines an interface for executing actions during the configuration loading process. The Name method is used to identify the extension by name. The PreLoad method is invoked prior to the main configuration loading phase. The PostLoad method is invoked after the main configuration loading phase.
type Option ¶
type Option func(*Config)
Option configures the config service constructor.
func WithExtension ¶
WithExtension registers an extension that provides pre/post-Load hooks.
func WithProvider ¶
WithProvider adds a configuration provider (env, JSON, .env, etc.).
func WithValidator ¶
WithValidator sets a custom validator instance, allowing callers to register custom validation tags before constructing the Config. If not provided, a new validator.New() instance is used.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package configtest provides a mock implementation of the config provider API for use in tests.
|
Package configtest provides a mock implementation of the config provider API for use in tests. |
|
extensions
|
|
|
gasenv
Package gasenv provides an extension for the config configuration library that manages application environments (development, testing, staging, production).
|
Package gasenv provides an extension for the config configuration library that manages application environments (development, testing, staging, production). |
|
internal
|
|
|
dotenv
Package dotenv provides functionality for parsing dotenv-style configuration files.
|
Package dotenv provides functionality for parsing dotenv-style configuration files. |
|
env
Package env provides utilities for parsing environment variables into nested Go data structures.
|
Package env provides utilities for parsing environment variables into nested Go data structures. |
|
maputils
Package maputils provides utilities for deep binding and merging of maps into Go data structures.
|
Package maputils provides utilities for deep binding and merging of maps into Go data structures. |
|
providers
Package providers implements a base FS-based configuration provider.
|
Package providers implements a base FS-based configuration provider. |
|
reflection
Package reflection provides utilities for working with Go's reflection system.
|
Package reflection provides utilities for working with Go's reflection system. |
|
sysfs
Package sysfs provides a file system implementation that ensures safe file operations.
|
Package sysfs provides a file system implementation that ensures safe file operations. |
|
secretsmanager
Package secretsmanager provides a gas/config provider that loads configuration from AWS Secrets Manager.
|
Package secretsmanager provides a gas/config provider that loads configuration from AWS Secrets Manager. |