[#2026] Adding config property HONO_MQTT_SEND_MESSAGE_TO_DEVICE_TIMEOUT

Adding a new configuration property for MQTT adapter called "HONO_MQTT_SEND_MESSAGE_TO_DEVICE_TIMEOUT" which will replace the current "HONO_MQTT_COMMAND_ACK_TIMEOUT" property. This is done in order to provide an abstraction for the configuration of protocols using a bidirectional connection (i.e. MQTT and AMQP).

This fixes #2026

Signed-off-by: Florian Kaltner <[email protected]>

Author: fkaltner

Diff for: adapters/amqp-vertx/src/main/java/org/eclipse/hono/adapter/amqp/AmqpAdapterProperties.java

@@ -38,7 +38,7 @@ public class AmqpAdapterProperties extends ProtocolAdapterProperties {
      */
     public static final int DEFAULT_IDLE_TIMEOUT_MILLIS = 60_000;
     /**
-     * The amount of time (in milliseconds) to wait for a device to acknowledge receiving a command message. 
+     * The amount of time (in milliseconds) to wait for a device to acknowledge receiving a command message.
      */
     public static final long DEFAULT_SEND_MESSAGE_TO_DEVICE_TIMEOUT = 1000L; // ms
 

Diff for: adapters/mqtt-vertx-base/src/main/java/org/eclipse/hono/adapter/mqtt/CommandSubscriptionsManager.java

@@ -72,7 +72,9 @@ public void handlePubAck(final Integer msgId) {
         Objects.requireNonNull(msgId);
         LOG.trace("Acknowledgement received for command [Msg-id: {}] that has been sent to device", msgId);
         Optional.ofNullable(removeFromWaitingForAcknowledgement(msgId)).ifPresent(value -> {
-            cancelTimer(value.timerId);
+            if (value.timerId != null) {
+                cancelTimer(value.timerId);
+            }
             value.onAckHandler.handle(msgId);
         });
     }
@@ -193,9 +195,12 @@ private Future<Void> closeCommandConsumer(final CommandSubscription subscription
                 });
     }
 
