Soft deprecation of MQTT 3.1.1 and V1 Service Clients

.github/workflows/ci.yml

@@ -42,7 +42,9 @@ jobs:
     - name: Build ${{ env.PACKAGE_NAME }}
       run: |
         aws s3 cp s3://aws-crt-test-stuff/ci/${{ env.BUILDER_VERSION }}/linux-container-ci.sh ./linux-container-ci.sh && chmod a+x ./linux-container-ci.sh
-        ./linux-container-ci.sh ${{ env.BUILDER_VERSION }} aws-crt-${{ matrix.image }} build -p ${{ env.PACKAGE_NAME }} --cmake-extra=-DUSE_OPENSSL=ON
+        ./linux-container-ci.sh ${{ env.BUILDER_VERSION }} aws-crt-${{ matrix.image }} build -p ${{ env.PACKAGE_NAME }} \
+        --cmake-extra=-DUSE_OPENSSL=ON \
+        --cmake-extra=-DAWS_CRT_DISABLE_DEPRECATION_WARNINGS=ON
 
   # These linux-compat images need to run without -DUSE_OPENSSL because they do not have OpenSSL packages
   # that are up-to-date (AL2) or don't provide OpenSSL development packages that is found in CMake (alpine)
@@ -72,7 +74,8 @@ jobs:
     - name: Build ${{ env.PACKAGE_NAME }}
       run: |
         aws s3 cp s3://aws-crt-test-stuff/ci/${{ env.BUILDER_VERSION }}/linux-container-ci.sh ./linux-container-ci.sh && chmod a+x ./linux-container-ci.sh
-        ./linux-container-ci.sh ${{ env.BUILDER_VERSION }} aws-crt-${{ matrix.image }} build -p ${{ env.PACKAGE_NAME }}
+        ./linux-container-ci.sh ${{ env.BUILDER_VERSION }} aws-crt-${{ matrix.image }} build -p ${{ env.PACKAGE_NAME }} \
+        --cmake-extra=-DAWS_CRT_DISABLE_DEPRECATION_WARNINGS=ON
 
   linux-compiler-compat:
     runs-on: ubuntu-24.04 # latest
@@ -105,7 +108,9 @@ jobs:
     - name: Build ${{ env.PACKAGE_NAME }}
       run: |
         aws s3 cp s3://aws-crt-test-stuff/ci/${{ env.BUILDER_VERSION }}/linux-container-ci.sh ./linux-container-ci.sh && chmod a+x ./linux-container-ci.sh
-        ./linux-container-ci.sh ${{ env.BUILDER_VERSION }} aws-crt-${{ env.LINUX_BASE_IMAGE }} build -p ${{ env.PACKAGE_NAME }} --compiler=${{ matrix.compiler }} --cmake-extra=-DUSE_OPENSSL=ON
+        ./linux-container-ci.sh ${{ env.BUILDER_VERSION }} aws-crt-${{ env.LINUX_BASE_IMAGE }} build -p ${{ env.PACKAGE_NAME }} --compiler=${{ matrix.compiler }} \
+        --cmake-extra=-DUSE_OPENSSL=ON \
+        --cmake-extra=-DAWS_CRT_DISABLE_DEPRECATION_WARNINGS=ON
 
   raspberry:
     runs-on: ubuntu-24.04 # latest
@@ -145,7 +150,10 @@ jobs:
     - name: Build ${{ env.PACKAGE_NAME }} with cxx${{ matrix.cxx-std }}
       run: |
         aws s3 cp s3://aws-crt-test-stuff/ci/${{ env.BUILDER_VERSION }}/linux-container-ci.sh ./linux-container-ci.sh && chmod a+x ./linux-container-ci.sh
-        ./linux-container-ci.sh ${{ env.BUILDER_VERSION }} aws-crt-${{ env.LINUX_BASE_IMAGE }} build -p ${{ env.PACKAGE_NAME }} --compiler=${{ matrix.compiler }} --cmake-extra=-DUSE_OPENSSL=ON --cmake-extra=-DCMAKE_CXX_STANDARD=${{ matrix.cxx-std }}
+        ./linux-container-ci.sh ${{ env.BUILDER_VERSION }} aws-crt-${{ env.LINUX_BASE_IMAGE }} build -p ${{ env.PACKAGE_NAME }} --compiler=${{ matrix.compiler }} \
+        --cmake-extra=-DUSE_OPENSSL=ON \
+        --cmake-extra=-DCMAKE_CXX_STANDARD=${{ matrix.cxx-std }} \
+        --cmake-extra=-DAWS_CRT_DISABLE_DEPRECATION_WARNINGS=ON
 
   byo-crypto:
     runs-on: ubuntu-24.04 # latest
