MyConnection 1.0.1

MyConnection

Thư viện kết nối mạng client-server cho .NET, hỗ trợ WebSocket + UDP + REST, xác thực JWT, pub/sub messaging theo subject. Thiết kế để hoạt động trên cả server (.NET 9.0) và Unity client (netstandard2.1, IL2CPP-safe).

Kiến trúc tổng quan

┌─────────────────────────────────────────────────────────────────┐
│                          CLIENT                                  │
│                                                                  │
│  IClient ──→ ClientAbstract ──→ ClientImplement                  │
│   │                              │                               │
│   │  Login(data)                 │  WebSocket (Native)           │
│   │  ConnectServer()             │  UdpClientWrapper             │
│   │  DisconnectAsync()           │  SubjectDispatcher×2          │
│   │  Logout()                    │  UdpPingService (RTT)         │
│   │  SendOnTcp / SendOnUdp       │  HttpClient (REST)            │
│   │  SubscribeTcp / SubscribeUdp │  Auto re-login                │
│   │  GetRequest / PostRequest    │  Warning (W001-W007)          │
│   │  OnDisconnect / OnWarning    │                               │
│   │  IsConnected / LatestRttMs   │                               │
│                                                                  │
└──────────────────────────┬──────────────────────────────────────┘
                           │
          HTTP/REST  ←─────┤─────→  WebSocket  ←─────→  UDP
          (Protobuf)       │        (Protobuf)          (Protobuf)
          POST /api        │        ws://host:port/ws   127.0.0.1:9091
                           │
┌──────────────────────────┴──────────────────────────────────────┐
│                          SERVER                                  │
│                                                                  │
│  IServer ──→ ServerAbstract → ServerCore (shared logic)         │
│   │              │               ├── ServerImplement (raw TCP)   │
│   │              │               └── ServerKestrel  (Kestrel)    │
│   │              │                                               │
│   │              │         ┌─────────────────────────┐           │
│   │              │         │ Shared:                  │           │
│   │              │         │ • ConnectionRegistry     │           │
│   │              │         │ • ServerTokenService     │           │
│   │              │         │ • UdpListener            │           │
│   │              │         │ • UdpSessionMap          │           │
│   │              │         │ • UdpHandshakeHandler    │           │
│   │              │         │ • REST dispatch          │           │
│   │              │         └─────────────────────────┘           │
│   │                                                              │
│   │  Create(config)        Tự chọn impl: ServerKestrelConfig     │
│   │  Connections           → ServerKestrel, ServerConfig         │
│   │  CreateToken / GetById → ServerImplement                     │
│   │  OnConnect/OnDisconnect                                      │
│   │  SendOnXxx / SendAllOnXxx                                    │
│   │  SubscribeXxx                                                │
│   │  OnLogin / OnGet / OnPost                                    │
│   │  OnWarning                                                   │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

Tính năng

Gói NuGet & phụ thuộc

Grpc.Tools 2.80.0 dùng để compile .proto tại build-time (PrivateAssets=all).
FrameworkReference Microsoft.AspNetCore.App cho server Kestrel (net9.0 only).

Cấu trúc thư mục

