Skip to content

CORE.md

Latest commit

 

History

History
550 lines (420 loc) · 12.7 KB

CORE.md

File metadata and controls

550 lines (420 loc) · 12.7 KB
Raw

Core Library Documentation

This document provides detailed information about the features and usage of the Cyaim.WebSocketServer core library.

Table of Contents

Overview

Cyaim.WebSocketServer is a lightweight, high-performance WebSocket server library that provides MVC-like routing mechanisms, supporting full-duplex communication, multiplexing, and pipeline processing.

Core Features

  • ✅ Lightweight & High Performance - Based on ASP.NET Core, excellent performance
  • ✅ Routing System - MVC-like routing mechanism, supports RESTful API
  • ✅ Full Duplex Communication - Supports bidirectional communication
  • ✅ Multiplexing - Single connection supports multiple requests/responses
  • ✅ Pipeline Processing - Supports middleware pipeline pattern
  • ✅ Type Safety - Strongly typed parameter binding and responses

Quick Start

1. Install NuGet Package

dotnet add package Cyaim.WebSocketServer

2. Configure Services

using Cyaim.WebSocketServer.Infrastructure.Handlers.MvcHandler;
using Cyaim.WebSocketServer.Infrastructure.Configures;

var builder = WebApplication.CreateBuilder(args);

// Configure WebSocket route
builder.Services.ConfigureWebSocketRoute(x =>
{
    // Define channels
    x.WebSocketChannels = new Dictionary<string, WebSocketRouteOption.WebSocketChannelHandler>()
    {
        { "/ws", new MvcChannelHandler(4 * 1024).ConnectionEntry }
    };
    x.ApplicationServiceCollection = builder.Services;
});

3. Configure Middleware

var app = builder.Build();

// Configure WebSocket options
var webSocketOptions = new WebSocketOptions()
{
    KeepAliveInterval = TimeSpan.FromSeconds(120)
};

app.UseWebSockets(webSocketOptions);
app.UseWebSocketServer();

4. Create Controller

using Cyaim.WebSocketServer.Infrastructure.Attributes;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    [WebSocket]
    [HttpGet]
    public IEnumerable<WeatherForecast> Get()
    {
        return new[]
        {
            new WeatherForecast { Date = DateTime.Now, TemperatureC = 25 }
        };
    }
}

Routing System

Channel Configuration

Channels are entry points for WebSocket connections, with each channel corresponding to a handler.

x.WebSocketChannels = new Dictionary<string, WebSocketRouteOption.WebSocketChannelHandler>()
{
    { "/ws", mvcHandler.ConnectionEntry },      // MVC handler
    { "/api", customHandler.ConnectionEntry }    // Custom handler
};

Endpoint Marking

Use the [WebSocket] attribute to mark WebSocket endpoints:

[WebSocket]
[HttpGet]
public string GetMessage()
{
    return "Hello, WebSocket!";
}

Note: The method parameter of the [WebSocket] attribute is case-insensitive.

Handlers

MvcChannelHandler

MvcChannelHandler is the default MVC-style handler that supports routing to controllers and action methods.

Constructor Parameters

// Receive and send buffer sizes (default 4KB)
var handler = new MvcChannelHandler(
    receiveBufferSize: 4 * 1024,
    sendBufferSize: 4 * 1024
);

Configuration Options

var handler = new MvcChannelHandler();

// Receive buffer sizes
handler.ReceiveTextBufferSize = 8 * 1024;
handler.ReceiveBinaryBufferSize = 8 * 1024;

// Send buffer sizes
handler.SendTextBufferSize = 8 * 1024;
handler.SendBinaryBufferSize = 8 * 1024;

// Response send timeout
handler.ResponseSendTimeout = TimeSpan.FromSeconds(30);

Custom Handlers

Implement the IWebSocketHandler interface to create custom handlers:

public class CustomHandler : IWebSocketHandler
{
    public WebSocketHandlerMetadata Metadata { get; } = new WebSocketHandlerMetadata
    {
        Describe = "Custom handler",
        CanHandleBinary = true,
        CanHandleText = true
    };

