feat: enable Refresh() to be called multiple times

Allow Refresh() to be called multiple times during the lifetime of an
Updater by removing workflow guards that prevented re-updating metadata
after dependent metadata was loaded.

The Update* methods in TrustedMetadata already handle atomic updates,
version checking, and rollback protection. The guards were only needed
to enforce workflow order within a single refresh cycle, but prevented
multiple refresh cycles.

This enables long-running processes to periodically refresh metadata
without creating new Updater instances. Updates are atomic and
thread-safe - metadata is never cleared, only replaced after validation.

Fixes #593

Author: kipz

metadata/trustedmetadata/trustedmetadata.go

@@ -57,9 +57,6 @@ func New(rootData []byte) (*TrustedMetadata, error) {
 func (trusted *TrustedMetadata) UpdateRoot(rootData []byte) (*metadata.Metadata[metadata.RootType], error) {
 	log := metadata.GetLogger()
 
-	if trusted.Timestamp != nil {
-		return nil, &metadata.ErrRuntime{Msg: "cannot update root after timestamp"}
-	}
 	log.Info("Updating root")
 	// generate root metadata
 	newRoot, err := metadata.Root().FromBytes(rootData)
@@ -99,9 +96,6 @@ func (trusted *TrustedMetadata) UpdateRoot(rootData []byte) (*metadata.Metadata[
 func (trusted *TrustedMetadata) UpdateTimestamp(timestampData []byte) (*metadata.Metadata[metadata.TimestampType], error) {
 	log := metadata.GetLogger()
 
-	if trusted.Snapshot != nil {
-		return nil, &metadata.ErrRuntime{Msg: "cannot update timestamp after snapshot"}
-	}
 	// client workflow 5.3.10: Make sure final root is not expired.
 	if trusted.Root.Signed.IsExpired(trusted.RefTime) {
 		// no need to check for 5.3.11 (fast forward attack recovery):
@@ -178,9 +172,6 @@ func (trusted *TrustedMetadata) UpdateSnapshot(snapshotData []byte, isTrusted bo
 	if trusted.Timestamp == nil {
 		return nil, &metadata.ErrRuntime{Msg: "cannot update snapshot before timestamp"}
 	}
-	if trusted.Targets[metadata.TARGETS] != nil {
-		return nil, &metadata.ErrRuntime{Msg: "cannot update snapshot after targets"}
-	}
 	log.Info("Updating snapshot")
 
 	// snapshot cannot be loaded if final timestamp is expired

metadata/trustedmetadata/trustedmetadata_test.go

@@ -227,9 +227,10 @@ func TestOutOfOrderOps(t *testing.T) {
 	_, err = trustedSet.UpdateTimestamp(allRoles[metadata.TIMESTAMP])
 	assert.NoError(t, err)
 
-	// Update root after timestamp
+	// Update root after timestamp is now allowed (for multiple Refresh() calls)
+	// but will fail due to version number check (expects v2, has v1)
 	_, err = trustedSet.UpdateRoot(allRoles[metadata.ROOT])
-	assert.ErrorIs(t, err, &metadata.ErrRuntime{Msg: "cannot update root after timestamp"})
+	assert.ErrorIs(t, err, &metadata.ErrBadVersionNumber{Msg: "bad version number, expected 2, got 1"})
 
 	// Update targets before snapshot
 	_, err = trustedSet.UpdateTargets(allRoles[metadata.TARGETS])
@@ -238,9 +239,10 @@ func TestOutOfOrderOps(t *testing.T) {
 	_, err = trustedSet.UpdateSnapshot(allRoles[metadata.SNAPSHOT], false)
 	assert.NoError(t, err)
 
-	// Update timestamp after snapshot
+	// Update timestamp after snapshot is now allowed (for multiple Refresh() calls)
+	// and will succeed since versions are equal
 	_, err = trustedSet.UpdateTimestamp(allRoles[metadata.TIMESTAMP])
-	assert.ErrorIs(t, err, &metadata.ErrRuntime{Msg: "cannot update timestamp after snapshot"})
+	assert.ErrorIs(t, err, &metadata.ErrEqualVersionNumber{Msg: "new timestamp version 1 equals the old one 1"})
 
 	// Update delegated targets before targets
 	_, err = trustedSet.UpdateDelegatedTargets(allRoles["role1"], "role1", metadata.TARGETS)
@@ -249,9 +251,10 @@ func TestOutOfOrderOps(t *testing.T) {
 	_, err = trustedSet.UpdateTargets(allRoles[metadata.TARGETS])
 	assert.NoError(t, err)
 
-	//  Update snapshot after sucessful targets update
+	//  Update snapshot after targets is now allowed (for multiple Refresh() calls)
+	// and will succeed since versions are equal
 	_, err = trustedSet.UpdateSnapshot(allRoles[metadata.SNAPSHOT], false)
-	assert.ErrorIs(t, err, &metadata.ErrRuntime{Msg: "cannot update snapshot after targets"})
+	assert.NoError(t, err)
 
 	_, err = trustedSet.UpdateDelegatedTargets(allRoles["role1"], "role1", metadata.TARGETS)
 	assert.NoError(t, err)

metadata/updater/updater.go

@@ -102,7 +102,9 @@ func New(config *config.UpdaterConfig) (*Updater, error) {
 // Downloads, verifies, and loads metadata for the top-level roles in the
 // specified order (root -> timestamp -> snapshot -> targets) implementing
 // all the checks required in the TUF client workflow.
-// A Refresh() can be done only once during the lifetime of an Updater.
+// Refresh() can be called multiple times during the lifetime of an Updater
+// to ensure that the metadata is up-to-date. Each call will reload the
+// timestamp, snapshot, and targets metadata while preserving the root metadata.
 // If Refresh() has not been explicitly called before the first
 // GetTargetInfo() call, it will be done implicitly at that time.
 // The metadata for delegated roles is not updated by Refresh():
@@ -135,6 +137,9 @@ func (update *Updater) onlineRefresh() error {
 	if err != nil {
 		return err
 	}
+	// Remove the targets entry to allow re-loading during multiple Refresh() calls
+	// while still preventing redundant loads during GetTargetInfo()
+	delete(update.trusted.Targets, metadata.TARGETS)
 	_, err = update.loadTargets(metadata.TARGETS, metadata.ROOT)
 	if err != nil {
 		return err
@@ -313,12 +318,16 @@ func (update *Updater) loadTimestamp() error {
 			if errors.Is(err, &metadata.ErrRepository{}) {
 				// local timestamp is not valid, proceed downloading from remote; note that this error type includes several other subset errors
 				log.Info("Local timestamp is not valid")
+			} else if errors.Is(err, &metadata.ErrEqualVersionNumber{}) {
+				// local timestamp version equals current trusted version, proceed to check remote for updates
+				log.Info("Local timestamp version equals trusted version")
 			} else {
 				// another error
 				return err
 			}
+		} else {
+			log.Info("Local timestamp is valid")
 		}
-		log.Info("Local timestamp is valid")
 		// all okay, local timestamp exists and it is valid, nevertheless proceed with downloading from remote
 	}
 	// load from remote (whether local load succeeded or not)
@@ -368,12 +377,12 @@ func (update *Updater) loadSnapshot() error {
 			}
 		} else {
 			// this means snapshot verification/loading succeeded
-			log.Info("Local snapshot is valid: not downloading new one")
-			return nil
+			log.Info("Local snapshot is valid")
+			// Continue to check remote for potential updates
 		}
 	}
-	// local snapshot does not exist or is invalid, update from remote
-	log.Info("Failed to load local snapshot")
+	// check remote for updates (whether local load succeeded or not)
+	log.Info("Checking remote for snapshot updates")
 	if update.trusted.Timestamp == nil {
 		return fmt.Errorf("trusted timestamp not set")
 	}
@@ -422,7 +431,7 @@ func (update *Updater) loadTargets(roleName, parentName string) (*metadata.Metad
 		log.Info("Local role does not exist", "role", roleName)
 	} else {
 		// successfully read a local targets metadata, so let's try to verify and load it to the trusted metadata set
-		delegatedTargets, err := update.trusted.UpdateDelegatedTargets(data, roleName, parentName)
+		_, err := update.trusted.UpdateDelegatedTargets(data, roleName, parentName)
 		if err != nil {
 			// this means targets verification/loading failed
 			if errors.Is(err, &metadata.ErrRepository{}) {
@@ -434,12 +443,12 @@ func (update *Updater) loadTargets(roleName, parentName string) (*metadata.Metad
 			}
 		} else {
 			// this means targets verification/loading succeeded
-			log.Info("Local role is valid: not downloading new one", "role", roleName)
-			return delegatedTargets, nil
+			log.Info("Local role is valid", "role", roleName)
+			// Continue to check remote for potential updates
 		}
 	}
-	// local "roleName" does not exist or is invalid, update from remote
-	log.Info("Failed to load local role", "role", roleName)
+	// check remote for updates (whether local load succeeded or not)
+	log.Info("Checking remote for role updates", "role", roleName)
 	if update.trusted.Snapshot == nil {
 		return nil, fmt.Errorf("trusted snapshot not set")
 	}