Add helper methods in SuccinctRoles

Add two helper methods in SuccinctRoles.
Those methods proved useful in the testing code, but I believe they have
a potential value for production code as well.

Signed-off-by: Martin Vrachev <mvrachev@vmware.com>

Author: Martin Vrachev

tests/test_api.py

@@ -35,6 +35,7 @@
     Metadata,
     Root,
     Snapshot,
+    SuccinctRoles,
     TargetFile,
     Targets,
     Timestamp,
@@ -695,6 +696,31 @@ def test_is_delegated_role(self) -> None:
             self.assertFalse(role.is_delegated_path("a/non-matching path"))
             self.assertTrue(role.is_delegated_path("a/path"))
 
+    def test_is_delegated_role_in_succinct_roles(self) -> None:
+        succinct_roles = SuccinctRoles([], 1, 5, "bin")
+        false_role_name_examples = ["foo", "bin-", "bin-s", "bin-20", "bin-100"]
+        for role_name in false_role_name_examples:
+            msg = f"Error for {role_name}"
+            self.assertFalse(succinct_roles.is_delegated_role(role_name), msg)
+
+        # delegated role name suffixes are in hex format.
+        true_name_examples = ["bin-00", "bin-0f", "bin-1f"]
+        for role_name in true_name_examples:
+            msg = f"Error for {role_name}"
+            self.assertTrue(succinct_roles.is_delegated_role(role_name), msg)
+
+    def test_get_roles_in_succinct_roles(self) -> None:
+        succinct_roles = SuccinctRoles([], 1, 16, "bin")
+        # bin names are in hex format and 4 hex digits are enough to represent
+        # all bins between 0 and 2^16 - 1 meaning suffix_len must be 4
+        expected_suffix_length = 4
+        self.assertEqual(succinct_roles.suffix_len, expected_suffix_length)
+        for bin_numer, role_name in enumerate(succinct_roles.get_roles()):
+            # This adds zero-padding if the bin_numer is represented by a hex
+            # number with a length less than expected_suffix_length.
+            expected_bin_suffix = f"{bin_numer:0{expected_suffix_length}x}"
+            self.assertEqual(role_name, f"bin-{expected_bin_suffix}")
+
 
 # Run unit test.
 if __name__ == "__main__":

tuf/api/metadata.py

@@ -39,6 +39,7 @@
     ClassVar,
     Dict,
     Generic,
+    Iterator,
     List,
     Mapping,
     Optional,
@@ -1548,6 +1549,36 @@ def get_role_for_target(self, target_filepath: str) -> str:
         suffix = f"{bin_number:0{self.suffix_len}x}"
         return f"{self.name_prefix}-{suffix}"
 
+    def get_roles(self) -> Iterator[str]:
+        """Yield the names of all different delegated roles one by one."""
+        for i in range(0, self.number_of_bins):
+            suffix = f"{i:0{self.suffix_len}x}"
+            yield f"{self.name_prefix}-{suffix}"
+
+    def is_delegated_role(self, role_name: str) -> bool:
+        """Determines whether the given ``role_name`` is in one of
+        the delegated roles that ``SuccinctRoles`` represents.
+
+        Args:
+            role_name: The name of the role to check against.
+        """
+        desired_prefix = self.name_prefix + "-"
+
+        if not role_name.startswith(desired_prefix):
+            return False
+
+        suffix = role_name[len(desired_prefix) :]
+        if len(suffix) != self.suffix_len:
+            return False
+
+        try:
+            # make sure suffix is hex value
+            num = int(suffix, 16)
+        except ValueError:
+            return False
+
+        return 0 <= num < self.number_of_bins
+
 
 class Delegations:
     """A container object storing information about all delegations.