konf

To use konf, you typically perform two distinct steps:

1. Setup (Application Entrypoint): Early in your application (e.g., in main()), create a konf.Config instance, load your desired sources (files, environment variables, etc.), and call konf.SetDefault(config) to make the configuration globally accessible.
2. Consumption (Application Logic): Throughout the rest of your application, use the package-level konf functions to read values without needing to know the underlying source.

This decoupling allows you to change your configuration source (e.g., moving from a local file to AWS AppConfig) without changing your business logic.

// 1. Setup in main()
func main() {
    var config konf.Config

    // Load from embed FS
    if err := config.Load(fs.New(config, "config/config.json")); err != nil {
        // handle error
    }

    // Load from environment variables
    if err := config.Load(env.New(env.WithPrefix("server"))); err != nil {
        // handle error
    }

    // Watch for changes
    go func() {
      if err := config.Watch(ctx); err != nil {
        // handle error
      }
    }()

    // Make it global
    konf.SetDefault(config)
}

// 2. Consumption in application logic
func (app *appObject) Run() {
    serverConfig := struct {
        Host string
        Port int
    }{
        Host: "localhost",
        Port: "8080",
    }

    // Read configuration into a struct
    if err := konf.Unmarshal("server", &serverConfig); err != nil {
        // handle error
    }

    // Register a callback for when "server" config changes
    konf.OnChange(func() {
      // Reconfigure application
    }, "server")
}

The pflag package allows you to load configuration from flags defined by the [spf13/pflag] library. It converts flags into a nested map[string]any based on a delimiter (defaulting to .).

Key Behaviors:

• Prefix Filtering: You can specify a prefix so that only flags starting with that prefix are loaded.
• Nesting: Flag names like parent.child.key="1" are parsed into nested maps: {parent: {child: {key: "1"}}}.
• Smart Merging: To prevent overriding values set by other providers, PFlag skips flags that have not been explicitly changed on the command line AND have a zero default value (e.g., 0, "", false, or []).
• Conflict Prevention: If a key already exists in the konf instance, PFlag will only merge the flag value if it was explicitly set in the command line.

// Example usage concept
// Assuming you have a konf instance and pflag defined
provider := pflag.New(myKonf, pflag.WithPrefix("app."))
config, err := provider.Load()
if err != nil {
    log.Fatal(err)
}
// config will contain flags like --app.database.port

The SecretManager provider allows you to load and watch configuration stored in Google Cloud Platform (GCP) Secret Manager.

Prerequisites

• The target GCP project must have the roles/secretmanager.viewer role assigned.
• If running on GCP, the provider can automatically detect the Project ID via metadata.

Key Features

• Automatic Loading: Fetches secret values using the latest version of each secret.
• Polling: Periodically checks for changes in secret ETags.
• Event-Driven Updates: Can be integrated with Pub/Sub to trigger updates immediately when secrets change.
• Hierarchical Keys: Supports mapping secret names to nested configuration keys using a custom splitter (defaults to splitting by -).

import "github.com/nil-go/konf/provider/secretmanager"

// Create a new provider
provider := secretmanager.New()

// Load configuration once
config, err := provider.Load()
if err != nil {
    panic(err)
}

The Watch method allows you to react to configuration changes in GCS. It supports two modes of change detection:

1. Polling (Default): Periodically checks the object for changes.
2. Pub/Sub Notifications: If you have configured Pub/Sub notifications for Cloud Storage, you can trigger updates manually by calling OnEvent with the appropriate attributes.

Watching with a callback

Pass a context and an onChange function that is executed whenever the configuration is updated.

Triggering updates via Pub/Sub

To use event-driven updates, call OnEvent(attributes) with the following map keys:

• bucketId: The name of the bucket.
• objectId: The name of the object.
• eventType: Must be OBJECT_FINALIZE to trigger a reload. Other event types are ignored.

ctx, cancel := context.WithCancel(context.Background())
// ... handle cancellation ...

err := provider.Watch(ctx, func(newConfig map[string]any) {
    fmt.Printf("Config updated: %v\n", newConfig)
})

// If receiving Pub/Sub events, call OnEvent:
// err := provider.OnEvent(map[string]string{
//     "bucketId": "my-bucket",
//     "objectId": "config.json",
//     "eventType": "OBJECT_FINALIZE",
// })