LHZ.WebSocket 1.2.0

LHZ.WebSocket

中文

A lightweight, zero-dependency WebSocket library for .NET, implementing RFC 6455 from the ground up using raw TcpListener / TcpClient. Supports both server-side and client-side WebSocket connections.

Features

• Zero dependencies — pure .NET, no third-party libraries
• RFC 6455 compliant — FIN, RSV1–3, all opcodes, masking, extended payload lengths
• Server & Client — create WebSocket servers or connect as a client via CreateWebSocketClient
• Fragmented messages — automatic reassembly of continuation frames (client → server)
• Streaming send — split large payloads across multiple frames via CreateDataFrame(Stream)
• Bounded channel — producer-consumer pattern for outgoing frames; no unbounded queues
• Event-driven — OnMessageReceived, OnBytesReceived, OnCloseReceived, OnClientClose, OnPingReceived, OnPongReceived
• Multi-targeting — net5.0, net6.0, net8.0, net9.0, net10.0 with nullable reference types enabled
• Handshake timeout — configurable timeout to reject slow HTTP upgrade requests
• xUnit tested — comprehensive unit tests for frame parsing, close messages, HTTP headers, server, and client

Quick Start

1. Add LHZ.WebSocket Package

Package Manager

Install-Package LHZ.WebSocket -version 1.2.0

.NET CLI

dotnet add package LHZ.WebSocket --Version 1.2.0

Package Reference

<PackageReference Include="LHZ.WebSocket" Version="1.2.0" />

Upgrading from 1.1.x? Some misspelled public names were corrected, so you will get compile errors until you rename the call sites:

Old	New
ClientStatus.Opend	ClientStatus.Opened
OnCloseRecived	OnCloseReceived
OnPingRecived	OnPingReceived
OnPongRecived	OnPongReceived
DataFrame.DataDataFrameFlag	DataFrame.DataFrameFlag

Two parameter names were corrected as well, which only matters if you pass them by name: CreateWebSocketClient's timeOUt is now timeOut, and CreateDataFrame's dataDataFrameLength is now dataFrameLength.

Also note that a Pong is now sent automatically on every incoming Ping, so a handler that replied by hand can be removed.

2. Create and start a server

using LHZ.WebSocket;
using LHZ.WebSocket.Core;
using LHZ.WebSocket.Http;
using LHZ.WebSocket.Interfaces;

// Listen on port 5000, all interfaces
var server = new WebSocketServer(5000);

server.OnUpgradeRequest += (HttpContext context) =>
{
    // Optional: inspect headers, add custom response headers, or deny the upgrade
    // context.Response?.Headers.Add("X-Custom", "value");

    var client = context.HttpUpgrade();    // completes the 101 handshake

    client.OnMessageReceived += (IWebSocketClient sender, string message) =>
    {
        Console.WriteLine($"Received: {message}");
        sender.SendMessage($"Echo: {message}");
    };

    client.OnBytesReceived += (IWebSocketClient sender, byte[] data) =>
    {
        Console.WriteLine($"Received {data.Length} bytes");
    };

    client.OnCloseReceived += (IWebSocketClient sender, CloseMessage msg) =>
    {
        Console.WriteLine($"Client closed: {msg.CloseCode} — {msg.Message}");
        sender.Close();
    };
};

server.Start();
Console.WriteLine($"Server started, {server.ClientNums} clients connected");
Console.ReadLine();
server.Stop();

3. Connect as a client

using LHZ.WebSocket;
using LHZ.WebSocket.Core;
using LHZ.WebSocket.Interfaces;

// Connect to a WebSocket server
var client = WebSocketClient.CreateWebSocketClient("ws://localhost:5000/");

client.OnMessageReceived += (IWebSocketClient sender, string message) =>
{
    Console.WriteLine($"Received: {message}");
};

client.OnCloseReceived += (IWebSocketClient sender, CloseMessage message) =>
{
    Console.WriteLine($"Connection closed: {message.CloseCode}");
    sender.Close();
};

client.Open();
client.SendMessage("Hello World!");

4. Bind to a specific IP

var server = new WebSocketServer(IPAddress.Loopback, 5000);

5. Run the tests

cd src
dotnet test

API Reference

WebSocketServer

IWebSocketClient (interface)

WebSocketClient

IHttpContext (interface)

HttpContextBase (abstract class)

