WebSocket: Expose transport specific options (#278)

Author: pglombardo

Source/HiveMQtt/Client/HiveMQClientOptionsBuilder.cs

@@ -15,6 +15,9 @@
  */
 namespace HiveMQtt.Client;
 
+using System;
+using System.Collections.Generic;
+using System.Net;
 using System.Security;
 using System.Security.Cryptography.X509Certificates;
 using HiveMQtt.Client.Options;
@@ -91,6 +94,81 @@ public HiveMQClientOptionsBuilder WithWebSocketServer(string webSocketServer)
         return this;
     }
 
+    /// <summary>
+    /// Sets the WebSocket keep-alive interval.
+    /// <para>
+    /// This specifies the interval at which the WebSocket client will send keep-alive pings to the server
+    /// to maintain the connection. If not set, the default WebSocket keep-alive behavior is used.
+    /// </para>
+    /// <para>
+    /// This option is only applicable when using WebSocket transport (ws:// or wss://).
+    /// </para>
+    /// </summary>
+    /// <param name="keepAliveInterval">The keep-alive interval.</param>
+    /// <returns>The HiveMQClientOptionsBuilder instance.</returns>
+    public HiveMQClientOptionsBuilder WithWebSocketKeepAliveInterval(TimeSpan keepAliveInterval)
+    {
+        this.options.WebSocketKeepAliveInterval = keepAliveInterval;
+        return this;
+    }
+
+    /// <summary>
+    /// Sets custom HTTP headers to be sent during the WebSocket handshake.
+    /// <para>
+    /// This allows you to add custom headers such as Authorization, X-API-Key, or any other
+    /// custom headers required by your WebSocket server. Headers are sent during the initial WebSocket
+    /// connection handshake.
+    /// </para>
+    /// <para>
+    /// This option is only applicable when using WebSocket transport (ws:// or wss://).
+    /// </para>
+    /// </summary>
+    /// <param name="headers">A dictionary of header names and values.</param>
+    /// <returns>The HiveMQClientOptionsBuilder instance.</returns>
+    public HiveMQClientOptionsBuilder WithWebSocketRequestHeaders(Dictionary<string, string> headers)
+    {
+        this.options.WebSocketRequestHeaders = headers;
+        return this;
+    }
+
+    /// <summary>
+    /// Adds a custom HTTP header to be sent during the WebSocket handshake.
+    /// <para>
+    /// This is a convenience method for adding a single header. For multiple headers, use
+    /// <see cref="WithWebSocketRequestHeaders(Dictionary{string, string})"/>.
+    /// </para>
+    /// <para>
+    /// This option is only applicable when using WebSocket transport (ws:// or wss://).
+    /// </para>
+    /// </summary>
+    /// <param name="name">The header name.</param>
+    /// <param name="value">The header value.</param>
+    /// <returns>The HiveMQClientOptionsBuilder instance.</returns>
+    public HiveMQClientOptionsBuilder WithWebSocketRequestHeader(string name, string value)
+    {
+        this.options.WebSocketRequestHeaders ??= new Dictionary<string, string>();
+        this.options.WebSocketRequestHeaders[name] = value;
+        return this;
+    }
+
+    /// <summary>
+    /// Sets the proxy configuration for WebSocket connections.
+    /// <para>
+    /// This allows you to configure a proxy server for WebSocket connections. If not set, the system's
+    /// default proxy settings are used.
+    /// </para>
+    /// <para>
+    /// This option is only applicable when using WebSocket transport (ws:// or wss://).
+    /// </para>
+    /// </summary>
+    /// <param name="proxy">The proxy configuration.</param>
+    /// <returns>The HiveMQClientOptionsBuilder instance.</returns>
+    public HiveMQClientOptionsBuilder WithWebSocketProxy(IWebProxy proxy)
+    {
+        this.options.WebSocketProxy = proxy;
+        return this;
+    }
+
     /// <summary>
     /// Sets the port to connect to.
     /// <para>

Source/HiveMQtt/Client/Options/HiveMQClientOptions.cs

@@ -16,7 +16,9 @@
 namespace HiveMQtt.Client.Options;
 
 using System;
+using System.Collections.Generic;
 using System.Linq;
+using System.Net;
 using System.Security;
 using System.Security.Cryptography.X509Certificates;
 using HiveMQtt.Client;