    public async Task ConnectionEntry(HttpContext context, WebSocket webSocket)
    {
        // Handle connection logic
    }
}

Middleware

WebSocketRouteMiddleware

WebSocketRouteMiddleware is the core middleware responsible for:

  • Routing WebSocket requests to corresponding channels
  • Managing WebSocket connection lifecycle
  • Handling connection upgrades

Usage

app.UseWebSockets(webSocketOptions);
app.UseWebSocketServer();

Configuration Options

WebSocketRouteOption

builder.Services.ConfigureWebSocketRoute(x =>
{
    // Channel configuration
    x.WebSocketChannels = new Dictionary<string, WebSocketRouteOption.WebSocketChannelHandler>();
    
    // Service collection (for dependency injection)
    x.ApplicationServiceCollection = builder.Services;
    
    // Bandwidth limit policy (optional)
    x.BandwidthLimitPolicy = new BandwidthLimitPolicy
    {
        Enabled = true,
        // ... configuration
    };
    
    // Cluster configuration (optional)
    x.EnableCluster = false;
});

WebSocketOptions

var webSocketOptions = new WebSocketOptions()
{
    // Keep-Alive interval
    KeepAliveInterval = TimeSpan.FromSeconds(120),
    
    // Receive buffer size (deprecated, configure in handler)
    // ReceiveBufferSize = 4 * 1024
};

Request and Response

Request Format

Requests use JSON format, following the MvcRequestScheme structure:

{
    "target": "ControllerName.ActionName",
    "body": {
        "param1": "value1",
        "param2": 123
    }
}

Note: The target parameter is case-insensitive.

Parameterless Request

{
    "target": "WeatherForecast.Get",
    "body": {}
}

Request with Parameters

{
    "target": "WeatherForecast.Get",
    "body": {
        "city": "Beijing",
        "date": "2024-01-01"
    }
}

Response Format

Responses use JSON format, following the MvcResponseScheme structure:

{
    "Target": "WeatherForecast.Get",
    "Status": 0,
    "Msg": null,
    "RequestTime": 637395762382112345,
    "CompleteTime": 637395762382134526,
    "Body": {
        // Method return value
    }
}

Response Field Description

  • Target: Target method of the request
  • Status: Status code (0 indicates success)
  • Msg: Error message (if any)
  • RequestTime: Request time (Ticks)
  • CompleteTime: Completion time (Ticks)
  • Body: Method return value

Message Types

Two message types are supported:

  • Text: Text messages (JSON format)
  • Binary: Binary messages

Advanced Features

Request Middleware

Request processing uses an ASP.NET Core-style middleware chain: register middleware with Use(...) on the route options. They are folded into a single delegate once at startup (zero per-message dispatch overhead). Each middleware may run code before/after calling next(ctx) (wrap the request), modify the request/response, or skip next to short-circuit.

services.ConfigureWebSocketRoute(options =>
{
    // Wrap: measure latency around the endpoint
    options.Use(async (ctx, next) =>
    {
        var sw = System.Diagnostics.Stopwatch.StartNew();
        await next(ctx);                       // run downstream middleware + endpoint
        logger.LogInformation("{Target} took {Ms}ms", ctx.Request?.Target, sw.ElapsedMilliseconds);
    });

    // Short-circuit: reject unauthorized requests; the endpoint never runs
    options.Use((ctx, next) =>
    {
        if (!IsAuthorized(ctx.HttpContext))
        {
            ctx.Response = new MvcResponseScheme { Status = 1, Id = ctx.Request?.Id, Msg = "unauthorized" };
            return Task.CompletedTask;         // don't call next => short-circuit
        }
        return next(ctx);
    });
});

You can also implement IWebSocketMiddleware and register it with options.Use(new MyMiddleware()).

