Fix warnings reported by gen_doc.sh
[csit.git] / resources / libraries / python / honeycomb / HoneycombUtil.py
1 # Copyright (c) 2018 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 """Implementation of low level functionality used in communication with
15 Honeycomb.
16
17 Exception HoneycombError is used in all methods and in all modules with
18 Honeycomb keywords.
19
20 Class HoneycombUtil implements methods used by Honeycomb keywords. They must not
21 be used directly in tests. Use keywords implemented in the module
22 HoneycombAPIKeywords instead.
23 """
24
25 from json import loads, dumps
26 from enum import Enum, unique
27
28 from robot.api import logger
29
30 from resources.libraries.python.ssh import SSH
31 from resources.libraries.python.HTTPRequest import HTTPRequest
32 from resources.libraries.python.constants import Constants as Const
33
34
35 @unique
36 class DataRepresentation(Enum):
37     """Representation of data sent by PUT and POST requests."""
38     NO_DATA = 0
39     JSON = 1
40     XML = 2
41     TXT = 3
42
43
44 # Headers used in requests. Key - content representation, value - header.
45 HEADERS = {DataRepresentation.NO_DATA:
46                {},  # It must be empty dictionary.
47            DataRepresentation.JSON:
48                {"Content-Type": "application/json",
49                 "Accept": "text/plain"},
50            DataRepresentation.XML:
51                {"Content-Type": "application/xml",
52                 "Accept": "text/plain"},
53            DataRepresentation.TXT:
54                {"Content-Type": "text/plain",
55                 "Accept": "text/plain"}
56           }
57
58
59 class HoneycombError(Exception):
60
61     """Exception(s) raised by methods working with Honeycomb.
62
63     When raising this exception, put this information to the message in this
64     order:
65
66      - short description of the encountered problem (parameter msg),
67      - relevant messages if there are any collected, e.g., from caught
68        exception (optional parameter details),
69      - relevant data if there are any collected (optional parameter details).
70
71     The logging is performed on two levels: 1. error - short description of the
72     problem; 2. debug - detailed information.
73     """
74
75     def __init__(self, msg, details='', enable_logging=True):
76         """Sets the exception message and enables / disables logging.
77
78         It is not wanted to log errors when using these keywords together
79         with keywords like "Wait until keyword succeeds". So you can disable
80         logging by setting enable_logging to False.
81
82         :param msg: Message to be displayed and logged.
83         :param enable_logging: When True, logging is enabled, otherwise
84             logging is disabled.
85         :type msg: str
86         :type enable_logging: bool
87         """
88         super(HoneycombError, self).__init__()
89         self._msg = "{0}: {1}".format(self.__class__.__name__, msg)
90         self._details = details
91         if enable_logging:
92             logger.debug(self._details)
93
94     def __repr__(self):
95         return repr(self._msg)
96
97     def __str__(self):
98         return str(self._msg)
99
100
101 class HoneycombUtil(object):
102     """Implements low level functionality used in communication with Honeycomb.
103
104     There are implemented methods to get, put and delete data to/from Honeycomb.
105     They are based on functionality implemented in the module HTTPRequests which
106     uses HTTP requests GET, PUT, POST and DELETE to communicate with Honeycomb.
107
108     It is possible to PUT the data represented as XML or JSON structures or as
109     plain text.
110     Data received in the response of GET are always represented as a JSON
111     structure.
112
113     There are also two supportive methods implemented:
114
115       - read_path_from_url_file which reads URL file and returns a path (see
116         docs/honeycomb_url_files.rst).
117       - parse_json_response which parses data from response in JSON
118         representation according to given path.
119     """
120
121     def __init__(self):
122         pass
123
124     @staticmethod
125     def read_path_from_url_file(url_file):
126         """Read path from .url file.
127
128         For more information about .url file see docs/honeycomb_url_files.rst
129
130         :param url_file: URL file. The argument contains only the name of file
131             without extension, not the full path.
132         :type url_file: str
133         :returns: Requested path.
134         :rtype: str
135         """
136
137         url_file = "{0}/{1}.url".format(Const.RESOURCES_TPL_HC, url_file)
138         with open(url_file) as template:
139             path = template.readline()
140         return path
141
142     @staticmethod
143     def find_item(data, path):
144         """Find a data item (single leaf or sub-tree) in data received from
145         Honeycomb REST API.
146
147         Path format:
148         The path is a tuple with items navigating to requested data. The items
149         can be strings or tuples:
150
151           - string item represents a dictionary key in data,
152           - tuple item represents list item in data.
153
154         Example::
155
156           data = \
157           {
158               "interfaces": {
159                   "interface": [
160                       {
161                           "name": "GigabitEthernet0/8/0",
162                           "enabled": "true",
163                           "type": "iana-if-type:ethernetCsmacd",
164                       },
165                       {
166                           "name": "local0",
167                           "enabled": "false",
168                           "type": "iana-if-type:ethernetCsmacd",
169                       }
170                   ]
171               }
172           }
173
174         path = ("interfaces", ("interface", "name", "local0"), "enabled")
175         This path points to "false".
176
177         The tuple ("interface", "name", "local0") consists of::
178
179           index 0 - dictionary key pointing to a list,
180           index 1 - key which identifies an item in the list, it is also marked
181                     as the key in corresponding yang file.
182           index 2 - key value.
183
184         :param data: Data received from Honeycomb REST API.
185         :param path: Path to data we want to find.
186         :type data: dict
187         :type path: tuple
188         :returns: Data represented by path.
189         :rtype: str, dict, or list
190         :raises HoneycombError: If the data has not been found.
191         """
192
193         for path_item in path:
194             try:
195                 if isinstance(path_item, str):
196                     data = data[path_item]
197                 elif isinstance(path_item, tuple):
198                     for data_item in data[path_item[0]]:
199                         if data_item[path_item[1]] == path_item[2]:
200                             data = data_item
201             except KeyError as err:
202                 raise HoneycombError("Data not found: {0}".format(err))
203
204         return data
205
206     @staticmethod
207     def remove_item(data, path):
208         """Remove a data item (single leaf or sub-tree) in data received from
209         Honeycomb REST API.
210
211         :param data: Data received from Honeycomb REST API.
212         :param path: Path to data we want to remove.
213         :type data: dict
214         :type path: tuple
215         :returns: Original data without removed part.
216         :rtype: dict
217         """
218
219         origin_data = previous_data = data
220         try:
221             for path_item in path:
222                 previous_data = data
223                 if isinstance(path_item, str):
224                     data = data[path_item]
225                 elif isinstance(path_item, tuple):
226                     for data_item in data[path_item[0]]:
227                         if data_item[path_item[1]] == path_item[2]:
228                             data = data_item
229         except KeyError as err:
230             logger.debug("Data not found: {0}".format(err))
231             return origin_data
232
233         if isinstance(path[-1], str):
234             previous_data.pop(path[-1])
235         elif isinstance(path[-1], tuple):
236             previous_data[path[-1][0]].remove(data)
237             if not previous_data[path[-1][0]]:
238                 previous_data.pop(path[-1][0])
239
240         return origin_data
241
242     @staticmethod
243     def set_item_value(data, path, new_value):
244         """Set or change the value (single leaf or sub-tree) in data received
245         from Honeycomb REST API.
246
247         If the item is not present in the data structure, it is created.
248
249         :param data: Data received from Honeycomb REST API.
250         :param path: Path to data we want to change or create.
251         :param new_value: The value to be set.
252         :type data: dict
253         :type path: tuple
254         :type new_value: str, dict or list
255         :returns: Original data with the new value.
256         :rtype: dict
257         """
258
259         origin_data = data
260         for path_item in path[:-1]:
261             if isinstance(path_item, str):
262                 try:
263                     data = data[path_item]
264                 except KeyError:
265                     data[path_item] = {}
266                     data = data[path_item]
267             elif isinstance(path_item, tuple):
268                 try:
269                     flag = False
270                     index = 0
271                     for data_item in data[path_item[0]]:
272                         if data_item[path_item[1]] == path_item[2]:
273                             data = data[path_item[0]][index]
274                             flag = True
275                             break
276                         index += 1
277                     if not flag:
278                         data[path_item[0]].append({path_item[1]: path_item[2]})
279                         data = data[path_item[0]][-1]
280                 except KeyError:
281                     data[path_item] = []
282
283         if not path[-1] in data.keys():
284             data[path[-1]] = {}
285
286         if isinstance(new_value, list) and isinstance(data[path[-1]], list):
287             for value in new_value:
288                 data[path[-1]].append(value)
289         else:
290             data[path[-1]] = new_value
291
292         return origin_data
293
294     @staticmethod
295     def get_honeycomb_data(node, url_file, path=""):
296         """Retrieve data from Honeycomb according to given URL.
297
298         :param node: Honeycomb node.
299         :param url_file: URL file. The argument contains only the name of file
300             without extension, not the full path.
301         :param path: Path which is added to the base path to identify the data.
302         :type node: dict
303         :type url_file: str
304         :type path: str
305         :returns: Status code and content of response.
306         :rtype: tuple
307         """
308
309         base_path = HoneycombUtil.read_path_from_url_file(url_file)
310         path = base_path + path
311         status_code, resp = HTTPRequest.get(node, path)
312
313         try:
314             data = loads(resp)
315         except ValueError:
316             logger.debug("Failed to deserialize JSON data.")
317             data = None
318
319         return status_code, data
320
321     @staticmethod
322     def put_honeycomb_data(node, url_file, data, path="",
323                            data_representation=DataRepresentation.JSON):
324         """Send configuration data using PUT request and return the status code
325         and response content.
326
327         :param node: Honeycomb node.
328         :param url_file: URL file. The argument contains only the name of file
329             without extension, not the full path.
330         :param data: Configuration data to be sent to Honeycomb.
331         :param path: Path which is added to the base path to identify the data.
332         :param data_representation: How the data is represented.
333         :type node: dict
334         :type url_file: str
335         :type data: dict, str
336         :type path: str
337         :type data_representation: DataRepresentation
338         :returns: Status code and content of response.
339         :rtype: tuple
340         :raises HoneycombError: If the given data representation is not defined
341             in HEADERS.
342         """
343
344         try:
345             header = HEADERS[data_representation]
346         except AttributeError as err:
347             raise HoneycombError("Wrong data representation: {0}.".
348                                  format(data_representation), repr(err))
349         if data_representation == DataRepresentation.JSON:
350             data = dumps(data)
351
352         logger.trace(data)
353
354         base_path = HoneycombUtil.read_path_from_url_file(url_file)
355         path = base_path + path
356         logger.trace(path)
357         return HTTPRequest.put(
358             node=node, path=path, headers=header, payload=data)
359
360     @staticmethod
361     def post_honeycomb_data(node, url_file, data=None,
362                             data_representation=DataRepresentation.JSON,
363                             timeout=10):
364         """Send a POST request and return the status code and response content.
365
366         :param node: Honeycomb node.
367         :param url_file: URL file. The argument contains only the name of file
368             without extension, not the full path.
369         :param data: Configuration data to be sent to Honeycomb.
370         :param data_representation: How the data is represented.
371         :param timeout: How long to wait for the server to send data before
372             giving up.
373         :type node: dict
374         :type url_file: str
375         :type data: dict, str
376         :type data_representation: DataRepresentation
377         :type timeout: int
378         :returns: Status code and content of response.
379         :rtype: tuple
380         :raises HoneycombError: If the given data representation is not defined
381             in HEADERS.
382         """
383
384         try:
385             header = HEADERS[data_representation]
386         except AttributeError as err:
387             raise HoneycombError("Wrong data representation: {0}.".
388                                  format(data_representation), repr(err))
389         if data_representation == DataRepresentation.JSON:
390             data = dumps(data)
391
392         path = HoneycombUtil.read_path_from_url_file(url_file)
393         return HTTPRequest.post(
394             node=node, path=path, headers=header, payload=data, timeout=timeout)
395
396     @staticmethod
397     def delete_honeycomb_data(node, url_file, path=""):
398         """Delete data from Honeycomb according to given URL.
399
400         :param node: Honeycomb node.
401         :param url_file: URL file. The argument contains only the name of file
402             without extension, not the full path.
403         :param path: Path which is added to the base path to identify the data.
404         :type node: dict
405         :type url_file: str
406         :type path: str
407         :returns: Status code and content of response.
408         :rtype: tuple
409         """
410
411         base_path = HoneycombUtil.read_path_from_url_file(url_file)
412         path = base_path + path
413         return HTTPRequest.delete(node, path)
414
415     @staticmethod
416     def append_honeycomb_log(node, suite_name):
417         """Append Honeycomb log for the current test suite to the full log.
418
419         :param node: Honeycomb node.
420         :param suite_name: Name of the current test suite. ${SUITE_NAME}
421             variable in robotframework.
422         :type node: dict
423         :type suite_name: str
424         """
425
426         ssh = SSH()
427         ssh.connect(node)
428
429         ssh.exec_command(
430             "echo '{separator}' >> /tmp/honeycomb.log".format(separator="="*80))
431         ssh.exec_command(
432             "echo 'Log for suite: {suite}' >> /tmp/honeycomb.log".format(
433                 suite=suite_name))
434         ssh.exec_command(
435             "cat {hc_log} >> /tmp/honeycomb.log".format(
436                 hc_log=Const.REMOTE_HC_LOG))
437
438     @staticmethod
439     def clear_honeycomb_log(node):
440         """Delete the Honeycomb log file for the current test suite.
441
442         :param node: Honeycomb node.
443         :type node: dict
444         """
445
446         ssh = SSH()
447         ssh.connect(node)
448
449         ssh.exec_command("sudo rm {hc_log}".format(hc_log=Const.REMOTE_HC_LOG))
450
451     @staticmethod
452     def archive_honeycomb_log(node, perf=False):
453         """Copy honeycomb log file from DUT node to VIRL for archiving.
454
455         :param node: Honeycomb node.
456         :param perf: Alternate handling, for use with performance test topology.
457         :type node: dict
458         :type perf: bool
459         """
460
461         ssh = SSH()
462         ssh.connect(node)
463
464         if not perf:
465             cmd = "cp /tmp/honeycomb.log /scratch/"
466             ssh.exec_command_sudo(cmd, timeout=60)
467         else:
468             ssh.scp(
469                 ".",
470                 "/tmp/honeycomb.log",
471                 get=True,
472                 timeout=60)
473             ssh.exec_command("rm /tmp/honeycomb.log")

©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.