source

Documentation

Overview

Package source provides configuration source implementations.

Types here load data from various locations and satisfy gopherly.dev/synthra.Source for use with gopherly.dev/synthra.WithSource and related options.

Available Sources

• File: Load configuration from the host file system
• FileFS: Load configuration from a path inside an io/fs.FS
• Map: In-memory map (defaults, embedded trees, tests)
• OSEnvVar: Load configuration from environment variables
• Consul: Load configuration from Consul key-value store

Example

Creating a file source:

fileSource := source.NewFile("config.yaml", codec.YAML)
config, err := fileSource.Load(context.Background())

Creating an environment variable source:

envSource := source.NewOSEnvVar("APP_")
config, err := envSource.Load(context.Background())

Loading from an io/fs.FS (for example testing/fstest.MapFS or embed.FS):

fsys := fstest.MapFS{"cfg.yaml": &fstest.MapFile{Data: []byte("k: v\n")}}
fsSrc := source.NewFileFS(fsys, "cfg.yaml", codec.YAML)
config, err := fsSrc.Load(context.Background())

Index

• type Consul
  • func NewConsul(path string, decoder codec.Decoder, kv ConsulKV) (*Consul, error)
  • func (c *Consul) Load(ctx context.Context) (map[string]any, error)
• type ConsulKV
• type File
  • func NewFile(path string, decoder codec.Decoder) *File
  • func NewFileContent(data []byte, decoder codec.Decoder) *File
  • func (f *File) Load(context.Context) (map[string]any, error)
• type FileFS
  • func NewFileFS(fsys fs.FS, name string, decoder codec.Decoder) *FileFS
  • func (f *FileFS) Load(_ context.Context) (map[string]any, error)
• type Map
  • func NewMap(m map[string]any) *Map
  • func (s *Map) Load(context.Context) (map[string]any, error)
• type OSEnvVar
  • func NewOSEnvVar(prefix string) *OSEnvVar
  • func (e *OSEnvVar) Load(_ context.Context) (map[string]any, error)

Types

type Consul

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

Consul represents a configuration source that loads data from Consul's key-value store.

The Consul client is configured using environment variables:

• CONSUL_HTTP_ADDR: The address of the Consul server (e.g., "http://localhost:8500")
• CONSUL_HTTP_TOKEN: The access token for authentication (optional)

func NewConsul

func NewConsul(path string, decoder codec.Decoder, kv ConsulKV) (*Consul, error)

NewConsul creates a new Consul configuration source with the given path and decoder. The path parameter specifies the key path in Consul's key-value store. If kv is nil, it uses the default Consul client KV implementation.

Errors:

• Returns error if the Consul client cannot be created

func (*Consul) Load

func (c *Consul) Load(ctx context.Context) (map[string]any, error)

Load retrieves configuration data from the Consul key-value store at the configured path. If the key does not exist in Consul, it returns an empty map without error.

Errors:

• Returns error if the Consul query fails
• Returns error if decoding the value fails

type ConsulKV

type ConsulKV interface {
	Get(key string, q *api.QueryOptions) (*api.KVPair, *api.QueryMeta, error)
}

ConsulKV defines the interface for Consul key-value operations. This interface enables testing by allowing mock implementations.

type File

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

File represents a configuration source that loads data from a file or byte content. It supports loading from file paths or directly from byte slices.

func NewFile

func NewFile(path string, decoder codec.Decoder) *File

NewFile creates a new File source that loads configuration from the specified file path. The decoder parameter determines how the file content is parsed.

func NewFileContent

func NewFileContent(data []byte, decoder codec.Decoder) *File

NewFileContent creates a new File source that loads configuration from the provided byte slice. This is useful for loading configuration from embedded content or dynamically generated data.

func (*File) Load

func (f *File) Load(context.Context) (map[string]any, error)

Load reads the configuration file and decodes its contents into a map[string]any. If the File was created with NewFile, it reads from the file system. If the File was created with NewFileContent, it uses the provided byte content.

Errors:

• Returns error if the file cannot be read (NewFile only)
• Returns error if decoding fails

type FileFS

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

FileFS loads configuration from a single file inside an io/fs.FS. Concurrent use is OK when the underlying fs.FS is safe for concurrent use.

func NewFileFS

func NewFileFS(fsys fs.FS, name string, decoder codec.Decoder) *FileFS

NewFileFS returns a source that reads name from fsys and decodes bytes with decoder. name must use slash-separated paths as required by fs.FS (for example "config/app.yaml").

func (*FileFS) Load

func (f *FileFS) Load(_ context.Context) (map[string]any, error)

Load reads the named file from fsys and decodes it into a map[string]any. Keys in the returned map are not normalized; the Synthra loader normalizes keys.

type Map

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

Map is a Source backed by an in-memory map.

NewMap aliases the caller's map for efficiency; callers must not mutate that map after passing it to NewMap if Load may run concurrently or if they rely on a stable snapshot. To pass an independent copy, use maps.Clone (or another deep copy strategy) before calling NewMap.

Each successful Load returns the same map reference.

func NewMap

func NewMap(m map[string]any) *Map

NewMap returns a Source that always loads from m. A nil m is treated as empty.

func (*Map) Load

func (s *Map) Load(context.Context) (map[string]any, error)

Load returns the configured map.

type OSEnvVar

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

OSEnvVar represents a configuration source that loads data from environment variables. It filters environment variables by prefix and creates nested configuration structures based on underscore-separated variable names.

For example, with prefix "APP_", the environment variable "APP_SERVER_PORT" becomes the configuration key "server.port".

func NewOSEnvVar

func NewOSEnvVar(prefix string) *OSEnvVar

NewOSEnvVar creates a new OSEnvVar source with the specified prefix. Only environment variables starting with this prefix will be loaded. The prefix is stripped from variable names before processing.

func (*OSEnvVar) Load

func (e *OSEnvVar) Load(_ context.Context) (map[string]any, error)

Load reads environment variables with the configured prefix and decodes them into a map[string]any. Variable names are converted to lowercase and underscores create nested structures.

Example:

APP_SERVER_PORT=8080     -> server.port = "8080"
APP_SERVER_HOST=localhost -> server.host = "localhost"
APP_DEBUG=true           -> debug = "true"

Errors:

• Returns error if decoding fails