RepletoryLib.WebSocket.Abstractions 1.0.0

RepletoryLib.WebSocket.Abstractions

WebSocket hub abstractions and interfaces for real-time connection management, group messaging, broadcast, and message handling.

Part of the RepletoryLib ecosystem -- standalone, reusable .NET 10 libraries with zero business logic.

Overview

RepletoryLib.WebSocket.Abstractions defines the core contracts, models, enums, and options for real-time WebSocket communication. It provides IWebSocketHub for sending messages to connections, users, and groups, IWebSocketConnectionManager for tracking connection lifecycle and group memberships, and IWebSocketMessageHandler for pluggable message routing based on message type.

This package contains no implementations -- it is the abstraction layer that concrete providers (in-memory, Redis-backed, etc.) implement. Reference this package in your application code to program against interfaces, then swap providers without changing business logic.

Key Features

• IWebSocketHub -- Core hub contract: send to connection, send to user, broadcast to all, broadcast to group, manage group membership, and disconnect
• IWebSocketConnectionManager -- Connection lifecycle management: add, remove, query by ID/user/group, group membership, and connection counting
• IWebSocketMessageHandler -- Pluggable message handler matched by message type string for custom message processing
• WebSocketMessage -- Message model with type, payload, sender info, timestamp, and optional metadata
• WebSocketConnection -- Connection model tracking identity, state, group memberships, and activity timestamps
• SendMessageRequest / BroadcastRequest / GroupBroadcastRequest -- Typed request models for targeted, broadcast, and group-scoped messaging
• SendResult / BulkSendResult -- Result types with per-connection success/failure tracking and static factory methods
• WebSocketOptions -- Shared configuration for heartbeat intervals, connection limits, message sizes, allowed origins, and endpoint path
• ConnectionState enum -- Connection lifecycle states: Connecting, Connected, Disconnecting, Disconnected
• WebSocketMessageType enum -- Message type classifications: Text, System, Ping, Pong, Connected, Disconnected, GroupJoined, GroupLeft, Error

Installation

dotnet add package RepletoryLib.WebSocket.Abstractions

Or add to your .csproj:

<PackageReference Include="RepletoryLib.WebSocket.Abstractions" Version="1.0.0" />

Note: RepletoryLib packages are published to a local BaGet feed. See the main repository README for feed configuration.

Dependencies

Quick Start

1. Reference the abstractions in your service layer

using RepletoryLib.WebSocket.Abstractions.Interfaces;
using RepletoryLib.WebSocket.Abstractions.Models;

public class ChatService
{
    private readonly IWebSocketHub _hub;

    public ChatService(IWebSocketHub hub) => _hub = hub;

    public async Task SendDirectMessageAsync(string connectionId, string text)
    {
        var result = await _hub.SendToConnectionAsync(new SendMessageRequest
        {
            ConnectionId = connectionId,
            Message = new WebSocketMessage
            {
                Type = "Chat",
                Payload = text
            }
        });

        if (!result.Success)
            throw new InvalidOperationException($"Send failed: {result.Error}");
    }
}

2. Register a concrete provider in Program.cs

// In-memory provider (from RepletoryLib.WebSocket.Core)
using RepletoryLib.WebSocket.Core;
builder.Services.AddRepletoryWebSocket(builder.Configuration);

Configuration

WebSocketOptions

Section name: "WebSocket"

{
  "WebSocket": {
    "HeartbeatIntervalSeconds": 30,
    "MaxConnections": 10000,
    "MaxMessageSizeBytes": 65536,
    "ConnectionTimeoutSeconds": 120,
    "AllowedOrigins": ["https://example.com", "https://app.example.com"],
    "EndpointPath": "/ws"
  }
}

Usage Examples

Send a Message to a Specific Connection

using RepletoryLib.WebSocket.Abstractions.Interfaces;
using RepletoryLib.WebSocket.Abstractions.Models;

public class NotificationService
{
    private readonly IWebSocketHub _hub;

    public NotificationService(IWebSocketHub hub) => _hub = hub;

    public async Task NotifyConnectionAsync(string connectionId, string eventType, string payload)
    {
        var result = await _hub.SendToConnectionAsync(new SendMessageRequest
        {
            ConnectionId = connectionId,
            Message = new WebSocketMessage
            {
                Type = eventType,
                Payload = payload,
                Metadata = new Dictionary<string, string>
                {
                    ["source"] = "notification-service"
                }
            }
        });

        if (!result.Success)
            Console.WriteLine($"Failed to send to {connectionId}: {result.Error}");
    }
}

Send to All Connections for a User

public async Task NotifyUserAsync(string userId, string message)
{
    var result = await _hub.SendToUserAsync(userId, new WebSocketMessage
    {
        Type = "Notification",
        Payload = message
    });

    if (!result.Success)
        Console.WriteLine($"Failed to notify user {userId}: {result.Error}");
}

Broadcast to All Connections

