Rename RepositoryError to MetadataError

RepositoryErrors are errors that could be thrown not only in the
future repository code, but in the client as well.
For example the Updater.referesh(), Updater.get_targetinfo()
and Updater.download_target() API calls all throw RepositoryError
exception.
This could be seen as strange behavior from the user who will
use the client code.
That's why it makes sense to rename this error to something more
generic as "MetadataError" which will denote errors from the
client as well as from the repository.

Signed-off-by: Martin Vrachev <[email protected]>

Author: MVrachev

examples/client_example/client_example.py

@@ -10,7 +10,7 @@
 import shutil
 from pathlib import Path
 
-from tuf.api.exceptions import RepositoryError
+from tuf.api.exceptions import MetadataError
 from tuf.ngclient import Updater
 
 # constants
@@ -73,7 +73,7 @@ def download(target: str) -> bool:
         path = updater.download_target(info)
         print(f"Target downloaded and available in {path}")
 
-    except (OSError, RepositoryError) as e:
+    except (OSError, MetadataError) as e:
         print(str(e))
         return False
 

tests/test_trusted_metadata_set.py

@@ -192,7 +192,7 @@ def test_root_with_invalid_json(self) -> None:
         # Test loading initial root and root update
         for test_func in [TrustedMetadataSet, self.trusted_set.update_root]:
             # root is not json
-            with self.assertRaises(exceptions.RepositoryError):
+            with self.assertRaises(exceptions.MetadataError):
                 test_func(b"")
 
             # root is invalid
@@ -202,7 +202,7 @@ def test_root_with_invalid_json(self) -> None:
                 test_func(root.to_bytes())
 
             # metadata is of wrong type
-            with self.assertRaises(exceptions.RepositoryError):
+            with self.assertRaises(exceptions.MetadataError):
                 test_func(self.metadata[Snapshot.type])
 
     def test_top_level_md_with_invalid_json(self) -> None:
@@ -214,7 +214,7 @@ def test_top_level_md_with_invalid_json(self) -> None:
         for metadata, update_func in top_level_md:
             md = Metadata.from_bytes(metadata)
             # metadata is not json
-            with self.assertRaises(exceptions.RepositoryError):
+            with self.assertRaises(exceptions.MetadataError):
                 update_func(b"")
 
             # metadata is invalid
@@ -223,7 +223,7 @@ def test_top_level_md_with_invalid_json(self) -> None:
                 update_func(md.to_bytes())
 
             # metadata is of wrong type
-            with self.assertRaises(exceptions.RepositoryError):
+            with self.assertRaises(exceptions.MetadataError):
                 update_func(self.metadata[Root.type])
 
             update_func(metadata)
@@ -305,7 +305,7 @@ def modify_snapshot_length(timestamp: Timestamp) -> None:
         timestamp = self.modify_metadata(Timestamp.type, modify_snapshot_length)
         self.trusted_set.update_timestamp(timestamp)
 
-        with self.assertRaises(exceptions.RepositoryError):
+        with self.assertRaises(exceptions.MetadataError):
             self.trusted_set.update_snapshot(self.metadata[Snapshot.type])
 
     def test_update_snapshot_fail_threshold_verification(self) -> None:
@@ -342,7 +342,7 @@ def remove_file_from_meta(snapshot: Snapshot) -> None:
 
         # Test removing a meta_file in new_snapshot compared to the old snapshot
         snapshot = self.modify_metadata(Snapshot.type, remove_file_from_meta)
-        with self.assertRaises(exceptions.RepositoryError):
+        with self.assertRaises(exceptions.MetadataError):
             self.trusted_set.update_snapshot(snapshot)
 
     def test_update_snapshot_meta_version_decreases(self) -> None:
@@ -405,7 +405,7 @@ def no_meta_modifier(snapshot: Snapshot) -> None:
             self.metadata[Timestamp.type], snapshot
         )
         # remove meta information with information about targets from snapshot
