Refine configsource interface

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
 }