public async Task BroadcastAnnouncementAsync(string announcement, string? excludeConnectionId = null)
{
    var request = new BroadcastRequest
    {
        Message = new WebSocketMessage
        {
            Type = "Announcement",
            Payload = announcement
        },
        ExcludeConnectionIds = excludeConnectionId is not null
            ? [excludeConnectionId]
            : null
    };

    var result = await _hub.BroadcastAsync(request);

    Console.WriteLine($"Broadcast: {result.SuccessCount} delivered, {result.FailureCount} failed");
}

Broadcast to a Group

public async Task SendToRoomAsync(string roomName, string senderConnectionId, string message)
{
    var result = await _hub.BroadcastToGroupAsync(new GroupBroadcastRequest
    {
        GroupName = roomName,
        Message = new WebSocketMessage
        {
            Type = "Chat",
            Payload = message,
            ConnectionId = senderConnectionId
        },
        ExcludeConnectionIds = [senderConnectionId] // Don't echo back to sender
    });
}

Group Management

// Add a connection to a group
await _hub.AddToGroupAsync(connectionId, "room-general");

// Remove a connection from a group
await _hub.RemoveFromGroupAsync(connectionId, "room-general");

// Forcefully disconnect a connection
await _hub.DisconnectAsync(connectionId);

Query Connections with IWebSocketConnectionManager

using RepletoryLib.WebSocket.Abstractions.Interfaces;
using RepletoryLib.WebSocket.Abstractions.Models;

public class AdminService
{
    private readonly IWebSocketConnectionManager _connections;

    public AdminService(IWebSocketConnectionManager connections) => _connections = connections;

    public async Task<int> GetOnlineCountAsync()
    {
        return await _connections.GetConnectionCountAsync();
    }

    public async Task<IReadOnlyList<WebSocketConnection>> GetUserSessionsAsync(string userId)
    {
        return await _connections.GetConnectionsByUserAsync(userId);
    }

    public async Task<IReadOnlyList<string>> GetGroupsAsync(string connectionId)
    {
        return await _connections.GetGroupsForConnectionAsync(connectionId);
    }
}

Implement a Custom Message Handler

using RepletoryLib.WebSocket.Abstractions.Interfaces;
using RepletoryLib.WebSocket.Abstractions.Models;

public class ChatMessageHandler : IWebSocketMessageHandler
{
    public string MessageType => "Chat";

    private readonly IWebSocketHub _hub;

    public ChatMessageHandler(IWebSocketHub hub) => _hub = hub;

    public async Task HandleAsync(WebSocketMessage message, WebSocketConnection connection, CancellationToken cancellationToken = default)
    {
        // Echo the message back to all connections in the sender's groups
        foreach (var group in connection.Groups)
        {
            await _hub.BroadcastToGroupAsync(new GroupBroadcastRequest
            {
                GroupName = group,
                Message = message,
                ExcludeConnectionIds = [connection.ConnectionId]
            }, cancellationToken);
        }
    }
}

// Register in DI
builder.Services.AddSingleton<IWebSocketMessageHandler, ChatMessageHandler>();

API Reference

Interfaces

IWebSocketHub

IWebSocketConnectionManager

IWebSocketMessageHandler

Models

WebSocketMessage

WebSocketConnection

SendMessageRequest

BroadcastRequest

GroupBroadcastRequest

SendResult

BulkSendResult

Enums

ConnectionState

WebSocketMessageType

Options

WebSocketOptions

Integration with Other RepletoryLib Packages

Testing

using NSubstitute;
using RepletoryLib.WebSocket.Abstractions.Interfaces;
using RepletoryLib.WebSocket.Abstractions.Models;

public class ChatServiceTests
{
    [Fact]
    public async Task SendDirectMessageAsync_sends_to_connection()
    {
        // Arrange
        var hub = Substitute.For<IWebSocketHub>();
        hub.SendToConnectionAsync(Arg.Any<SendMessageRequest>(), Arg.Any<CancellationToken>())
            .Returns(SendResult.Succeeded("conn-123"));

        var service = new ChatService(hub);

        // Act
        await service.SendDirectMessageAsync("conn-123", "Hello!");

        // Assert
        await hub.Received(1).SendToConnectionAsync(
            Arg.Is<SendMessageRequest>(r =>
                r.ConnectionId == "conn-123" &&
                r.Message.Type == "Chat" &&
                r.Message.Payload == "Hello!"),
            Arg.Any<CancellationToken>());
    }

    [Fact]
    public async Task SendDirectMessageAsync_throws_on_failure()
    {
        // Arrange
        var hub = Substitute.For<IWebSocketHub>();
        hub.SendToConnectionAsync(Arg.Any<SendMessageRequest>(), Arg.Any<CancellationToken>())
            .Returns(SendResult.Failed("Connection not found"));

        var service = new ChatService(hub);

        // Act & Assert
        await Assert.ThrowsAsync<InvalidOperationException>(
            () => service.SendDirectMessageAsync("conn-999", "Hello!"));
    }
}

Troubleshooting

License

This project is licensed under the MIT License.

Copyright (c) 2024-2026 Repletory.

For complete documentation, infrastructure setup, and configuration reference, see the RepletoryLib main repository.