ConnectOptions & v1.0 Test Plan Updates (#232)

Author: pglombardo

Documentation/docs/reference/connect_options.md

@@ -0,0 +1,35 @@
+# ConnectOptions
+
+The `ConnectOptions` class provides options for a connect call made with `ConnectAsync`. These options can override settings that were originally set in `HiveMQClientOptions`.
+
+## Constructors
+
+* `ConnectOptions()`: Initializes a new instance of the `ConnectOptions` class with defaults.
+
+## Properties
+
+* `SessionExpiryInterval`: Gets or sets the session expiry interval in seconds. This overrides any value set in HiveMQClientOptions.
+    + Example: `SessionExpiryInterval = 3600` sets the session to expire in 1 hour.
+
+* `KeepAlive`: Gets or sets the keep alive period in seconds. This overrides any value set in HiveMQClientOptions.
+    + Example: `KeepAlive = 60` sets the keep alive to 60 seconds.
+
+* `CleanStart`: Gets or sets whether to use a clean start. This overrides any value set in HiveMQClientOptions.
+    + Example: `CleanStart = true` starts a new session, discarding any existing session.
+
+## Examples
+
+```csharp
+ConnectOptions connectOptions = new ConnectOptions();
+connectOptions.SessionExpiryInterval = 3600;  // 1 hour session expiry
+connectOptions.KeepAlive = 60;                // 60 second keep alive
+connectOptions.CleanStart = true;             // Start with a clean session
+
+await client.ConnectAsync(connectOptions);
+```
+
+## See Also
+
+* [HiveMQClientOptions Reference](/docs/reference/client_options)
+* [Connecting to an MQTT Broker](/docs/connecting)
+* [Session Handling](/docs/how-to/session-handling) 

Documentation/docs/reference/connect_options_builder.md

@@ -0,0 +1,68 @@
+# ConnectOptionsBuilder
+
+The `ConnectOptionsBuilder` class is a builder pattern implementation that provides a convenient way to construct `ConnectOptions` objects for configuring connect behavior in HiveMQtt client applications.
+
+## Methods
+
+### `WithSessionExpiryInterval(long sessionExpiryInterval)`
+
+Sets the session expiry interval for the connection.
+
+- **Description:** Specifies the duration, in seconds, for which the session state will be maintained by the broker. This overrides any value set in HiveMQClientOptions.
+- **Example:** 
+  ```csharp
+  .WithSessionExpiryInterval(3600) // 1 hour session expiry
+  ```
+
+### `WithKeepAlive(int keepAlive)`
+
+Sets the keep alive period for the connection.
+
+- **Description:** Specifies the maximum time interval that is permitted to elapse between the point at which the Client finishes transmitting one Control Packet and the point it starts sending the next. This overrides any value set in HiveMQClientOptions.
+- **Example:** 
+  ```csharp
+  .WithKeepAlive(60) // 60 second keep alive
+  ```
+
+### `WithCleanStart(bool cleanStart)`
+
+Sets whether to use a clean start for the connection.
+
+- **Description:** Specifies whether the Connection starts a new Session or is a continuation of an existing Session. This overrides any value set in HiveMQClientOptions.
+- **Example:** 
+  ```csharp
+  .WithCleanStart(true) // Start with a clean session
+  ```
+
+### `Build()`
+
+Builds the ConnectOptions instance.
+
+- **Description:** Creates and returns a new ConnectOptions object with all the configured settings.
+- **Example:**
+  ```csharp
+  ConnectOptions options = new ConnectOptionsBuilder()
+      .WithSessionExpiryInterval(3600)
+      .WithKeepAlive(60)
+      .WithCleanStart(true)
+      .Build();
+  ```
+
+## Complete Example
+
+```csharp
+var connectOptions = new ConnectOptionsBuilder()
+    .WithSessionExpiryInterval(3600)  // 1 hour session expiry
+    .WithKeepAlive(60)               // 60 second keep alive
+    .WithCleanStart(true)            // Start with a clean session
+    .Build();
+
+await client.ConnectAsync(connectOptions);
+```
+
+## See Also
+
+* [ConnectOptions Reference](/docs/reference/connect_options)
+* [HiveMQClientOptions Reference](/docs/reference/client_options)
+* [Connecting to an MQTT Broker](/docs/connecting)
+* [Session Handling](/docs/how-to/session-handling) 

Source/HiveMQtt/Client/ConnectOptionsbuilder.cs

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2025-present HiveMQ and the HiveMQ Community
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+namespace HiveMQtt.Client;
+
+using HiveMQtt.Client.Options;
+
+/// <summary>
+/// Builder class for the ConnectOptions class.
+/// </summary>
+public class ConnectOptionsBuilder
+{
+    // private static readonly NLog.Logger Logger = NLog.LogManager.GetCurrentClassLogger();
+    private readonly ConnectOptions options;
+
+    public ConnectOptionsBuilder() => this.options = new ConnectOptions();
+
+    /// <summary>
+    /// Sets the session expiry interval for the connect options.
+    /// </summary>
+    /// <param name="sessionExpiryInterval">The session expiry interval in seconds.</param>
+    /// <returns>The ConnectOptionsBuilder instance.</returns>
+    public ConnectOptionsBuilder WithSessionExpiryInterval(long sessionExpiryInterval)
+    {
+        this.options.SessionExpiryInterval = sessionExpiryInterval;
+        return this;
+    }
+
+    /// <summary>
+    /// Sets the keep alive for the connect options.
+    /// </summary>
+    /// <param name="keepAlive">The keep alive in seconds.</param>
+    /// <returns>The ConnectOptionsBuilder instance.</returns>
+    public ConnectOptionsBuilder WithKeepAlive(int keepAlive)
+    {
+        this.options.KeepAlive = keepAlive;
+        return this;
+    }
+
+    /// <summary>
+    /// Sets the clean start for the connect options.
+    /// </summary>
+    /// <param name="cleanStart">The clean start flag.</param>
+    /// <returns>The ConnectOptionsBuilder instance.</returns>
+    public ConnectOptionsBuilder WithCleanStart(bool cleanStart)
+    {
+        this.options.CleanStart = cleanStart;
+        return this;
+    }
+
+    /// <summary>
+    /// Builds the ConnectOptions instance.
+    /// </summary>
+    /// <returns>The ConnectOptions instance.</returns>
+    public ConnectOptions Build() => this.options;
+}

Source/HiveMQtt/Client/Connection/ConnectionManagerHandlers.cs

@@ -19,11 +19,21 @@ public partial class ConnectionManager
     internal void HandleIncomingConnAckPacket(ConnAckPacket connAckPacket)
     {
         Logger.Trace($"{this.Client.Options.ClientId}-(RPH)- <-- Received ConnAck");
+
+        // If SessionPresent is false, we need to reset any in-flight transactions
+        // To manage disconnections, users should subscribe to the OnPublishSent event and timeout
+        // if no response is received from the broker.  This is done to make this client simpler,
+        // and to avoid the complexity of managing in-flight transactions across connections.
+        if (!connAckPacket.SessionPresent)
+        {
+            this.IPubTransactionQueue.Clear();
+            this.OPubTransactionQueue.Clear();
+        }
+
         if (connAckPacket.ReasonCode == ConnAckReasonCode.Success && connAckPacket.Properties.ReceiveMaximum != null)
         {
             Logger.Debug($"{this.Client.Options.ClientId}-(RPH)- <-- Broker ReceiveMaximum is {connAckPacket.Properties.ReceiveMaximum}.");
 
-            // FIXME: A resize would be better to not lose any existing.  Can we send publishes before the CONNACK?
             // Replace the OPubTransactionQueue BoundedDictionary with a new one with the broker's ReceiveMaximum
             this.OPubTransactionQueue = new BoundedDictionaryX<int, List<ControlPacket>>((int)connAckPacket.Properties.ReceiveMaximum);
         }

Source/HiveMQtt/Client/HiveMQClient.cs

@@ -70,12 +70,31 @@ public HiveMQClient(HiveMQClientOptions? options = null)
     public bool IsConnected() => this.Connection.State == ConnectState.Connected;
 
     /// <inheritdoc />
-    public async Task<ConnectResult> ConnectAsync()
+    public async Task<ConnectResult> ConnectAsync(ConnectOptions? connectOptions = null)
     {
         this.Connection.State = ConnectState.Connecting;
 
         Logger.Info("Connecting to broker at {0}:{1}", this.Options.Host, this.Options.Port);
 
+        // Apply the connect override options if provided
+        if (connectOptions != null)
+        {
+            if (connectOptions.SessionExpiryInterval != null)
+            {
+                this.Options.SessionExpiryInterval = connectOptions.SessionExpiryInterval.Value;
+            }
+
+            if (connectOptions.KeepAlive != null)
+            {
+                this.Options.KeepAlive = connectOptions.KeepAlive.Value;
+            }
+
+            if (connectOptions.CleanStart != null)
+            {
+                this.Options.CleanStart = connectOptions.CleanStart.Value;
+            }
+        }
+
         // Fire the corresponding event
         this.BeforeConnectEventLauncher(this.Options);
 
@@ -193,6 +212,13 @@ public async Task<PublishResult> PublishAsync(MQTT5PublishMessage message, Cance
     {
         message.Validate();
 
+        if (message.QoS.HasValue && this.Connection.ConnectionProperties.MaximumQoS.HasValue &&
+            (ushort)message.QoS.Value > this.Connection.ConnectionProperties.MaximumQoS.Value)
+        {
+            Logger.Debug($"Reducing message QoS from {message.QoS} to broker enforced maximum of {this.Connection.ConnectionProperties.MaximumQoS}");
+            message.QoS = (QualityOfService)this.Connection.ConnectionProperties.MaximumQoS.Value;
+        }
+
         // QoS 0: Fast Service
         if (message.QoS == QualityOfService.AtMostOnceDelivery)
         {

Source/HiveMQtt/Client/IHiveMQClient.cs

@@ -58,15 +58,17 @@ public interface IHiveMQClient : IDisposable
     /// Asynchronously makes a TCP connection to the remote specified in HiveMQClientOptions and then
     /// proceeds to make an MQTT Connect request.
     /// </summary>
+    /// <param name="connectOptions">The connect override options for the MQTT Connect call.  These settings
+    /// will override the settings in HiveMQClientOptions.</param>
     /// <returns>A ConnectResult class representing the result of the MQTT connect call.</returns>
-    public Task<ConnectResult> ConnectAsync();
+    public Task<ConnectResult> ConnectAsync(ConnectOptions? connectOptions);
 
     /// <summary>
     /// Asynchronous disconnect from the previously connected MQTT broker.
     /// </summary>
     /// <param name="options">The options for the MQTT Disconnect call.</param>
     /// <returns>A boolean indicating on success or failure.</returns>
-    public Task<bool> DisconnectAsync(DisconnectOptions options);
+    public Task<bool> DisconnectAsync(DisconnectOptions? options);
 
     /// <summary>
     /// Publish a message to an MQTT topic.

Source/HiveMQtt/Client/Options/ConnectOptions.cs

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2025-present HiveMQ and the HiveMQ Community
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+namespace HiveMQtt.Client.Options;
+
+/// <summary>
+/// The options class for a Connect call.  The settings here can override the settings that may have
+/// been set in the HiveMQClientOptions.
+/// </summary>
+public class ConnectOptions
+{
+    public long? SessionExpiryInterval { get; set; }
+
+    public int? KeepAlive { get; set; }
+
+    public bool? CleanStart { get; set; }
+}

Source/HiveMQtt/Client/Transport/WebSocketTransport.cs

@@ -117,9 +117,7 @@ public override async Task<TransportReadResult> ReadAsync(CancellationToken canc
             do
             {
                 result = await this.Socket.ReceiveAsync(buffer, CancellationToken.None).ConfigureAwait(false);
-#pragma warning disable CA1835 // Prefer the 'Memory'-based overloads for 'ReadAsync' and 'WriteAsync'
-                await ms.WriteAsync(buffer.Array, buffer.Offset, result.Count, cancellationToken).ConfigureAwait(false);
-#pragma warning restore CA1835 // Prefer the 'Memory'-based overloads for 'ReadAsync' and 'WriteAsync'
+                await ms.WriteAsync(buffer.AsMemory(buffer.Offset, result.Count), cancellationToken).ConfigureAwait(false);
             }
             while (!result.EndOfMessage);
 

Source/HiveMQtt/Client/internal/BoundedDictionaryX.cs

@@ -168,7 +168,12 @@ public bool Clear()
         {
             var numItems = this.dictionary.Count;
             this.dictionary.Clear();
-            this.semaphore.Release(numItems);
+
+            if (numItems > 0)
+            {
+                this.semaphore.Release(numItems);
+            }
+
             return true;
         }
         catch (ArgumentNullException ex)

Source/HiveMQtt/Client/internal/Validator.cs

@@ -40,6 +40,7 @@ public static void ValidateClientId(string clientId)
         }
 
         // Regular expression to match any character that is NOT in the specified set
+        // We can't use GeneratedRegexAttribute because it's not available in .net 6.0
         var regex = new Regex("[^0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ]");
 
         // Check if the input string contains any character that does not match the pattern