@@ -158,7 +166,10 @@ jobs:
     - name: Build ${{ env.PACKAGE_NAME }}
       run: |
         aws s3 cp s3://aws-crt-test-stuff/ci/${{ env.BUILDER_VERSION }}/linux-container-ci.sh ./linux-container-ci.sh && chmod a+x ./linux-container-ci.sh
-        ./linux-container-ci.sh ${{ env.BUILDER_VERSION }} aws-crt-${{ env.LINUX_BASE_IMAGE }} build -p ${{ env.PACKAGE_NAME }} --cmake-extra=-DBYO_CRYPTO=ON --cmake-extra=-DUSE_OPENSSL=ON
+        ./linux-container-ci.sh ${{ env.BUILDER_VERSION }} aws-crt-${{ env.LINUX_BASE_IMAGE }} build -p ${{ env.PACKAGE_NAME }} \
+        --cmake-extra=-DBYO_CRYPTO=ON \
+        --cmake-extra=-DUSE_OPENSSL=ON \
+        --cmake-extra=-DAWS_CRT_DISABLE_DEPRECATION_WARNINGS=ON
 
   linux-shared-libs:
     runs-on: ubuntu-24.04 # latest
@@ -175,7 +186,9 @@ jobs:
     - name: Build ${{ env.PACKAGE_NAME }}
       run: |
         aws s3 cp s3://aws-crt-test-stuff/ci/${{ env.BUILDER_VERSION }}/linux-container-ci.sh ./linux-container-ci.sh && chmod a+x ./linux-container-ci.sh
-        ./linux-container-ci.sh ${{ env.BUILDER_VERSION }} aws-crt-${{ env.LINUX_BASE_IMAGE }} build -p ${{ env.PACKAGE_NAME }} --compiler=${{ matrix.compiler }} --cmake-extra=-DBUILD_SHARED_LIBS=ON
+        ./linux-container-ci.sh ${{ env.BUILDER_VERSION }} aws-crt-${{ env.LINUX_BASE_IMAGE }} build -p ${{ env.PACKAGE_NAME }} --compiler=${{ matrix.compiler }} \
+        --cmake-extra=-DBUILD_SHARED_LIBS=ON \
+        --cmake-extra=-DAWS_CRT_DISABLE_DEPRECATION_WARNINGS=ON
 
   linux-glibcxx-ancient-abi:
     runs-on: ubuntu-24.04 # latest
@@ -187,7 +200,11 @@ jobs:
     - name: Build ${{ env.PACKAGE_NAME }}
       run: |
         aws s3 cp s3://aws-crt-test-stuff/ci/${{ env.BUILDER_VERSION }}/linux-container-ci.sh ./linux-container-ci.sh && chmod a+x ./linux-container-ci.sh
-        ./linux-container-ci.sh ${{ env.BUILDER_VERSION }} aws-crt-${{ env.LINUX_BASE_IMAGE }} build -p ${{ env.PACKAGE_NAME }} --compiler=gcc-11 --cmake-extra=-DBUILD_SHARED_LIBS=ON --cmake-extra=-DCMAKE_CXX_FLAGS=-D_GLIBCXX_USE_CXX11_ABI=0
+        ./linux-container-ci.sh ${{ env.BUILDER_VERSION }} aws-crt-${{ env.LINUX_BASE_IMAGE }} build -p ${{ env.PACKAGE_NAME }} --compiler=gcc-11 \
+        --cmake-extra=-DBUILD_SHARED_LIBS=ON \
+        --cmake-extra=-DCMAKE_CXX_FLAGS=-D_GLIBCXX_USE_CXX11_ABI=0 \
+        --cmake-extra="-DCMAKE_C_FLAGS=-DAWS_CRT_DISABLE_DEPRECATION_WARNINGS" \
+        --cmake-extra="-DCMAKE_CXX_FLAGS=-DAWS_CRT_DISABLE_DEPRECATION_WARNINGS"
 
   linux-openssl-static:
     runs-on: ubuntu-24.04 # latest
@@ -200,7 +217,9 @@ jobs:
     - name: Build ${{ env.PACKAGE_NAME }}
       run: |
         aws s3 cp s3://aws-crt-test-stuff/ci/${{ env.BUILDER_VERSION }}/linux-container-ci.sh ./linux-container-ci.sh && chmod a+x ./linux-container-ci.sh
