Metadata API: include target name in targetfile

Currently, TargetFile instances do not contain the filename of the file
they represent. The API itself does not need it but it could be useful
for users of the API.

As an example, the current client returns a dict for
get_one_valid_targetinfo(): that dict contains a filepath field and
a targetinfo field (essentially TargetFile).
We would like to keep a similar API, but avoid hand-crafted dicts.
It would be much nicer to return a TargetFile that would contain the
full "metadata" of the targetfile.

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

Author: MVrachev

tuf/api/metadata.py

@@ -1085,13 +1085,15 @@ class TargetFile(BaseFile):
     Attributes:
         length: An integer indicating the length of the target file.
         hashes: A dictionary of hash algorithm names to hash values.
+        targetname: An optional string denoting the target file name.
         unrecognized_fields: Dictionary of all unrecognized fields.
     """
 
     def __init__(
         self,
         length: int,
         hashes: Dict[str, str],
+        targetname: Optional[str] = None,
         unrecognized_fields: Optional[Mapping[str, Any]] = None,
     ) -> None:
 
@@ -1100,20 +1102,23 @@ def __init__(
 
         self.length = length
         self.hashes = hashes
+        self.targetname = targetname
         self.unrecognized_fields = unrecognized_fields or {}
 
     @property
     def custom(self) -> Any:
         return self.unrecognized_fields.get("custom", None)
 
     @classmethod
-    def from_dict(cls, target_dict: Dict[str, Any]) -> "TargetFile":
+    def from_dict(
+        cls, target_dict: Dict[str, Any], targetname: Optional[str] = None
+    ) -> "TargetFile":
         """Creates TargetFile object from its dict representation."""
         length = target_dict.pop("length")
         hashes = target_dict.pop("hashes")
 
         # All fields left in the target_dict are unrecognized.
-        return cls(length, hashes, target_dict)
+        return cls(length, hashes, targetname, target_dict)
 
     def to_dict(self) -> Dict[str, Any]:
         """Returns the JSON-serializable dictionary representation of self."""

tuf/ngclient/updater.py

@@ -61,13 +61,14 @@
 import fnmatch
 import logging
 import os
-from typing import Any, Dict, List, Optional
+from typing import Dict, List, Optional
 from urllib import parse
 
 from securesystemslib import hash as sslib_hash
 from securesystemslib import util as sslib_util
 
 from tuf import exceptions
+from tuf.api.metadata import TargetFile
 from tuf.ngclient._internal import requests_fetcher, trusted_metadata_set
 from tuf.ngclient.config import UpdaterConfig
 from tuf.ngclient.fetcher import FetcherInterface
@@ -143,8 +144,8 @@ def refresh(self) -> None:
         self._load_snapshot()
         self._load_targets("targets", "root")
 
-    def get_one_valid_targetinfo(self, target_path: str) -> Dict:
-        """Returns target information for 'target_path'.
+    def get_one_valid_targetinfo(self, target_path: str) -> TargetFile:
+        """Returns TargetFile instance with information for 'target_path'.
 
         The return value can be used as an argument to
         :func:`download_target()` and :func:`updated_targets()`.
@@ -174,8 +175,8 @@ def get_one_valid_targetinfo(self, target_path: str) -> Dict:
 
     @staticmethod
     def updated_targets(
-        targets: List[Dict[str, Any]], destination_directory: str
-    ) -> List[Dict[str, Any]]:
+        targets: List[TargetFile], destination_directory: str
+    ) -> List[TargetFile]:
         """Checks whether local cached target files are up to date
 
         After retrieving the target information for the targets that should be
@@ -198,17 +199,16 @@ def updated_targets(
             # against each hash listed for its fileinfo.  Note: join() discards
             # 'destination_directory' if 'filepath' contains a leading path
             # separator (i.e., is treated as an absolute path).
-            filepath = target["filepath"]
-            target_fileinfo: "TargetFile" = target["fileinfo"]
-
-            target_filepath = os.path.join(destination_directory, filepath)
+            target_filepath = os.path.join(
+                destination_directory, target.targetname
+            )
 
             if target_filepath in updated_targetpaths:
                 continue
 
             try:
                 with open(target_filepath, "rb") as target_file:
-                    target_fileinfo.verify_length_and_hashes(target_file)
+                    target.verify_length_and_hashes(target_file)
             # If the file does not exist locally or length and hashes
             # do not match, append to updated targets.
             except (OSError, exceptions.LengthOrHashMismatchError):
@@ -219,15 +219,15 @@ def updated_targets(
 
     def download_target(
         self,
-        targetinfo: Dict,
+        targetinfo: TargetFile,
         destination_directory: str,
         target_base_url: Optional[str] = None,
     ):
         """Downloads the target file specified by 'targetinfo'.
 
         Args:
-            targetinfo: data received from get_one_valid_targetinfo() or
-                updated_targets().
+            targetinfo: TargetFile instance received from
+                get_one_valid_targetinfo() or updated_targets().
             destination_directory: existing local directory to download into.
                 Note that new directories may be created inside
                 destination_directory as required.
@@ -248,15 +248,14 @@ def download_target(
         else:
             target_base_url = _ensure_trailing_slash(target_base_url)
 
-        target_filepath = targetinfo["filepath"]
-        target_fileinfo: "TargetFile" = targetinfo["fileinfo"]
+        target_filepath = targetinfo.targetname
         full_url = parse.urljoin(target_base_url, target_filepath)
 
         with self._fetcher.download_file(
-            full_url, target_fileinfo.length
+            full_url, targetinfo.length
         ) as target_file:
             try:
-                target_fileinfo.verify_length_and_hashes(target_file)
+                targetinfo.verify_length_and_hashes(target_file)
             except exceptions.LengthOrHashMismatchError as e:
                 raise exceptions.RepositoryError(
                     f"{target_filepath} length or hashes do not match"
@@ -368,7 +367,7 @@ def _load_targets(self, role: str, parent_role: str) -> None:
             self._trusted_set.update_delegated_targets(data, role, parent_role)
             self._persist_metadata(role, data)
 
-    def _preorder_depth_first_walk(self, target_filepath) -> Dict:
+    def _preorder_depth_first_walk(self, target_filepath) -> TargetFile:
         """
         Interrogates the tree of target delegations in order of appearance
         (which implicitly order trustworthiness), and returns the matching
@@ -460,7 +459,8 @@ def _preorder_depth_first_walk(self, target_filepath) -> Dict:
                 self.config.max_delegations,
             )
 
-        return {"filepath": target_filepath, "fileinfo": target}
+        target.targetname = target_filepath
+        return target
 
 
 def _visit_child_role(child_role: Dict, target_filepath: str) -> str: