conf

package module

v0.4.0 Latest Latest Go to latest Published: Sep 10, 2025 License: MPL-2.0 Imports: 15 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/sower-proxy/feconf

Links

Open Source Insights

README ¶

feconf

A flexible, URI-based configuration management library for Go that supports multiple protocols, formats, and real-time configuration updates.

Features

🌐 Multiple Protocols: Support for HTTP/HTTPS, WebSocket, Redis, and local files
📄 Multiple Formats: JSON, YAML, INI, TOML, and XML configuration formats
🔄 Real-time Updates: Subscribe to configuration changes with automatic reloading
🚩 Command-line Flags: Built-in support for reading configuration URI from flags
🔌 Extensible: Plugin-based architecture for custom readers and decoders
⚡ Performance: Efficient parsing with connection pooling and retry mechanisms
🔒 Security: TLS support with custom certificates and authentication
📋 Type Safety: Strong typing with struct mapping using mapstructure
🎣 Extensible Hooks: Built-in hook functions for type conversion and data processing

Installation

go get github.com/sower-proxy/feconf

Quick Start

package main

import (
    "fmt"
    "log"

    "github.com/sower-proxy/feconf"
    _ "github.com/sower-proxy/feconf/decoder/json"
    _ "github.com/sower-proxy/feconf/reader/file"
)

type Config struct {
    Host string `json:"host"`
    Port int    `json:"port"`
}

func main() {
    loader := conf.New[Config]("file://./config.json")
    defer loader.Close()

    config, err := loader.Load()
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Server: %s:%d\n", config.Host, config.Port)
}

For command-line flag support:

// Read config URI from -config flag, fallback to default if not provided
loader := conf.NewWithFlags[Config]("file://./default-config.json")

For real-time updates:

eventChan, _ := loader.Subscribe()
for event := range eventChan {
    if event.IsValid() {
        fmt.Printf("Config updated: %v\n", event.Config)
    }
}

Supported Protocols

File System

loader := conf.New[Config]("file:///path/to/config.json")

HTTP/HTTPS

loader := conf.New[Config]("https://api.example.com/config.yaml?timeout=30s")

WebSocket

loader := conf.New[Config]("wss://realtime.example.com/config?ping_interval=30s")

Redis

loader := conf.New[Config]("redis://localhost:6379/config-key?db=1&pool_size=10")

// For Redis hash fields
loader := conf.New[Config]("redis://localhost:6379/config-hash#field-name")

Kubernetes ConfigMap/Secret

// Read from a ConfigMap
loader := conf.New[Config]("k8s://configmap/default/app-config")

// Read a specific key from a ConfigMap
loader := conf.New[Config]("k8s://configmap/default/app-config/config.yaml")

// Read from a Secret
loader := conf.New[string]("k8s://secret/default/db-secret/password")

Supported Formats

The library automatically detects format from file extensions or can be specified via content-type parameter:

JSON: .json or content-type=application/json
YAML: .yaml, .yml or content-type=application/yaml
INI: .ini or content-type=text/ini
TOML: .toml or content-type=application/toml
XML: .xml or content-type=application/xml

Examples

The examples/ directory contains complete working examples:

File + JSON: Basic file-based configuration with JSON format
HTTP + YAML: HTTP-based configuration with YAML format and authentication
Redis + INI: Redis-based configuration with INI format
Redis + Hash: Redis hash field configuration with JSON format
WebSocket + XML: Real-time configuration updates via WebSocket with XML format
Kubernetes: Kubernetes ConfigMap/Secret configuration with YAML format
Flags: Command-line flag support for configuration URI specification

Running Examples

# File example
cd examples/file-json && go run .

# HTTP example (starts a demo server)
cd examples/http-yaml && go run .

# Redis example (requires Redis server)
cd examples/redis-ini && ./setup.sh && go run .

# Command-line flags example
cd examples/flags && go run . -config file://./prod-config.json

# WebSocket example (starts a demo WebSocket server)
cd examples/ws-xml && go run .

# Kubernetes example (requires Kubernetes cluster)
cd examples/k8s-yaml && ./setup.sh && go run .

Architecture

The library follows a modular plugin-based architecture:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Application   │    │   Configuration  │    │   Decoder       │
│                 │───▶│   Loader (conf)  │───▶│   (json/yaml/   │
│   Your Code     │    │                  │    │    ini/etc)     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌──────────────────┐
                       │   Reader         │
                       │   (file/http/    │
                       │   redis/ws)      │
                       └──────────────────┘

Best Practices