-        ./linux-container-ci.sh ${{ env.BUILDER_VERSION }} aws-crt-${{ env.LINUX_BASE_IMAGE }} build -p ${{ env.PACKAGE_NAME }} --variant=openssl --cmake-extra=-DUSE_OPENSSL=ON
+        ./linux-container-ci.sh ${{ env.BUILDER_VERSION }} aws-crt-${{ env.LINUX_BASE_IMAGE }} build -p ${{ env.PACKAGE_NAME }} --variant=openssl \
+        --cmake-extra=-DUSE_OPENSSL=ON \
+        --cmake-extra=-DAWS_CRT_DISABLE_DEPRECATION_WARNINGS=ON
 
   linux-openssl-shared:
     runs-on: ubuntu-24.04 # latest
@@ -213,7 +232,10 @@ jobs:
     - name: Build ${{ env.PACKAGE_NAME }}
       run: |
         aws s3 cp s3://aws-crt-test-stuff/ci/${{ env.BUILDER_VERSION }}/linux-container-ci.sh ./linux-container-ci.sh && chmod a+x ./linux-container-ci.sh
-        ./linux-container-ci.sh ${{ env.BUILDER_VERSION }} aws-crt-${{ env.LINUX_BASE_IMAGE }} build -p ${{ env.PACKAGE_NAME }} --variant=openssl --cmake-extra=-DUSE_OPENSSL=ON --cmake-extra=-DBUILD_SHARED_LIBS=ON
+        ./linux-container-ci.sh ${{ env.BUILDER_VERSION }} aws-crt-${{ env.LINUX_BASE_IMAGE }} build -p ${{ env.PACKAGE_NAME }} --variant=openssl \
+        --cmake-extra=-DUSE_OPENSSL=ON \
+        --cmake-extra=-DBUILD_SHARED_LIBS=ON \
+        --cmake-extra=-DAWS_CRT_DISABLE_DEPRECATION_WARNINGS=ON
 
   linux-no-cpu-extensions:
     runs-on: ubuntu-24.04 # latest
@@ -226,7 +248,10 @@ jobs:
     - name: Build ${{ env.PACKAGE_NAME }}
       run: |
         aws s3 cp s3://aws-crt-test-stuff/ci/${{ env.BUILDER_VERSION }}/linux-container-ci.sh ./linux-container-ci.sh && chmod a+x ./linux-container-ci.sh
-        ./linux-container-ci.sh ${{ env.BUILDER_VERSION }} aws-crt-${{ env.LINUX_BASE_IMAGE }} build -p ${{ env.PACKAGE_NAME }} --cmake-extra=-DUSE_CPU_EXTENSIONS=OFF --cmake-extra=-DUSE_OPENSSL=ON
+        ./linux-container-ci.sh ${{ env.BUILDER_VERSION }} aws-crt-${{ env.LINUX_BASE_IMAGE }} build -p ${{ env.PACKAGE_NAME }} \
+        --cmake-extra=-DUSE_CPU_EXTENSIONS=OFF \
+        --cmake-extra=-DUSE_OPENSSL=ON \
+        --cmake-extra=-DAWS_CRT_DISABLE_DEPRECATION_WARNINGS=ON
 
   windows:
     runs-on: windows-2025 # latest
@@ -236,6 +261,8 @@ jobs:
         role-to-assume: ${{ env.CRT_CI_ROLE }}
         aws-region: ${{ env.AWS_DEFAULT_REGION }}
     - name: Build ${{ env.PACKAGE_NAME }} + consumers
+      env:
+        CL: "/DAWS_CRT_DISABLE_DEPRECATION_WARNINGS /EHsc"
       run: |
         python -c "from urllib.request import urlretrieve; urlretrieve('${{ env.BUILDER_HOST }}/${{ env.BUILDER_SOURCE }}/${{ env.BUILDER_VERSION }}/builder.pyz?run=${{ env.RUN }}', 'builder.pyz')"
         python builder.pyz build -p ${{ env.PACKAGE_NAME }}
@@ -245,6 +272,7 @@ jobs:
     env:
       CFLAGS: "-DWIN32_LEAN_AND_MEAN"
       CXXFLAGS: "-DWIN32_LEAN_AND_MEAN"
