add: config overlay example, more default paths

Signed-off-by: Christoph Hoopmann <[email protected]>

Author: choopm

.devcontainer/devcontainer.json

@@ -19,7 +19,7 @@
 			"version": "os-provided"
 		},
 		"ghcr.io/devcontainers/features/go:1": {
-			"version": "1.24"
+			"version": "1.25"
 		}
 	},
 	"customizations": {

README.md

@@ -21,9 +21,11 @@ By using stdfx as an application starter you benefit from:
 
 See [examples/webserver](./examples/webserver/) to test and experience it in action.
 
+It acts as a demo for every stdfx feature.
+
 ### Usage example
 
-A complete usage might look like this:
+A minimal usage might look like this:
 
 <!-- markdownlint-disable MD010 -->
 ```golang

configfx/defaults.go

@@ -44,11 +44,15 @@ func DefaultEnvironmentPrefix(configName string) string {
 // - $HOME/.config/
 // - $HOME/.<configName>/
 // - $HOME/.local/etc/
+// - $HOME/.local/etc/<configName>/
 // - $HOME/
 // - /opt/<configName>/
 // - /opt/<configName>/etc/
+// - /opt/<configName>/etc/<configName>/
 // - /usr/local/etc/
+// - /usr/local/etc/<configName>/
 // - /etc/
+// - /etc/<configName>/
 func DefaultFileSearchPaths(configName string) []string {
 	// working dir
 	paths := []string{
@@ -61,6 +65,7 @@ func DefaultFileSearchPaths(configName string) []string {
 			filepath.Join(home, ".config", configName),
 			filepath.Join(home, "."+configName),
 			filepath.Join(home, ".local/etc"),
+			filepath.Join(home, ".local/etc", configName),
 			home,
 		}...)
 	}
@@ -69,8 +74,11 @@ func DefaultFileSearchPaths(configName string) []string {
 	paths = append(paths, []string{
 		filepath.Join("/opt", configName),
 		filepath.Join("/opt", configName, "etc"),
+		filepath.Join("/opt", configName, "etc", configName),
 		"/usr/local/etc",
+		filepath.Join("/usr/local/etc", configName),
 		"/etc",
+		filepath.Join("/etc", configName),
 	}...)
 
 	return paths

configfx/overlay.go

@@ -63,9 +63,25 @@ func (s *Overlay) applyTo(vip *viper.Viper, cfg any) error {
 	}
 
 	// retrieve the from key
-	from, ok := s.viper.AllSettings()[s.From]
-	if !ok {
-		return fmt.Errorf("referenced from field %q not found in overlay", s.From)
+	fromPath := strings.Split(s.From, ".")
+	fromSlice := s.viper.AllSettings()
+	var from any
+	for _, elem := range fromPath {
+		// retrieve path element
+		var ok bool
+		from, ok = fromSlice[elem]
+		if !ok {
+			return fmt.Errorf("referenced from field %q in path %q not found in overlay %q", elem, s.From, s.Filename)
+		}
+
+		// check if it is a map for next iter
+		if cast, ok := from.(map[string]any); ok {
+			fromSlice = cast
+		}
+	}
+	// sanity check
+	if from == nil {
+		return fmt.Errorf("referenced from path %q is nil in overlay %q", s.From, s.Filename)
 	}
 
 	for _, path := range s.To {

examples/webserver/cmd/webserver/main.go

@@ -17,12 +17,16 @@ limitations under the License.
 package main
 
 import (
+	"sync"
+
 	"go.uber.org/fx"
+	"k8s.io/utils/diff"
 
 	"github.com/choopm/stdfx"
 	"github.com/choopm/stdfx/configfx"
 	"github.com/choopm/stdfx/examples/webserver"
 	"github.com/choopm/stdfx/loggingfx/zerologfx"
+	"github.com/fsnotify/fsnotify"
 	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
 )
@@ -76,8 +80,66 @@ func serverCommand(
 			}
 			log.Logger = *logger
 
+			var server *webserver.Server
+
+			// build config options
+			opts := []configfx.ConfigOption{
+				configfx.WithOverlays(cfg.Config.Overlays...),
+			}
+			if cfg.Config.HotReload {
+				cfgSwap := sync.Mutex{}
+
+				// callback for hot-reloading of config
+				opts = append(opts, configfx.WithOnConfigChange(func(in fsnotify.Event) {
+					// we only care for config writes
+					if in.Op != fsnotify.Write {
+						return
+					}
+
+					// synchronize config swapping
+					cfgSwap.Lock()
+					defer cfgSwap.Unlock()
+
+					log.Debug().
+						Msg("config file has changed on disk - reloading config")
+
+					// re-create config with opts (overlays, config change)
+					newcfg, err := configProvider.Config(opts...)
+					if err != nil {
+						log.Error().Err(err).
+							Msg("new config file can't be parsed")
+						return
+					}
+					// check config
+					err = newcfg.Validate()
+					if err != nil {
+						log.Error().Err(err).
+							Msg("new config file has errors")
+						return
+					}
+
+					changelog := diff.ObjectReflectDiff(cfg, newcfg)
+					*cfg = *newcfg // this replaces the config
+
+					log.Info().
+						Msgf("updated config, changelog: %s", changelog)
+
+					log.Info().Msg("reconfiguring server...")
+					err = server.Reconfigure(cfg)
+					if err != nil {
+						log.Panic().Err(err).Msg("failed to reconfiguring server")
+						return
+					}
+				}))
+			}
+			// re-create config with opts (overlays, config change)
+			cfg, err = configProvider.Config(opts...)
+			if err != nil {
+				return err
+			}
+
 			// create server instance
-			server, err := webserver.NewServer(cfg, logger)
+			server, err = webserver.NewServer(cfg, logger)
 			if err != nil {
 				return err
 			}

examples/webserver/config.go

@@ -19,6 +19,7 @@ package webserver
 import (
 	"fmt"
 
+	"github.com/choopm/stdfx/configfx"
 	"github.com/choopm/stdfx/loggingfx"
 	"github.com/go-viper/mapstructure/v2"
 )
@@ -27,13 +28,21 @@ import (
 type Config struct {
 	Logging loggingfx.Config `mapstructure:"log"`
 
+	Config ConfigConfig `mapstructure:"config"`
+
 	// Webserver defines the http server config
 	Webserver WebserverConfig `mapstructure:"webserver"`
 
 	// Routes defines the webserver routes
 	Routes []*Route `mapstructure:"routes" default:"[]"`
 }
 
+// ConfigConfig struct stores all config options
+type ConfigConfig struct {
+	HotReload bool                `mapstructure:"hot-reload" default:"false"`
+	Overlays  []*configfx.Overlay `mapstructure:"overlays" default:"[]"`
+}
+
 // Validate validates the Config
 func (c *Config) Validate() error {
 	if err := c.Webserver.Validate(); err != nil {

examples/webserver/go.mod

@@ -6,21 +6,22 @@ toolchain go1.24.5
 
 require (
 	github.com/choopm/stdfx v0.1.5
+	github.com/fsnotify/fsnotify v1.9.0
 	github.com/go-viper/mapstructure/v2 v2.4.0
 	github.com/rs/zerolog v1.34.0
 	github.com/spf13/cobra v1.9.1
 	go.uber.org/fx v1.24.0
 	golang.org/x/sync v0.16.0
+	k8s.io/utils v0.0.0-20250820121507-0af2bda4dd1d
 )
 
 require (
 	github.com/creasty/defaults v1.8.0 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/earthboundkid/versioninfo/v2 v2.24.1 // indirect
-	github.com/fsnotify/fsnotify v1.9.0 // indirect
 	github.com/fxamacker/cbor/v2 v2.9.0 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
-	github.com/go-openapi/jsonpointer v0.21.1 // indirect
+	github.com/go-openapi/jsonpointer v0.21.2 // indirect
 	github.com/go-openapi/jsonreference v0.21.0 // indirect
 	github.com/go-openapi/swag v0.23.1 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
@@ -32,13 +33,13 @@ require (
 	github.com/mattn/go-colorable v0.1.14 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
-	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee // indirect
 	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
-	github.com/sagikazarmark/locafero v0.9.0 // indirect
+	github.com/sagikazarmark/locafero v0.10.0 // indirect
 	github.com/samber/lo v1.51.0 // indirect
 	github.com/samber/slog-common v0.19.0 // indirect
 	github.com/samber/slog-zerolog/v2 v2.7.3 // indirect
-	github.com/sourcegraph/conc v0.3.0 // indirect
+	github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8 // indirect
 	github.com/spf13/afero v1.14.0 // indirect
 	github.com/spf13/cast v1.9.2 // indirect
 	github.com/spf13/pflag v1.0.7 // indirect
@@ -51,18 +52,17 @@ require (
 	go.uber.org/zap v1.27.0 // indirect
 	go.yaml.in/yaml/v2 v2.4.2 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
-	golang.org/x/net v0.42.0 // indirect
-	golang.org/x/sys v0.34.0 // indirect
-	golang.org/x/text v0.27.0 // indirect
-	google.golang.org/protobuf v1.36.6 // indirect
+	golang.org/x/net v0.43.0 // indirect
+	golang.org/x/sys v0.35.0 // indirect
+	golang.org/x/text v0.28.0 // indirect
+	google.golang.org/protobuf v1.36.8 // indirect
 	gopkg.in/inf.v0 v0.9.1 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
-	k8s.io/apimachinery v0.33.3 // indirect
+	k8s.io/apimachinery v0.34.0 // indirect
 	k8s.io/klog/v2 v2.130.1 // indirect
-	k8s.io/kube-openapi v0.0.0-20250710124328-f3f2b991d03b // indirect
-	k8s.io/utils v0.0.0-20250604170112-4c0f3b243397 // indirect
-	sigs.k8s.io/json v0.0.0-20241014173422-cfa47c3a1cc8 // indirect
+	k8s.io/kube-openapi v0.0.0-20250814151709-d7b6acb124c3 // indirect
+	sigs.k8s.io/json v0.0.0-20250730193827-2d320260d730 // indirect
 	sigs.k8s.io/randfill v1.0.0 // indirect
-	sigs.k8s.io/structured-merge-diff/v4 v4.7.0 // indirect
-	sigs.k8s.io/yaml v1.5.0 // indirect
+	sigs.k8s.io/structured-merge-diff/v6 v6.3.0 // indirect
+	sigs.k8s.io/yaml v1.6.0 // indirect
 )