resources/libraries/python/VppApiCrc.py

   1 # Copyright (c) 2020 Cisco and/or its affiliates.
   2 # Licensed under the Apache License, Version 2.0 (the "License");
   3 # you may not use this file except in compliance with the License.
   4 # You may obtain a copy of the License at:
   5 #
   6 #     http://www.apache.org/licenses/LICENSE-2.0
   7 #
   8 # Unless required by applicable law or agreed to in writing, software
   9 # distributed under the License is distributed on an "AS IS" BASIS,
  10 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  11 # See the License for the specific language governing permissions and
  12 # limitations under the License.
  13
  14 """Module for keeping track of VPP API CRCs relied on by CSIT."""
  15
  16 import json
  17 import os
  18 import yaml
  19
  20 from robot.api import logger
  21
  22 from resources.libraries.python.Constants import Constants
  23
  24
  25 def _str(text):
  26     """Convert from possible unicode without interpreting as number.
  27
  28     :param text: Input to convert.
  29     :type text: str or unicode
  30     :returns: Converted text.
  31     :rtype: str
  32     """
  33     return text.encode("utf-8") if isinstance(text, unicode) else text
  34
  35
  36 class VppApiCrcChecker(object):
  37     """Holder of data related to tracking VPP API CRCs.
  38
  39     Both message names and crc hexa strings are tracked as
  40     ordinary Python2 (bytes) str, so _str() is used when input is
  41     possibly unicode or otherwise not safe.
  42
  43     Each instance of this class starts with same default state,
  44     so make sure the calling libraries have appropriate robot library scope.
  45     For usual testing, it means "GLOBAL" scope."""
  46
  47     def __init__(
  48             self, directory, fail_on_mismatch=Constants.FAIL_ON_CRC_MISMATCH):
  49         """Initialize empty state, then register known collections.
  50
  51         This also scans directory for .api.json files
  52         and performs initial checks, but does not report the findings yet.
  53
  54         :param directory: Root directory of the search for .api.json files.
  55         :type directory: str
  56         """
  57
  58         self.fail_on_mismatch = fail_on_mismatch
  59         """If True, mismatch leads to test failure, by raising exception.
  60         If False, the mismatch is logged, but the test is allowed to continue.
  61         """
  62
  63         self._expected = dict()
  64         """Mapping from collection name to mapping from API name to CRC string.
  65
  66         Collection name should be something useful for logging.
  67
  68         Order of addition reflects the order collections should be queried.
  69         If an incompatible CRC is found, affected collections are removed.
  70         A CRC that would remove all does not, added to _reported instead,
  71         while causing a failure in single test (if fail_on_mismatch)."""
  72
  73         self._missing = dict()
  74         """Mapping from collection name to mapping from API name to CRC string.
  75
  76         Starts the same as _expected, but each time an encountered api,crc pair
  77         fits the expectation, the pair is removed from all collections
  78         within this mapping. Ideally, the active mappings will become empty.
  79         If not, it is an error, VPP removed or renamed a message CSIT needs."""
  80
  81         self._found = dict()
  82         """Mapping from API name to CRC string.
  83
  84         This gets populated with CRCs found in .api.json,
  85         to serve as a hint when reporting errors."""
  86
  87         self._reported = dict()
  88         """Mapping from API name to CRC string.
  89
  90         This gets populated with APIs used, but not found in collections,
  91         just before the fact is reported in an exception.
  92         The CRC comes from _found mapping (otherwise left as None).
  93         The idea is to not report those next time, allowing the job
  94         to find more problems in a single run."""
  95
  96         self._initial_conflicts_reported = False
  97         self._register_all()
  98         self._check_dir(directory)
  99
 100     def log_and_raise(self, exc_msg):
 101         """Log to console, on fail_on_mismatch also raise runtime exception.
 102
 103         :param exc_msg: The message to include in log or exception.
 104         :type exc_msg: str
 105         :raises RuntimeError: With the message, if fail_on_mismatch.
 106         """
 107         logger.console("RuntimeError:\n{m}".format(m=exc_msg))
 108         if self.fail_on_mismatch:
 109             raise RuntimeError(exc_msg)
 110
 111     def _register_collection(self, collection_name, name_to_crc_mapping):
 112         """Add a named (copy of) collection of CRCs.
 113
 114         :param collection_name: Helpful string describing the collection.
 115         :param name_to_crc_mapping: Mapping from API names to CRCs.
 116         :type collection_name: str or unicode
 117         :type name_to_crc_mapping: dict from str/unicode to str/unicode
 118         :raises RuntimeError: If the name of a collection is registered already.
 119         """
 120         collection_name = _str(collection_name)
 121         if collection_name in self._expected:
 122             raise RuntimeError("Collection {cl!r} already registered.".format(
 123                 cl=collection_name)
 124             )
 125         mapping = {_str(k): _str(v) for k, v in name_to_crc_mapping.items()}
 126         self._expected[collection_name] = mapping
 127         self._missing[collection_name] = mapping.copy()
 128
 129     def _register_all(self):
 130         """Add all collections this CSIT codebase is tested against."""
 131
 132         file_path = os.path.normpath(os.path.join(
 133             os.path.dirname(os.path.abspath(__file__)), "..", "..",
 134             "api", "vpp", "supported_crcs.yaml"))
 135         with open(file_path, "r") as file_in:
 136             collections_dict = yaml.load(file_in.read())
 137         for collection_name, name_to_crc_mapping in collections_dict.items():
 138             self._register_collection(collection_name, name_to_crc_mapping)
 139
 140     @staticmethod
 141     def _get_name(msg_obj):
 142         """Utility function to extract API name from an intermediate json.
 143
 144         :param msg_obj: Loaded json object, item of "messages" list.
 145         :type msg_obj: list of various types
 146         :returns: Name of the message.
 147         :rtype: str or unicode
 148         :raises RuntimeError: If no name is found.
 149         """
 150         for item in msg_obj:
 151             if isinstance(item, (dict, list)):
 152                 continue
 153             return _str(item)
 154         raise RuntimeError("No name found for message: {obj!r}".format(
 155             obj=msg_obj)
 156         )
 157
 158     @staticmethod
 159     def _get_crc(msg_obj):
 160         """Utility function to extract API CRC from an intermediate json.
 161
 162         :param msg_obj: Loaded json object, item of "messages" list.
 163         :type msg_obj: list of various types
 164         :returns: CRC of the message.
 165         :rtype: str or unicode
 166         :raises RuntimeError: If no CRC is found.
 167         """
 168         for item in reversed(msg_obj):
 169             if not isinstance(item, dict):
 170                 continue
 171             crc = item.get("crc", None)
 172             if crc:
 173                 return _str(crc)
 174         raise RuntimeError("No CRC found for message: {obj!r}".format(
 175             obj=msg_obj)
 176         )
 177
 178     def _process_crc(self, api_name, crc):
 179         """Compare API to verified collections, update class state.
 180
 181         Here, API stands for (message name, CRC) pair.
 182
 183         Conflict is NOT when a collection does not recognize the API.
 184         Such APIs are merely added to _found for later reporting.
 185         Conflict is when a collection recognizes the API under a different CRC.
 186         If a partial match happens, only the matching collections are preserved.
 187         On no match, all current collections are preserved,
 188         but the offending API is added to _reported mapping.
 189
 190         Note that it is expected that collections are incompatible
 191         with each other for some APIs. The removal of collections
 192         on partial match is there to help identify the intended collection
 193         for the VPP build under test. But if no collection fits perfectly,
 194         the last collections to determine the "known" flag
 195         depends on the order of api_name submitted,
 196         which tends to be fairly random (depends on order of .api.json files).
 197         Order of collection registrations does not help much in this regard.
 198
 199         Attempts to overwrite value in _found or _reported should not happen,
 200         so the code does not check for that, simply overwriting.
 201
 202         The intended usage is to call this method multiple times,
 203         and then raise exception listing all _reported.
 204
 205         :param api_name: API name to check.
 206         :param crc: Discovered CRC to check for the name.
 207         :type api_name: str
 208         :type crc: str
 209         """
 210         # Regardless of the result, remember as found.
 211         self._found[api_name] = crc
 212         old_expected = self._expected
 213         new_expected = old_expected.copy()
 214         for collection_name, name_to_crc_mapping in old_expected.items():
 215             if api_name not in name_to_crc_mapping:
 216                 continue
 217             if name_to_crc_mapping[api_name] == crc:
 218                 self._missing[collection_name].pop(api_name, None)
 219                 continue
 220             # Remove the offending collection.
 221             new_expected.pop(collection_name, None)
 222         if new_expected:
 223             # Some collections recognized the CRC.
 224             self._expected = new_expected
 225             self._missing = {name: self._missing[name] for name in new_expected}
 226             return
 227         # No new_expected means some collections knew the api_name,
 228         # but CRC does not match any. This has to be reported.
 229         self._reported[api_name] = crc
 230
 231     def _check_dir(self, directory):
 232         """Parse every .api.json found under directory, remember conflicts.
 233
 234         As several collections are supported, each conflict invalidates
 235         some of them, failure happens only when no collections would be left.
 236         In that case, set of collections just before the failure is preserved,
 237         the _reported mapping is filled with conflicting APIs.
 238         The _found mapping is filled with discovered api names and crcs.
 239
 240         The exception is not thrown here, but from report_initial_conflicts.
 241
 242         :param directory: Root directory of the search for .api.json files.
 243         :type directory: str
 244         """
 245         for root, _, files in os.walk(directory):
 246             for filename in files:
 247                 if not filename.endswith(".api.json"):
 248                     continue
 249                 with open(root + '/' + filename, "r") as file_in:
 250                     json_obj = json.load(file_in)
 251                 msgs = json_obj["messages"]
 252                 for msg_obj in msgs:
 253                     msg_name = self._get_name(msg_obj)
 254                     msg_crc = self._get_crc(msg_obj)
 255                     self._process_crc(msg_name, msg_crc)
 256         logger.debug("Surviving collections: {col!r}".format(
 257             col=self._expected.keys())
 258         )
 259
 260     def report_initial_conflicts(self, report_missing=False):
 261         """Report issues discovered by _check_dir, if not done that already.
 262
 263         Intended use: Call once after init, at a time when throwing exception
 264         is convenient.
 265
 266         Optionally, report also missing messages.
 267         Missing reporting is disabled by default, because some messages
 268         come from plugins that might not be enabled at runtime.
 269
 270         After the report, clear _reported, so that test cases report them again,
 271         thus tracking which message is actually used (by which test).
 272
 273         :param report_missing: Whether to raise on missing messages.
 274         :type report_missing: bool
 275         :raises RuntimeError: If CRC mismatch or missing messages are detected,
 276             and fail_on_mismatch is True.
 277         """
 278         if self._initial_conflicts_reported:
 279             return
 280         self._initial_conflicts_reported = True
 281         if self._reported:
 282
 283             reported_indented = json.dumps(
 284                 self._reported, indent=1, sort_keys=True,
 285                 separators=[",", ":"]
 286             )
 287             self._reported = dict()
 288             self.log_and_raise(
 289                 "Incompatible API CRCs found in .api.json files:\n"
 290                 "{r_i}".format(r_i=reported_indented)
 291             )
 292         if not report_missing:
 293             return
 294         missing = {name: mapp for name, mapp in self._missing.items() if mapp}
 295         if missing:
 296             missing_indented = json.dumps(
 297                 missing, indent=1, sort_keys=True, separators=[",", ":"])
 298             self.log_and_raise(
 299                 "API CRCs missing from .api.json:\n"
 300                 "{m_i}".format(m_i=missing_indented)
 301             )
 302
 303     def check_api_name(self, api_name):
 304         """Fail if the api_name has no, or different from known CRC associated.
 305
 306         Do not fail if this particular failure has been already reported.
 307
 308         Intended use: Call during test (not in initialization),
 309         every time an API call is queued or response received.
 310
 311
 312         :param api_name: VPP API message name to check.
 313         :type api_name: str or unicode
 314         :raises RuntimeError: If no verified CRC for the api_name is found.
 315         """
 316         api_name = _str(api_name)
 317         if api_name in self._reported:
 318             return
 319         old_expected = self._expected
 320         new_expected = old_expected.copy()
 321         for collection_name, name_to_crc_mapping in old_expected.items():
 322             if api_name in name_to_crc_mapping:
 323                 continue
 324             # Remove the offending collection.
 325             new_expected.pop(collection_name, None)
 326         if new_expected:
 327             # Some collections recognized the message name.
 328             self._expected = new_expected
 329         crc = self._found.get(api_name, None)
 330         matching = False
 331         if crc is not None:
 332             # Regardless of how many collections are remaining,
 333             # verify the known CRC is on one of them.
 334             for col, name_to_crc_mapping in self._expected.items():
 335                 if api_name not in name_to_crc_mapping:
 336                     continue
 337                 if name_to_crc_mapping[api_name] == crc:
 338                     matching = True
 339                     break
 340         if matching:
 341             return
 342         self._reported[api_name] = crc
 343         self.log_and_raise(
 344             "No active collection contains API {a_n!r} with CRC {crc!r}".format(
 345                 a_n=api_name, crc=crc)
 346         )