-        with self.assertRaises(exceptions.RepositoryError):
+        with self.assertRaises(exceptions.MetadataError):
             self.trusted_set.update_targets(self.metadata[Targets.type])
 
     def test_update_targets_hash_diverge_from_snapshot_meta_hash(self) -> None:
@@ -418,7 +418,7 @@ def meta_length_modifier(snapshot: Snapshot) -> None:
             self.metadata[Timestamp.type], snapshot
         )
         # observed_hash != stored hash in snapshot meta for targets
-        with self.assertRaises(exceptions.RepositoryError):
+        with self.assertRaises(exceptions.MetadataError):
             self.trusted_set.update_targets(self.metadata[Targets.type])
 
     def test_update_targets_version_diverge_snapshot_meta_version(self) -> None:

tests/test_updater_fetch_target.py

@@ -15,7 +15,7 @@
 
 from tests import utils
 from tests.repository_simulator import RepositorySimulator
-from tuf.api.exceptions import RepositoryError
+from tuf.api.exceptions import MetadataError
 from tuf.ngclient import Updater
 
 
@@ -135,12 +135,12 @@ def test_invalid_target_download(self) -> None:
 
         # Corrupt the file content to not match the hash
         self.sim.target_files[target.path].data = b"conten@"
-        with self.assertRaises(RepositoryError):
+        with self.assertRaises(MetadataError):
             updater.download_target(info)
 
         # Corrupt the file content to not match the length
         self.sim.target_files[target.path].data = b"cont"
-        with self.assertRaises(RepositoryError):
+        with self.assertRaises(MetadataError):
             updater.download_target(info)
 
         # Verify the file is not persisted in cache

tests/test_updater_ng.py

@@ -295,11 +295,11 @@ def test_length_hash_mismatch(self) -> None:
         assert isinstance(targetinfo, TargetFile)
 
         length = targetinfo.length
-        with self.assertRaises(exceptions.RepositoryError):
+        with self.assertRaises(exceptions.MetadataError):
             targetinfo.length = 44
             self.updater.download_target(targetinfo)
 
-        with self.assertRaises(exceptions.RepositoryError):
+        with self.assertRaises(exceptions.MetadataError):
             targetinfo.length = length
             targetinfo.hashes = {"sha256": "abcd"}
             self.updater.download_target(targetinfo)

tests/test_updater_top_level_update.py

@@ -19,7 +19,7 @@
 from tuf.api.exceptions import (
     BadVersionNumberError,
     ExpiredMetadataError,
-    RepositoryError,
+    MetadataError,
     UnsignedMetadataError,
 )
 from tuf.api.metadata import (
@@ -389,7 +389,7 @@ def test_new_snapshot_hash_mismatch(self) -> None:
         self.sim.timestamp.version += 1  # timestamp v3
 
         # Hash mismatch error
-        with self.assertRaises(RepositoryError):
+        with self.assertRaises(MetadataError):
             self._run_refresh()
 
         self._assert_version_equals(Timestamp.type, 3)
@@ -495,7 +495,7 @@ def test_new_targets_hash_mismatch(self) -> None:
         self.sim.snapshot.version += 1
         self.sim.update_timestamp()
 
-        with self.assertRaises(RepositoryError):
+        with self.assertRaises(MetadataError):
             self._run_refresh()
 
         self._assert_version_equals(Snapshot.type, 3)

tuf/api/exceptions.py

@@ -15,31 +15,30 @@
 # pylint: disable=unused-import
 from securesystemslib.exceptions import UnsupportedAlgorithmError
 
-
-class LengthOrHashMismatchError(Exception):
-    """An error while checking the length and hash values of an object."""
-
-
-#### Repository errors ####
+#### MetadataError errors ####
 
 
-class RepositoryError(Exception):
+class MetadataError(Exception):
     """An error with a repository's state, such as a missing file."""
 
 
-class UnsignedMetadataError(RepositoryError):
+class UnsignedMetadataError(MetadataError):
     """An error about metadata object with insufficient threshold of
     signatures."""
 
 
-class BadVersionNumberError(RepositoryError):
+class BadVersionNumberError(MetadataError):
     """An error for metadata that contains an invalid version number."""
 
 
-class ExpiredMetadataError(RepositoryError):
+class ExpiredMetadataError(MetadataError):
     """Indicate that a TUF Metadata file has expired."""
 
 
+class LengthOrHashMismatchError(MetadataError):
+    """An error while checking the length and hash values of an object."""
+
+
 #### Download Errors ####
 
 

tuf/ngclient/_internal/trusted_metadata_set.py

@@ -30,7 +30,7 @@
 
 Example of loading root, timestamp and snapshot:
 
->>> # Load local root (RepositoryErrors here stop the update)
+>>> # Load local root (MetadataError here stop the update)
 >>> with open(root_path, "rb") as f:
 >>>     trusted_set = TrustedMetadataSet(f.read())
 >>>
@@ -42,7 +42,7 @@
 >>> try:
 >>>     with open(timestamp_path, "rb") as f:
 >>>         trusted_set.update_timestamp(f.read())
->>> except (RepositoryError, OSError):
+>>> except (MetadataError, OSError):
 >>>     pass # failure to load a local file is ok
 >>>
 >>> with download(Timestamp.type) as f:
@@ -52,15 +52,15 @@
 >>> try:
 >>>     with open(snapshot_path, "rb") as f:
 >>>         trusted_set.update_snapshot(f.read())
->>> except (RepositoryError, OSError):
+>>> except (MetadataError, OSError):
 >>>     # local snapshot is not valid, load from remote
->>>     # (RepositoryErrors here stop the update)
+>>>     # (MetadataError here stop the update)
 >>>     with download(Snapshot.type, version) as f:
 >>>         trusted_set.update_snapshot(f.read())
 
 TODO:
  * exceptions are not final: the idea is that client could just handle
-   a generic RepositoryError that covers every issue that server provided
+   a generic MetadataError that covers every issue that server provided
    metadata could inflict (other errors would be user errors), but this is not
    yet the case
  * Progress through Specification update process should be documented
@@ -96,7 +96,7 @@ def __init__(self, root_data: bytes):
                 all metadata in the TrustedMetadataSet
 
         Raises:
-            RepositoryError: Metadata failed to load or verify. The actual
+            MetadataVerificationError: Metadata failed to load or verify. The actual
                 error type and content will contain more details.
         """
         self._trusted_set: Dict[str, Metadata] = {}
@@ -151,7 +151,7 @@ def update_root(self, data: bytes) -> Metadata[Root]:
             data: unverified new root metadata as bytes
 
         Raises:
-            RepositoryError: Metadata failed to load or verify. The actual
+            MetadataError: Metadata failed to load or verify. The actual
                 error type and content will contain more details.
 
         Returns:
@@ -164,10 +164,10 @@ def update_root(self, data: bytes) -> Metadata[Root]:
         try:
             new_root = Metadata[Root].from_bytes(data)
         except DeserializationError as e:
-            raise exceptions.RepositoryError("Failed to load root") from e
+            raise exceptions.MetadataError("Failed to load root") from e
 
         if new_root.signed.type != Root.type:
-            raise exceptions.RepositoryError(
+            raise exceptions.MetadataError(
                 f"Expected 'root', got '{new_root.signed.type}'"
             )
 
@@ -202,7 +202,7 @@ def update_timestamp(self, data: bytes) -> Metadata[Timestamp]:
             data: unverified new timestamp metadata as bytes
 
         Raises:
-            RepositoryError: Metadata failed to load or verify as final
+            MetadataError: Metadata failed to load or verify as final
                 timestamp. The actual error type and content will contain
                 more details.
 
@@ -221,10 +221,10 @@ def update_timestamp(self, data: bytes) -> Metadata[Timestamp]:
         try:
             new_timestamp = Metadata[Timestamp].from_bytes(data)
         except DeserializationError as e:
-            raise exceptions.RepositoryError("Failed to load timestamp") from e
+            raise exceptions.MetadataError("Failed to load timestamp") from e
 
         if new_timestamp.signed.type != Timestamp.type:
-            raise exceptions.RepositoryError(
+            raise exceptions.MetadataError(
                 f"Expected 'timestamp', got '{new_timestamp.signed.type}'"
             )
 
@@ -288,7 +288,7 @@ def update_snapshot(
                 match data. Default is False.
 
         Raises:
-            RepositoryError: data failed to load or verify as final snapshot.
+            MetadataError: data failed to load or verify as final snapshot.
                 The actual error type and content will contain more details.
 
         Returns:
@@ -312,17 +312,17 @@ def update_snapshot(
             try:
                 snapshot_meta.verify_length_and_hashes(data)
             except exceptions.LengthOrHashMismatchError as e:
-                raise exceptions.RepositoryError(
+                raise exceptions.MetadataError(
                     "Snapshot length or hashes do not match"
                 ) from e
 
         try:
             new_snapshot = Metadata[Snapshot].from_bytes(data)
         except DeserializationError as e:
-            raise exceptions.RepositoryError("Failed to load snapshot") from e
+            raise exceptions.MetadataError("Failed to load snapshot") from e
 
         if new_snapshot.signed.type != Snapshot.type:
-            raise exceptions.RepositoryError(
+            raise exceptions.MetadataError(
                 f"Expected 'snapshot', got '{new_snapshot.signed.type}'"
             )
 
@@ -338,7 +338,7 @@ def update_snapshot(
 
                 # Prevent removal of any metadata in meta
                 if new_fileinfo is None:
-                    raise exceptions.RepositoryError(
+                    raise exceptions.MetadataError(
                         f"New snapshot is missing info for '{filename}'"
                     )
 
@@ -381,7 +381,7 @@ def update_targets(self, data: bytes) -> Metadata[Targets]:
             data: unverified new targets metadata as bytes
 
         Raises:
-            RepositoryError: Metadata failed to load or verify. The actual
+            MetadataError: Metadata failed to load or verify. The actual
                 error type and content will contain more details.
 
         Returns:
@@ -400,7 +400,7 @@ def update_delegated_targets(
             delegator_name: The name of the role delegating to the new metadata
 
         Raises:
-            RepositoryError: Metadata failed to load or verify. The actual
+            MetadataError: Metadata failed to load or verify. The actual
                 error type and content will contain more details.
 
         Returns:
@@ -422,24 +422,24 @@ def update_delegated_targets(
         # Verify against the hashes in snapshot, if any
         meta = self.snapshot.signed.meta.get(f"{role_name}.json")
         if meta is None:
-            raise exceptions.RepositoryError(
+            raise exceptions.MetadataError(
                 f"Snapshot does not contain information for '{role_name}'"
             )
 
         try:
             meta.verify_length_and_hashes(data)
         except exceptions.LengthOrHashMismatchError as e:
-            raise exceptions.RepositoryError(
+            raise exceptions.MetadataError(
                 f"{role_name} length or hashes do not match"
             ) from e
 
         try:
             new_delegate = Metadata[Targets].from_bytes(data)
         except DeserializationError as e:
-            raise exceptions.RepositoryError("Failed to load snapshot") from e
+            raise exceptions.MetadataError("Failed to load snapshot") from e
 
         if new_delegate.signed.type != Targets.type:
-            raise exceptions.RepositoryError(
+            raise exceptions.MetadataError(
                 f"Expected 'targets', got '{new_delegate.signed.type}'"
             )
 
@@ -468,10 +468,10 @@ def _load_trusted_root(self, data: bytes) -> None:
         try:
             new_root = Metadata[Root].from_bytes(data)
         except DeserializationError as e:
-            raise exceptions.RepositoryError("Failed to load root") from e
+            raise exceptions.MetadataError("Failed to load root") from e
 
         if new_root.signed.type != Root.type:
-            raise exceptions.RepositoryError(
+            raise exceptions.MetadataError(
                 f"Expected 'root', got '{new_root.signed.type}'"
             )