LHZ.WebSocket 1.0.2

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, OnCloseRecived, OnClientClose, OnPingRecived, OnPongRecived
• Multi-targeting — net5.0, net6.0, net8.0, net9.0, net10.0 with nullable reference types enabled

Quick Start

1. Add LHZ.WebSocket Package

Package Manager

Install-Package LHZ.WebSocket -Version 1.0.1

.NET CLI

dotnet add package LHZ.WebSocket --Version 1.0.1

Package Reference

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

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.OnCloseRecived += (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.OnCloseRecived += (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 demo

cd src/LHZ.WebSocket.TestConsole
dotnet run

API Reference

WebSocketServer

IWebSocketClient (interface)

WebSocketClient

HttpContext

HttpRequest

HttpResponse

DataFrame

CloseMessage

Delegates

EventHandler<TSender, TEventArgs> — Custom delegate defined in LHZ.WebSocket.Delegates, with in modifier on the sender parameter:

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, Opend, Close

ServerStatus — Ready, Start, Closing, Closed

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 / OnPingRecived / OnPongRecived
    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
│   │   │   ├── OpCode.cs                # Frame opcodes
│   │   │   └── ServerStatus.cs          # Server lifecycle states
│   │   ├── Http/
│   │   │   ├── HttpContext.cs           # HTTP upgrade handshake (server & client)
│   │   │   ├── HttpHeaders.cs           # Internal header collection
│   │   │   ├── HttpRequest.cs           # HTTP request-line & header parser/writer
│   │   │   └── HttpResponse.cs          # HTTP response builder & parser
│   │   └── Interfaces/
│   │       └── IWebSocketClient.cs      # WebSocket client interface
│   ├── LHZ.WebSocket.TestConsole/       # Client & server demo
│   │   └── Program.cs
│   └── LHZ.WebSocket.slnx              # Solution file
├── test-client.html                     # Browser-based test client
├── LICENSE
├── README.md
└── README.zh-CN.md

Requirements

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

License

MIT