Base class implementing IHttpContext. Provides HTTP request parsing, timeout handling, and the HttpUpgrade() handshake logic. The concrete HttpContext class adds TcpClient support.

HttpContext (sealed, extends HttpContextBase)

HttpRequest

HttpResponse

DataFrame

CloseMessage

Delegates

EventHandler<TSender, TEventArgs> — Custom delegate defined in LHZ.WebSocket.Delegates

public delegate void EventHandler<in TSender, TEventArgs>(TSender sender, TEventArgs e);

Enums

OpCode — Continuation (0x0), Text (0x1), Binary (0x2), Close (0x8), Ping (0x9), Pong (0xA)

CloseCode — All RFC 6455 codes: Normal (1000), GoingAway (1001), ProtocolError (1002), …, TlsHandshake (1015)

ClientStatus — Connection, Opened, Close

ServerStatus — Ready, Start, Closing, Closed

HttpContextStatus — NotInitialized (0), Initialized (1), Upgraded (2), TimedOut (-2), Rejected (-1)

Architecture

sequenceDiagram
    participant Peer
    participant TcpListener
    participant WebSocketServer
    participant HttpContext
    participant WebSocketClient

    Peer->>TcpListener: TCP connect
    TcpListener->>WebSocketServer: AcceptTcpClientAsync()
    WebSocketServer->>HttpContext: Parse HTTP upgrade request
    WebSocketServer->>+Peer: OnUpgradeRequest (user code calls HttpUpgrade())
    HttpContext->>Peer: HTTP 101 + Sec-WebSocket-Accept
    HttpContext->>WebSocketClient: new WebSocketClient(httpContext)
    WebSocketClient->>WebSocketClient: Open() → StartReceiver() + StartSender()
    Peer->>WebSocketClient: Data frames
    WebSocketClient->>Peer: OnMessageReceived / OnBytesReceived / OnPingReceived / OnPongReceived
    WebSocketClient-->>Peer: SendMessage() / SendByte() / Ping() / Pong()

Internally, each WebSocketClient runs two background tasks:

• Receiver — reads frames via DataFrameReader, reassembles fragmented messages, dispatches by opcode
• Sender — dequeues frames from a bounded Channel<DataFrame>, writes header + payload to the network stream

Project Structure

LHZ.WebSocket/
├── src/
│   ├── LHZ.WebSocket/                    # Core library
│   │   ├── WebSocketServer.cs           # TCP listener & client lifecycle
│   │   ├── WebSocketClient.cs           # Per-connection send/receive (server & client)
│   │   ├── Core/
│   │   │   ├── CloseMessage.cs          # Close frame payload
│   │   │   ├── DataFrame.cs             # Frame builder / parser (RFC 6455 §5.2)
│   │   │   └── DataFrameReader.cs       # Frame reader from Stream
│   │   ├── Delegates/
│   │   │   └── EventHandler.cs          # Custom event delegate with `in` modifier
│   │   ├── Enums/
│   │   │   ├── ClientStatus.cs          # Client lifecycle states
│   │   │   ├── CloseCode.cs             # RFC 6455 close status codes
│   │   │   ├── HttpContextStatus.cs     # HTTP context lifecycle states
│   │   │   ├── OpCode.cs                # Frame opcodes
│   │   │   └── ServerStatus.cs          # Server lifecycle states
│   │   ├── Http/
│   │   │   ├── HttpContext.cs           # HTTP upgrade handshake (server & client)
│   │   │   ├── HttpContextBase.cs       # Abstract base with handshake & timeout logic
│   │   │   ├── HttpHeaders.cs           # Internal header collection
│   │   │   ├── HttpRequest.cs           # HTTP request-line & header parser/writer
│   │   │   └── HttpResponse.cs          # HTTP response builder & parser
│   │   └── Interfaces/
│   │       ├── IHttpContext.cs          # HTTP context interface
│   │       └── IWebSocketClient.cs      # WebSocket client interface
│   ├── LHZ.WebSocket.Test/              # xUnit test project
│   │   ├── WebSocketServerTests.cs
│   │   ├── WebSocketClientTests.cs
│   │   └── Core/ / Http/
│   └── LHZ.WebSocket.slnx              # Solution file
├── LICENSE
├── README.md
└── README.zh-CN.md

Requirements

• .NET 5 / 6 / 8 / 9 / 10 SDK

License

MIT