+      CL: "/DAWS_CRT_DISABLE_DEPRECATION_WARNINGS /EHsc"
     steps:
     - uses: aws-actions/configure-aws-credentials@v4
       with:
@@ -267,6 +295,8 @@ jobs:
         role-to-assume: ${{ env.CRT_CI_ROLE }}
         aws-region: ${{ env.AWS_DEFAULT_REGION }}
     - name: Build ${{ env.PACKAGE_NAME }} + consumers
+      env:
+        CL: "/DAWS_CRT_DISABLE_DEPRECATION_WARNINGS /EHsc"
       run: |
         python -c "from urllib.request import urlretrieve; urlretrieve('${{ env.BUILDER_HOST }}/${{ env.BUILDER_SOURCE }}/${{ env.BUILDER_VERSION }}/builder.pyz?run=${{ env.RUN }}', 'builder.pyz')"
         python builder.pyz build -p ${{ env.PACKAGE_NAME }} --compiler msvc-17 --target windows-${{ matrix.arch }}
@@ -279,6 +309,8 @@ jobs:
         role-to-assume: ${{ env.CRT_CI_ROLE }}
         aws-region: ${{ env.AWS_DEFAULT_REGION }}
     - name: Build ${{ env.PACKAGE_NAME }} + consumers
+      env:
+        CL: "/DAWS_CRT_DISABLE_DEPRECATION_WARNINGS /EHsc"
       run: |
         python -c "from urllib.request import urlretrieve; urlretrieve('${{ env.BUILDER_HOST }}/${{ env.BUILDER_SOURCE }}/${{ env.BUILDER_VERSION }}/builder.pyz?run=${{ env.RUN }}', 'builder.pyz')"
         python builder.pyz build -p ${{ env.PACKAGE_NAME }} --cmake-extra=-DBUILD_SHARED_LIBS=ON
@@ -297,6 +329,8 @@ jobs:
         role-to-assume: ${{ env.CRT_CI_ROLE }}
         aws-region: ${{ env.AWS_DEFAULT_REGION }}
     - name: Build ${{ env.PACKAGE_NAME }} + consumers
+      env:
+        CL: "/DAWS_CRT_DISABLE_DEPRECATION_WARNINGS /EHsc"
       run: |
         python -c "from urllib.request import urlretrieve; urlretrieve('${{ env.BUILDER_HOST }}/${{ env.BUILDER_SOURCE }}/${{ env.BUILDER_VERSION }}/builder.pyz?run=${{ env.RUN }}', 'builder.pyz')"
         python builder.pyz build -p ${{ env.PACKAGE_NAME }} --cmake-extra=-DBUILD_SHARED_LIBS=ON
@@ -309,6 +343,8 @@ jobs:
         role-to-assume: ${{ env.CRT_CI_ROLE }}
         aws-region: ${{ env.AWS_DEFAULT_REGION }}
     - name: Build ${{ env.PACKAGE_NAME }} + consumers
+      env:
+        CL: "/DAWS_CRT_DISABLE_DEPRECATION_WARNINGS /EHsc"
       run: |
         python -c "from urllib.request import urlretrieve; urlretrieve('${{ env.BUILDER_HOST }}/${{ env.BUILDER_SOURCE }}/${{ env.BUILDER_VERSION }}/builder.pyz?run=${{ env.RUN }}', 'builder.pyz')"
         python builder.pyz build -p ${{ env.PACKAGE_NAME }} --cmake-extra=-DUSE_CPU_EXTENSIONS=OFF
@@ -353,7 +389,8 @@ jobs:
       run: |
         python3 -c "from urllib.request import urlretrieve; urlretrieve('${{ env.BUILDER_HOST }}/${{ env.BUILDER_SOURCE }}/${{ env.BUILDER_VERSION }}/builder.pyz?run=${{ env.RUN }}', 'builder')"
         chmod a+x builder
-        ./builder build -p ${{ env.PACKAGE_NAME }} --target=ios-arm64 --cmake-extra=-DCMAKE_XCODE_ATTRIBUTE_CODE_SIGNING_ALLOWED=NO
+        ./builder build -p ${{ env.PACKAGE_NAME }} --target=ios-arm64 \
+        --cmake-extra=-DCMAKE_XCODE_ATTRIBUTE_CODE_SIGNING_ALLOWED=NO
 
   cross_compile:
     name: Cross Compile ${{matrix.arch}}
@@ -362,7 +399,6 @@ jobs:
       fail-fast: false
       matrix:
         arch: [linux-armv6, linux-armv7, linux-arm64, android-armv7]
