d55058e43155105f4ab79c356850ecc0e4a81173
[csit.git] / resources / libraries / python / VppApiCrc.py
1 # Copyright (c) 2019 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 bytes 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.decode(u"utf-8") if isinstance(text, bytes) else text
34
35
36 class VppApiCrcChecker:
37     """Holder of data related to tracking VPP API CRCs.
38
39     Both message names and crc hexa strings are tracked as
40     ordinary Python3 (unicode) string, so _str() is used when input is
41     possibly bytes 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(
123                 f"Collection {collection_name!r} already registered."
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__)), u"..", u"..",
134             u"api", u"vpp", u"supported_crcs.yaml"))
135         with open(file_path, "r") as file_in:
136             collections_dict = yaml.safe_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(f"No name found for message: {msg_obj!r}")
155
156     @staticmethod
157     def _get_crc(msg_obj):
158         """Utility function to extract API CRC from an intermediate json.
159
160         :param msg_obj: Loaded json object, item of "messages" list.
161         :type msg_obj: list of various types
162         :returns: CRC of the message.
163         :rtype: str or unicode
164         :raises RuntimeError: If no CRC is found.
165         """
166         for item in reversed(msg_obj):
167             if not isinstance(item, dict):
168                 continue
169             crc = item.get(u"crc", None)
170             if crc:
171                 return _str(crc)
172         raise RuntimeError(f"No CRC found for message: {msg_obj!r}")
173
174     def _process_crc(self, api_name, crc):
175         """Compare API to verified collections, update class state.
176
177         Here, API stands for (message name, CRC) pair.
178
179         Conflict is NOT when a collection does not recognize the API.
180         Such APIs are merely added to _found for later reporting.
181         Conflict is when a collection recognizes the API under a different CRC.
182         If a partial match happens, only the matching collections are preserved.
183         On no match, all current collections are preserved,
184         but the offending API is added to _reported mapping.
185
186         Note that it is expected that collections are incompatible
187         with each other for some APIs. The removal of collections
188         on partial match is there to help identify the intended collection
189         for the VPP build under test. But if no collection fits perfectly,
190         the last collections to determine the "known" flag
191         depends on the order of api_name submitted,
192         which tends to be fairly random (depends on order of .api.json files).
193         Order of collection registrations does not help much in this regard.
194
195         Attempts to overwrite value in _found or _reported should not happen,
196         so the code does not check for that, simply overwriting.
197
198         The intended usage is to call this method multiple times,
199         and then raise exception listing all _reported.
200
201         :param api_name: API name to check.
202         :param crc: Discovered CRC to check for the name.
203         :type api_name: str
204         :type crc: str
205         """
206         # Regardless of the result, remember as found.
207         self._found[api_name] = crc
208         old_expected = self._expected
209         new_expected = old_expected.copy()
210         for collection_name, name_to_crc_mapping in old_expected.items():
211             if api_name not in name_to_crc_mapping:
212                 continue
213             if name_to_crc_mapping[api_name] == crc:
214                 self._missing[collection_name].pop(api_name, None)
215                 continue
216             # Remove the offending collection.
217             new_expected.pop(collection_name, None)
218         if new_expected:
219             # Some collections recognized the CRC.
220             self._expected = new_expected
221             self._missing = {name: self._missing[name] for name in new_expected}
222             return
223         # No new_expected means some collections knew the api_name,
224         # but CRC does not match any. This has to be reported.
225         self._reported[api_name] = crc
226
227     def _check_dir(self, directory):
228         """Parse every .api.json found under directory, remember conflicts.
229
230         As several collections are supported, each conflict invalidates
231         some of them, failure happens only when no collections would be left.
232         In that case, set of collections just before the failure is preserved,
233         the _reported mapping is filled with conflicting APIs.
234         The _found mapping is filled with discovered api names and crcs.
235
236         The exception is not thrown here, but from report_initial_conflicts.
237
238         :param directory: Root directory of the search for .api.json files.
239         :type directory: str
240         """
241         for root, _, files in os.walk(directory):
242             for filename in files:
243                 if not filename.endswith(u".api.json"):
244                     continue
245                 with open(f"{root}/{filename}", "r") as file_in:
246                     json_obj = json.load(file_in)
247                 msgs = json_obj[u"messages"]
248                 for msg_obj in msgs:
249                     msg_name = self._get_name(msg_obj)
250                     msg_crc = self._get_crc(msg_obj)
251                     self._process_crc(msg_name, msg_crc)
252         logger.debug(f"Surviving collections: {self._expected.keys()!r}")
253
254     def report_initial_conflicts(self, report_missing=False):
255         """Report issues discovered by _check_dir, if not done that already.
256
257         Intended use: Call once after init, at a time when throwing exception
258         is convenient.
259
260         Optionally, report also missing messages.
261         Missing reporting is disabled by default, because some messages
262         come from plugins that might not be enabled at runtime.
263
264         After the report, clear _reported, so that test cases report them again,
265         thus tracking which message is actually used (by which test).
266
267         :param report_missing: Whether to raise on missing messages.
268         :type report_missing: bool
269         :raises RuntimeError: If CRC mismatch or missing messages are detected,
270             and fail_on_mismatch is True.
271         """
272         if self._initial_conflicts_reported:
273             return
274         self._initial_conflicts_reported = True
275         if self._reported:
276             reported_indented = json.dumps(
277                 self._reported, indent=1, sort_keys=True,
278                 separators=[u",", u":"]
279             )
280             self._reported = dict()
281             self.log_and_raise(
282                 f"Incompatible API CRCs found in .api.json files:\n"
283                 f"{reported_indented}"
284             )
285         if not report_missing:
286             return
287         missing = {name: mapp for name, mapp in self._missing.items() if mapp}
288         if missing:
289             missing_indented = json.dumps(
290                 missing, indent=1, sort_keys=True, separators=[u",", u":"])
291             self.log_and_raise(
292                 f"API CRCs missing from .api.json:\n{missing_indented}"
293             )
294
295     def check_api_name(self, api_name):
296         """Fail if the api_name has no, or different from known CRC associated.
297
298         Do not fail if this particular failure has been already reported.
299
300         Intended use: Call during test (not in initialization),
301         every time an API call is queued or response received.
302
303         :param api_name: VPP API message name to check.
304         :type api_name: str or unicode
305         :raises RuntimeError: If no verified CRC for the api_name is found.
306         """
307         api_name = _str(api_name)
308         if api_name in self._reported:
309             return
310         old_expected = self._expected
311         new_expected = old_expected.copy()
312         for collection_name, name_to_crc_mapping in old_expected.items():
313             if api_name in name_to_crc_mapping:
314                 continue
315             # Remove the offending collection.
316             new_expected.pop(collection_name, None)
317         if new_expected:
318             # Some collections recognized the message name.
319             self._expected = new_expected
320         crc = self._found.get(api_name, None)
321         matching = False
322         if crc is not None:
323             # Regardless of how many collections are remaining,
324             # verify the known CRC is on one of them.
325             for name_to_crc_mapping in self._expected.values():
326                 if api_name not in name_to_crc_mapping:
327                     continue
328                 if name_to_crc_mapping[api_name] == crc:
329                     matching = True
330                     break
331         if matching:
332             return
333         self._reported[api_name] = crc
334         self.log_and_raise(
335             f"No active collection contains API {api_name!r} with CRC {crc!r}"
336         )

©2016 FD.io a Linux Foundation Collaborative Project. All Rights Reserved.
Linux Foundation is a registered trademark of The Linux Foundation. Linux is a registered trademark of Linus Torvalds.
Please see our privacy policy and terms of use.