Update samples and builder with improved proxy support (#196)

* Update samples and builder with improved proxy support
* Deprecate and don't use old parameter in samples when using websockets
* Doc update

Co-authored-by: Michael Graeb <graebm@amazon.com>

Author: bretambrose

awsiot/mqtt_connection_builder.py

@@ -90,6 +90,8 @@
 
     **enable_metrics_collection** (`bool`): Whether to send the SDK version number in the CONNECT packet.
         Default is True.
+
+    **http_proxy_options** (:class: 'awscrt.http.HttpProxyOptions'): HTTP proxy options to use
 """
 
 # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
@@ -143,7 +145,6 @@ def _builder(
         tls_ctx_options,
         use_websockets=False,
         websocket_handshake_transform=None,
-        websocket_proxy_options=None,
         **kwargs):
 
     ca_bytes = _get(kwargs, 'ca_bytes')
@@ -188,6 +189,7 @@ def _builder(
     tls_ctx = awscrt.io.ClientTlsContext(tls_ctx_options)
     mqtt_client = awscrt.mqtt.Client(client_bootstrap, tls_ctx)
 
+    proxy_options = kwargs.get('http_proxy_options', kwargs.get('websocket_proxy_options', None))
     return awscrt.mqtt.Connection(
         client=mqtt_client,
         on_connection_interrupted=_get(kwargs, 'on_connection_interrupted'),
@@ -207,7 +209,7 @@ def _builder(
         socket_options=socket_options,
         use_websockets=use_websockets,
         websocket_handshake_transform=websocket_handshake_transform,
-        websocket_proxy_options=websocket_proxy_options,
+        proxy_options=proxy_options,
     )
 
 
@@ -264,7 +266,10 @@ def websockets_with_default_aws_signing(
 
         credentials_provider (awscrt.auth.AwsCredentialsProvider): Source of AWS credentials to use when signing.
 
-        websocket_proxy_options (awscrt.http.HttpProxyOptions): If specified, a proxy is used when connecting.
+        websocket_proxy_options (awscrt.http.HttpProxyOptions): Deprecated,
+            for proxy settings use `http_proxy_options` (described in
+            :mod:`common arguments<awsiot.mqtt_connection_builder>`)
+
     """
     _check_required_kwargs(**kwargs)
 
@@ -312,7 +317,9 @@ def websockets_with_custom_handshake(
 
                 *   `**kwargs` (dict): Forward-compatibility kwargs.
 
-        websocket_proxy_options (awscrt.http.HttpProxyOptions): If specified, a proxy is used when connecting.
+        websocket_proxy_options (awscrt.http.HttpProxyOptions):  Deprecated,
+            for proxy settings use `http_proxy_options` (described in
+            :mod:`common arguments<awsiot.mqtt_connection_builder>`)
     """
     _check_required_kwargs(**kwargs)
     tls_ctx_options = awscrt.io.TlsContextOptions()

docs/awsiot/mqtt_connection_builder.html

@@ -133,6 +133,7 @@ <h3>Navigation</h3>
 <dt><strong>enable_metrics_collection</strong> (<cite>bool</cite>): Whether to send the SDK version number in the CONNECT packet.</dt><dd><p>Default is True.</p>
 </dd>
 </dl>
+<p><strong>http_proxy_options</strong> (:class: ‘awscrt.http.HttpProxyOptions’): HTTP proxy options to use</p>
 </div></blockquote>
 <dl class="py function">
 <dt class="sig sig-object py" id="awsiot.mqtt_connection_builder.mtls_from_path">
@@ -186,7 +187,9 @@ <h3>Navigation</h3>
 <dd class="field-odd"><ul class="simple">
 <li><p><strong>region</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a>) – AWS region to use when signing.</p></li>
 <li><p><strong>credentials_provider</strong> (<a class="reference external" href="https://awslabs.github.io/aws-crt-python/api/auth.html#awscrt.auth.AwsCredentialsProvider" title="(in awscrt)"><em>awscrt.auth.AwsCredentialsProvider</em></a>) – Source of AWS credentials to use when signing.</p></li>
-<li><p><strong>websocket_proxy_options</strong> (<a class="reference external" href="https://awslabs.github.io/aws-crt-python/api/http.html#awscrt.http.HttpProxyOptions" title="(in awscrt)"><em>awscrt.http.HttpProxyOptions</em></a>) – If specified, a proxy is used when connecting.</p></li>
+<li><p><strong>websocket_proxy_options</strong> (<a class="reference external" href="https://awslabs.github.io/aws-crt-python/api/http.html#awscrt.http.HttpProxyOptions" title="(in awscrt)"><em>awscrt.http.HttpProxyOptions</em></a>) – Deprecated,
+for proxy settings use <cite>http_proxy_options</cite> (described in
+<a class="reference internal" href="#module-awsiot.mqtt_connection_builder" title="awsiot.mqtt_connection_builder"><code class="xref py py-mod docutils literal notranslate"><span class="pre">common</span> <span class="pre">arguments</span></code></a>)</p></li>
 </ul>
 </dd>
 <dt class="field-even">Return type</dt>
@@ -219,7 +222,9 @@ <h3>Navigation</h3>
 </ul>
 </div></blockquote>
 </p></li>
-<li><p><strong>websocket_proxy_options</strong> (<a class="reference external" href="https://awslabs.github.io/aws-crt-python/api/http.html#awscrt.http.HttpProxyOptions" title="(in awscrt)"><em>awscrt.http.HttpProxyOptions</em></a>) – If specified, a proxy is used when connecting.</p></li>
+<li><p><strong>websocket_proxy_options</strong> (<a class="reference external" href="https://awslabs.github.io/aws-crt-python/api/http.html#awscrt.http.HttpProxyOptions" title="(in awscrt)"><em>awscrt.http.HttpProxyOptions</em></a>) – Deprecated,
+for proxy settings use <cite>http_proxy_options</cite> (described in
+<a class="reference internal" href="#module-awsiot.mqtt_connection_builder" title="awsiot.mqtt_connection_builder"><code class="xref py py-mod docutils literal notranslate"><span class="pre">common</span> <span class="pre">arguments</span></code></a>)</p></li>
 </ul>
 </dd>
 <dt class="field-even">Return type</dt>

docs/searchindex.js

@@ -37,12 +37,11 @@
 parser.add_argument('--client-id', default="test-" + str(uuid4()), help="Client ID for MQTT connection.")
 parser.add_argument('--use-websocket', default=False, action='store_true',
                     help="To use a websocket instead of raw mqtt. If you " +
-                         "specify this option you must specify a region for signing, you can also enable proxy mode.")
+                         "specify this option you must specify a region for signing.")
 parser.add_argument('--signing-region', default='us-east-1', help="If you specify --use-web-socket, this " +
                                                                   "is the region that will be used for computing the Sigv4 signature")
-parser.add_argument('--proxy-host', help="Hostname for proxy to connect to. Note: if you use this feature, " +
-                                         "you will likely need to set --root-ca to the ca for your proxy.")
-parser.add_argument('--proxy-port', type=int, default=8080, help="Port for proxy to connect to.")
+parser.add_argument('--proxy-host', help="Hostname of proxy to connect to.")
+parser.add_argument('--proxy-port', type=int, default=8080, help="Port of proxy to connect to.")
 parser.add_argument('--verbosity', choices=[x.name for x in io.LogLevel], default=io.LogLevel.NoLogs.name,
                     help='Logging level')
 parser.add_argument("--csr", help="File path to your client CSR in PEM format")
@@ -233,18 +232,18 @@ def waitForRegisterThingResponse():
     host_resolver = io.DefaultHostResolver(event_loop_group)
     client_bootstrap = io.ClientBootstrap(event_loop_group, host_resolver)
 
-    if args.use_websocket == True:
-        proxy_options = None
-        if (args.proxy_host):
-            proxy_options = http.HttpProxyOptions(host_name=args.proxy_host, port=args.proxy_port)
+    proxy_options = None
+    if (args.proxy_host):
+        proxy_options = http.HttpProxyOptions(host_name=args.proxy_host, port=args.proxy_port)
 
+    if args.use_websocket == True:
         credentials_provider = auth.AwsCredentialsProvider.new_default_chain(client_bootstrap)
         mqtt_connection = mqtt_connection_builder.websockets_with_default_aws_signing(
             endpoint=args.endpoint,
             client_bootstrap=client_bootstrap,
             region=args.signing_region,
             credentials_provider=credentials_provider,
-            websocket_proxy_options=proxy_options,
+            http_proxy_options=proxy_options,
             on_connection_interrupted=on_connection_interrupted,
             on_connection_resumed=on_connection_resumed,
             ca_filepath=args.root_ca,
@@ -263,7 +262,8 @@ def waitForRegisterThingResponse():
             on_connection_interrupted=on_connection_interrupted,
             on_connection_resumed=on_connection_resumed,
             clean_session=False,
-            keep_alive_secs=6)
+            keep_alive_secs=6,
+            http_proxy_options=proxy_options)
 
     print("Connecting to {} with client ID '{}'...".format(
         args.endpoint, args.client_id))

samples/fleetprovisioning.py

@@ -46,12 +46,11 @@
 parser.add_argument('--job-time', default=5, type=float, help="Emulate working on job by sleeping this many seconds.")
 parser.add_argument('--use-websocket', default=False, action='store_true',
     help="To use a websocket instead of raw mqtt. If you " +
-    "specify this option you must specify a region for signing, you can also enable proxy mode.")
+    "specify this option you must specify a region for signing.")
 parser.add_argument('--signing-region', default='us-east-1', help="If you specify --use-web-socket, this " +
     "is the region that will be used for computing the Sigv4 signature")
-parser.add_argument('--proxy-host', help="Hostname for proxy to connect to. Note: if you use this feature, " +
-    "you will likely need to set --root-ca to the ca for your proxy.")
-parser.add_argument('--proxy-port', type=int, default=8080, help="Port for proxy to connect to.")
+parser.add_argument('--proxy-host', help="Hostname of proxy to connect to.")
+parser.add_argument('--proxy-port', type=int, default=8080, help="Port of proxy to connect to.")
 parser.add_argument('--verbosity', choices=[x.name for x in io.LogLevel], default=io.LogLevel.NoLogs.name,
     help='Logging level')
 
@@ -230,18 +229,18 @@ def on_update_job_execution_rejected(rejected):
     host_resolver = io.DefaultHostResolver(event_loop_group)
     client_bootstrap = io.ClientBootstrap(event_loop_group, host_resolver)
 
-    if args.use_websocket == True:
-        proxy_options = None
-        if (args.proxy_host):
-            proxy_options = http.HttpProxyOptions(host_name=args.proxy_host, port=args.proxy_port)
+    proxy_options = None
+    if (args.proxy_host):
+        proxy_options = http.HttpProxyOptions(host_name=args.proxy_host, port=args.proxy_port)
 
+    if args.use_websocket == True:
         credentials_provider = auth.AwsCredentialsProvider.new_default_chain(client_bootstrap)
         mqtt_connection = mqtt_connection_builder.websockets_with_default_aws_signing(
             endpoint=args.endpoint,
             client_bootstrap=client_bootstrap,
             region=args.signing_region,
             credentials_provider=credentials_provider,
-            websocket_proxy_options=proxy_options,
+            http_proxy_options=proxy_options,
             ca_filepath=args.root_ca,
             client_id=args.client_id,
             clean_session=False,
@@ -256,7 +255,8 @@ def on_update_job_execution_rejected(rejected):
             ca_filepath=args.root_ca,
             client_id=args.client_id,
             clean_session=False,
-            keep_alive_secs=6)
+            keep_alive_secs=6,
+            http_proxy_options=proxy_options)
 
     print("Connecting to {} with client ID '{}'...".format(
         args.endpoint, args.client_id))

samples/jobs.py

@@ -32,12 +32,11 @@
                                                           "Specify 0 to run forever.")
 parser.add_argument('--use-websocket', default=False, action='store_true',
     help="To use a websocket instead of raw mqtt. If you " +
-    "specify this option you must specify a region for signing, you can also enable proxy mode.")
+    "specify this option you must specify a region for signing.")
 parser.add_argument('--signing-region', default='us-east-1', help="If you specify --use-web-socket, this " +
     "is the region that will be used for computing the Sigv4 signature")
-parser.add_argument('--proxy-host', help="Hostname for proxy to connect to. Note: if you use this feature, " +
-    "you will likely need to set --root-ca to the ca for your proxy.")
-parser.add_argument('--proxy-port', type=int, default=8080, help="Port for proxy to connect to.")
+parser.add_argument('--proxy-host', help="Hostname of proxy to connect to.")
+parser.add_argument('--proxy-port', type=int, default=8080, help="Port of proxy to connect to.")
 parser.add_argument('--verbosity', choices=[x.name for x in io.LogLevel], default=io.LogLevel.NoLogs.name,
     help='Logging level')
 
@@ -90,18 +89,18 @@ def on_message_received(topic, payload, dup, qos, retain, **kwargs):
     host_resolver = io.DefaultHostResolver(event_loop_group)
     client_bootstrap = io.ClientBootstrap(event_loop_group, host_resolver)
 
-    if args.use_websocket == True:
-        proxy_options = None
-        if (args.proxy_host):
-            proxy_options = http.HttpProxyOptions(host_name=args.proxy_host, port=args.proxy_port)
+    proxy_options = None
+    if (args.proxy_host):
+        proxy_options = http.HttpProxyOptions(host_name=args.proxy_host, port=args.proxy_port)
 
+    if args.use_websocket == True:
         credentials_provider = auth.AwsCredentialsProvider.new_default_chain(client_bootstrap)
         mqtt_connection = mqtt_connection_builder.websockets_with_default_aws_signing(
             endpoint=args.endpoint,
             client_bootstrap=client_bootstrap,
             region=args.signing_region,
             credentials_provider=credentials_provider,
-            websocket_proxy_options=proxy_options,
+            http_proxy_options=proxy_options,
             ca_filepath=args.root_ca,
             on_connection_interrupted=on_connection_interrupted,
             on_connection_resumed=on_connection_resumed,
@@ -121,7 +120,8 @@ def on_message_received(topic, payload, dup, qos, retain, **kwargs):
             on_connection_resumed=on_connection_resumed,
             client_id=args.client_id,
             clean_session=False,
-            keep_alive_secs=6)
+            keep_alive_secs=6,
+            http_proxy_options=proxy_options)
 
     print("Connecting to {} with client ID '{}'...".format(
         args.endpoint, args.client_id))

samples/pubsub.py

@@ -43,12 +43,11 @@
 parser.add_argument('--shadow-property', default="color", help="Name of property in shadow to keep in sync")
 parser.add_argument('--use-websocket', default=False, action='store_true',
     help="To use a websocket instead of raw mqtt. If you " +
-    "specify this option you must specify a region for signing, you can also enable proxy mode.")
+    "specify this option you must specify a region for signing.")
 parser.add_argument('--signing-region', default='us-east-1', help="If you specify --use-web-socket, this " +
     "is the region that will be used for computing the Sigv4 signature")
-parser.add_argument('--proxy-host', help="Hostname for proxy to connect to. Note: if you use this feature, " +
-    "you will likely need to set --root-ca to the ca for your proxy.")
-parser.add_argument('--proxy-port', type=int, default=8080, help="Port for proxy to connect to.")
+parser.add_argument('--proxy-host', help="Hostname of proxy to connect to.")
+parser.add_argument('--proxy-port', type=int, default=8080, help="Port of proxy to connect to.")
 parser.add_argument('--verbosity', choices=[x.name for x in io.LogLevel], default=io.LogLevel.NoLogs.name,
     help='Logging level')
 
@@ -232,18 +231,18 @@ def user_input_thread_fn():
     host_resolver = io.DefaultHostResolver(event_loop_group)
     client_bootstrap = io.ClientBootstrap(event_loop_group, host_resolver)
 
-    if args.use_websocket == True:
-        proxy_options = None
-        if (args.proxy_host):
-            proxy_options = http.HttpProxyOptions(host_name=args.proxy_host, port=args.proxy_port)
+    proxy_options = None
+    if (args.proxy_host):
+        proxy_options = http.HttpProxyOptions(host_name=args.proxy_host, port=args.proxy_port)
 
+    if args.use_websocket == True:
         credentials_provider = auth.AwsCredentialsProvider.new_default_chain(client_bootstrap)
         mqtt_connection = mqtt_connection_builder.websockets_with_default_aws_signing(
             endpoint=args.endpoint,
             client_bootstrap=client_bootstrap,
             region=args.signing_region,
             credentials_provider=credentials_provider,
-            websocket_proxy_options=proxy_options,
+            http_proxy_options=proxy_options,
             ca_filepath=args.root_ca,
             client_id=args.client_id,
             clean_session=False,
@@ -258,7 +257,8 @@ def user_input_thread_fn():
             ca_filepath=args.root_ca,
             client_id=args.client_id,
             clean_session=False,
-            keep_alive_secs=6)
+            keep_alive_secs=6,
+            http_proxy_options=proxy_options)
 
     print("Connecting to {} with client ID '{}'...".format(
         args.endpoint, args.client_id))

samples/shadow.py

@@ -40,7 +40,7 @@ def _load_version():
         "Operating System :: OS Independent",
     ],
     install_requires=[
-        'awscrt==0.11.19',
+        'awscrt==0.11.20',
     ],
     python_requires='>=3.6',
 )