Import required modules: Always import specific decoder and reader modules
Handle errors: Always check and handle configuration loading errors
Resource cleanup: Use defer loader.Close() to cleanup resources
Use timeouts: Leverage context for request timeouts
Validate configuration: Validate loaded configuration before use
Use appropriate hook functions: Leverage built-in hook functions for common data transformations

Advanced Features

Custom Mapstructure Configuration

loader := conf.New[Config](uri)
loader.ParserConf.TagName = "config"  // Use 'config' tags instead of 'json'
loader.ParserConf.ErrorUnused = true  // Error on unused fields

// Custom hook functions can be added to the decode chain
customHook := mapstructure.ComposeDecodeHookFunc(
    conf.HookFuncDefault(),      // Default value handling
    conf.HookFuncEnvRender(),     // Environment variable rendering
    conf.HookFuncStringToBool(),  // String to boolean conversion
    conf.HookFuncStringToSlogLevel(), // String to log level conversion
    // Add your custom hooks here
)
loader.ParserConf.DecodeHook = customHook

Environment-specific Configuration

env := os.Getenv("APP_ENV")
if env == "" {
    env = "development"
}

uri := fmt.Sprintf("file://./config-%s.yaml", env)
loader := conf.New[Config](uri)

URI Query Parameters

Universal Parameters

Parameter	Type	Default	Description	Example
`content-type`	string	From file extension	Specifies the MIME type to determine decoder format	`?content-type=application/json`

HTTP/HTTPS Parameters

Parameter	Type	Default	Description	Example
`timeout`	duration	`30s`	HTTP request timeout duration	`?timeout=60s`
`retry_attempts`	integer	`3`	Number of retry attempts for failed requests	`?retry_attempts=5`
`retry_delay`	duration	`1s`	Delay between retry attempts	`?retry_delay=2s`
`header_*`	string	-	Custom HTTP headers (format: `header_<name>=<value>`)	`?header_Authorization=Bearer%20token`
`tls_insecure`	boolean	`false`	Skip TLS certificate verification	`?tls_insecure=true`

Redis Parameters

Parameter	Type	Default	Description	Example
`db`	integer	`0`	Redis database number	`?db=1`
`timeout`	duration	`30s`	Redis operation timeout	`?timeout=10s`
`pool_size`	integer	`10`	Redis connection pool size	`?pool_size=20`
`tls_insecure`	boolean	`false`	Skip TLS certificate verification for REDISS	`?tls_insecure=true`

