Refactor subscribe_xpaths into Client

Author: remingtonc

README.md

@@ -257,12 +257,12 @@ cisco-gnmi capabilities 127.0.0.1:57500 -auto_ssl_target_override
 ```
 cisco-gnmi capabilities --help
 usage: cisco-gnmi [-h] [-os {None,IOS XR,NX-OS,IOS XE}]
-              [-root_certificates ROOT_CERTIFICATES]
-              [-private_key PRIVATE_KEY]
-              [-certificate_chain CERTIFICATE_CHAIN]
-              [-ssl_target_override SSL_TARGET_OVERRIDE]
-              [-auto_ssl_target_override] [-debug]
-              netloc
+                  [-root_certificates ROOT_CERTIFICATES]
+                  [-private_key PRIVATE_KEY]
+                  [-certificate_chain CERTIFICATE_CHAIN]
+                  [-ssl_target_override SSL_TARGET_OVERRIDE]
+                  [-auto_ssl_target_override] [-debug]
+                  netloc
 
 Performs Capabilities RPC against network element.
 
@@ -309,16 +309,17 @@ cisco-gnmi get 127.0.0.1:57500 -os "IOS XR" -xpath /interfaces/interface/state/c
 
 #### Usage
 ```
+cisco-gnmi get --help
 usage: cisco-gnmi [-h] [-xpath XPATH]
-              [-encoding [{JSON,BYTES,PROTO,ASCII,JSON_IETF}]]
-              [-data_type [{ALL,CONFIG,STATE,OPERATIONAL}]] [-dump_json]
-              [-os {None,IOS XR,NX-OS,IOS XE}]
-              [-root_certificates ROOT_CERTIFICATES]
-              [-private_key PRIVATE_KEY]
-              [-certificate_chain CERTIFICATE_CHAIN]
-              [-ssl_target_override SSL_TARGET_OVERRIDE]
-              [-auto_ssl_target_override] [-debug]
-              netloc
+                  [-encoding {JSON,BYTES,PROTO,ASCII,JSON_IETF}]
+                  [-data_type {ALL,CONFIG,STATE,OPERATIONAL}] [-dump_json]
+                  [-os {None,IOS XR,NX-OS,IOS XE}]
+                  [-root_certificates ROOT_CERTIFICATES]
+                  [-private_key PRIVATE_KEY]
+                  [-certificate_chain CERTIFICATE_CHAIN]
+                  [-ssl_target_override SSL_TARGET_OVERRIDE]
+                  [-auto_ssl_target_override] [-debug]
+                  netloc
 
 Performs Get RPC against network element.
 
@@ -328,9 +329,9 @@ positional arguments:
 optional arguments:
   -h, --help            show this help message and exit
   -xpath XPATH          XPaths to Get.
-  -encoding [{JSON,BYTES,PROTO,ASCII,JSON_IETF}]
+  -encoding {JSON,BYTES,PROTO,ASCII,JSON_IETF}
                         gNMI Encoding.
-  -data_type [{ALL,CONFIG,STATE,OPERATIONAL}]
+  -data_type {ALL,CONFIG,STATE,OPERATIONAL}
                         gNMI GetRequest DataType
   -dump_json            Dump as JSON instead of textual protos.
   -os {None,IOS XR,NX-OS,IOS XE}
@@ -381,16 +382,17 @@ Please note that `Set` operations may be destructive to operations and should be
 
 #### Usage
 ```
+cisco-gnmi set --help
 usage: cisco-gnmi [-h] [-update_json_config UPDATE_JSON_CONFIG]
-              [-replace_json_config REPLACE_JSON_CONFIG]
-              [-delete_xpath DELETE_XPATH] [-no_ietf] [-dump_json]
-              [-os {None,IOS XR,NX-OS,IOS XE}]
-              [-root_certificates ROOT_CERTIFICATES]
-              [-private_key PRIVATE_KEY]
-              [-certificate_chain CERTIFICATE_CHAIN]
-              [-ssl_target_override SSL_TARGET_OVERRIDE]
-              [-auto_ssl_target_override] [-debug]
-              netloc
+                  [-replace_json_config REPLACE_JSON_CONFIG]
+                  [-delete_xpath DELETE_XPATH] [-no_ietf] [-dump_json]
+                  [-os {None,IOS XR,NX-OS,IOS XE}]
+                  [-root_certificates ROOT_CERTIFICATES]
+                  [-private_key PRIVATE_KEY]
+                  [-certificate_chain CERTIFICATE_CHAIN]
+                  [-ssl_target_override SSL_TARGET_OVERRIDE]
+                  [-auto_ssl_target_override] [-debug]
+                  netloc
 
 Performs Set RPC against network element.
 
@@ -469,24 +471,28 @@ interface Loopback9339
 ```
 
 ### Subscribe
