Natify 1.0.2

Natify

Đây là một framework giao tiếp High-Performance dành cho kiến trúc Microservice và Game Server (đặc biệt tối ưu cho Unity), được xây dựng trên nền tảng NATS Core.

Phụ thuộc (Dependencies)

• Google.Protobuf (v3.34.1): Mã hóa dữ liệu siêu tốc.
• NATS.Client.Core (v2.7.3): Giao tiếp mạng (Không cần cấu hình JetStream phức tạp).
• System.Threading.Channels: Xử lý hàng đợi đa luồng Lock-free.

Tính năng Nổi bật (Core Features)

1. Micro-Batching 2 Chiều: Tự động gom lô tin nhắn để tối ưu băng thông. Kích hoạt xả lô khi đạt 1.000 tin nhắn, hoặc 50KB, hoặc sau 50ms.
2. Tin cậy cấp Ứng dụng (Reliability): Tự động gửi ACK và Retry (thử lại) nếu gói tin bị rớt do lỗi mạng, đảm bảo không bao giờ mất tin nhắn (At-Least-Once Delivery).
3. Chống trùng lặp siêu tốc (O(1) Deduplication): Tích hợp TimedSortedSet (Time Wheel) dọn rác tự động sau 10 giây, chặn đứng lỗi nhân đôi dữ liệu (Dupe Bug) khi mạng chập chờn.
4. Graceful Shutdown (Tắt mềm): Cơ chế Dispose() an toàn, chờ vắt kiệt hàng đợi và xác nhận ACK trước khi ngắt mạng, chống treo Game/App.
5. Telemetry & Triggers: Tích hợp bộ đếm nguyên tử (Atomic Counters) để giám sát RAM, lưu lượng mạng và số lượng gói tin theo thời gian thực mà không làm nghẽn luồng chính.

Client NatifyClient (Dành cho Unity / App)

Khởi tạo Client:

var client = new NatifyClient("nats://localhost:4222", "client_name", "group_name", "regionId", "server_name_to_connect");

• client_name: Tên định danh của client.
• group_name: Consumer Group của NATS (chia sẻ tải).
• regionId: ID phân vùng của Client (VD: "VN-01").
• server_name_to_connect: Tên Server đích muốn kết nối tới.

1. Nhận tin nhắn (Subscribe)

client.OnMessage<IMessageProto>("topic", data => 
{
    // Xử lý dữ liệu
});

• Lưu ý quan trọng cho Unity: Callback truyền vào OnMessage sẽ KHÔNG chạy ngay lập tức. Nó được đẩy vào một hàng đợi an toàn. Bạn bắt buộc phải gọi hàm client.Tick() trong vòng lặp Update() của Unity để thực thi callback trên Main Thread.

void Update()
{
    client.Tick(); // Lấy tối đa 100 action ra xử lý mỗi frame
}

2. Gửi tin nhắn (Publish)

client.Publish("topic", new IMessageProto { ... });

• Cơ chế gửi là Fire-and-Forget ở luồng gọi, nhưng bên dưới dữ liệu được đẩy vào Channel, gom thành Batch và gửi đi an toàn ở một luồng ngầm (BatchWorker), không làm giật lag FPS.

3. Request - Reply (RPC)

Gửi yêu cầu và đợi kết quả (Bất đồng bộ):

var response = await client.RequestAsync<IReqProto, IResProto>("topic", requestData, TimeSpan.FromSeconds(2));

Lắng nghe và trả lời Request từ Server (Chạy trên Unity Main Thread):

// Dạng Đồng bộ (Xử lý logic nhanh)
client.OnRequest<IReqProto, IResProto>("topic", request => {
    return new IResProto { ... };
});

// Dạng Bất đồng bộ (Load Asset, đọc File)
client.OnRequest<IReqProto, IResProto>("topic", async request => {
    await Task.Delay(500); // Tác vụ nặng
    return new IResProto { ... };
});

Client NatifyClientFast (Dành cho Backend / Console App)

Hoạt động với cơ chế y hệt như NatifyClient nhưng không yêu cầu vòng lặp Tick(). Phù hợp cho các ứng dụng .NET Core thông thường, hệ thống Microservices hoặc Worker Services cần đóng vai trò làm thiết bị trạm (Client) nhưng không chịu rào cản đồng bộ Main Thread giống môi trường Unity.

Khởi tạo và sử dụng:

var clientFast = new NatifyClientFast("nats://localhost:4222", "client_name", "group_name", "regionId", "server_name_to_connect");