Hash Field Support: Use URI fragment (#field-name) to read from specific hash fields:

redis://localhost:6379/user:123?content-type=application/json#profile

License

This project is licensed under the Mozilla Public License Version 2.0 - see the LICENSE file for details.

Documentation ¶

Index ¶

Variables
func HookFuncDefault() mapstructure.DecodeHookFuncType
func HookFuncEnvRender() mapstructure.DecodeHookFuncType
func HookFuncStringToBool() mapstructure.DecodeHookFuncType
func HookFuncStringToSlogLevel() mapstructure.DecodeHookFuncType
func Load[T any](obj *T, uri string) error
func LoadCtx[T any](ctx context.Context, obj *T, uri string) error
func LoadFlags[T any](result *T) error
func LoadFlagsCtx[T any](ctx context.Context, config *T) error
func LoadWithFlags[T any](obj *T, uriOrFlag string) error
func LoadWithFlagsCtx[T any](ctx context.Context, obj *T, uriOrFlag string) error
type ConfEvent
- func (c *ConfEvent[T]) IsValid() bool
type ConfOpt

Constants ¶

This section is empty.

Variables ¶

View Source

var DefaultParserConfig = mapstructure.DecoderConfig{
	DecodeHook: mapstructure.ComposeDecodeHookFunc(
		HookFuncDefault(),
		HookFuncEnvRender(),
		HookFuncStringToBool(),
		HookFuncStringToSlogLevel(),
		mapstructure.StringToTimeDurationHookFunc(),
		mapstructure.StringToSliceHookFunc(","),
		mapstructure.StringToBasicTypeHookFunc(),
	),
	TagName:          "json",
	WeaklyTypedInput: true,
	ErrorUnused:      false,
	ZeroFields:       false,
	MatchName: func(mapKey, fieldName string) bool {
		return strings.EqualFold(strings.ReplaceAll(mapKey, "_", ""), fieldName)
	},
}

DefaultParserConfig 默认解析器配置

Functions ¶

func HookFuncStringToSlogLevel ¶

func HookFuncStringToSlogLevel() mapstructure.DecodeHookFuncType

HookFuncStringToSlogLevel 字符串和数字到slog.Level的钩子

func Load ¶

func Load[T any](obj *T, uri string) error

Load loads configuration from URI and unmarshals it to the provided object

func LoadCtx ¶

func LoadCtx[T any](ctx context.Context, obj *T, uri string) error

LoadCtx loads configuration from URI with context and unmarshals it to the provided object

func LoadFlags ¶

func LoadFlags[T any](result *T) error

LoadFlags parses struct fields and adds command-line flags for fields with 'usage' tag, parses command-line flags, maps flag values to the struct, and modifies the provided struct pointer This is a public entry function for flag parsing functionality

func LoadFlagsCtx ¶

func LoadFlagsCtx[T any](ctx context.Context, config *T) error

LoadFlagsCtx parses struct fields and adds command-line flags for fields with 'usage' tag with context support, parses command-line flags, maps flag values to the struct, and modifies the provided struct pointer The context can be used for cancellation or timeout during flag parsing

func LoadWithFlags ¶

func LoadWithFlags[T any](obj *T, uriOrFlag string) error

LoadWithFlags loads configuration from URI or flag and unmarshals it to the provided object If uriOrFlag is a valid URI, it will be used as the configuration source If uriOrFlag is not a URI, it will be treated as a flag name for configuration It also parses the struct type T and adds flags for fields with 'usage' tag

func LoadWithFlagsCtx ¶

func LoadWithFlagsCtx[T any](ctx context.Context, obj *T, uriOrFlag string) error

LoadWithFlagsCtx loads configuration from URI or flag with context and unmarshals it to the provided object If uriOrFlag is a valid URI, it will be used as the configuration source If uriOrFlag is not a URI, it will be treated as a flag name for configuration It also parses the struct type T and adds flags for fields with 'usage' tag The context can be used for cancellation or timeout during loading

Types ¶

type ConfEvent ¶

type ConfEvent[T any] struct {
	SourceURI string    `json:"source_uri"`
	Timestamp time.Time `json:"timestamp"`
	Error     error     `json:"error,omitempty"`
	Config    *T        `json:"config,omitempty"`
}

func (*ConfEvent[T]) IsValid ¶

func (c *ConfEvent[T]) IsValid() bool

type ConfOpt ¶

type ConfOpt[T any] struct {
	ParserConf mapstructure.DecoderConfig
	// contains filtered or unexported fields
}

func New ¶

func New[T any](uri string) *ConfOpt[T]

func NewWithFlags ¶

func NewWithFlags[T any](uriOrFlag string) *ConfOpt[T]

NewWithFlags creates a configuration loader that reads URI from command-line flags If uriOrFlag is a valid URI, it will be used as the configuration source If uriOrFlag is not a URI, it will be treated as a flag name for configuration It also parses the struct type T and adds flags for fields with 'usage' tag

func NewWithFlagsCtx ¶

func NewWithFlagsCtx[T any](ctx context.Context, uriOrFlag string) *ConfOpt[T]

NewWithFlagsCtx creates a configuration loader that reads URI from command-line flags with context support If uriOrFlag is a valid URI, it will be used as the configuration source If uriOrFlag is not a URI, it will be treated as a flag name for configuration It also parses the struct type T and adds flags for fields with 'usage' tag The context can be used for cancellation or timeout during flag parsing

func (*ConfOpt[T]) Close ¶

func (c *ConfOpt[T]) Close() error

func (*ConfOpt[T]) Load ¶

func (c *ConfOpt[T]) Load(obj *T) error

Load loads configuration and unmarshals it to the provided object

func (*ConfOpt[T]) LoadCtx ¶

func (c *ConfOpt[T]) LoadCtx(ctx context.Context, obj *T) error

LoadCtx loads configuration with context and unmarshals it to the provided object

func (*ConfOpt[T]) Parse ¶

func (c *ConfOpt[T]) Parse() (*T, error)

func (*ConfOpt[T]) ParseCtx ¶

func (c *ConfOpt[T]) ParseCtx(ctx context.Context) (*T, error)

func (c *ConfOpt[T]) Subscribe() (<-chan *ConfEvent[T], error)

func (*ConfOpt[T]) SubscribeCtx ¶

func (c *ConfOpt[T]) SubscribeCtx(ctx context.Context) (<-chan *ConfEvent[T], error)

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
decoder
ini
json
toml
xml
yaml
reader
file
http
k8s Package k8s provides a configuration reader implementation for Kubernetes ConfigMaps and Secrets.	Package k8s provides a configuration reader implementation for Kubernetes ConfigMaps and Secrets.
redis
ws

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL