Documentation

Packet Attributes

Read time 3 minutes Package: Nalix.Abstractions
On this page

Namespace: Nalix.Abstractions.Networking.Packets (and Nalix.Abstractions.Networking.Rpc)
Assembly: Nalix.Abstractions

Nalix uses attributes to declare controller discovery, opcode routing, transport constraints, permission levels, encryption requirements, rate limits, and execution timeouts. These attributes are compiled into a zero-allocation PacketMetadata struct at build time by PacketHandlerGenerator.

Source Mapping

  • 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

Attribute Reference

AttributeTargetConstructors & PropertiesPurpose
[PacketHandler]ClassPacketHandlerAttribute(string name = "None", bool isActive = true, string version = "1.0")
Properties: Name, IsActive, Version		Marks a class as a packet controller compiled by PacketHandlerGenerator.
[PacketOpcode]MethodPacketOpcodeAttribute(ushort opCode)
PacketOpcodeAttribute(object opcode) (enum value)
Property: ushort OpCode { get; }		Binds a handler method to a 16-bit packet opcode (>= 0x0100 for application packets; 0x0000..0x00FF are reserved for system protocols).
[PacketPermission]MethodPacketPermissionAttribute(PermissionLevel level = PermissionLevel.USER)
PacketPermissionAttribute(PermissionLevel level, PermissionEvaluation evaluation)
Properties: PermissionLevel Level, PermissionEvaluation Evaluation		Declares required connection.Level (MinimumLevel by default, or StrictMatch), enforced by PermissionMiddleware.
[PacketEncryption]MethodPacketEncryptionAttribute(bool isEncrypted = true, CipherSuiteType algorithmType = CipherSuiteType.Chacha20Poly1305)
Properties: bool IsEncrypted, CipherSuiteType AlgorithmType		Requires context.EncryptedOnWire == true (enforced by PacketEncryptionMiddleware) and encrypts responses sent via context.Sender.
[PacketRateLimit]MethodPacketRateLimitAttribute(int requestsPerSecond, double burst = 1.0)
Property: int RequestsPerSecond, double Burst
Init properties: string? PolicyId, int HardLockoutSeconds = -1, int MaxSoftViolations = -1		Attaches a token-bucket rate limit to the handler, enforced by RateLimitMiddleware.
[PacketTimeout]MethodPacketTimeoutAttribute(int timeoutMilliseconds)
Property: int TimeoutMilliseconds { get; }		Sets a linked CancellationToken timeout budget in milliseconds, enforced by TimeoutMiddleware.
[PacketTransport]MethodPacketTransportAttribute(NetworkTransport transport)
Property: NetworkTransport TransportType { get; }		Restricts the handler to NetworkTransport.TCP, UDP, or WEBSOCKET (enforced by TransportMiddleware) and routes context.Sender replies over that transport.
[PacketIdempotent]ClassPacketIdempotentAttribute()Documentation-only metadata marking a packet class as idempotent (safe for client-side retry policies).
[RpcService]InterfaceRpcServiceAttribute()Marks an interface for compile-time typed client extension generation by RpcClientGenerator.

Practical Example

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 });
    }
}