improve docs

config/config.go

@@ -83,6 +83,13 @@ var (
 	defaultRedisURL, _          = ct.NewOptURLAbsoluteFromString("redis://localhost:6379")       //nolint:gochecknoglobals
 )
 
+const (
+	// This minimum value was chosen not as a recommendation, but more to protect the host system from thousands of syscalls +
+	// the CPU time it takes to read the archive over and over again. It is somewhat arbitrary.
+	// It likely doesn't make sense to use an interval this frequent in production use-cases.
+	minimumFileDataSourceMonitoringInterval = 100 * time.Millisecond
+)
+
 // DefaultLoggers is the default logging configuration used by Relay.
 //
 // Output goes to stdout, except Error level which goes to stderr. Debug level is disabled.

config/config_validation.go

@@ -3,11 +3,9 @@ package config
 import (
 	"errors"
 	"fmt"
-	"strings"
-	"time"
-
 	ct "github.com/launchdarkly/go-configtypes"
 	"github.com/launchdarkly/go-sdk-common/v3/ldlog"
+	"strings"
 )
 
 var (
@@ -19,12 +17,12 @@ var (
 	errOfflineModeWithEnvironments     = errors.New("cannot configure specific environments if offline mode is enabled")
 	errAutoConfWithoutDBDisambig       = errors.New(`when using auto-configuration with database storage, database prefix (or,` +
 		` if using DynamoDB, table name) must be specified and must contain "` + AutoConfigEnvironmentIDPlaceholder + `"`)
-	errRedisURLWithHostAndPort           = errors.New("please specify Redis URL or host/port, but not both")
-	errRedisBadHostname                  = errors.New("invalid Redis hostname")
-	errConsulTokenAndTokenFile           = errors.New("Consul token must be specified as either an inline value or a file, but not both") //nolint:stylecheck
-	errAutoConfWithFilters               = errors.New("cannot configure filters if auto-configuration is enabled")
-	errMissingProjKey                    = errors.New("when filters are configured, all environments must specify a 'projKey'")
-	errInvalidFileDataSourcePollInterval = errors.New("file data source poll interval must be at least 100ms")
+	errRedisURLWithHostAndPort                 = errors.New("please specify Redis URL or host/port, but not both")
+	errRedisBadHostname                        = errors.New("invalid Redis hostname")
+	errConsulTokenAndTokenFile                 = errors.New("Consul token must be specified as either an inline value or a file, but not both") //nolint:stylecheck
+	errAutoConfWithFilters                     = errors.New("cannot configure filters if auto-configuration is enabled")
+	errMissingProjKey                          = errors.New("when filters are configured, all environments must specify a 'projKey'")
+	errInvalidFileDataSourceMonitoringInterval = fmt.Errorf("file data source monitoring interval must be >= %s", minimumFileDataSourceMonitoringInterval)
 )
 
 func errEnvironmentWithNoSDKKey(envName string) error {
@@ -191,8 +189,8 @@ func validateConfigFilters(result *ct.ValidationResult, c *Config) {
 func validateOfflineMode(result *ct.ValidationResult, c *Config) {
 	if c.OfflineMode.FileDataSourceMonitoringInterval.IsDefined() {
 		interval := c.OfflineMode.FileDataSourceMonitoringInterval.GetOrElse(0)
-		if interval < 100*time.Millisecond {
-			result.AddError(nil, errInvalidFileDataSourcePollInterval)
+		if interval < minimumFileDataSourceMonitoringInterval {
+			result.AddError(nil, errInvalidFileDataSourceMonitoringInterval)
 		}
 	}
 }

internal/filedata/archive_manager.go

@@ -11,8 +11,10 @@ import (
 )
 
 const (
+	// This value was chosen as a default after switching from file-watcher event-based monitoring to simple polling.
+	// This idea is that polling should react fairly quickly to changes, just as the event-based system did to preserve
+	// any use-cases that relied on it. In practice, much longer intervals could likely be chosen.
 	defaultMonitoringInterval = 1 * time.Second
-	maxRetryDuration          = time.Second * 2
 )
 
 // ArchiveManager manages the file data source.
@@ -73,7 +75,7 @@ func NewArchiveManager(
 	defer ar.Close()
 
 	am.updatedArchive(ar)
-	go am.monitorForChangesByPolling(fileInfo)
+	go am.monitorForChanges(fileInfo)
 
 	return am, nil
 }
@@ -86,7 +88,7 @@ func (am *ArchiveManager) Close() error {
 	return nil
 }
 
-func (am *ArchiveManager) monitorForChangesByPolling(original os.FileInfo) {
+func (am *ArchiveManager) monitorForChanges(original os.FileInfo) {
 	ticker := time.NewTicker(am.monitoringInterval)
 	defer ticker.Stop()
 

internal/filedata/archive_manager_test_base_test.go

@@ -18,7 +18,7 @@ import (
 )
 
 const (
-	testPollInterval = time.Millisecond * 100
+	testMonitoringInterval = time.Millisecond * 10
 )
 
 type archiveManagerTestParams struct {
@@ -61,7 +61,7 @@ func archiveManagerTest(t *testing.T, setupFile func(filePath string), action fu
 		archiveManager, err := NewArchiveManager(
 			filePath,
 			messageHandler,
-			testPollInterval,
+			testMonitoringInterval,
 			mockLog.Loggers,
 		)
 		if archiveManager != nil {

relay/filedata_actions_test.go

@@ -73,7 +73,7 @@ func offlineModeTest(
 	relay, err := newRelayInternal(config, relayInternalOptions{
 		loggers:       mockLog.Loggers,
 		clientFactory: testclient.RealLDClientFactoryWithChannel(true, clientsCreatedCh),
-		archiveManagerFactory: func(filename string, handler filedata.UpdateHandler, loggers ldlog.Loggers) (
+		archiveManagerFactory: func(filename string, monitoringInterval time.Duration, handler filedata.UpdateHandler, loggers ldlog.Loggers) (
 			filedata.ArchiveManagerInterface, error) {
 			p.updateHandler = handler
 			return stubArchiveManager{}, nil