-    private long startTimer(final Integer msgId) {
+    private Long startTimer(final Integer msgId) {
+        if (config.getEffectiveSendMessageToDeviceTimeout() < 1) {
+            return null;
+        }
 
-        return vertx.setTimer(config.getCommandAckTimeout(), timerId -> {
+        return vertx.setTimer(config.getEffectiveSendMessageToDeviceTimeout(), timerId -> {
             Optional.ofNullable(removeFromWaitingForAcknowledgement(msgId))
                     .ifPresent(value -> value.onAckTimeoutHandler.handle(null));
         });
@@ -218,7 +223,7 @@ private static class PendingCommandRequest {
 
         private PendingCommandRequest(final Long timerId, final Handler<Integer> onAckHandler,
                 final Handler<Void> onAckTimeoutHandler) {
-            this.timerId = Objects.requireNonNull(timerId);
+            this.timerId = timerId;
             this.onAckHandler = Objects.requireNonNull(onAckHandler);
             this.onAckTimeoutHandler = Objects.requireNonNull(onAckTimeoutHandler);
         }

Diff for: adapters/mqtt-vertx-base/src/main/java/org/eclipse/hono/adapter/mqtt/MqttProtocolAdapterProperties.java

@@ -25,37 +25,100 @@ public class MqttProtocolAdapterProperties extends ProtocolAdapterProperties {
      * The default number of milliseconds to wait for PUBACK.
      */
     protected static final int DEFAULT_COMMAND_ACK_TIMEOUT = 100;
+    /**
+     * The amount of time (in milliseconds) to wait for a device to acknowledge receiving a command message.
+     */
+    protected static final long DEFAULT_SEND_MESSAGE_TO_DEVICE_TIMEOUT = 1000L; // ms
+
     private int commandAckTimeout = DEFAULT_COMMAND_ACK_TIMEOUT;
+    private long sendMessageToDeviceTimeout = DEFAULT_SEND_MESSAGE_TO_DEVICE_TIMEOUT;
 
     /**
-     * Gets the waiting for acknowledgement time out in milliseconds for commands published with QoS 1.
+     * Gets the waiting for acknowledgement timeout in milliseconds for commands published with QoS 1.
      * <p>
-     * This time out is used by the MQTT adapter for commands published with QoS 1. If there is no acknowledgement
+     * This timeout is used by the MQTT adapter for commands published with QoS 1. If there is no acknowledgement
      * within this time limit, then the command is settled with the <em>released</em> outcome.
      * <p>
      * The default value is {@link #DEFAULT_COMMAND_ACK_TIMEOUT}.
      *
-     * @return The time out in milliseconds.
+     * @deprecated Use {@link #getSendMessageToDeviceTimeout()} instead.
+     *
+     * @return The timeout in milliseconds.
      */
+    @Deprecated(forRemoval = true)
     public final int getCommandAckTimeout() {
         return commandAckTimeout;
     }
 
     /**
-     * Sets the waiting for acknowledgement time out in milliseconds for commands published with QoS 1.
+     * Sets the waiting for acknowledgement timeout in milliseconds for commands published with QoS 1.
      * <p>
-     * This time out is used by the MQTT adapter for commands published with QoS 1. If there is no acknowledgement
+     * This timeout is used by the MQTT adapter for commands published with QoS 1. If there is no acknowledgement
      * within this time limit, then the command is settled with the <em>released</em> outcome.
      * <p>
      * The default value is {@link #DEFAULT_COMMAND_ACK_TIMEOUT}.
      *
-     * @param timeout The time out in milliseconds.
+     * @deprecated Use {@link #setSendMessageToDeviceTimeout(long)} ()} instead.
+     *
+     * @param timeout The timeout in milliseconds.
      * @throws IllegalArgumentException if the timeout is negative.
      */
+    @Deprecated(forRemoval = true)
     public final void setCommandAckTimeout(final int timeout) {
         if (timeout < 0) {
             throw new IllegalArgumentException("timeout must not be negative");
         }
         this.commandAckTimeout = timeout;
     }
+
+    /**
+     * Gets the waiting for acknowledgement timeout in milliseconds for commands published with QoS 1.
+     * <p>
+     * This timeout is used by the MQTT adapter for commands published with QoS 1. If there is no acknowledgement
+     * within this time limit, then the command is settled with the <em>released</em> outcome.
+     * <p>
+     * The default value of this property is {@link #DEFAULT_SEND_MESSAGE_TO_DEVICE_TIMEOUT}.
+     *
+     * @return The timeout in milliseconds.
+     */
+    public long getSendMessageToDeviceTimeout() {
+        return sendMessageToDeviceTimeout;
+    }
+
+    /**
+     * Sets the waiting for acknowledgement timeout in milliseconds for commands published with QoS 1.
+     * <p>
+     * This timeout is used by the MQTT adapter for commands published with QoS 1. If there is no acknowledgement
+     * within this time limit, then the command is settled with the <em>released</em> outcome.
+     * <p>
+     * The default value of this property is {@link #DEFAULT_SEND_MESSAGE_TO_DEVICE_TIMEOUT}.
+     *
+     * @param sendMessageToDeviceTimeout The timeout in milliseconds.
+     * @throws IllegalArgumentException if the timeout is negative.
+     */
+    public void setSendMessageToDeviceTimeout(final long sendMessageToDeviceTimeout) {
+        if (sendMessageToDeviceTimeout < 0) {
+            throw new IllegalArgumentException("timeout must not be negative");
+        }
+
+        this.sendMessageToDeviceTimeout = sendMessageToDeviceTimeout;
+    }
+
+    /**
+     * Gets the effective timeout for waiting for acknowledgement in milliseconds for commands published with QoS 1
+     * by taking the {@link #sendMessageToDeviceTimeout} and {@link #commandAckTimeout} properties into account.
+     *
+     * Can be removed when the deprecated {@link #commandAckTimeout} property is removed.
+     *
+     * @return The timeout in milliseconds.
+     */
+    long getEffectiveSendMessageToDeviceTimeout() {
+        if (sendMessageToDeviceTimeout == DEFAULT_SEND_MESSAGE_TO_DEVICE_TIMEOUT
+                && commandAckTimeout != DEFAULT_COMMAND_ACK_TIMEOUT) {
+            return commandAckTimeout;
+        } else {
+            return sendMessageToDeviceTimeout;
+        }
+    }
+
 }

Diff for: site/documentation/content/admin-guide/kura-adapter-config.md

@@ -44,6 +44,7 @@ The following table provides an overview of the configuration variables and corr
 | `HONO_KURA_PORT`<br>`--hono.kura.port` | no | `8883` | The secure port that the protocol adapter should listen on.<br>See [Port Configuration]({{< relref "#port-configuration" >}}) below for details. |
 | `HONO_KURA_SECURE_PROTOCOLS`<br>`--hono.kura.secureProtocols` | no | `TLSv1.2` | A (comma separated) list of secure protocols that are supported when negotiating TLS sessions. Please refer to the [vert.x documentation](https://vertx.io/docs/vertx-core/java/#ssl) for a list of supported protocol names. |
 | `HONO_KURA_TENANT_IDLE_TIMEOUT`<br>`--hono.kura.tenantIdleTimeout` | no | `0ms` | The duration after which the protocol adapter removes local state of the tenant (e.g. open AMQP links) with an amount and a unit, e.g. `2h` for 2 hours. See the [Spring Boot documentation](https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-features.html#boot-features-external-config-conversion-duration) for an explanation of the format. The value `0ms` disables the timeout. |
+| `HONO_KURA_SEND_MESSAGE_TO_DEVICE_TIMEOUT`<br>`--hono.kura.sendMessageToDeviceTimeout` | no | `1000` | The amount of time (milliseconds) after which the sending of a command to a device using QoS 1 is considered to be failed. The value of this variable should be increased in cases where devices are connected over a network with high latency. |
 
 The variables only need to be set if the default values do not match your environment.
 

Diff for: site/documentation/content/admin-guide/mqtt-adapter-config.md

@@ -27,7 +27,8 @@ The following table provides an overview of the configuration variables and corr
 | `HONO_MQTT_AUTHENTICATION_REQUIRED`<br>`--hono.mqtt.authenticationRequired` | no | `true` | If set to `true` the protocol adapter requires devices to authenticate when connecting to the adapter. The credentials provided by the device are verified using the configured [Credentials Service]({{< relref "#credentials-service-connection-configuration" >}}). Devices that have failed to authenticate are not allowed to publish any data. |
 | `HONO_MQTT_BIND_ADDRESS`<br>`--hono.mqtt.bindAddress` | no | `127.0.0.1` | The IP address of the network interface that the secure port should be bound to.<br>See [Port Configuration]({{< relref "#port-configuration" >}}) below for details. |
 | `HONO_MQTT_CERT_PATH`<br>`--hono.mqtt.certPath` | no | - | The absolute path to the PEM file containing the certificate that the protocol adapter should use for authenticating to clients. This option must be used in conjunction with `HONO_MQTT_KEY_PATH`.<br>Alternatively, the `HONO_MQTT_KEY_STORE_PATH` option can be used to configure a key store containing both the key as well as the certificate. |
-| `HONO_MQTT_COMMAND_ACK_TIMEOUT`<br>`--hono.mqtt.commandAckTimeout` | no | `100` | The amount of time (milliseconds) after which the sending of a command to a device using QoS 1 is considered to be failed. The value of this variable should be increased in cases where devices are connected over a network with high latency. |
+| `HONO_MQTT_COMMAND_ACK_TIMEOUT`<br>`--hono.mqtt.commandAckTimeout` | no | `100` | Deprecated. Use `HONO_MQTT_SEND_MESSAGE_TO_DEVICE_TIMEOUT` instead. The amount of time (milliseconds) after which the sending of a command to a device using QoS 1 is considered to be failed. The value of this variable should be increased in cases where devices are connected over a network with high latency. |
+| `HONO_MQTT_SEND_MESSAGE_TO_DEVICE_TIMEOUT`<br>`--hono.mqtt.sendMessageToDeviceTimeout` | no | `1000` | The amount of time (milliseconds) after which the sending of a command to a device using QoS 1 is considered to be failed. The value of this variable should be increased in cases where devices are connected over a network with high latency. |
 | `HONO_MQTT_DEFAULTS_ENABLED`<br>`--hono.mqtt.defaultsEnabled` | no | `true` | If set to `true` the protocol adapter uses *default values* registered for a device to augment messages published by the device with missing information like a content type. In particular, the protocol adapter adds default values registered for the device as (application) properties with the same name to the AMQP 1.0 messages it sends downstream to the AMQP Messaging Network. |
 | `HONO_MQTT_INSECURE_PORT_BIND_ADDRESS`<br>`--hono.mqtt.insecurePortBindAddress` | no | `127.0.0.1` | The IP address of the network interface that the insecure port should be bound to.<br>See [Port Configuration]({{< relref "#port-configuration" >}}) below for details. |
 | `HONO_MQTT_INSECURE_PORT_ENABLED`<br>`--hono.mqtt.insecurePortEnabled` | no | `false` | If set to `true` the protocol adapter will open an insecure port (not secured by TLS) using either the port number set via `HONO_MQTT_INSECURE_PORT` or the default MQTT port number (`1883`) if not set explicitly.<br>See [Port Configuration]({{< relref "#port-configuration" >}}) below for details. |

Diff for: site/homepage/content/release-notes.md

@@ -78,6 +78,11 @@ title = "Release Notes"
   because the Device Registration API does not define a corresponding operation.
   Consequently, the C&C functionality of the Kerlink Lora provider which relied on the *get*
   method has been removed.
+ 
+### Deprecations
+ 
+ * The configuration property `HONO_MQTT_COMMAND_ACK_TIMEOUT` of the MQTT adapter is now deprecated
+   and planned to be removed in a future release. Use `HONO_MQTT_SEND_MESSAGE_TO_DEVICE_TIMEOUT` instead.
 
 ## 1.2.3