Configuration Sources

source.Chain (priority-ordered)
  ├── source.Memory   (in-memory, supports Watch)
  ├── source.Env      (environment variables)
  └── source.Database (reads from config.Store)

import "github.com/xraph/vault/source"

type Source interface {
    Name() string
    Get(ctx context.Context, key string) (*Value, error)
    List(ctx context.Context, prefix string) ([]*Value, error)
    Watch(ctx context.Context, key string, fn WatchFunc) error
    Close() error
}

type Value struct {
    Key       string            `json:"key"`
    Raw       string            `json:"raw"`
    Source    string            `json:"source"`
    Version   int64             `json:"version,omitempty"`
    ExpiresAt *time.Time        `json:"expires_at,omitempty"`
    Metadata  map[string]string `json:"metadata,omitempty"`
}

type WatchFunc func(ctx context.Context, key string, val *Value)

var ErrKeyNotFound = errors.New("source: key not found")

func NewMemory() *Memory

mem := source.NewMemory()

func (m *Memory) Set(ctx context.Context, key, raw string)

mem.Set(ctx, "feature.enabled", "true")

val, err := mem.Get(ctx, "feature.enabled")
if err != nil {
    // source: key not found
}
fmt.Println(val.Raw) // "true"

vals, err := mem.List(ctx, "feature.")
for _, v := range vals {
    fmt.Printf("%s = %s\n", v.Key, v.Raw)
}

mem.Watch(ctx, "feature.enabled", func(ctx context.Context, key string, val *source.Value) {
    fmt.Printf("changed: %s = %s\n", key, val.Raw)
})

func NewEnv(prefix string) *Env

// Without prefix: looks up "DB_HOST" for key "db-host"
env := source.NewEnv("")

// With prefix: looks up "MYAPP_DB_HOST" for key "db-host"
env := source.NewEnv("MYAPP")

val, err := env.Get(ctx, "db-host")
if err != nil {
    // source: key not found (env var not set or empty)
}
fmt.Println(val.Raw) // value of DB_HOST

func NewDatabase(store config.Store, appID string, opts ...DatabaseOption) *Database

db := source.NewDatabase(configStore, "myapp")

db := source.NewDatabase(configStore, "myapp",
    source.WithPollInterval(10 * time.Second),
)

val, err := db.Get(ctx, "max-connections")
if err != nil {
    // source: key not found
}
fmt.Println(val.Raw)     // "25"
fmt.Println(val.Version) // 3

vals, err := db.List(ctx, "db.")

db.Watch(ctx, "max-connections", func(ctx context.Context, key string, val *source.Value) {
    if val == nil {
        fmt.Printf("key %s was deleted\n", key)
        return
    }
    fmt.Printf("changed: %s = %s (version %d)\n", key, val.Raw, val.Version)
})

db.Close()

func NewChain(sources ...Source) *Chain

chain := source.NewChain(
    source.NewMemory(),                        // highest priority
    source.NewEnv("MYAPP"),                    // middle priority
    source.NewDatabase(configStore, "myapp"),   // lowest priority
)

func (c *Chain) Get(ctx context.Context, key string) (*Value, error)

val, err := chain.Get(ctx, "db-host")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("value=%s source=%s\n", val.Raw, val.Source)
// e.g., "value=localhost source=env"

func (c *Chain) List(ctx context.Context, prefix string) ([]*Value, error)

vals, err := chain.List(ctx, "")
for _, v := range vals {
    fmt.Printf("%-20s = %-20s (from %s)\n", v.Key, v.Raw, v.Source)
}

func (c *Chain) Watch(ctx context.Context, key string, fn WatchFunc) error

chain.Watch(ctx, "feature.enabled", func(ctx context.Context, key string, val *source.Value) {
    fmt.Printf("changed: %s = %s (from %s)\n", key, val.Raw, val.Source)
})

func (c *Chain) Close() error

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/xraph/vault/source"
)

func main() {
    ctx := context.Background()

    // Create sources.
    mem := source.NewMemory()
    env := source.NewEnv("MYAPP")
    db := source.NewDatabase(configStore, "myapp")

    // Build a priority chain.
    chain := source.NewChain(mem, env, db)
    defer chain.Close()

    // Set a value in memory (highest priority).
    mem.Set(ctx, "feature.enabled", "true")

    // Environment variable MYAPP_DB_HOST=prod-db.example.com is set.
    // Database has db-host=localhost.

    // Memory wins for this key.
    val, err := chain.Get(ctx, "feature.enabled")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%s = %s (from %s)\n", val.Key, val.Raw, val.Source)
    // feature.enabled = true (from memory)

    // Env wins over database for this key.
    val, err = chain.Get(ctx, "db-host")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%s = %s (from %s)\n", val.Key, val.Raw, val.Source)
    // db-host = prod-db.example.com (from env)

    // Watch for changes (memory source supports this).
    chain.Watch(ctx, "feature.enabled", func(ctx context.Context, key string, val *source.Value) {
        fmt.Printf("CHANGED: %s = %s\n", key, val.Raw)
    })

    // Trigger the watcher.
    mem.Set(ctx, "feature.enabled", "false")
    // CHANGED: feature.enabled = false

    // List all values (merged from all sources).
    vals, err := chain.List(ctx, "")
    if err != nil {
        log.Fatal(err)
    }
    for _, v := range vals {
        fmt.Printf("  %-25s = %-20s (from %s)\n", v.Key, v.Raw, v.Source)
    }
}