Packet Attributes¶

Nalix uses packet attributes to declare handler routing and execution policy.

Audit Summary¶

Existing page used one incorrect attribute name (PacketConcurrency) and included behavior wording stronger than what attributes alone guarantee.
Needed direct mapping to actual attribute types and their constructor parameters.

Missing Content Identified¶

Accurate attribute list with exact names from Nalix.Abstractions.Networking.Packets.
Clear distinction between declaration (attribute) and enforcement (runtime/middleware).

Improvement Rationale¶

Precise attribute docs reduce handler-registration errors and avoid policy misunderstandings.

Source Mapping¶

src/Nalix.Abstractions/Networking/Packets/PacketControllerAttribute.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/PacketConcurrencyLimitAttribute.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/NetworkTransport.cs

Attribute Reference¶

Attribute	Scope	Purpose
`PacketControllerAttribute`	Class	Marks a controller class for packet handlers. Defaults: `Name = "None"`, `IsActive = true`, `Version = "1.0"`.
`PacketOpcodeAttribute`	Method	Binds a handler to an opcode.
`PacketPermissionAttribute`	Method	Declares the minimum `PermissionLevel` required to run. Defaults to `USER`.
`PacketRateLimitAttribute`	Method	Declares requests-per-second and burst values.
`PacketConcurrencyLimitAttribute`	Method	Declares concurrency and queue limits.
`PacketEncryptionAttribute`	Method	Declares whether encryption is required and which cipher suite to use. Defaults to `true` and `Chacha20Poly1305`.
`PacketTimeoutAttribute`	Method	Declares a handler timeout budget in milliseconds.
`PacketTransportAttribute`	Method	Declares the preferred transport protocol for the handler's outbound response.

Why Attributes Exist¶

Attributes provide declarative metadata at registration time so dispatch/runtime layers can apply policy without embedding those policies directly inside business handlers.

Practical Example¶

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

[PacketController("SecureChat", version: "1.2")]
public sealed class SecureChatController
{
    [PacketOpcode(0x3001)]
    [PacketPermission(PermissionLevel.USER)]
    [PacketRateLimit(10, burst: 2)]
    [PacketConcurrencyLimit(100, queue: true, queueMax: 1000)]
    [PacketEncryption(true)]
    [PacketTimeout(5000)]
    [PacketTransport(NetworkTransport.UDP)]
    public static ValueTask HandleAsync(IPacketContext<ChatPacket> context)
    {
        // Application logic here
        return ValueTask.CompletedTask;
    }
}

For a comprehensive walkthrough of handler implementation, including error handling and registration, see the Implementing Packet Handlers guide.

Best Practices¶

Treat attributes as policy declarations; verify enforcement in runtime middleware configuration.
Keep opcode values centrally managed to avoid collisions.
Use explicit permission/rate/concurrency attributes on public-facing handlers.