Add WebSockets (#1423)

* Add WebSockets

* Add tests

* fix

* more tests

* Add tests

* ...

* remove IOwin

* -

* tests

* fluent

* ok

* match

* .

* byte[]

* x

* func

* func

* byte

* trans

* ...

* frameworks.........

* jmes

* xxx

* sc

src/WireMock.Net.Shared/Extensions/ArrayPoolExtensions.cs

@@ -0,0 +1,20 @@
+// Copyright © WireMock.Net
+
+namespace System.Buffers;
+
+internal sealed class Lease<T>(ArrayPool<T> pool, int length) : IDisposable
+{
+    public T[] Rented { get; } = pool.Rent(length);
+
+    public static implicit operator T[](Lease<T> lease) => lease.Rented;
+
+    public void Dispose()
+    {
+        pool.Return(Rented, true);
+    }
+}
+
+internal static class ArrayPoolExtensions
+{
+    public static Lease<T> Lease<T>(this ArrayPool<T> source, int length) => new(source, length);
+}

src/WireMock.Net.Shared/Extensions/DictionaryExtensions.cs

@@ -28,4 +28,18 @@ internal static class DictionaryExtensions
         value = default;
         return false;
     }
-}
+
+    public static bool TryGetValue<T>(this IDictionary<object, object?> dictionary, string key, [NotNullWhen(true)] out T? value)
+    {
+        Guard.NotNull(dictionary);
+
+        if (dictionary[key] is T typedValue)
+        {
+            value = typedValue;
+            return true;
+        }
+
+        value = default;
+        return false;
+    }
+}

src/WireMock.Net.Shared/Extensions/EnumerableExtensions.cs

@@ -0,0 +1,21 @@
+// Copyright © WireMock.Net
+
+namespace System.Collections.Generic;
+
+internal static class EnumerableExtensions
+{
+    //internal static IEnumerable<T> ReverseEx<T>(this IEnumerable<T> source)
+    //{
+    //    var stack = new Stack<T>();
+
+    //    foreach (var item in source)
+    //    {
+    //        stack.Push(item);
+    //    }
+
+    //    while (stack.Count > 0)
+    //    {
+    //        yield return stack.Pop();
+    //    }
+    //}
+}

src/WireMock.Net.Shared/Extensions/StringExtensions.cs

@@ -1,6 +1,10 @@
-using System.Globalization;
+// Copyright © WireMock.Net
 
-namespace WireMock.Extensions;
+using System.Globalization;
+using System.Text.RegularExpressions;
+using WireMock.Constants;
+
+namespace System;
 
 internal static class StringExtensions
 {
@@ -28,4 +32,12 @@ internal static class StringExtensions
             return result.ToString(CultureInfo.InvariantCulture).Replace('-', '_');
         }
     }
+
+#if !NET8_0_OR_GREATER
+    public static string Replace(this string text, string oldValue, string newValue, StringComparison stringComparison)
+    {
+        var options = stringComparison == StringComparison.OrdinalIgnoreCase ? RegexOptions.IgnoreCase : RegexOptions.None;
+        return Regex.Replace(text, oldValue, newValue, options, RegexConstants.DefaultTimeout);
+    }
+#endif
 }

src/WireMock.Net.Shared/Matchers/IFuncMatcher.cs

@@ -0,0 +1,17 @@
+// Copyright © WireMock.Net
+
+namespace WireMock.Matchers;
+
+/// <summary>
+/// IFuncMatcher
+/// </summary>
+/// <inheritdoc cref="IMatcher"/>
+public interface IFuncMatcher : IMatcher
+{
+    /// <summary>
+    /// Determines whether the specified function is match.
+    /// </summary>
+    /// <param name="value">The value to check for a match.</param>
+    /// <returns>MatchResult</returns>
+    MatchResult IsMatch(object? value);
+}

src/WireMock.Net.Shared/Matchers/MatchResult.cs

@@ -1,7 +1,5 @@
 // Copyright © WireMock.Net
 
-using System;
-using System.Collections.Generic;
 using System.Linq;
 using Stef.Validation;
 using WireMock.Extensions;
@@ -40,6 +38,18 @@ public class MatchResult
     /// </summary>
     public bool IsPerfect() => MatchScores.IsPerfect(Score);
 
