diff --git a/config/internal/configsource/component.go b/config/internal/configsource/component.go index 445b1e7b502a..c65ea9bda5c0 100644 --- a/config/internal/configsource/component.go +++ b/config/internal/configsource/component.go @@ -21,8 +21,22 @@ import ( // ErrSessionClosed is returned by WatchForUpdate functions when its parent Session // object is closed. +// This error can be wrapped with additional information. Callers trying to identify this +// specific error must use errors.Is. var ErrSessionClosed = errors.New("parent session was closed") +// ErrValueUpdated is returned by WatchForUpdate functions when the value being watched +// was changed or expired and needs to be retrieved again. +// This error can be wrapped with additional information. Callers trying to identify this +// specific error must use errors.Is. +var ErrValueUpdated = errors.New("configuration must retrieve the updated value") + +// ErrWatcherNotSupported is returned by WatchForUpdate functions when the configuration +// source can't watch for updates on the value. +// This error can be wrapped with additional information. Callers trying to identify this +// specific error must use errors.Is. +var ErrWatcherNotSupported = errors.New("value watcher is not supported") + // ConfigSource is the interface to be implemented by objects used by the collector // to retrieve external configuration information. type ConfigSource interface { @@ -67,21 +81,29 @@ type Session interface { } // Retrieved holds the result of a call to the Retrieve method of a Session object. -type Retrieved struct { +type Retrieved interface { // Value is the retrieved data that will be injected on the configuration. - Value interface{} - // WatchForUpdate must not return until one of the following happens: + Value() interface{} + + // WatchForUpdate is used to monitor for updates on the retrieved value. + // + // If a watcher is not supported by the configuration store in general or for the specific + // retrieved value the WatchForUpdate must immediately return ErrWatcherNotSupported or + // an error wrapping it. + // + // When watching is supported WatchForUpdate must not return until one of the following happens: // - // 1. An update is detected for the monitored value. + // 1. An update is detected for the monitored value. In this case the function should + // return ErrValueUpdated or an error wrapping it. // // 2. The parent Session object is closed, in which case the method should return - // ErrSessionClosed. + // ErrSessionClosed or an error wrapping it. // // 3. An error happens while watching for updates. The method should not return // on first instances of transient errors, optionally there should be // configurable thresholds to control for how long such errors can be ignored. // - // The method must return with a nil error when an update has happened to - // the value monitored by the Watcher. - WatchForUpdate func() error + // This method must only be called when the RetrieveEnd method of the Session that + // retrieved the value was successfully completed. + WatchForUpdate() error }