Fix MQTT5 Connect Reason Codes

adapters/mqtt-base/src/main/java/org/eclipse/hono/adapter/mqtt/AbstractVertxBasedMqttProtocolAdapter.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2016, 2023 Contributors to the Eclipse Foundation
+ * Copyright (c) 2023 Contributors to the Eclipse Foundation
  *
  * See the NOTICE file(s) distributed with this work for additional
  * information regarding copyright ownership.
@@ -41,6 +41,9 @@
 import org.eclipse.hono.adapter.AbstractProtocolAdapterBase;
 import org.eclipse.hono.adapter.AdapterConnectionsExceededException;
 import org.eclipse.hono.adapter.AuthorizationException;
+import org.eclipse.hono.adapter.ConnectionDurationExceededException;
+import org.eclipse.hono.adapter.DataVolumeExceededException;
+import org.eclipse.hono.adapter.TenantConnectionsExceededException;
 import org.eclipse.hono.adapter.auth.device.AuthHandler;
 import org.eclipse.hono.adapter.auth.device.ChainAuthHandler;
 import org.eclipse.hono.adapter.auth.device.CredentialsApiAuthProvider;
@@ -90,6 +93,7 @@
 import io.netty.handler.codec.mqtt.MqttConnectReturnCode;
 import io.netty.handler.codec.mqtt.MqttProperties;
 import io.netty.handler.codec.mqtt.MqttQoS;
+import io.netty.handler.codec.mqtt.MqttVersion;
 import io.opentracing.Span;
 import io.opentracing.SpanContext;
 import io.opentracing.log.Fields;
@@ -518,7 +522,8 @@ final void handleEndpointConnection(final MqttEndpoint endpoint) {
                     log.debug("rejecting connection request from client [clientId: {}], cause:",
                             endpoint.clientIdentifier(), t);
 
-                    final MqttConnectReturnCode code = getConnectReturnCode(t);
+                    final boolean isPreMqtt5 = ((int) MqttVersion.MQTT_5.protocolLevel()) > endpoint.protocolVersion();
+                    final var code = isPreMqtt5 ? getMqtt3ConnackReturnCode(t) : getMqtt5ConnackReasonCode(t);
                     rejectConnectionRequest(endpoint, code, span);
                     TracingHelper.logError(span, t);
                 }
@@ -1106,18 +1111,18 @@ final MqttDeviceEndpoint createMqttDeviceEndpoint(
         return mqttDeviceEndpoint;
     }
 