-
     steps:
     - uses: aws-actions/configure-aws-credentials@v4
       with:
@@ -372,7 +408,8 @@ jobs:
       run: |
         python3 -c "from urllib.request import urlretrieve; urlretrieve('${{ env.BUILDER_HOST }}/${{ env.BUILDER_SOURCE }}/${{ env.BUILDER_VERSION }}/builder.pyz?run=${{ env.RUN }}', 'builder')"
         chmod a+x builder
-        ./builder build -p aws-crt-cpp --spec=downstream --target=${{matrix.arch}} run_tests=false
+        ./builder build -p aws-crt-cpp --spec=downstream --target=${{matrix.arch}} run_tests=false \
+        --cmake-extra=-DAWS_CRT_DISABLE_DEPRECATION_WARNINGS=ON
 
   # check that docs can still build
   check-docs:
@@ -422,4 +459,6 @@ jobs:
     - name: Build ${{ env.PACKAGE_NAME }}
       run: |
         aws s3 cp s3://aws-crt-test-stuff/ci/${{ env.BUILDER_VERSION }}/linux-container-ci.sh ./linux-container-ci.sh && chmod a+x ./linux-container-ci.sh
-        ./linux-container-ci.sh ${{ env.BUILDER_VERSION }} aws-crt-${{ env.LINUX_BASE_IMAGE }} build -p ${{ env.PACKAGE_NAME }} --compiler=clang-12 --cmake-extra=-DENABLE_SANITIZERS=ON --cmake-extra=-DSANITIZERS="${{ matrix.sanitizers }}"
+        ./linux-container-ci.sh ${{ env.BUILDER_VERSION }} aws-crt-${{ env.LINUX_BASE_IMAGE }} build -p ${{ env.PACKAGE_NAME }} --compiler=clang-12 \
+        --cmake-extra=-DENABLE_SANITIZERS=ON \
+        --cmake-extra=-DSANITIZERS="${{ matrix.sanitizers }}"

CMakeLists.txt

@@ -4,6 +4,10 @@ option(BUILD_DEPS "Builds aws common runtime dependencies as part of build. Turn
 option(BYO_CRYPTO "Don't build a tls implementation or link against a crypto interface. This feature is only for unix builds currently" OFF)
 option(USE_OPENSSL "Set this if you want to use your system's OpenSSL 1.0.2/1.1.1 compatible libcrypto" OFF)
 option(ENFORCE_SUBMODULE_VERSIONS "Check and enforce submodule versions to verify they are the minimum expected version or later. Versioning is only checked if BUILD_DEPS is ON." ON)
+option(AWS_CRT_DISABLE_DEPRECATION_WARNINGS "Set this to silence [[deprecated]] warnings coming from aws-crt-cpp headers" OFF)
+if(AWS_CRT_DISABLE_DEPRECATION_WARNINGS)
+    add_compile_definitions(AWS_CRT_DISABLE_DEPRECATION_WARNINGS)
+endif()
 
 # Let aws-iot-device-sdk-cpp-v2 report its own version in MQTT connections (instead of reporting aws-crt-cpp's version).
 option(AWS_IOT_SDK_VERSION "Set the version reported by Aws::Iot::MqttClientConnectionConfigBuilder")

codebuild/linux-integration-tests.yml

@@ -24,7 +24,7 @@ phases:
       - git submodule update --init
       # Build using builder, which will also run tests
       - python3 -c "from urllib.request import urlretrieve; urlretrieve('$BUILDER_HOST/$BUILDER_SOURCE/$BUILDER_VERSION/builder.pyz?run=$CODEBUILD_BUILD_ID', 'builder.pyz')"
-      - python3 builder.pyz build --project aws-crt-cpp downstream --cmake-extra=-DUSE_OPENSSL=ON
+      - python3 builder.pyz build --project aws-crt-cpp downstream --cmake-extra=-DUSE_OPENSSL=ON --cmake-extra=-DAWS_CRT_DISABLE_DEPRECATION_WARNINGS=ON
   post_build:
     commands:
       - echo Build completed on `date`

docsrc/Doxyfile

@@ -2284,15 +2284,15 @@ ENABLE_PREPROCESSING   = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
 # the macro expansion is limited to the macros specified with the PREDEFINED and
 # EXPAND_AS_DEFINED tags.
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_ONLY_PREDEF     = NO
+EXPAND_ONLY_PREDEF     = YES
 
 # If the SEARCH_INCLUDES tag is set to YES, the include files in the
 # INCLUDE_PATH will be searched if a #include is found.
@@ -2325,7 +2325,8 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             =
+PREDEFINED             += AWS_CRT_SOFT_DEPRECATED(x)=
+PREDEFINED             += AWS_CRT_CPP_API=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

include/aws/crt/Exports.h

@@ -36,3 +36,30 @@
 #        define AWS_CRT_CPP_API
 #    endif
 #endif
+
+/*
+ * Deprecation warnings are emitted unless callers compile with -DAWS_CRT_DISABLE_DEPRECATION_WARNINGS=ON.
+ */
+#ifndef AWS_CRT_SOFT_DEPRECATED
+#    if !defined(AWS_CRT_DISABLE_DEPRECATION_WARNINGS)
+/* On compilers that support __has_atribute check whether the `deprecated` attribute exists */
+#        if defined(__has_attribute)
+#            if __has_attribute(deprecated)
+#                define AWS_CRT_SOFT_DEPRECATED(msg) __attribute__((deprecated(msg)))
+#            endif
+#        endif
+/* Otherwise we fallback to standard C++14 or MSVC syntax */
+#        if !defined(AWS_CRT_SOFT_DEPRECATED)
+#            if __cplusplus >= 201402L /* C++14 supports [[deprecated]] */
+#                define AWS_CRT_SOFT_DEPRECATED(msg) [[deprecated(msg)]]
+#            elif defined(_MSC_VER) /* Older MSVC */
+#                define AWS_CRT_SOFT_DEPRECATED(msg) __declspec(deprecated(msg))
+#            else /* Unknown compiler. Do nothing. */
+#                define AWS_CRT_SOFT_DEPRECATED(msg)
+#            endif
+#        endif
+#    else
+/* If AWS_CRT_DISABLE_DEPRECATION_WARNINGS do nothing */
+#        define AWS_CRT_SOFT_DEPRECATED(msg)
+#    endif
+#endif

include/aws/crt/mqtt/MqttClient.h

@@ -32,27 +32,41 @@ namespace Aws
             class HttpRequest;
         }
 