// Xử lý luồng ngầm (ThreadPool) đa luồng lập tức ngay khi có tin nhắn thay vì đợi Tick()
clientFast.OnMessage<IMessageProto>("topic", data => 
{
    // ...
});

Server NatifyServer (Dành cho Game Server / Microservices)

Khởi tạo Server:

var server = new NatifyServer("nats://localhost:4222", "server_name", "group_name", "client_name_to_connect");

1. Nhận tin nhắn

server.OnMessage<IMessageProto>("topic", callbackData => 
{
    string regionId = callbackData.regionId;
    IMessageProto data = callbackData.data;
});

• Khác với Client, Server xử lý dữ liệu đa luồng lập tức ngay khi nhận được, tối đa hóa sức mạnh CPU. Không cần gọi Tick().

2. Gửi tin nhắn xuống Client

// Cần chỉ định đích danh RegionId của Client
server.Publish("topic", "VN-01", new IMessageProto { ... });

3. Request - Reply (RPC)

Gửi yêu cầu xuống một Client cụ thể:

var response = await server.RequestAsync<IReqProto, IResProto>("topic", "VN-01", requestData, TimeSpan.FromSeconds(2));

Xử lý Request từ Client gửi lên (Đa luồng):

server.OnRequest<IReqProto, IResProto>("topic", incoming => 
{
    string clientRegion = incoming.regionId;
    IReqProto request = incoming.request;
    
    return new IResProto { ... };
});

Giám sát Hệ thống (Telemetry & Triggers)

Cả NatifyClient và NatifyServer đều có thuộc tính .Trigger, cho phép bạn truy xuất các chỉ số thời gian thực và cài đặt cảnh báo.

Xem chỉ số (VD: làm API Dashboard):

long totalSent = server.Trigger.MessagesSent;
double ramUsage = server.Trigger.ProcessMemoryMB;
long dedupCacheSize = server.Trigger.CurrentDedupCacheSize;

Cài đặt Luật Cảnh Báo (Smart Triggers): Trigger sử dụng luồng chạy ngầm độc lập (Cold Path), không làm chậm tốc độ mạng (Hot Path).

// Báo động nếu RAM quá 1.5 GB
server.Trigger.RegisterTrigger(
    condition: t => t.ProcessMemoryMB > 1500,
    action: t => Console.WriteLine($"[CẢNH BÁO OOM] RAM đang ở mức {t.ProcessMemoryMB} MB!"),
    oneTime: false
);

// In log định kỳ sau mỗi 100.000 tin nhắn
server.Trigger.RegisterTrigger(
    condition: t => t.MessagesReceived % 100000 == 0 && t.MessagesReceived > 0,
    action: t => Console.WriteLine($"Đã xử lý: {t.MessagesReceived} tin nhắn."),
);

Quy ước Chủ đề (Routing Topics)

Hệ thống sử dụng bộ định tuyến ngầm định trong NatifyTopics:

• Client lắng nghe: NatifyClient.<client_name>.<server_name>.<regionId>.<topic>
• Server lắng nghe: NatifyServer.<server_name>.<client_name>.*.<topic>
• (Ký tự * cho phép Server gom tập trung tin nhắn từ mọi Region vào chung một đầu mối xử lý).

Quản lý Vòng đời (Dispose & Graceful Shutdown)

Hệ thống được thiết kế Tắt Mềm (Graceful Shutdown) để bảo vệ dữ liệu. Khi gọi client.Dispose() hoặc server.Dispose():

1. Van đầu vào bị khóa (Không nhận thêm lệnh Publish mới).
2. Hệ thống sẽ đợi tối đa 2 giây để các luồng ngầm gom nốt Batch cuối cùng và chờ nhận đủ ACK từ phía đối diện.
3. Giải phóng bộ nhớ TimeWheel.
4. An toàn đóng kết nối NATS.

Bắt buộc phải gọi .Dispose() khi tắt ứng dụng hoặc khi đối tượng không còn được sử dụng để tránh Memory Leak.

V 1.0.2 - Ra mắt NatifyClientFast: Phiên bản Client tối ưu tốc độ đa luồng dành riêng cho hệ thống Backend chạy ngầm (Tick-free). - Cải thiện luồng Request xử lý tốt hơn ở mức cường độ lên tới hàng trăm ngàn tác vụ (200K RPS). V 1.0.1 - fix request bị miss tin nhắn nếu client gửi liên tục nhiều request cùng lúc