-    private static MqttConnectReturnCode getConnectReturnCode(final Throwable e) {
-
-        if (e instanceof MqttConnectionException) {
-            return ((MqttConnectionException) e).code();
-        } else if (e instanceof AuthorizationException) {
-            if (e instanceof AdapterConnectionsExceededException) {
-                return MqttConnectReturnCode.CONNECTION_REFUSED_SERVER_UNAVAILABLE;
-            } else {
-                return MqttConnectReturnCode.CONNECTION_REFUSED_NOT_AUTHORIZED;
-            }
-        } else if (e instanceof ServiceInvocationException) {
-            switch (((ServiceInvocationException) e).getErrorCode()) {
+    private static MqttConnectReturnCode getMqtt3ConnackReturnCode(final Throwable e) {
+        if (e instanceof MqttConnectionException connectionException) {
+            return connectionException.code();
+        }
+        if (e instanceof AdapterConnectionsExceededException) {
+            return MqttConnectReturnCode.CONNECTION_REFUSED_SERVER_UNAVAILABLE;
+        }
+        if (e instanceof AuthorizationException) {
+            return MqttConnectReturnCode.CONNECTION_REFUSED_NOT_AUTHORIZED;
+        }
+        if (e instanceof ServiceInvocationException exception) {
+            switch (exception.getErrorCode()) {
             case HttpURLConnection.HTTP_UNAUTHORIZED:
             case HttpURLConnection.HTTP_NOT_FOUND:
                 return MqttConnectReturnCode.CONNECTION_REFUSED_BAD_USER_NAME_OR_PASSWORD;
@@ -1126,9 +1131,39 @@ private static MqttConnectReturnCode getConnectReturnCode(final Throwable e) {
             default:
                 return MqttConnectReturnCode.CONNECTION_REFUSED_NOT_AUTHORIZED;
             }
-        } else {
-            return MqttConnectReturnCode.CONNECTION_REFUSED_NOT_AUTHORIZED;
         }
+
+        return MqttConnectReturnCode.CONNECTION_REFUSED_NOT_AUTHORIZED;
+    }
+
+    private static MqttConnectReturnCode getMqtt5ConnackReasonCode(final Throwable e) {
+
+        if (e instanceof MqttConnectionException connectionException) {
+            return connectionException.code();
+        }
+        if (e instanceof AdapterConnectionsExceededException) {
+            return MqttConnectReturnCode.CONNECTION_REFUSED_USE_ANOTHER_SERVER;
+        }
+        if (e instanceof TenantConnectionsExceededException
+                || e instanceof DataVolumeExceededException
+                || e instanceof ConnectionDurationExceededException) {
+            return MqttConnectReturnCode.CONNECTION_REFUSED_QUOTA_EXCEEDED;
+        }
+        if (e instanceof AuthorizationException) {
+            return MqttConnectReturnCode.CONNECTION_REFUSED_NOT_AUTHORIZED_5;
+        }
+        if (e instanceof ServiceInvocationException exception) {
+            switch (exception.getErrorCode()) {
+            case HttpURLConnection.HTTP_UNAUTHORIZED:
+            case HttpURLConnection.HTTP_NOT_FOUND:
+                return MqttConnectReturnCode.CONNECTION_REFUSED_BAD_USERNAME_OR_PASSWORD;
+            case HttpURLConnection.HTTP_UNAVAILABLE:
+                return MqttConnectReturnCode.CONNECTION_REFUSED_SERVER_UNAVAILABLE_5;
+            default:
+                return MqttConnectReturnCode.CONNECTION_REFUSED_NOT_AUTHORIZED_5;
+            }
+        }
+        return MqttConnectReturnCode.CONNECTION_REFUSED_UNSPECIFIED_ERROR;
     }
 
     /**

bom/pom.xml

@@ -595,6 +595,12 @@ quarkus.vertx.max-event-loop-execute-time=${max.event-loop.execute-time:20000}
       </dependency>
 
       <!-- Testing -->
+      <dependency>
+        <groupId>com.hivemq</groupId>
+        <artifactId>hivemq-mqtt-client</artifactId>
+        <version>1.3.3</version>
+        <scope>test</scope>
+      </dependency>
       <dependency>
         <groupId>org.eclipse.hono</groupId>
         <artifactId>core-test-utils</artifactId>

site/documentation/content/user-guide/mqtt-adapter.md

@@ -9,7 +9,7 @@ consumers and for receiving commands from applications and sending back response
 
 The MQTT adapter is **not** a general purpose MQTT broker. In particular the adapter
 
-* supports MQTT 3.1.1 only.
+* supports clients connecting using MQTT 3.1.1 or 5.0 only.
 * does not maintain session state for clients and thus always sets the *session present* flag in its CONNACK packet
   to `0`, regardless of the value  of the *clean session* flag provided in a client's CONNECT packet.
 * ignores any *Will* included in a client's CONNECT packet.
@@ -23,7 +23,7 @@ The MQTT adapter is **not** a general purpose MQTT broker. In particular the ada
 ## Authentication
 
 The MQTT adapter by default requires clients (devices or gateway components) to authenticate during connection
-establishment. The adapter supports both the authentication based on the username/password provided in an MQTT CONNECT
+establishment. The adapter supports both authentication based on the username/password provided in an MQTT CONNECT
 packet as well as client certificate based authentication as part of a TLS handshake for that purpose.
 
 The adapter tries to authenticate the device using these mechanisms in the following order
@@ -46,7 +46,8 @@ in order to support this mechanism.
 
 The MQTT adapter supports authenticating clients based on credentials provided during MQTT connection establishment.
 This means that clients need to provide a *user* and a *password* field in their MQTT CONNECT packet as defined in
-[MQTT Version 3.1.1, Section 3.1](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718028)
+[MQTT Version 3.1.1, Section 3.1.3](https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718031)
+and [MQTT Version 5.0, Section 3.1.3](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901058)
 when connecting to the MQTT adapter. The username provided in the *user* field must match the pattern
 *auth-id@tenant*, e.g. `sensor1@DEFAULT_TENANT`.
 
@@ -68,8 +69,9 @@ concepts.
 The MQTT adapter supports authenticating clients based on a signed 
 [JSON Web Token](https://www.rfc-editor.org/rfc/rfc7519) (JWT) provided during MQTT connection establishment. This requires
 a client to provide a *client identifier*, a *user* and a *password* field in its MQTT CONNECT packet as defined in
-[MQTT Version 3.1.1, Section 3.1](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718028)
-when connecting to the MQTT adapter. The JWT must be sent in the password field. The content of the *user* field is
+[MQTT Version 3.1.1, Section 3.1.3](https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718031)
+and [MQTT Version 5.0, Section 3.1.3](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901058)
+when connecting to the MQTT adapter. The JWT must be sent in the *password* field. The content of the *user* field is
 ignored. The information about the tenant and the authentication identifier can be presented to the protocol adapter in
 one of two ways:
 
@@ -107,26 +109,38 @@ a client tries to connect and/or send a message to the adapter.
 
 ### Connection Limits
 
-The adapter rejects a client’s connection attempt with return code
+The adapter rejects a client’s attempt to connect using 
 
-* `0x03` (*Connection Refused: server unavailable*), if the maximum number of connections per protocol adapter instance
-  is reached
-* `0x05` (*Connection Refused: not authorized*), if the maximum number of simultaneously connected devices for the
-  tenant is reached.
+* MQTT 3.1.1 with return code `0x03` (*Server Unavailable*),
+* MQTT 5.0 with reason code `0x9C` (*Use Another Server*),
+
+if the maximum number of connections per protocol adapter instance is reached.
+
+The adapter rejects a client’s attempt to connect using
+
+* MQTT 3.1.1 with return code `0x05` (*Not Authorized*),
+* MQTT 5.0 with reason code `0x97` (*Quota Exceeded*),
+
+if the maximum number of simultaneously connected devices for the tenant is reached.
 
 ### Connection Duration Limits
 
-The adapter rejects a client’s connection attempt with return code `0x05` (*Connection Refused: not authorized*), if the
-[connection duration limit]({{< relref "/concepts/resource-limits#connection-duration-limit" >}}) that has been
-configured for the client’s tenant is exceeded.
+The adapter rejects a client’s attempt to connect using
+
+* MQTT 3.1.1 with return code `0x05` (*Not Authorized*)
+* MQTT 5.0 with reason code `0x97` (*Quota Exceeded*)
+
+if the [connection duration limit]({{< relref "/concepts/resource-limits#connection-duration-limit" >}})
+that has been configured for the client’s tenant is exceeded.
 
 ### Message Limits
 
 The adapter
 
-* rejects a client's connection attempt with return code `0x05` (*Connection Refused: not authorized*),
+* rejects a client's attempt to connect using MQTT 3.1.1 with return code `0x05` (*Not Authorized*),
+* rejects a client's attempt to connect using MQTT 5.0 with reason code `0x97` (*Quota Exceeded*),
 * discards any MQTT PUBLISH packet containing telemetry data or an event that is sent by a client and
-* rejects any AMQP 1.0 message containing a command sent by a north bound application
+* rejects any command messages sent by a north bound application
 
 if the [message limit]({{< relref "/concepts/resource-limits.md" >}}) that has been configured for the device’s tenant
 is exceeded.

tests/pom.xml

@@ -319,6 +319,11 @@
       <artifactId>vertx-mqtt</artifactId>
       <scope>test</scope>
     </dependency>
+    <dependency>
+      <groupId>com.hivemq</groupId>
+      <artifactId>hivemq-mqtt-client</artifactId>
+      <scope>test</scope>
+    </dependency>
     <dependency>
       <groupId>org.eclipse.californium</groupId>
       <artifactId>californium-core</artifactId>

tests/src/test/java/org/eclipse/hono/tests/mqtt/MqttConnectionIT.java

@@ -67,7 +67,7 @@
 import io.vertx.mqtt.MqttConnectionException;
 
 /**
- * Integration tests for checking connection to the MQTT adapter.
+ * Integration tests for checking MQTT 3.1.1 based connection to the MQTT adapter.
  *
  */
 @ExtendWith(VertxExtension.class)

tests/src/test/java/org/eclipse/hono/tests/mqtt/MqttTestBase.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2016, 2023 Contributors to the Eclipse Foundation
+ * Copyright (c) 2023 Contributors to the Eclipse Foundation
  *
  * See the NOTICE file(s) distributed with this work for additional
  * information regarding copyright ownership.
@@ -36,7 +36,7 @@
 import io.vertx.mqtt.messages.MqttConnAckMessage;
 
 /**
- * Base class for MQTT adapter integration tests.
+ * Base class for MQTT adapter integration tests using MQTT 3.1.1.
  *
  */
 public abstract class MqttTestBase {
@@ -70,7 +70,7 @@ public abstract class MqttTestBase {
     protected Context context;
 
     /**
-     * Creates default AMQP client options.
+     * Creates default MQTT client options.
      */
     @BeforeAll
     public static void init() {