core: Config LoadInterval -> LoadDelay for clarity

And improve/clarify docs about this feature

See #4577

2 files changed, 19 insertions, 13 deletions

diff --git a/admin.go b/admin.go
index 33bb5c6..891f818 100644
--- a/admin.go
+++ b/admin.go
@@ -101,20 +101,26 @@ type ConfigSettings struct {
 	// are not persisted; only configs that are pushed to Caddy get persisted.
 	Persist *bool `json:"persist,omitempty"`
 
-	// Loads a configuration to use. This is helpful if your configs are
-	// managed elsewhere, and you want Caddy to pull its config dynamically
+	// Loads a new configuration. This is helpful if your configs are
+	// managed elsewhere and you want Caddy to pull its config dynamically
 	// when it starts. The pulled config completely replaces the current
 	// one, just like any other config load. It is an error if a pulled
-	// config is configured to pull another config.
+	// config is configured to pull another config without a load_delay,
+	// as this creates a tight loop.
 	//
 	// EXPERIMENTAL: Subject to change.
 	LoadRaw json.RawMessage `json:"load,omitempty" caddy:"namespace=caddy.config_loaders inline_key=module"`
 
-	// The interval to pull config. With a non-zero value, will pull config
-	// from config loader (eg. a http loader) with given interval.
+	// The duration after which to load config. If set, config will be pulled
+	// from the config loader after this duration. A delay is required if a
+	// dynamically-loaded config is configured to load yet another config. To
+	// load configs on a regular interval, ensure this value is set the same
+	// on all loaded configs; it can also be variable if needed, and to stop
+	// the loop, simply remove dynamic config loading from the next-loaded
+	// config.
 	//
 	// EXPERIMENTAL: Subject to change.
-	LoadInterval Duration `json:"load_interval,omitempty"`
+	LoadDelay Duration `json:"load_delay,omitempty"`
 }
 
 // IdentityConfig configures management of this server's identity. An identity
diff --git a/caddy.go b/caddy.go
index 81f80e8..127484d 100644
--- a/caddy.go
+++ b/caddy.go
@@ -268,8 +268,8 @@ func unsyncedDecodeAndRun(cfgJSON []byte, allowPersist bool) error {
 		newCfg.Admin != nil &&
 		newCfg.Admin.Config != nil &&
 		newCfg.Admin.Config.LoadRaw != nil &&
-		newCfg.Admin.Config.LoadInterval <= 0 {
-		return fmt.Errorf("recursive config loading detected: pulled configs cannot pull other configs without positive load_interval")
+		newCfg.Admin.Config.LoadDelay <= 0 {
+		return fmt.Errorf("recursive config loading detected: pulled configs cannot pull other configs without positive load_delay")
 	}
 
 	// run the new config and start all its apps
@@ -483,7 +483,7 @@ func finishSettingUp(ctx Context, cfg *Config) error {
 
 		logger := Log().Named("config_loader").With(
 			zap.String("module", val.(Module).CaddyModule().ID.Name()),
-			zap.Int("pull_interval", int(cfg.Admin.Config.LoadInterval)))
+			zap.Int("load_delay", int(cfg.Admin.Config.LoadDelay)))
 
 		runLoadedConfig := func(config []byte) {
 			logger.Info("applying dynamically-loaded config")
@@ -495,9 +495,9 @@ func finishSettingUp(ctx Context, cfg *Config) error {
 			}
 		}
 
-		if cfg.Admin.Config.LoadInterval > 0 {
+		if cfg.Admin.Config.LoadDelay > 0 {
 			go func() {
-				timer := time.NewTimer(time.Duration(cfg.Admin.Config.LoadInterval))
+				timer := time.NewTimer(time.Duration(cfg.Admin.Config.LoadDelay))
 				select {
 				case <-timer.C:
 					loadedConfig, err := val.(ConfigLoader).LoadConfig(ctx)
@@ -510,11 +510,11 @@ func finishSettingUp(ctx Context, cfg *Config) error {
 					if !timer.Stop() {
 						<-timer.C
 					}
-					Log().Info("stopping config load interval")
+					Log().Info("stopping dynamic config loading")
 				}
 			}()
 		} else {
-			// if no LoadInterval is provided, will load config synchronously
+			// if no LoadDelay is provided, will load config synchronously
 			loadedConfig, err := val.(ConfigLoader).LoadConfig(ctx)
 			if err != nil {
 				return fmt.Errorf("loading dynamic config from %T: %v", val, err)