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:
6 # http://www.apache.org/licenses/LICENSE-2.0
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.
14 """Module for keeping track of VPP API CRCs relied on by CSIT."""
20 from robot.api import logger
22 from resources.libraries.python.Constants import Constants
26 """Convert from possible unicode without interpreting as number.
28 :param text: Input to convert.
29 :type text: str or unicode
30 :returns: Converted text.
33 return text.encode("utf-8") if isinstance(text, unicode) else text
36 class VppApiCrcChecker(object):
37 """Holder of data related to tracking VPP API CRCs.
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.
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."""
48 self, directory, fail_on_mismatch=Constants.FAIL_ON_CRC_MISMATCH):
49 """Initialize empty state, then register known collections.
51 This also scans directory for .api.json files
52 and performs initial checks, but does not report the findings yet.
54 :param directory: Root directory of the search for .api.json files.
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.
63 self._expected = dict()
64 """Mapping from collection name to mapping from API name to CRC string.
66 Collection name should be something useful for logging.
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)."""
73 self._missing = dict()
74 """Mapping from collection name to mapping from API name to CRC string.
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."""
82 """Mapping from API name to CRC string.
84 This gets populated with CRCs found in .api.json,
85 to serve as a hint when reporting errors."""
87 self._reported = dict()
88 """Mapping from API name to CRC string.
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."""
96 self._initial_conflicts_reported = False
98 self._check_dir(directory)
100 def log_and_raise(self, exc_msg):
101 """Log to console, on fail_on_mismatch also raise runtime exception.
103 :param exc_msg: The message to include in log or exception.
105 :raises RuntimeError: With the message, if fail_on_mismatch.
107 logger.console("RuntimeError:\n{m}".format(m=exc_msg))
108 if self.fail_on_mismatch:
109 raise RuntimeError(exc_msg)
111 def _register_collection(self, collection_name, name_to_crc_mapping):
112 """Add a named (copy of) collection of CRCs.
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.
120 collection_name = _str(collection_name)
121 if collection_name in self._expected:
122 raise RuntimeError("Collection {cl!r} already registered.".format(
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()
129 def _register_all(self):
130 """Add all collections this CSIT codebase is tested against."""
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)
141 def _get_name(msg_obj):
142 """Utility function to extract API name from an intermediate json.
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.
151 if isinstance(item, (dict, list)):
154 raise RuntimeError("No name found for message: {obj!r}".format(
159 def _get_crc(msg_obj):
160 """Utility function to extract API CRC from an intermediate json.
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.
168 for item in reversed(msg_obj):
169 if not isinstance(item, dict):
171 crc = item.get("crc", None)
174 raise RuntimeError("No CRC found for message: {obj!r}".format(
178 def _process_crc(self, api_name, crc):
179 """Compare API to verified collections, update class state.
181 Here, API stands for (message name, CRC) pair.
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.
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.
199 Attempts to overwrite value in _found or _reported should not happen,
200 so the code does not check for that, simply overwriting.
202 The intended usage is to call this method multiple times,
203 and then raise exception listing all _reported.
205 :param api_name: API name to check.
206 :param crc: Discovered CRC to check for the name.
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:
217 if name_to_crc_mapping[api_name] == crc:
218 self._missing[collection_name].pop(api_name, None)
220 # Remove the offending collection.
221 new_expected.pop(collection_name, None)
223 # Some collections recognized the CRC.
224 self._expected = new_expected
225 self._missing = {name: self._missing[name] for name in new_expected}
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
231 def _check_dir(self, directory):
232 """Parse every .api.json found under directory, remember conflicts.
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.
240 The exception is not thrown here, but from report_initial_conflicts.
242 :param directory: Root directory of the search for .api.json files.
245 for root, _, files in os.walk(directory):
246 for filename in files:
247 if not filename.endswith(".api.json"):
249 with open(root + '/' + filename, "r") as file_in:
250 json_obj = json.load(file_in)
251 msgs = json_obj["messages"]
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())
260 def report_initial_conflicts(self, report_missing=False):
261 """Report issues discovered by _check_dir, if not done that already.
263 Intended use: Call once after init, at a time when throwing exception
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.
270 After the report, clear _reported, so that test cases report them again,
271 thus tracking which message is actually used (by which test).
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.
278 if self._initial_conflicts_reported:
280 self._initial_conflicts_reported = True
283 reported_indented = json.dumps(
284 self._reported, indent=1, sort_keys=True,
285 separators=[",", ":"]
287 self._reported = dict()
289 "Incompatible API CRCs found in .api.json files:\n"
290 "{r_i}".format(r_i=reported_indented)
292 if not report_missing:
294 missing = {name: mapp for name, mapp in self._missing.items() if mapp}
296 missing_indented = json.dumps(
297 missing, indent=1, sort_keys=True, separators=[",", ":"])
299 "API CRCs missing from .api.json:\n"
300 "{m_i}".format(m_i=missing_indented)
303 def check_api_name(self, api_name):
304 """Fail if the api_name has no, or different from known CRC associated.
306 Do not fail if this particular failure has been already reported.
308 Intended use: Call during test (not in initialization),
309 every time an API call is queued or response received.
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.
316 api_name = _str(api_name)
317 if api_name in self._reported:
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:
324 # Remove the offending collection.
325 new_expected.pop(collection_name, None)
327 # Some collections recognized the message name.
328 self._expected = new_expected
329 crc = self._found.get(api_name, 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:
337 if name_to_crc_mapping[api_name] == crc:
342 self._reported[api_name] = crc
344 "No active collection contains API {a_n!r} with CRC {crc!r}".format(
345 a_n=api_name, crc=crc)