MyConnection/
├── src/                              # Mã nguồn thư viện
│   ├── IClient.cs                    # Interface client
│   ├── ClientAbstract.cs             # Abstract class client
│   ├── IServer.cs                    # Interface server + static factory
│   ├── ServerAbstract.cs             # Abstract class server
│   ├── ServerCore.cs                 # Shared logic (net9.0)
│   ├── IConnection.cs                # Interface kết nối
│   ├── IUser.cs                      # Interface người dùng
│   ├── ISubscribe.cs                 # Handle hủy đăng ký subscribe
│   ├── ConnectionFailedException.cs
│   └── impl/                         # Triển khai
│       ├── ClientConfig.cs           # Cấu hình client
│       ├── ClientImplement.cs        # Client implementation
│       ├── ServerConfig.cs           # Cấu hình server (raw TCP)
│       ├── ServerKestrelConfig.cs     # Cấu hình server Kestrel
│       ├── ServerImplement.cs        # Server raw TcpListener
│       ├── ServerKestrel.cs          # Server ASP.NET Core Kestrel
│       ├── ConnectionImplement.cs    # Connection wrapper
│       ├── ConnectionRegistry.cs     # Tracking + routing
│       ├── SubjectDispatcher.cs      # Pub/sub dispatcher (2x)
│       ├── ProtoSerializer.cs        # Protobuf serialize/deserialize
│       ├── WebSocketListener.cs      # HTTP+WebSocket raw TCP
│       ├── UdpListener.cs            # UDP server
│       ├── UdpClientWrapper.cs       # UDP client
│       ├── UdpSessionMap.cs          # Connection → UDP endpoint
│       ├── UdpHandshakeHandler.cs    # Sinh key UDP
│       ├── UdpPingService.cs         # Ping/pong RTT
│       ├── KestrelHostedService.cs   # DI extension AddMyConnectionServer
│       ├── MyConnectionWebApplicationExtensions.cs  # UseMyConnectionServer
│       ├── ServerTokenService.cs     # JWT create + validate
│       ├── ApiException.cs           # REST API exception
│       └── WarningInfo.cs            # Thông tin cảnh báo
├── protos/                           # Protocol Buffer schema
│   ├── api_request.proto
│   ├── api_response.proto
│   ├── login_response.proto
│   ├── message_envelope.proto
│   └── string_value.proto
├── MyConnection.Tests/               # xUnit tests (net9.0)
│   └── ConnectionTests.cs            # 13 tests
├── ConsoleDemo/                      # Demo server console app
│   ├── ConsoleDemo.csproj
│   └── Program.cs                    # ASP.NET Core + Kestrel demo
├── plan/                             # Tài liệu thiết kế
│   ├── kestrel-server.md             # Plan ServerKestrel (đã hoàn thành)
│   ├── kestrel-integration.md        # Refactor tích hợp WebApplication
│   ├── api-call-system.md
│   └── logout.md
├── libs/                             # DLL bundle cho netstandard2.1
│   ├── Google.Protobuf.dll
│   └── NativeWebSocket.dll
├── nupkgs/                           # NuGet package output
│   └── MyConnection.1.0.0.nupkg
└── MyConnection.csproj

Interface chính

IClient

public interface IClient : IAsyncDisposable
{
    static IClient Create(ClientConfig config);

    // Connection lifecycle
    Task ConnectServer();           // Mở WS + bắt tay UDP, gọi sau Login
    Task DisconnectAsync();         // Ngắt WS + UDP, giữ token để reconnect
    Task Logout();                  // Xóa token + disconnect, cần Login lại

    // Messaging (Protobuf)
    void SendOnUdp<TData>(string subject, TData data);
    void SendOnTcp<TData>(string subject, TData data);

    // Subscribe
    ISubscribe SubscribeUdp<TData>(string subject, Action<TData> callback);
    ISubscribe SubscribeTcp<TData>(string subject, Action<TData> callback);

    // Events
    ISubscribe OnDisconnect(Action callback);
    ISubscribe OnWarning(Action<WarningInfo> callback);

    // Status
    bool IsConnected { get; }
    long? LatestRttMs { get; }

    // REST API
    Task<IUser> Login<TData>(Func<TData> data);
    Task<IUser> Login<TData>(Func<Task<TData>> data);
    Task<TResponse> GetRequest<TResponse>(string subject);
    Task<TResponse> PostRequest<TRequest, TResponse>(string subject, TRequest body);
}

IServer

public interface IServer : IAsyncDisposable
{
    static IServer Create(ServerConfig config);  // Chỉ .NET 9.0

    IReadOnlyCollection<IConnection> Connections { get; }
    string CreateToken(string id, string name);
    IConnection GetConnectionById(string id);

    // Events
    ISubscribe OnConnect(Action<IConnection> callback);
    ISubscribe OnDisconnect(Action<IConnection> callback);
    ISubscribe OnWarning(Action<ServerWarningInfo> callback);

    // Targeted send
    void SendOnTcp<TData>(string subject, IConnection conn, TData data);
    void SendOnUdp<TData>(string subject, IConnection conn, TData data);

    // Broadcast
    void SendAllOnTcp<TData>(string subject, TData data);
    void SendAllOnUdp<TData>(string subject, TData data);

    // Subscribe (receive from clients)
    ISubscribe SubscribeTcp<TData>(string subject, Action<IConnection, TData> callback);
    ISubscribe SubscribeUdp<TData>(string subject, Action<IConnection, TData> callback);

    // REST handlers
    void OnLogin<TData>(Func<TData, Task<IUser>> authLogic);
    void OnGetRequest<TResponse>(string subject, Func<Task<TResponse>> handler);
    void OnPostRequest<TRequest, TResponse>(string subject, Func<TRequest, Task<TResponse>> handler);
}

IConnection