Middleware context (WebSocketMessageContext)

  • HttpContext / WebSocket / Options: connection and route info
  • Request / RequestBody: the parsed request (Id/Target/Body)
  • Response: the endpoint result; serialized and sent after the chain (JSON for the MVC channel, binary for the MessagePack channel)
  • SuppressResponse: set true so the framework does not send a response
  • Items: scratch state shared across middleware for this message
  • ReceivedData: raw inbound bytes (materialized only when middleware is registered; copied in async mode for safety)

Connection connect/disconnect are lifecycle events — use BeforeConnectionEvent / DisconnectedEvent on the route options, not the message middleware chain.

Dependency Injection

Controllers support full dependency injection:

public class WeatherForecastController : ControllerBase
{
    private readonly ILogger<WeatherForecastController> _logger;
    private readonly IWeatherService _weatherService;

    public WeatherForecastController(
        ILogger<WeatherForecastController> logger,
        IWeatherService weatherService)
    {
        _logger = logger;
        _weatherService = weatherService;
    }

    [WebSocket]
    [HttpGet]
    public async Task<WeatherForecast> Get(string city)
    {
        return await _weatherService.GetWeatherAsync(city);
    }
}

Parameter Binding

Multiple parameter binding methods are supported:

Simple Types

[WebSocket]
public string GetMessage(string message)
{
    return $"Received: {message}";
}

Request:

{
    "target": "Controller.GetMessage",
    "body": {
        "message": "Hello"
    }
}

Complex Types

public class RequestModel
{
    public string Name { get; set; }
    public int Age { get; set; }
}

[WebSocket]
public string Process(RequestModel model)
{
    return $"Name: {model.Name}, Age: {model.Age}";
}

Request:

{
    "target": "Controller.Process",
    "body": {
        "name": "John",
        "age": 30
    }
}

Arrays and Collections

[WebSocket]
public string ProcessList(List<string> items)
{
    return string.Join(", ", items);
}

Request:

{
    "target": "Controller.ProcessList",
    "body": {
        "items": ["item1", "item2", "item3"]
    }
}

Async Methods

Full support for async methods:

[WebSocket]
public async Task<string> GetAsync(string id)
{
    var data = await _repository.GetAsync(id);
    return data;
}

Error Handling

Exception Handling

Exceptions thrown by methods are caught and returned as error responses:

{
    "Target": "Controller.Action",
    "Status": 1,
    "Msg": "Exception message",
    "RequestTime": 123456789,
    "CompleteTime": 123456790,
    "Body": null
}

Custom Error Handling

Custom error handling can be implemented by wrapping the endpoint with a middleware:

options.Use(async (ctx, next) =>
{
    try
    {
        await next(ctx);
    }
    catch (Exception ex)
    {
        // Custom error handling: replace the response
        ctx.Response = new MvcResponseScheme { Status = 1, Id = ctx.Request?.Id, Msg = ex.Message };
    }
});

Performance Optimization

Buffer Sizes

Adjust buffer sizes based on message size:

// Small messages (< 4KB)
var handler = new MvcChannelHandler(4 * 1024, 4 * 1024);

// Medium messages (4KB - 64KB)
var handler = new MvcChannelHandler(64 * 1024, 64 * 1024);

// Large messages (> 64KB)
var handler = new MvcChannelHandler(256 * 1024, 256 * 1024);

Connection Management

Use static dictionary to manage connections:

// Get all connections
var connections = MvcChannelHandler.Clients;

// Check if connection exists
if (MvcChannelHandler.Clients.TryGetValue(connectionId, out var webSocket))
{
    // Connection exists
}

Concurrent Processing

MvcChannelHandler supports concurrent processing of multiple requests, with each connection processed independently.

Best Practices

  1. Use Dependency Injection - Fully utilize ASP.NET Core's dependency injection system
  2. Async Methods - Use async methods for I/O operations to improve performance
  3. Error Handling - Properly handle exceptions and return meaningful error messages
  4. Parameter Validation - Validate parameters in methods to ensure data validity
  5. Logging - Use logging to record important operations and errors

Example Code

For complete examples, refer to:

Related Documentation