+    /// <summary>
+    /// Create a MatchResult.
+    /// </summary>
+    /// <param name="name">The name or description of the matcher.</param>
+    /// <param name="matchBehaviour">The match behaviour.</param>
+    /// <param name="isMatch">Is this a match?</param>
+    /// <param name="exception">The exception in case the matching fails. [Optional]</param>
+    public static MatchResult From(string name, MatchBehaviour matchBehaviour, bool isMatch, Exception? exception = null)
+    {
+        return From(name, MatchBehaviourHelper.Convert(matchBehaviour, MatchScores.ToScore(isMatch)), exception);
+    }
+
     /// <summary>
     /// Create a MatchResult.
     /// </summary>

src/WireMock.Net.Shared/RequestBuilders/IHttpVersionBuilder.cs

@@ -1,14 +1,13 @@
 // Copyright © WireMock.Net
 
 using WireMock.Matchers;
-using WireMock.Matchers.Request;
 
 namespace WireMock.RequestBuilders;
 
 /// <summary>
 /// The HttpVersionBuilder interface.
 /// </summary>
-public interface IHttpVersionBuilder : IRequestMatcher
+public interface IHttpVersionBuilder : IWebSocketRequestBuilder
 {
     /// <summary>
     /// WithHttpVersion

src/WireMock.Net.Shared/RequestBuilders/IWebSocketRequestBuilder.cs

@@ -0,0 +1,20 @@
+// Copyright © WireMock.Net
+using WireMock.Matchers.Request;
+
+namespace WireMock.RequestBuilders;
+
+/// <summary>
+/// The BodyRequestBuilder interface.
+/// </summary>
+public interface IWebSocketRequestBuilder : IRequestMatcher
+{
+    /// <summary>
+    /// Gets a value indicating whether the connection uses the WebSocket protocol.
+    /// </summary>
+    bool IsWebSocket { get; }
+
+    /// <summary>
+    /// Match WebSocket upgrade with optional protocols.
+    /// </summary>
+    IRequestBuilder WithWebSocketUpgrade(params string[] protocols);
+}

src/WireMock.Net.Shared/ResponseBuilders/ICallbackResponseBuilder.cs

@@ -3,14 +3,13 @@
 using System;
 using System.Threading.Tasks;
 using JetBrains.Annotations;
-using WireMock.ResponseProviders;
 
 namespace WireMock.ResponseBuilders;
 
 /// <summary>
 /// The CallbackResponseBuilder interface.
 /// </summary>
-public interface ICallbackResponseBuilder : IResponseProvider
+public interface ICallbackResponseBuilder : IWebSocketResponseBuilder
 {
     /// <summary>
     /// The callback builder

src/WireMock.Net.Shared/ResponseBuilders/IWebSocketResponseBuilder.cs

@@ -0,0 +1,29 @@
+// Copyright © WireMock.Net
+
+using System;
+using WireMock.ResponseProviders;
+using WireMock.Settings;
+using WireMock.WebSockets;
+
+namespace WireMock.ResponseBuilders;
+
+/// <summary>
+/// The WebSocketResponseBuilder interface.
+/// </summary>
+public interface IWebSocketResponseBuilder : IResponseProvider
+{
+    /// <summary>
+    /// Configure WebSocket response behavior
+    /// </summary>
+    IResponseBuilder WithWebSocket(Action<IWebSocketBuilder> configure);
+
+    /// <summary>
+    /// Proxy WebSocket to another server
+    /// </summary>
+    IResponseBuilder WithWebSocketProxy(string targetUrl);
+
+    /// <summary>
+    /// Proxy WebSocket to another server with settings
+    /// </summary>
+    IResponseBuilder WithWebSocketProxy(ProxyAndRecordSettings settings);
+}

src/WireMock.Net.Shared/Settings/WebSocketSettings.cs

@@ -0,0 +1,21 @@
+// Copyright © WireMock.Net
+
+using WireMock.Constants;
+
+namespace WireMock.Settings;
+
+/// <summary>
+/// WebSocket-specific settings
+/// </summary>
+public class WebSocketSettings
+{
+    /// <summary>
+    /// Maximum number of concurrent WebSocket connections (default: 100)
+    /// </summary>
+    public int MaxConnections { get; set; } = 100;
+
+    /// <summary>
+    /// Default keep-alive interval (default: 30 seconds)
+    /// </summary>
+    public int KeepAliveIntervalSeconds { get; set; } = WebSocketConstants.DefaultKeepAliveIntervalSeconds;
+}

src/WireMock.Net.Shared/Settings/WireMockServerSettings.cs

@@ -346,4 +346,10 @@ public class WireMockServerSettings
     /// </remarks>
     [PublicAPI]
     public ActivityTracingOptions? ActivityTracingOptions { get; set; }
+
+    /// <summary>
+    /// WebSocket settings.
+    /// </summary>
+    [PublicAPI]
+    public WebSocketSettings? WebSocketSettings { get; set; }
 }

src/WireMock.Net.Shared/WebSockets/IWebSocketBuilder.cs

@@ -0,0 +1,104 @@
+// Copyright © WireMock.Net
+
+using System;
+using JetBrains.Annotations;
+using WireMock.Matchers;
+using WireMock.Settings;
+using WireMock.Types;
+
+namespace WireMock.WebSockets;
+
+/// <summary>
+/// WebSocket Response Builder interface
+/// </summary>
+public interface IWebSocketBuilder
+{
+    /// <summary>
+    /// Accept the WebSocket with a specific protocol
+    /// </summary>
+    [PublicAPI]
+    IWebSocketBuilder WithAcceptProtocol(string protocol);
+
+    /// <summary>
+    /// Echo all received messages back to client
+    /// </summary>
+    [PublicAPI]
+    IWebSocketBuilder WithEcho();
+
+    /// <summary>
+    /// Configure and send a single message in response to any received message
+    /// </summary>
+    /// <param name="configure">Action to configure the message</param>
+    [PublicAPI]
+    IWebSocketBuilder SendMessage(Action<IWebSocketMessageBuilder> configure);
+
+    /// <summary>
+    /// Configure and send multiple messages in response to any received message
+    /// </summary>
+    /// <param name="configure">Action to configure the messages</param>
+    [PublicAPI]
+    IWebSocketBuilder SendMessages(Action<IWebSocketMessagesBuilder> configure);
+
+    /// <summary>
+    /// Configure message sending based on message content matching
+    /// </summary>
+    /// <param name="condition">String to match in message text</param>
+    [PublicAPI]
+    IWebSocketMessageConditionBuilder WhenMessage(string condition);
+
+    /// <summary>
+    /// Configure message sending based on message content matching
+    /// </summary>
+    /// <param name="condition">Bytes to match in message</param>
+    [PublicAPI]
+    IWebSocketMessageConditionBuilder WhenMessage(byte[] condition);
+
+    /// <summary>
+    /// Configure message sending based on IMatcher
+    /// </summary>
+    /// <param name="matcher">IMatcher to match the message</param>
+    [PublicAPI]
+    IWebSocketMessageConditionBuilder WhenMessage(IMatcher matcher);
+
+    /// <summary>
+    /// Handle incoming WebSocket messages
+    /// </summary>
+    [PublicAPI]
+    IWebSocketBuilder WithMessageHandler(Func<WebSocketMessage, IWebSocketContext, Task> handler);
+
+    /// <summary>
+    /// Enable broadcast mode for this mapping
+    /// </summary>
+    [PublicAPI]
+    IWebSocketBuilder WithBroadcast();
+
+    /// <summary>
+    /// Proxy to another WebSocket server
+    /// </summary>
+    [PublicAPI]
+    IWebSocketBuilder WithProxy(ProxyAndRecordSettings settings);
+
+    /// <summary>
+    /// Set close timeout (default: 10 minutes)
+    /// </summary>
+    [PublicAPI]
+    IWebSocketBuilder WithCloseTimeout(TimeSpan timeout);
+
+    /// <summary>
+    /// Set maximum message size in bytes (default: 1 MB)
+    /// </summary>
+    [PublicAPI]
+    IWebSocketBuilder WithMaxMessageSize(int sizeInBytes);
+
+    /// <summary>
+    /// Set receive buffer size (default: 4096 bytes)
+    /// </summary>
+    [PublicAPI]
+    IWebSocketBuilder WithReceiveBufferSize(int sizeInBytes);
+
+    /// <summary>
+    /// Set keep-alive interval (default: 30 seconds)
+    /// </summary>
+    [PublicAPI]
+    IWebSocketBuilder WithKeepAliveInterval(TimeSpan interval);
+}

src/WireMock.Net.Shared/WebSockets/IWebSocketContext.cs

@@ -0,0 +1,72 @@
+// Copyright © WireMock.Net
+
+using System.Net.WebSockets;
+using Microsoft.AspNetCore.Http;
+
+namespace WireMock.WebSockets;
+
+/// <summary>
+/// WebSocket context interface for handling WebSocket connections
+/// </summary>
+public interface IWebSocketContext
+{
+    /// <summary>
+    /// Unique connection identifier
+    /// </summary>
+    Guid ConnectionId { get; }
+
+    /// <summary>
+    /// The ASP.NET Core HttpContext
+    /// </summary>
+    HttpContext HttpContext { get; }
+
+    /// <summary>
+    /// The WebSocket instance
+    /// </summary>
+    WebSocket WebSocket { get; }
+
+    /// <summary>
+    /// The original request that initiated the WebSocket connection
+    /// </summary>
+    IRequestMessage RequestMessage { get; }
+
+    /// <summary>
+    /// The mapping that matched this WebSocket request
+    /// </summary>
+    IMapping Mapping { get; }
+
+    /// <summary>
+    /// Send text message to the client
+    /// </summary>
+    Task SendAsync(string text, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Send binary message to the client
+    /// </summary>
+    Task SendAsync(byte[] bytes, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Close the WebSocket connection
+    /// </summary>
+    Task CloseAsync(WebSocketCloseStatus closeStatus, string statusDescription);
+
+    /// <summary>
+    /// Manually set the scenario state. This bypasses the counter logic and directly sets the next state.
+    /// Use this for programmatic state changes during WebSocket sessions.
+    /// </summary>
+    /// <param name="nextState">The next state to transition to</param>
+    void SetScenarioState(string nextState);
+
+    /// <summary>
+    /// Manually set the scenario state with description. This bypasses the counter logic and directly sets the next state.
+    /// Use this for programmatic state changes during WebSocket sessions.
+    /// </summary>
+    /// <param name="nextState">The next state to transition to</param>
+    /// <param name="description">Optional description for logging</param>
+    void SetScenarioState(string nextState, string? description);
+
+    /// <summary>
+    /// Broadcast text message to all connections in this mapping
+    /// </summary>
+    Task BroadcastTextAsync(string text, CancellationToken cancellationToken = default);
+}

src/WireMock.Net.Shared/WebSockets/IWebSocketMessageBuilder.cs

@@ -0,0 +1,51 @@
+// Copyright © WireMock.Net
+
+using JetBrains.Annotations;
+
+namespace WireMock.WebSockets;
+
+/// <summary>
+/// WebSocket Message Builder interface for building individual messages with optional delays
+/// </summary>
+public interface IWebSocketMessageBuilder
+{
+    /// <summary>
+    /// Send a specific text message
+    /// </summary>
+    /// <param name="text">The text message to send</param>
+    [PublicAPI]
+    IWebSocketMessageBuilder WithText(string text);
+
+    /// <summary>
+    /// Send specific binary data
+    /// </summary>
+    /// <param name="bytes">The binary data to send</param>
+    [PublicAPI]
+    IWebSocketMessageBuilder WithBinary(byte[] bytes);
+
+    /// <summary>
+    /// Set a delay before sending the message (using TimeSpan)
+    /// </summary>
+    /// <param name="delay">The delay before sending the message</param>
+    [PublicAPI]
+    IWebSocketMessageBuilder WithDelay(TimeSpan delay);
+
+    /// <summary>
+    /// Set a delay before sending the message (using milliseconds)
+    /// </summary>
+    /// <param name="delayInMilliseconds">The delay in milliseconds before sending the message</param>
+    [PublicAPI]
+    IWebSocketMessageBuilder WithDelay(int delayInMilliseconds);
+
+    /// <summary>
+    /// Close the WebSocket connection after this message
+    /// </summary>
+    [PublicAPI]
+    IWebSocketMessageBuilder AndClose();
+
+    /// <summary>
+    /// Close the WebSocket connection.
+    /// </summary>
+    [PublicAPI]
+    IWebSocketMessageBuilder Close();
+}

src/WireMock.Net.Shared/WebSockets/IWebSocketMessageConditionBuilder.cs

@@ -0,0 +1,25 @@
+// Copyright © WireMock.Net
+
+using JetBrains.Annotations;
+
+namespace WireMock.WebSockets;
+
+/// <summary>
+/// WebSocket Message Condition Builder interface for building conditional message responses
+/// </summary>
+public interface IWebSocketMessageConditionBuilder
+{
+    /// <summary>
+    /// Configure and send a message when the condition matches
+    /// </summary>
+    /// <param name="configure">Action to configure the message</param>
+    [PublicAPI]
+    IWebSocketBuilder SendMessage(Action<IWebSocketMessageBuilder> configure);
+
+    /// <summary>
+    /// Configure and send multiple messages when the condition matches
+    /// </summary>
+    /// <param name="configure">Action to configure the messages</param>
+    [PublicAPI]
+    IWebSocketBuilder SendMessages(Action<IWebSocketMessagesBuilder> configure);
+}

src/WireMock.Net.Shared/WebSockets/IWebSocketMessagesBuilder.cs

@@ -0,0 +1,18 @@
+// Copyright © WireMock.Net
+
+using JetBrains.Annotations;
+
+namespace WireMock.WebSockets;
+
+/// <summary>
+/// WebSocket Messages Builder interface for building multiple messages
+/// </summary>
+public interface IWebSocketMessagesBuilder
+{
+    /// <summary>
+    /// Add a message to the sequence
+    /// </summary>
+    /// <param name="configure">Action to configure the message</param>
+    [PublicAPI]
+    IWebSocketMessagesBuilder AddMessage(Action<IWebSocketMessageBuilder> configure);
+}

src/WireMock.Net.Shared/WebSockets/WebSocketMessage.cs

@@ -0,0 +1,36 @@
+// Copyright © WireMock.Net
+
+using System.Net.WebSockets;
+
+namespace WireMock.WebSockets;
+
+/// <summary>
+/// Represents a WebSocket message
+/// </summary>
+public class WebSocketMessage
+{
+    /// <summary>
+    /// The message type (Text or Binary)
+    /// </summary>
+    public WebSocketMessageType MessageType { get; set; }
+
+    /// <summary>
+    /// Text content (when MessageType is Text)
+    /// </summary>
+    public string? Text { get; set; }
+
+    /// <summary>
+    /// Binary content (when MessageType is Binary)
+    /// </summary>
+    public byte[]? Bytes { get; set; }
+
+    /// <summary>
+    /// Indicates whether this is the final message
+    /// </summary>
+    public bool EndOfMessage { get; set; }
+
+    /// <summary>
+    /// Timestamp when the message was received
+    /// </summary>
+    public DateTime Timestamp { get; set; }
+}

src/WireMock.Net.Shared/WireMock.Net.Shared.csproj

@@ -1,9 +1,9 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
     <PropertyGroup>
         <Description>Shared interfaces, models, enumerations and types.</Description>
         <Authors>Stef Heyenrath</Authors>
-        <!--<TargetFrameworks>net451;net452;net46;net461;netstandard1.3;netstandard2.0;netstandard2.1;netcoreapp3.1;net5.0;net6.0;net7.0;net8.0</TargetFrameworks>-->
-        <TargetFrameworks>net48;net8.0</TargetFrameworks>
+        <!--<TargetFrameworks>net451;net452;net46;net462;netstandard1.3;netstandard2.0;netstandard2.1;netcoreapp3.1;net5.0;net6.0;net7.0;net8.0</TargetFrameworks>-->
+        <TargetFrameworks>netstandard2.0;netstandard2.1;net8.0</TargetFrameworks>
         <GenerateDocumentationFile>true</GenerateDocumentationFile>
         <PackageTags>tdd;mock;http;wiremock;test;server;shared</PackageTags>
         <RootNamespace>WireMock</RootNamespace>
@@ -27,15 +27,10 @@
     </PropertyGroup>
 
     <ItemGroup>
-        <!-- Keep at 6.14.0 -->
         <PackageReference Include="Microsoft.AspNetCore.Http" Version="2.3.9" />
-        <PackageReference Include="Polyfill" Version="6.14.0">
-            <PrivateAssets>all</PrivateAssets>
-            <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
-        </PackageReference>
         <PackageReference Include="Stef.Validation" Version="0.2.0" />
         <PackageReference Include="AnyOf" Version="0.5.0.1" />
-        <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
+        <PackageReference Include="Newtonsoft.Json" Version="13.0.4" />
         <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="8.0.2" />
         <PackageReference Include="JsonConverter.Abstractions" Version="0.7.2" />
     </ItemGroup>
@@ -54,4 +49,19 @@
     <ItemGroup>
         <ProjectReference Include="..\WireMock.Net.Abstractions\WireMock.Net.Abstractions.csproj" />
     </ItemGroup>
+
+    <ItemGroup Condition=" '$(TargetFramework)' == 'netstandard2.0' or '$(TargetFramework)' == 'netstandard2.1' ">
+        <PackageReference Include="Required" Version="1.0.0">
+            <PrivateAssets>all</PrivateAssets>
+            <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+        </PackageReference>
+        <PackageReference Include="IsExternalInit" Version="1.0.3">
+            <PrivateAssets>all</PrivateAssets>
+            <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+        </PackageReference>
+        <PackageReference Include="Nullable" Version="1.3.1">
+            <PrivateAssets>all</PrivateAssets>
+            <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+        </PackageReference>
+    </ItemGroup>
 </Project>