pr changes

sbSteveK · sbSteveK · commit 581e34fd5f12 · 2026-04-14T09:45:01.000-07:00
diff --git a/documents/MQTT5_Userguide.md b/documents/MQTT5_Userguide.md
@@ -23,9 +23,9 @@
     + [Client Operations](#client-operations)
         + [Publish](#publish)
         + [Subscribe and Unsubscribe](#subscribe-and-unsubscribe)
+    + [Advanced Operations and Settings](#advanced-operations-and-settings)
+        * [Manual Publish Acknowledgement](#manual-publish-acknowledgement)
     + [MQTT5 Best Practices](#mqtt5-best-practices)
-* [Advanced Operations and Settings](#advanced-operations-and-settings)
-    + [Manual Publish Acknowledgement](#manual-publish-acknowledgement)
 
 # Introduction
 
@@ -556,17 +556,6 @@ unsubBuilder.withSubscription("hello/world/qos1");
 client.unsubscribe(unsubBuilder.build()).get(60, TimeUnit.SECONDS);
 ~~~
 
-## MQTT5 Best Practices
-
-Below are some best practices for the MQTT5 client that are recommended to follow for the best development experience:
-
-* When creating MQTT5 clients, make sure to use ClientIDs that are unique! If you connect two MQTT5 clients with the same ClientID, they will Disconnect each other! If you do not configure a ClientID, the MQTT5 server will automatically assign one.
-* Use the minimum QoS you can get away with for the lowest latency and bandwidth costs. For example, if you are sending data consistently multiple times per second and do not have to have a guarantee the server got each and every publish, using QoS 0 may be ideal compared to QoS 1. Of course, this heavily depends on your use case but generally it is recommended to use the lowest QoS possible.
-* If you are getting unexpected disconnects when trying to connect to AWS IoT Core, make sure to check your IoT Core Thing’s policy and permissions to make sure your device is has the permissions it needs to connect!
-* Make sure to always call `close()` when finished a MQTT5 client to avoid native resource leaks!
-* For [publish](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/Mqtt5Client.html#publish(software.amazon.awssdk.crt.mqtt5.packets.PublishPacket)), [subscribe](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/Mqtt5Client.html#subscribe(software.amazon.awssdk.crt.mqtt5.packets.SubscribePacket)), and [unsubscribe](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/Mqtt5Client.html#unsubscribe(software.amazon.awssdk.crt.mqtt5.packets.UnsubscribePacket)), make sure to check the reason codes in the ACK ([PubAckPacket](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/packets/PubAckPacket.html), [SubAckPacket](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/packets/SubAckPacket.html), and [UnsubAckPacket](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/packets/UnsubAckPacket.html) respectively) to see if the operation actually succeeded.
-* You MUST NOT perform blocking operations on any callback, or you will cause a deadlock. For example: in the `onMessageReceived` callback, do not send a publish, and then wait for the future to complete within the callback. The Client cannot do work until your callback returns, so the thread will be stuck.
-
 ## Advanced Operations and Settings
 
 ### Manual Publish Acknowledgement
@@ -576,7 +565,7 @@ By default, the MQTT5 client automatically sends a PUBACK for every QoS 1 PUBLIS
 To take manual control of the PUBACK, call `publishReturn.acquirePublishAcknowledgementControl()` **within** the `onMessageReceived` callback. This returns a `Mqtt5PublishAcknowledgementControlHandle` that you can store and use later to send the PUBACK by calling `client.invokePublishAcknowledgement()`.
 
 **Important constraints:**
-* `acquirePublishAcknowledgementControl()` must be called within the `onMessageReceived` callback. Calling it outside the callback or after it returns will return `null`.
+* `acquirePublishAcknowledgementControl()` must be called within the `onMessageReceived` callback. Calling it outside the callback after it returns or from a different thread will return `null`.
 * `acquirePublishAcknowledgementControl()` may only be called once per received PUBLISH. Subsequent calls will return `null`.
 * This is only relevant for QoS 1 messages. Calling it on a QoS 0 message will return `null`.
 * If `acquirePublishAcknowledgementControl()` is not called, the client will automatically send the PUBACK when the callback returns.
@@ -617,3 +606,22 @@ if (handle != null) {
     client.invokePublishAcknowledgement(handle);
 }
 ~~~
+
+**AWS IoT broker redelivery behavior**
+
+The AWS IoT broker will periodically resend unacknowledged QoS 1 PUBLISH packets. These redeliveries should be treated as duplicates even if the DUP flag in the PUBLISH packet is not set. If `acquirePublishAcknowledgementControl()` is not called again for a redelivered packet, the acknowledgement will be sent automatically.
+
+**Session resumption after disconnect/reconnect**
+
+Upon a disconnect and reconnect of the MQTT5 client, if a session is resumed, any previously acquired `Mqtt5PublishAcknowledgementControlHandle` is void. The broker will resend the unacknowledged PUBLISH packet, and `acquirePublishAcknowledgementControl()` must be called again within the callback for that resent packet. If the resent packet is not handled for manual acknowledgement, the acknowledgement will be sent automatically.
+
+## MQTT5 Best Practices
+
+Below are some best practices for the MQTT5 client that are recommended to follow for the best development experience:
+
+* When creating MQTT5 clients, make sure to use ClientIDs that are unique! If you connect two MQTT5 clients with the same ClientID, they will Disconnect each other! If you do not configure a ClientID, the MQTT5 server will automatically assign one.
+* Use the minimum QoS you can get away with for the lowest latency and bandwidth costs. For example, if you are sending data consistently multiple times per second and do not have to have a guarantee the server got each and every publish, using QoS 0 may be ideal compared to QoS 1. Of course, this heavily depends on your use case but generally it is recommended to use the lowest QoS possible.
+* If you are getting unexpected disconnects when trying to connect to AWS IoT Core, make sure to check your IoT Core Thing's policy and permissions to make sure your device is has the permissions it needs to connect!
+* Make sure to always call `close()` when finished a MQTT5 client to avoid native resource leaks!
+* For [publish](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/Mqtt5Client.html#publish(software.amazon.awssdk.crt.mqtt5.packets.PublishPacket)), [subscribe](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/Mqtt5Client.html#subscribe(software.amazon.awssdk.crt.mqtt5.packets.SubscribePacket)), and [unsubscribe](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/Mqtt5Client.html#unsubscribe(software.amazon.awssdk.crt.mqtt5.packets.UnsubscribePacket)), make sure to check the reason codes in the ACK ([PubAckPacket](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/packets/PubAckPacket.html), [SubAckPacket](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/packets/SubAckPacket.html), and [UnsubAckPacket](https://awslabs.github.io/aws-crt-java/software/amazon/awssdk/crt/mqtt5/packets/UnsubAckPacket.html) respectively) to see if the operation actually succeeded.
+* You MUST NOT perform blocking operations on any callback, or you will cause a deadlock. For example: in the `onMessageReceived` callback, do not send a publish, and then wait for the future to complete within the callback. The Client cannot do work until your callback returns, so the thread will be stuck.
