Tài liệu

Thuộc tính gói tin

Thời gian đọc 3 phút Gói: Nalix.Abstractions
Trên trang này

Không gian tên: Nalix.Abstractions.Networking.Packets (và Nalix.Abstractions.Networking.Rpc)
Assembly: Nalix.Abstractions

Nalix dùng attribute để khai báo việc phát hiện controller, định tuyến opcode, ràng buộc transport, mức quyền, yêu cầu mã hóa, giới hạn tốc độ và timeout thực thi. Các attribute này được PacketHandlerGenerator biên dịch thành struct PacketMetadata không cấp phát bộ nhớ lúc build.

Ánh xạ mã nguồn

  • src/Nalix.Abstractions/Networking/Packets/PacketHandlerAttribute.cs
  • src/Nalix.Abstractions/Networking/Packets/PacketOpcodeAttribute.cs
  • src/Nalix.Abstractions/Networking/Packets/PacketPermissionAttribute.cs
  • src/Nalix.Abstractions/Networking/Packets/PacketRateLimitAttribute.cs
  • src/Nalix.Abstractions/Networking/Packets/PacketEncryptionAttribute.cs
  • src/Nalix.Abstractions/Networking/Packets/PacketTimeoutAttribute.cs
  • src/Nalix.Abstractions/Networking/Packets/PacketTransportAttribute.cs
  • src/Nalix.Abstractions/Networking/Packets/PacketIdempotentAttribute.cs
  • src/Nalix.Abstractions/Networking/Rpc/RpcServiceAttribute.cs

Tham chiếu attribute

AttributePhạm viHàm dựng & thuộc tínhMục đích
[PacketHandler]LớpPacketHandlerAttribute(string name = "None", bool isActive = true, string version = "1.0")
Thuộc tính: Name, IsActive, Version		Đánh dấu một lớp là controller gói tin được biên dịch bởi PacketHandlerGenerator.
[PacketOpcode]Phương thứcPacketOpcodeAttribute(ushort opCode)
PacketOpcodeAttribute(object opcode) (giá trị enum)
Thuộc tính: ushort OpCode { get; }		Gắn một method handler với opcode gói tin 16-bit (>= 0x0100 cho gói ứng dụng; 0x0000..0x00FF dành riêng cho protocol hệ thống).
[PacketPermission]Phương thứcPacketPermissionAttribute(PermissionLevel level = PermissionLevel.USER)
PacketPermissionAttribute(PermissionLevel level, PermissionEvaluation evaluation)
Thuộc tính: PermissionLevel Level, PermissionEvaluation Evaluation		Khai báo connection.Level yêu cầu (MinimumLevel mặc định, hoặc StrictMatch), được PermissionMiddleware thi hành.
[PacketEncryption]Phương thứcPacketEncryptionAttribute(bool isEncrypted = true, CipherSuiteType algorithmType = CipherSuiteType.Chacha20Poly1305)
Thuộc tính: bool IsEncrypted, CipherSuiteType AlgorithmType		Yêu cầu context.EncryptedOnWire == true (được PacketEncryptionMiddleware thi hành) và mã hóa các phản hồi gửi qua context.Sender.
[PacketRateLimit]Phương thứcPacketRateLimitAttribute(int requestsPerSecond, double burst = 1.0)
Thuộc tính: int RequestsPerSecond, double Burst
Thuộc tính khởi tạo: string? PolicyId, int HardLockoutSeconds = -1, int MaxSoftViolations = -1		Gắn giới hạn token-bucket cho handler, được RateLimitMiddleware thi hành.
[PacketTimeout]Phương thứcPacketTimeoutAttribute(int timeoutMilliseconds)
Thuộc tính: int TimeoutMilliseconds { get; }		Đặt ngân sách timeout cho CancellationToken liên kết, tính bằng mili giây, được TimeoutMiddleware thi hành.
[PacketTransport]Phương thứcPacketTransportAttribute(NetworkTransport transport)
Thuộc tính: NetworkTransport TransportType { get; }		Giới hạn handler vào NetworkTransport.TCP, UDP hoặc WEBSOCKET (được TransportMiddleware thi hành) và định tuyến phản hồi của context.Sender qua transport đó.
[PacketIdempotent]LớpPacketIdempotentAttribute()Chỉ là metadata mang tính tài liệu, đánh dấu lớp gói tin là idempotent (an toàn cho chính sách retry phía client).
[ReservedOpcodePermitted]Lớp, Phương thứcReservedOpcodePermittedAttribute() (Nalix.Abstractions; không kế thừa, chỉ dùng một lần)Đánh dấu một kiểu hoặc method được phép dùng opcode dành riêng (0x0000..0x00FF), vốn thường bị chặn ở mức ứng dụng.
[RpcService]InterfaceRpcServiceAttribute()Đánh dấu một interface để RpcClientGenerator sinh extension client có kiểu lúc biên dịch.

Ví dụ thực tế

using System.Threading.Tasks;
using Nalix.Abstractions.Networking;
using Nalix.Abstractions.Networking.Packets;
using Nalix.Abstractions.Security;

[PacketHandler("SecureChat", version: "1.2")]
public sealed class SecureChatController
{
    [PacketOpcode(0x3001)]
    [PacketPermission(PermissionLevel.USER, PermissionEvaluation.MinimumLevel)]
    [PacketRateLimit(requestsPerSecond: 10, burst: 3, PolicyId = "chat-send", HardLockoutSeconds = 30, MaxSoftViolations = 5)]
    [PacketEncryption(true, CipherSuiteType.Chacha20Poly1305)]
    [PacketTimeout(5000)]
    [PacketTransport(NetworkTransport.TCP)]
    public ValueTask HandleChatMessageAsync(IPacketContext<ChatMessagePacket> context)
    {
        return context.Sender.ReplyAsync(new ChatAckPacket { MessageId = context.Packet.MessageId });
    }
}

API liên quan