resources/libraries/python/PapiExecutor.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 """Python API executor library.
  15 """
  16
  17 import binascii
  18 import json
  19
  20 from pprint import pformat
  21 from robot.api import logger
  22
  23 from resources.libraries.python.Constants import Constants
  24 from resources.libraries.python.PapiHistory import PapiHistory
  25 from resources.libraries.python.PythonThree import raise_from
  26 from resources.libraries.python.ssh import SSH, SSHTimeout
  27
  28
  29 __all__ = ["PapiExecutor"]
  30
  31
  32 class PapiExecutor(object):
  33     """Contains methods for executing VPP Python API commands on DUTs.
  34
  35     Note: Use only with "with" statement, e.g.:
  36
  37         with PapiExecutor(node) as papi_exec:
  38             replies = papi_exec.add('show_version').get_replies(err_msg)
  39
  40     This class processes three classes of VPP PAPI methods:
  41     1. simple request / reply: method='request',
  42     2. dump functions: method='dump',
  43     3. vpp-stats: method='stats'.
  44
  45     The recommended ways of use are (examples):
  46
  47     1. Simple request / reply
  48
  49     a. One request with no arguments:
  50
  51         with PapiExecutor(node) as papi_exec:
  52             reply = papi_exec.add('show_version').get_reply()
  53
  54     b. Three requests with arguments, the second and the third ones are the same
  55        but with different arguments.
  56
  57         with PapiExecutor(node) as papi_exec:
  58             replies = papi_exec.add(cmd1, **args1).add(cmd2, **args2).\
  59                 add(cmd2, **args3).get_replies(err_msg)
  60
  61     2. Dump functions
  62
  63         cmd = 'sw_interface_rx_placement_dump'
  64         with PapiExecutor(node) as papi_exec:
  65             details = papi_exec.add(cmd, sw_if_index=ifc['vpp_sw_index']).\
  66                 get_details(err_msg)
  67
  68     3. vpp-stats
  69
  70         path = ['^/if', '/err/ip4-input', '/sys/node/ip4-input']
  71
  72         with PapiExecutor(node) as papi_exec:
  73             stats = papi_exec.add(api_name='vpp-stats', path=path).get_stats()
  74
  75         print('RX interface core 0, sw_if_index 0:\n{0}'.\
  76             format(stats[0]['/if/rx'][0][0]))
  77
  78         or
  79
  80         path_1 = ['^/if', ]
  81         path_2 = ['^/if', '/err/ip4-input', '/sys/node/ip4-input']
  82
  83         with PapiExecutor(node) as papi_exec:
  84             stats = papi_exec.add('vpp-stats', path=path_1).\
  85                 add('vpp-stats', path=path_2).get_stats()
  86
  87         print('RX interface core 0, sw_if_index 0:\n{0}'.\
  88             format(stats[1]['/if/rx'][0][0]))
  89
  90         Note: In this case, when PapiExecutor method 'add' is used:
  91         - its parameter 'csit_papi_command' is used only to keep information
  92           that vpp-stats are requested. It is not further processed but it is
  93           included in the PAPI history this way:
  94           vpp-stats(path=['^/if', '/err/ip4-input', '/sys/node/ip4-input'])
  95           Always use csit_papi_command="vpp-stats" if the VPP PAPI method
  96           is "stats".
  97         - the second parameter must be 'path' as it is used by PapiExecutor
  98           method 'add'.
  99     """
 100
 101     def __init__(self, node):
 102         """Initialization.
 103
 104         :param node: Node to run command(s) on.
 105         :type node: dict
 106         """
 107
 108         # Node to run command(s) on.
 109         self._node = node
 110
 111         # The list of PAPI commands to be executed on the node.
 112         self._api_command_list = list()
 113
 114         self._ssh = SSH()
 115
 116     def __enter__(self):
 117         try:
 118             self._ssh.connect(self._node)
 119         except IOError:
 120             raise RuntimeError("Cannot open SSH connection to host {host} to "
 121                                "execute PAPI command(s)".
 122                                format(host=self._node["host"]))
 123         return self
 124
 125     def __exit__(self, exc_type, exc_val, exc_tb):
 126         self._ssh.disconnect(self._node)
 127
 128     def add(self, csit_papi_command="vpp-stats", history=True, **kwargs):
 129         """Add next command to internal command list; return self.
 130
 131         The argument name 'csit_papi_command' must be unique enough as it cannot
 132         be repeated in kwargs.
 133
 134         :param csit_papi_command: VPP API command.
 135         :param history: Enable/disable adding command to PAPI command history.
 136         :param kwargs: Optional key-value arguments.
 137         :type csit_papi_command: str
 138         :type history: bool
 139         :type kwargs: dict
 140         :returns: self, so that method chaining is possible.
 141         :rtype: PapiExecutor
 142         """
 143         if history:
 144             PapiHistory.add_to_papi_history(
 145                 self._node, csit_papi_command, **kwargs)
 146         self._api_command_list.append(dict(api_name=csit_papi_command,
 147                                            api_args=kwargs))
 148         return self
 149
 150     def get_stats(self, err_msg="Failed to get statistics.", timeout=120):
 151         """Get VPP Stats from VPP Python API.
 152
 153         :param err_msg: The message used if the PAPI command(s) execution fails.
 154         :param timeout: Timeout in seconds.
 155         :type err_msg: str
 156         :type timeout: int
 157         :returns: Requested VPP statistics.
 158         :rtype: list of dict
 159         """
 160
 161         paths = [cmd['api_args']['path'] for cmd in self._api_command_list]
 162         self._api_command_list = list()
 163
 164         stdout = self._execute_papi(
 165             paths, method='stats', err_msg=err_msg, timeout=timeout)
 166
 167         return json.loads(stdout)
 168
 169     def get_replies(self, err_msg="Failed to get replies.", timeout=120):
 170         """Get replies from VPP Python API.
 171
 172         The replies are parsed into dict-like objects,
 173         "retval" field is guaranteed to be zero on success.
 174
 175         :param err_msg: The message used if the PAPI command(s) execution fails.
 176         :param timeout: Timeout in seconds.
 177         :type err_msg: str
 178         :type timeout: int
 179         :returns: Responses, dict objects with fields due to API and "retval".
 180         :rtype: list of dict
 181         :raises RuntimeError: If retval is nonzero, parsing or ssh error.
 182         """
 183         return self._execute(method='request', err_msg=err_msg, timeout=timeout)
 184
 185     def get_reply(self, err_msg="Failed to get reply.", timeout=120):
 186         """Get reply from VPP Python API.
 187
 188         The reply is parsed into dict-like object,
 189         "retval" field is guaranteed to be zero on success.
 190
 191         TODO: Discuss exception types to raise, unify with inner methods.
 192
 193         :param err_msg: The message used if the PAPI command(s) execution fails.
 194         :param timeout: Timeout in seconds.
 195         :type err_msg: str
 196         :type timeout: int
 197         :returns: Response, dict object with fields due to API and "retval".
 198         :rtype: dict
 199         :raises AssertionError: If retval is nonzero, parsing or ssh error.
 200         """
 201         replies = self.get_replies(err_msg=err_msg, timeout=timeout)
 202         if len(replies) != 1:
 203             raise RuntimeError("Expected single reply, got {replies!r}".format(
 204                 replies=replies))
 205         return replies[0]
 206
 207     def get_sw_if_index(self, err_msg="Failed to get reply.", timeout=120):
 208         """Get sw_if_index from reply from VPP Python API.
 209
 210         Frequently, the caller is only interested in sw_if_index field
 211         of the reply, this wrapper makes such call sites shorter.
 212
 213         TODO: Discuss exception types to raise, unify with inner methods.
 214
 215         :param err_msg: The message used if the PAPI command(s) execution fails.
 216         :param timeout: Timeout in seconds.
 217         :type err_msg: str
 218         :type timeout: int
 219         :returns: Response, sw_if_index value of the reply.
 220         :rtype: int
 221         :raises AssertionError: If retval is nonzero, parsing or ssh error.
 222         """
 223         return self.get_reply(err_msg=err_msg, timeout=timeout)["sw_if_index"]
 224
 225     def get_details(self, err_msg="Failed to get dump details.", timeout=120):
 226         """Get dump details from VPP Python API.
 227
 228         The details are parsed into dict-like objects.
 229         The number of details per single dump command can vary,
 230         and all association between details and dumps is lost,
 231         so if you care about the association (as opposed to
 232         logging everything at once for debugging purposes),
 233         it is recommended to call get_details for each dump (type) separately.
 234
 235         :param err_msg: The message used if the PAPI command(s) execution fails.
 236         :param timeout: Timeout in seconds.
 237         :type err_msg: str
 238         :type timeout: int
 239         :returns: Details, dict objects with fields due to API without "retval".
 240         :rtype: list of dict
 241         """
 242         return self._execute(method='dump', err_msg=err_msg, timeout=timeout)
 243
 244     @staticmethod
 245     def dump_and_log(node, cmds):
 246         """Dump and log requested information, return None.
 247
 248         :param node: DUT node.
 249         :param cmds: Dump commands to be executed.
 250         :type node: dict
 251         :type cmds: list of str
 252         """
 253         with PapiExecutor(node) as papi_exec:
 254             for cmd in cmds:
 255                 details = papi_exec.add(cmd).get_details()
 256                 logger.debug("{cmd}:\n{details}".format(
 257                     cmd=cmd, details=pformat(details)))
 258
 259     @staticmethod
 260     def run_cli_cmd(node, cmd, log=True):
 261         """Run a CLI command as cli_inband, return the "reply" field of reply.
 262
 263         Optionally, log the field value.
 264
 265         :param node: Node to run command on.
 266         :param cmd: The CLI command to be run on the node.
 267         :param log: If True, the response is logged.
 268         :type node: dict
 269         :type cmd: str
 270         :type log: bool
 271         :returns: CLI output.
 272         :rtype: str
 273         """
 274
 275         cli = 'cli_inband'
 276         args = dict(cmd=cmd)
 277         err_msg = "Failed to run 'cli_inband {cmd}' PAPI command on host " \
 278                   "{host}".format(host=node['host'], cmd=cmd)
 279
 280         with PapiExecutor(node) as papi_exec:
 281             reply = papi_exec.add(cli, **args).get_reply(err_msg)["reply"]
 282
 283         if log:
 284             logger.info("{cmd}:\n{reply}".format(cmd=cmd, reply=reply))
 285
 286         return reply
 287
 288     @staticmethod
 289     def _process_api_data(api_d):
 290         """Process API data for smooth converting to JSON string.
 291
 292         Apply binascii.hexlify() method for string values.
 293
 294         :param api_d: List of APIs with their arguments.
 295         :type api_d: list
 296         :returns: List of APIs with arguments pre-processed for JSON.
 297         :rtype: list
 298         """
 299
 300         def process_value(val):
 301             """Process value.
 302
 303             :param val: Value to be processed.
 304             :type val: object
 305             :returns: Processed value.
 306             :rtype: dict or str or int
 307             """
 308             if isinstance(val, dict):
 309                 for val_k, val_v in val.iteritems():
 310                     val[str(val_k)] = process_value(val_v)
 311                 return val
 312             elif isinstance(val, list):
 313                 for idx, val_l in enumerate(val):
 314                     val[idx] = process_value(val_l)
 315                 return val
 316             else:
 317                 return binascii.hexlify(val) if isinstance(val, str) else val
 318
 319         api_data_processed = list()
 320         for api in api_d:
 321             api_args_processed = dict()
 322             for a_k, a_v in api["api_args"].iteritems():
 323                 api_args_processed[str(a_k)] = process_value(a_v)
 324             api_data_processed.append(dict(api_name=api["api_name"],
 325                                            api_args=api_args_processed))
 326         return api_data_processed
 327
 328     @staticmethod
 329     def _revert_api_reply(api_r):
 330         """Process API reply / a part of API reply.
 331
 332         Apply binascii.unhexlify() method for unicode values.
 333
 334         TODO: Implement complex solution to process of replies.
 335
 336         :param api_r: API reply.
 337         :type api_r: dict
 338         :returns: Processed API reply / a part of API reply.
 339         :rtype: dict
 340         """
 341         def process_value(val):
 342             """Process value.
 343
 344             :param val: Value to be processed.
 345             :type val: object
 346             :returns: Processed value.
 347             :rtype: dict or str or int
 348             """
 349             if isinstance(val, dict):
 350                 for val_k, val_v in val.iteritems():
 351                     val[str(val_k)] = process_value(val_v)
 352                 return val
 353             elif isinstance(val, list):
 354                 for idx, val_l in enumerate(val):
 355                     val[idx] = process_value(val_l)
 356                 return val
 357             elif isinstance(val, unicode):
 358                 return binascii.unhexlify(val)
 359             else:
 360                 return val
 361
 362         reply_dict = dict()
 363         reply_value = dict()
 364         for reply_key, reply_v in api_r.iteritems():
 365             for a_k, a_v in reply_v.iteritems():
 366                 reply_value[a_k] = process_value(a_v)
 367             reply_dict[reply_key] = reply_value
 368         return reply_dict
 369
 370     def _process_reply(self, api_reply):
 371         """Process API reply.
 372
 373         :param api_reply: API reply.
 374         :type api_reply: dict or list of dict
 375         :returns: Processed API reply.
 376         :rtype: list or dict
 377         """
 378         if isinstance(api_reply, list):
 379             reverted_reply = [self._revert_api_reply(a_r) for a_r in api_reply]
 380         else:
 381             reverted_reply = self._revert_api_reply(api_reply)
 382         return reverted_reply
 383
 384     def _execute_papi(self, api_data, method='request', err_msg="",
 385                       timeout=120):
 386         """Execute PAPI command(s) on remote node and store the result.
 387
 388         :param api_data: List of APIs with their arguments.
 389         :param method: VPP Python API method. Supported methods are: 'request',
 390             'dump' and 'stats'.
 391         :param err_msg: The message used if the PAPI command(s) execution fails.
 392         :param timeout: Timeout in seconds.
 393         :type api_data: list
 394         :type method: str
 395         :type err_msg: str
 396         :type timeout: int
 397         :returns: Stdout from remote python utility, to be parsed by caller.
 398         :rtype: str
 399         :raises SSHTimeout: If PAPI command(s) execution has timed out.
 400         :raises RuntimeError: If PAPI executor failed due to another reason.
 401         :raises AssertionError: If PAPI command(s) execution has failed.
 402         """
 403
 404         if not api_data:
 405             raise RuntimeError("No API data provided.")
 406
 407         json_data = json.dumps(api_data) \
 408             if method in ("stats", "stats_request") \
 409             else json.dumps(self._process_api_data(api_data))
 410
 411         cmd = "{fw_dir}/{papi_provider} --method {method} --data '{json}'".\
 412             format(
 413                 fw_dir=Constants.REMOTE_FW_DIR, method=method, json=json_data,
 414                 papi_provider=Constants.RESOURCES_PAPI_PROVIDER)
 415         try:
 416             ret_code, stdout, _ = self._ssh.exec_command_sudo(
 417                 cmd=cmd, timeout=timeout, log_stdout_err=False)
 418         # TODO: Fail on non-empty stderr?
 419         except SSHTimeout:
 420             logger.error("PAPI command(s) execution timeout on host {host}:"
 421                          "\n{apis}".format(host=self._node["host"],
 422                                            apis=api_data))
 423             raise
 424         except Exception as exc:
 425             raise_from(RuntimeError(
 426                 "PAPI command(s) execution on host {host} "
 427                 "failed: {apis}".format(
 428                     host=self._node["host"], apis=api_data)), exc)
 429         if ret_code != 0:
 430             raise AssertionError(err_msg)
 431
 432         return stdout
 433
 434     def _execute(self, method='request', err_msg="", timeout=120):
 435         """Turn internal command list into data and execute; return replies.
 436
 437         This method also clears the internal command list.
 438
 439         IMPORTANT!
 440         Do not use this method in L1 keywords. Use:
 441         - get_stats()
 442         - get_replies()
 443         - get_details()
 444
 445         :param method: VPP Python API method. Supported methods are: 'request',
 446             'dump' and 'stats'.
 447         :param err_msg: The message used if the PAPI command(s) execution fails.
 448         :param timeout: Timeout in seconds.
 449         :type method: str
 450         :type err_msg: str
 451         :type timeout: int
 452         :returns: Papi responses parsed into a dict-like object,
 453             with field due to API or stats hierarchy.
 454         :rtype: list of dict
 455         :raises KeyError: If the reply is not correct.
 456         """
 457
 458         local_list = self._api_command_list
 459
 460         # Clear first as execution may fail.
 461         self._api_command_list = list()
 462
 463         stdout = self._execute_papi(
 464             local_list, method=method, err_msg=err_msg, timeout=timeout)
 465         replies = list()
 466         try:
 467             json_data = json.loads(stdout)
 468         except ValueError as err:
 469             raise_from(RuntimeError(err_msg), err)
 470         for data in json_data:
 471             if method == "request":
 472                 api_reply = self._process_reply(data["api_reply"])
 473                 # api_reply contains single key, *_reply.
 474                 obj = api_reply.values()[0]
 475                 retval = obj["retval"]
 476                 if retval != 0:
 477                     # TODO: What exactly to log and raise here?
 478                     err = AssertionError("Got retval {rv!r}".format(rv=retval))
 479                     raise_from(AssertionError(err_msg), err, level="INFO")
 480                 replies.append(obj)
 481             elif method == "dump":
 482                 api_reply = self._process_reply(data["api_reply"])
 483                 # api_reply is a list where item contas single key, *_details.
 484                 for item in api_reply:
 485                     obj = item.values()[0]
 486                     replies.append(obj)
 487             else:
 488                 # TODO: Implement support for stats.
 489                 raise RuntimeError("Unsuported method {method}".format(
 490                     method=method))
 491
 492         # TODO: Make logging optional?
 493         logger.debug("PAPI replies: {replies}".format(replies=replies))
 494
 495         return replies