public interface IConnection
{
    string Id { get; }                       // Id kết nối duy nhất
    IUser User { get; }                      // Thông tin người dùng
    IDictionary<string, object> Attributes { get; }  // Dữ liệu tùy chỉnh
    bool Connected { get; }                  // Trạng thái kết nối
    string UdpAddress { get; }              // Endpoint UDP của client
    string WebSocketSessionId { get; }
    long UdpPingTime { get; }
    long WebSocketPingTime { get; }
}

Cấu hình

ClientConfig

ServerConfig (raw TCP — ServerImplement)

ServerKestrelConfig (Kestrel — ServerKestrel, kế thừa ServerConfig)

Vòng đời kết nối (Client Lifecycle)

Login(data)  ──→  REST POST /api subject=__login__  →  server xác thực → trả LoginResponse
    │
    ├── _token = loginResult.Token
    ├── _reLoginFactory = closure auto re-login
    └── _loginDataFactory = data factory

ConnectServer()  ──→  WebSocket ws://host:9090/ws + header Bearer <token>
    │                   → server ValidateToken → WebSocket upgrade
    │
    ├── Bắt tay UDP: request_udp_auth → server cấp key → ping 5 lần → bound
    └── UdpPingService.Start() đo RTT mỗi 5s

━━━━━━━  Đã kết nối  ━━━━━━━
SendOnTcp / SendOnUdp / GetRequest / PostRequest
SubscribeTcp / SubscribeUdp
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

DisconnectAsync()  ──→  đóng WS + UDP, _token giữ nguyên
    │
ConnectServer()  ──→  reconnect OK (token còn valid)

Logout()  ──→  xóa _token + _reLoginFactory + disconnect

DisposeAsync()  ──→  Logout() + cleanup _udpClient + _sendLock

Giao thức message

Mọi message trao đổi qua WebSocket và UDP đều dùng MessageEnvelope:

message MessageEnvelope {
  string subject = 1;       // Chủ đề (VD: "chat", "move", "__ping__", "__pong__")
  bytes payload = 2;        // Dữ liệu Protobuf (IMessage<T>.ToByteArray())
  bytes session_key = 3;    // Key session UDP
  int64 ticks = 4;          // Timestamp (dùng cho RTT)
}

• subject: string phân biệt chủ đề, dùng để route đến subscriber
• payload: byte[] serialize từ bất kỳ IMessage<T> nào
• Các subject đặc biệt: __login__, __ping__, __pong__, __udp_auth__, __udp_bound__, request_udp_auth

REST API system

Client gọi Login, GetRequest, PostRequest → HTTP POST /{restEndpoint} với body ApiRequest Protobuf.

message ApiRequest {
  string subject = 1;       // Chủ đề (__login__ hoặc subject đăng ký)
  bytes payload = 2;        // Dữ liệu gửi lên (đã nén nếu Compressed=true)
  bool compressed = 3;      // Đánh dấu payload đã nén Deflate
  bool has_payload = 4;     // true = POST-style, false = GET-style
  string token = 5;         // JWT token (trừ __login__)
}

message ApiResponse {
  string subject = 1;
  bytes payload = 2;
  bool compressed = 3;
  bool success = 4;
  string error_code = 5;    // "" nếu thành công, "TokenExpired", ...
  string error_message = 6;
}

Luồng xử lý REST trên server:

1. Nhận HTTP POST → parse ApiRequest
2. Nếu subject != "__login__" → validate JWT token
3. Nếu Compressed → giải nén payload
4. Route theo subject → _getHandlers hoặc _postHandlers
5. Serialize kết quả → ApiResponse
6. Trả về HTTP response

Auto re-login trên client: khi GetRequest/PostRequest gặp ApiResponse.error_code == "TokenExpired", gọi _reLoginFactory 1 lần để lấy token mới → retry request.

Hệ thống cảnh báo

WarningInfo (client) chứa Code, Message, Exception.
ServerWarningInfo : WarningInfo thêm Connection để biết cảnh báo liên quan đến client nào.

Xử lý lỗi

Hỗ trợ nền tảng

Ví dụ sử dụng

Server — Raw TCP (ServerImplement)

using MyConnection;

var config = new ServerConfig
{
    tcpPort = 9090,
    websocketEndpoint = "/ws",
    restEndpoint = "/api",
    udpPort = 9091,
    jwtSecret = "your-secret-key-at-least-32-bytes!!",
    jwtIssuer = "my-issuer",
    jwtAudience = "my-audience"
};

await using var server = (ServerImplement)IServer.Create(config);

server.OnLogin<StringValue>(async data =>
{
    if (data.Value == "admin")
        return new MyUser("1", "Admin");
    throw new Exception("Sai thông tin đăng nhập");
});