-This command will output the `SubscribeResponse` to `stdout` or `-dump_file`. `-xpath` may be specified multiple times to specify multiple `Path`s for the `GetRequest`. Subscribe currently only supports a sampled stream. `ON_CHANGE` is possible but not implemented in the CLI, yet. :)
+This command will output the `SubscribeResponse` to `stdout` or `-dump_file`. `-xpath` may be specified multiple times to specify multiple `Path`s for the `GetRequest`.
+
 ```
 cisco-gnmi subscribe 127.0.0.1:57500 -os "IOS XR" -xpath /interfaces/interface/state/counters -auto_ssl_target_override
 ```
 
 #### Usage
 ```
 cisco-gnmi subscribe --help
-usage: cisco-gnmi [-h] [-xpath XPATH] [-interval INTERVAL] [-dump_file DUMP_FILE]
-              [-dump_json] [-sync_stop]
-              [-encoding [{JSON,BYTES,PROTO,ASCII,JSON_IETF}]]
-              [-os {None,IOS XR,NX-OS,IOS XE}]
-              [-root_certificates ROOT_CERTIFICATES]
-              [-private_key PRIVATE_KEY]
-              [-certificate_chain CERTIFICATE_CHAIN]
-              [-ssl_target_override SSL_TARGET_OVERRIDE]
-              [-auto_ssl_target_override] [-debug]
-              netloc
+usage: cisco-gnmi [-h] [-xpath XPATH] [-interval INTERVAL]
+                  [-mode {TARGET_DEFINED,ON_CHANGE,SAMPLE}]
+                  [-suppress_redundant]
+                  [-heartbeat_interval HEARTBEAT_INTERVAL]
+                  [-dump_file DUMP_FILE] [-dump_json] [-sync_stop]
+                  [-sync_start] [-encoding {JSON,BYTES,PROTO,ASCII,JSON_IETF}]
+                  [-os {None,IOS XR,NX-OS,IOS XE}]
+                  [-root_certificates ROOT_CERTIFICATES]
+                  [-private_key PRIVATE_KEY]
+                  [-certificate_chain CERTIFICATE_CHAIN]
+                  [-ssl_target_override SSL_TARGET_OVERRIDE]
+                  [-auto_ssl_target_override] [-debug]
+                  netloc
 
 Performs Subscribe RPC against network element.
 
@@ -498,11 +504,18 @@ optional arguments:
   -xpath XPATH          XPath to subscribe to.
   -interval INTERVAL    Sample interval in seconds for Subscription. Defaults
                         to 10.
+  -mode {TARGET_DEFINED,ON_CHANGE,SAMPLE}
+                        SubscriptionMode for Subscription. Defaults to SAMPLE.
+  -suppress_redundant   Suppress redundant information in Subscription.
+  -heartbeat_interval HEARTBEAT_INTERVAL
+                        Heartbeat interval in seconds.
   -dump_file DUMP_FILE  Filename to dump to. Defaults to stdout.
   -dump_json            Dump as JSON instead of textual protos.
   -sync_stop            Stop on sync_response.
-  -encoding [{JSON,BYTES,PROTO,ASCII,JSON_IETF}]
-                        gNMI Encoding.
+  -sync_start           Start processing messages after sync_response.
+  -encoding {JSON,BYTES,PROTO,ASCII,JSON_IETF}
+                        gNMI Encoding. Defaults to whatever Client wrapper
+                        prefers.
   -os {None,IOS XR,NX-OS,IOS XE}
                         OS wrapper to utilize. Defaults to IOS XR.
   -root_certificates ROOT_CERTIFICATES

src/cisco_gnmi/cli.py

@@ -91,8 +91,7 @@ def gnmi_capabilities():
 
 
 def gnmi_subscribe():
-    """Performs a sampled Subscribe against network element.
-    TODO: ON_CHANGE
+    """Performs a streaming Subscribe against network element.
     """
     parser = argparse.ArgumentParser(
         description="Performs Subscribe RPC against network element."
@@ -106,6 +105,20 @@ def gnmi_subscribe():
         type=int,
         default=10,
     )
+    parser.add_argument(
+        "-mode",
+        help="SubscriptionMode for Subscription. Defaults to SAMPLE.",
+        default="SAMPLE",
+        choices=proto.gnmi_pb2.SubscriptionMode.keys(),
+    )
+    parser.add_argument(
+        "-suppress_redundant",
+        help="Suppress redundant information in Subscription.",
+        action="store_true",
+    )
+    parser.add_argument(
+        "-heartbeat_interval", help="Heartbeat interval in seconds.", type=int
+    )
     parser.add_argument(
         "-dump_file",
         help="Filename to dump to. Defaults to stdout.",
@@ -120,11 +133,15 @@ def gnmi_subscribe():
     parser.add_argument(
         "-sync_stop", help="Stop on sync_response.", action="store_true"
     )
+    parser.add_argument(
+        "-sync_start",
+        help="Start processing messages after sync_response.",
+        action="store_true",
+    )
     parser.add_argument(
         "-encoding",
-        help="gNMI Encoding.",
+        help="gNMI Encoding. Defaults to whatever Client wrapper prefers.",
         type=str,
-        nargs="?",
         choices=proto.gnmi_pb2.Encoding.keys(),
     )
     args = __common_args_handler(parser)
@@ -138,20 +155,30 @@ def gnmi_subscribe():
         kwargs["encoding"] = args.encoding
     if args.interval:
         kwargs["sample_interval"] = args.interval * int(1e9)
+    if args.mode:
+        kwargs["sub_mode"] = args.mode
+    if args.suppress_redundant:
+        kwargs["suppress_redundant"] = args.suppress_redundant
+    if args.heartbeat_interval:
+        kwargs["heartbeat_interval"] = args.heartbeat_interval * int(1e9)
     try:
-        logging.info(
+        logging.debug(
             "Dumping responses to %s as %s ...",
             args.dump_file,
             "JSON" if args.dump_json else "textual proto",
         )
-        logging.info("Subscribing to:\n%s", "\n".join(args.xpath))
+        logging.debug("Subscribing to:\n%s", "\n".join(args.xpath))
+        synced = False
         for subscribe_response in client.subscribe_xpaths(args.xpath, **kwargs):
             logging.debug("SubscribeResponse received.")
             if subscribe_response.sync_response:
                 logging.debug("sync_response received.")
                 if args.sync_stop:
                     logging.warning("Stopping on sync_response.")
                     break
+                synced = True
+            if not synced and args.sync_start:
+                continue
             formatted_message = __format_message(subscribe_response)
             if args.dump_file == "stdout":
                 logging.info(formatted_message)
@@ -175,14 +202,12 @@ def gnmi_get():
         "-encoding",
         help="gNMI Encoding.",
         type=str,
-        nargs="?",
         choices=proto.gnmi_pb2.Encoding.keys(),
     )
     parser.add_argument(
         "-data_type",
         help="gNMI GetRequest DataType",
         type=str,
-        nargs="?",
         choices=enum_type_wrapper.EnumTypeWrapper(
             proto.gnmi_pb2._GETREQUEST_DATATYPE
         ).keys(),

src/cisco_gnmi/client.py

@@ -251,6 +251,140 @@ def validate_request(request):
         )
         return response_stream
 
+    def subscribe_xpaths(
+        self,
+        xpath_subscriptions,
+        request_mode="STREAM",
+        sub_mode="SAMPLE",
+        encoding="JSON",
+        sample_interval=_NS_IN_S * 10,
+        suppress_redundant=False,
+        heartbeat_interval=None,
+    ):
+        """A convenience wrapper of subscribe() which aids in building of SubscriptionRequest
+        with request as subscribe SubscriptionList. This method accepts an iterable of simply xpath strings,
+        dictionaries with Subscription attributes for more granularity, or already built Subscription
+        objects and builds the SubscriptionList. Fields not supplied will be defaulted with the default arguments
+        to the method.
+
+        Generates a single SubscribeRequest.
+
+        Parameters
+        ----------
+        xpath_subscriptions : str or iterable of str, dict, Subscription
+            An iterable which is parsed to form the Subscriptions in the SubscriptionList to be passed
+            to SubscriptionRequest. Strings are parsed as XPaths and defaulted with the default arguments,
+            dictionaries are treated as dicts of args to pass to the Subscribe init, and Subscription is
+            treated as simply a pre-made Subscription.
+        request_mode : proto.gnmi_pb2.SubscriptionList.Mode, optional
+            Indicates whether STREAM to stream from target,
+            ONCE to stream once (like a get),
+            POLL to respond to POLL.
+            [STREAM, ONCE, POLL]
+        sub_mode : proto.gnmi_pb2.SubscriptionMode, optional
+            The default SubscriptionMode on a per Subscription basis in the SubscriptionList.
+            TARGET_DEFINED indicates that the target (like device/destination) should stream
+            information however it knows best. This instructs the target to decide between ON_CHANGE
+            or SAMPLE - e.g. the device gNMI server may understand that we only need RIB updates
+            as an ON_CHANGE basis as opposed to SAMPLE, and we don't have to explicitly state our
+            desired behavior.
+            ON_CHANGE only streams updates when changes occur.
+            SAMPLE will stream the subscription at a regular cadence/interval.
+            [TARGET_DEFINED, ON_CHANGE, SAMPLE]
+        encoding : proto.gnmi_pb2.Encoding, optional
+            A member of the proto.gnmi_pb2.Encoding enum specifying desired encoding of returned data
+            [JSON, BYTES, PROTO, ASCII, JSON_IETF]
+        sample_interval : int, optional
+            Default nanoseconds for SAMPLE to occur.
+            Defaults to 10 seconds.
+        suppress_redundant : bool, optional
+            Indicates whether values that have not changed should be sent in a SAMPLE subscription.
+        heartbeat_interval : int, optional
+            Specifies the maximum allowable silent period in nanoseconds when
+            suppress_redundant is in use. The target should send a value at least once
+            in the period specified. Also applies in ON_CHANGE.
+
+        Returns
+        -------
+        subscribe()
+        """
+        subscription_list = proto.gnmi_pb2.SubscriptionList()
+        subscription_list.mode = util.validate_proto_enum(
+            "mode",
+            request_mode,
+            "SubscriptionList.Mode",
+            proto.gnmi_pb2.SubscriptionList.Mode,
+        )
+        subscription_list.encoding = util.validate_proto_enum(
+            "encoding", encoding, "Encoding", proto.gnmi_pb2.Encoding
+        )
+        if isinstance(
+            xpath_subscriptions, (string_types, dict, proto.gnmi_pb2.Subscription)
+        ):
+            xpath_subscriptions = [xpath_subscriptions]
+        subscriptions = []
+        for xpath_subscription in xpath_subscriptions:
+            subscription = None
+            if isinstance(xpath_subscription, proto.gnmi_pb2.Subscription):
+                subscription = xpath_subscription
+            elif isinstance(xpath_subscription, string_types):
+                subscription = proto.gnmi_pb2.Subscription()
+                subscription.path.CopyFrom(
+                    self.parse_xpath_to_gnmi_path(xpath_subscription)
+                )
+                subscription.mode = util.validate_proto_enum(
+                    "sub_mode",
+                    sub_mode,
+                    "SubscriptionMode",
+                    proto.gnmi_pb2.SubscriptionMode,
+                )
+                if sub_mode == "SAMPLE":
+                    subscription.sample_interval = sample_interval
+            elif isinstance(xpath_subscription, dict):
+                subscription_dict = {}
+                if "path" not in xpath_subscription.keys():
+                    raise Exception("path must be specified in dict!")
+                if isinstance(xpath_subscription["path"], proto.gnmi_pb2.Path):
+                    subscription_dict["path"] = xpath_subscription["path"]
+                elif isinstance(xpath_subscription["path"], string_types):
+                    subscription_dict["path"] = self.parse_xpath_to_gnmi_path(
+                        xpath_subscription["path"]
+                    )
+                else:
+                    raise Exception("path must be string or Path proto!")
+                sub_mode_name = (
+                    sub_mode
+                    if "mode" not in xpath_subscription.keys()
+                    else xpath_subscription["mode"]
+                )
+                subscription_dict["mode"] = util.validate_proto_enum(
+                    "sub_mode",
+                    sub_mode,
+                    "SubscriptionMode",
+                    proto.gnmi_pb2.SubscriptionMode,
+                )
+                if sub_mode_name == "SAMPLE":
+                    subscription_dict["sample_interval"] = (
+                        sample_interval
+                        if "sample_interval" not in xpath_subscription.keys()
+                        else xpath_subscription["sample_interval"]
+                    )
+                    if "suppress_redundant" in xpath_subscription.keys():
+                        subscription_dict["suppress_redundant"] = xpath_subscription[
+                            "suppress_redundant"
+                        ]
+                if sub_mode_name != "TARGET_DEFINED":
+                    if "heartbeat_interval" in xpath_subscription.keys():
+                        subscription_dict["heartbeat_interval"] = xpath_subscription[
+                            "heartbeat_interval"
+                        ]
+                subscription = proto.gnmi_pb2.Subscription(**subscription_dict)
+            else:
+                raise Exception("path must be string, dict, or Subscription proto!")
+            subscriptions.append(subscription)
+        subscription_list.subscription.extend(subscriptions)
+        return self.subscribe([subscription_list])
+
     def parse_xpath_to_gnmi_path(self, xpath, origin=None):
         """Parses an XPath to proto.gnmi_pb2.Path.
         This function should be overridden by any child classes for origin logic.