@@ -214,6 +216,59 @@ public HiveMQClientOptions()
     /// </summary>
     public bool AutomaticReconnect { get; set; }
 
+    /// <summary>
+    /// Gets or sets the WebSocket keep-alive interval.
+    /// <para>
+    /// This specifies the interval at which the WebSocket client will send keep-alive pings to the server
+    /// to maintain the connection. If not set, the default WebSocket keep-alive behavior is used.
+    /// </para>
+    /// <para>
+    /// This option is only applicable when using WebSocket transport (ws:// or wss://).
+    /// </para>
+    /// </summary>
+    public TimeSpan? WebSocketKeepAliveInterval { get; set; }
+
+    /// <summary>
+    /// Gets or sets custom HTTP headers to be sent during the WebSocket handshake.
+    /// <para>
+    /// This dictionary allows you to add custom headers such as Authorization, X-API-Key, or any other
+    /// custom headers required by your WebSocket server. Headers are sent during the initial WebSocket
+    /// connection handshake.
+    /// </para>
+    /// <para>
+    /// This option is only applicable when using WebSocket transport (ws:// or wss://).
+    /// </para>
+    /// <para>
+    /// Example:
+    /// <code>
+    /// options.WebSocketRequestHeaders = new Dictionary&lt;string, string&gt;
+    /// {
+    ///     { "Authorization", "Bearer token123" },
+    ///     { "X-API-Key", "api-key-value" }
+    /// };
+    /// </code>
+    /// </para>
+    /// </summary>
+    public Dictionary<string, string>? WebSocketRequestHeaders { get; set; }
+
+    /// <summary>
+    /// Gets or sets the proxy configuration for WebSocket connections.
+    /// <para>
+    /// This allows you to configure a proxy server for WebSocket connections. If not set, the system's
+    /// default proxy settings are used.
+    /// </para>
+    /// <para>
+    /// This option is only applicable when using WebSocket transport (ws:// or wss://).
+    /// </para>
+    /// <para>
+    /// Example:
+    /// <code>
+    /// options.WebSocketProxy = new WebProxy("http://proxy.example.com:8080");
+    /// </code>
+    /// </para>
+    /// </summary>
+    public IWebProxy? WebSocketProxy { get; set; }
+
     /// <summary>
     /// Generate a semi-random client identifier to be used in <c>Client</c> connections.
     /// hmqc#-pid-randomstring.

Source/HiveMQtt/Client/Transport/WebSocketTransport.cs

@@ -64,6 +64,9 @@ public WebSocketTransport(HiveMQClientOptions options)
             throw new ArgumentException("Invalid WebSocket URI scheme");
         }
 
+        // Configure WebSocket-specific options
+        this.ConfigureWebSocketOptions();
+
         // Configure TLS options for secure WebSocket (wss://)
         if (uri.Scheme == "wss")
         {
@@ -114,6 +117,37 @@ private static bool ValidateWebSocketServerCertificate(
         return false;
     }
 
+    /// <summary>
+    /// Configure WebSocket-specific options from HiveMQClientOptions.
+    /// </summary>
+    private void ConfigureWebSocketOptions()
+    {
+        // Configure keep-alive interval if specified
+        if (this.Options.WebSocketKeepAliveInterval.HasValue)
+        {
+            this.Socket.Options.KeepAliveInterval = this.Options.WebSocketKeepAliveInterval.Value;
+            Logger.Trace($"WebSocket keep-alive interval set to {this.Options.WebSocketKeepAliveInterval.Value}");
+        }
+
+        // Configure custom request headers if specified
+        if (this.Options.WebSocketRequestHeaders != null && this.Options.WebSocketRequestHeaders.Count > 0)
+        {
+            foreach (var header in this.Options.WebSocketRequestHeaders)
+            {
+                this.Socket.Options.SetRequestHeader(header.Key, header.Value);
+            }
+
+            Logger.Trace($"Added {this.Options.WebSocketRequestHeaders.Count} custom header(s) for WebSocket connection");
+        }
+
+        // Configure proxy if specified
+        if (this.Options.WebSocketProxy != null)
+        {
+            this.Socket.Options.Proxy = this.Options.WebSocketProxy;
+            Logger.Trace($"WebSocket proxy configured: {this.Options.WebSocketProxy}");
+        }
+    }
+
     /// <summary>
     /// Configure TLS options for secure WebSocket connections.
     /// </summary>