server.OnConnect(conn =>
    Console.WriteLine($"[+] {conn.User.Name} đã kết nối (Id={conn.Id})"));

server.SubscribeTcp<StringValue>("chat", (conn, msg) =>
{
    Console.WriteLine($"{conn.User.Name}: {msg.Value}");
    server.SendAllOnTcp("chat", msg);
});

Console.WriteLine($"Token: {server.CreateToken("1", "Admin")}");
await Task.Delay(-1); // Giữ server chạy

Server — Kestrel standalone (ServerKestrel)

using MyConnection;

var config = new ServerKestrelConfig
{
    KestrelUrls = "http://0.0.0.0:9090",
    websocketEndpoint = "/ws",
    restEndpoint = "/api",
    udpPort = 9091,
    jwtSecret = "your-secret-key-at-least-32-bytes!!",
    jwtIssuer = "my-issuer",
    jwtAudience = "my-audience"
};

await using var server = (ServerKestrel)IServer.Create(config);

// Đăng ký handlers giống hệt ServerImplement
server.OnLogin<StringValue>(...);
server.SubscribeTcp<StringValue>("chat", ...);

await Task.Delay(-1); // Server tự quản lý Kestrel lifecycle

Server — ASP.NET Core DI (ServerKestrel + shared pipeline)

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using MyConnection;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMyConnectionServer(new ServerKestrelConfig
{
    KestrelUrls = "http://0.0.0.0:9090",
    websocketEndpoint = "/ws",
    restEndpoint = "/api",
    udpPort = 9091,
    jwtSecret = "your-secret-key-at-least-32-bytes!!",
    jwtIssuer = "my-issuer",
    jwtAudience = "my-audience"
});

var app = builder.Build();

var server = app.Services.GetRequiredService<IServer>();

// Đăng ký handlers
server.OnLogin<StringValue>(...);
server.OnConnect(conn => Console.WriteLine($"[+] {conn.User.Name} connected"));
server.SubscribeTcp<StringValue>("chat", (conn, msg) =>
{
    server.SendAllOnTcp("chat", msg);
});

// Đăng ký MyConnection middleware vào shared WebApplication pipeline
app.UseMyConnectionServer();

await app.RunAsync(); // 1 Kestrel duy nhất

Lưu ý: UseMyConnectionServer() tự động áp KestrelUrls từ config vào host Kestrel và xóa default localhost:5000 — chỉ 1 cổng duy nhất. Server lifecycle do KestrelHostedService (IHostedService) quản lý.

So sánh 3 cách dùng server

Client

using MyConnection;

var config = new ClientConfig
{
    tcpServer = "127.0.0.1:9090",
    websocketEnpoint = "/ws",
    restEndpoint = "/api",
    udpServer = ""
};

var client = IClient.Create(config);

client.OnDisconnect(() => Console.WriteLine("[!] Mất kết nối"));
client.OnWarning(w => Console.WriteLine($"[W] {w.Code}: {w.Message}"));

client.SubscribeTcp<StringValue>("chat", msg =>
    Console.WriteLine($"Chat: {msg.Value}"));

var user = await client.Login(() => new StringValue { Value = "admin" });
Console.WriteLine($"Logged in as {user.Name} (Id={user.Id})");

await client.ConnectServer();

client.SendOnTcp("chat", new StringValue { Value = "Xin chào!" });

var pong = await client.GetRequest<StringValue>("ping");
Console.WriteLine(pong.Value); // "pong"

var echo = await client.PostRequest<StringValue, StringValue>("echo",
    new StringValue { Value = "hello" });
Console.WriteLine(echo.Value); // "hello"

await client.DisconnectAsync();  // Giữ token
await client.ConnectServer();    // Reconnect
await client.Logout();           // Xóa token
await client.DisposeAsync();     // Dọn dẹp

Testing

dotnet test

13 test cases trong ConnectionTests.cs:

Build & Pack

# Build cả 2 target (net9.0 + netstandard2.1)
dotnet build                              # 0 error, 0 warning

# Chạy test
dotnet test                               # 13/13 passed

# Build NuGet package
dotnet pack -c Release -o nupkgs          # → nupkgs/MyConnection.1.0.0.nupkg

# Build + chạy ConsoleDemo
dotnet build ConsoleDemo/ConsoleDemo.csproj
dotnet run --project ConsoleDemo

# Publish ConsoleDemo self-contained (không cần cài .NET)
dotnet publish ConsoleDemo -c Release --self-contained true -r win-x64 -o ConsoleDemo\publish

License

MIT