-        namespace Mqtt5
-        {
-            class Mqtt5ClientCore;
-        }
-
         namespace Mqtt
         {
             /**
+             * @deprecated We strongly recommend using the Aws::Crt::Mqtt5::Mqtt5Client. There are no current plans to
+             * fully deprecate the MQTT 3.1.1 client but it is highly recommended customers migrate to the MQTT5 client
+             * to access a more robust feature set, clearer error handling, and lifetime management. More details can be
+             * found in the GitHub Repo FAQ
+             *
              * An MQTT client. This is a move-only type. Unless otherwise specified,
              * all function arguments need only to live through the duration of the
              * function call.
              */
-            class AWS_CRT_CPP_API MqttClient final
+            class AWS_CRT_CPP_API AWS_CRT_SOFT_DEPRECATED(
+                "We strongly recommend using the Aws::Crt::Mqtt5::Mqtt5Client. There are no current plans to fully "
+                "deprecate the MQTT 3.1.1 client but it is highly recommended customers migrate to the MQTT5 client to "
+                "access a more robust feature set, clearer error handling, and lifetime management. More details can "
+                "be found in the GitHub Repo FAQ") MqttClient final
             {
               public:
                 /**
+                 * @deprecated We strongly recommend using the Aws::Crt::Mqtt5::Mqtt5Client. There are no current plans
+                 * to fully deprecate the MQTT 3.1.1 client but it is highly recommended customers migrate to the MQTT5
+                 * client to access a more robust feature set, clearer error handling, and lifetime management. More
+                 * details can be found in the GitHub Repo FAQ
+                 *
                  * Initialize an MqttClient using bootstrap and allocator
                  */
                 MqttClient(Io::ClientBootstrap &bootstrap, Allocator *allocator = ApiAllocator()) noexcept;
 
                 /**
+                 * @deprecated We strongly recommend using the Aws::Crt::Mqtt5::Mqtt5Client. There are no current plans
+                 * to fully deprecate the MQTT 3.1.1 client but it is highly recommended customers migrate to the MQTT5
+                 * client to access a more robust feature set, clearer error handling, and lifetime management. More
+                 * details can be found in the GitHub Repo FAQ
+                 *
                  * Initialize an MqttClient using a allocator and the default ClientBootstrap
                  *
                  * For more information on the default ClientBootstrap see