Documentation

Packet Contracts

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

Nalix.Abstractions.Networking.Packets defines the wire packet, handler context, sender, and deserializer contracts shared across Nalix.Codec, Nalix.Runtime, Nalix.Network, and Nalix.SDK.

Source Mapping

  • src/Nalix.Abstractions/Networking/Packets/IPacket.cs
  • src/Nalix.Abstractions/Networking/Packets/IPacketHeader.cs
  • src/Nalix.Abstractions/Networking/Packets/IPacketStaticOpcode.cs
  • src/Nalix.Abstractions/Networking/Packets/IPacketContext.cs
  • src/Nalix.Abstractions/Networking/Packets/IPacketDeserializer.cs
  • src/Nalix.Abstractions/Networking/Packets/IPacketSender.cs
  • src/Nalix.Abstractions/Networking/Packets/PacketDeserializer.cs
  • src/Nalix.Abstractions/Networking/Packets/IPacketTimestamped.cs
  • src/Nalix.Abstractions/Networking/Packets/IPacketReasoned.cs
  • src/Nalix.Abstractions/Networking/Packets/IPacketValidatable.cs
  • src/Nalix.Abstractions/Networking/Packets/IPacketStreamable.cs
  • src/Nalix.Abstractions/Primitives/Bytes32.cs

Main Types

IPacket

public interface IPacket is the base contract for every wire packet (PacketBase<TSelf> in Nalix.Codec implements IPacket, IPacketHeader, and IPoolable):

MemberTypeDescription
HeaderPacketHeader6-byte wire header (OpCode, Flags, Priority, SequenceId).
LengthintTotal serialized byte length of the packet (including the 6-byte header).
Serialize()byte[]Serializes the packet into a newly allocated byte array.
Serialize(Span<byte> buffer)intZero-allocation serialization directly into buffer, returning the number of bytes written.

IPacketContext<TPacket>

public interface IPacketContext<TPacket> : IPoolable where TPacket : IPacket represents the pooled per-packet dispatch context passed as parameter 0 to every [PacketOpcode] handler:

PropertyTypeDescription
PacketTPacketThe deserialized request packet.
ConnectionIConnectionThe client connection that sent the packet.
AttributesPacketMetadataCompile-time handler attributes (PacketOpcode, Timeout, Permission, Encryption, RateLimit, Transport).
SenderIPacketSenderMetadata-aware outbound packet sender bound to this context.
ScopeIPacketScopePer-packet service scope used to resolve [FromScope] handler parameters.
EncryptedOnWirebooltrue if the inbound frame arrived encrypted on the wire before FrameCipher.DecryptFrame stripped PacketFlags.ENCRYPTED.
IsReliablebooltrue when the packet arrived over a reliable transport (TCP or WEBSOCKET).
SkipOutboundboolWhen set to true, skips outbound middleware execution for this context.
CancellationTokenCancellationTokenCancellation token governing the handler execution (including TimeoutMiddleware budgets).

IPacketSender

public interface IPacketSender : IPoolable provides metadata-aware response helpers inside handlers and middleware:

MethodSignatureDescription
Initialize<TPacket>void Initialize<TPacket>(IPacketContext<TPacket> context) where TPacket : IPacketBinds the pooled sender to the active IPacketContext<TPacket>.
SendAsyncValueTask SendAsync(IPacket packet, CancellationToken ct = default)Sends packet to context.Connection, automatically applying [PacketEncryption] and [PacketTransport] metadata from the handler.
SendAsync (explicit encryption)ValueTask SendAsync(IPacket packet, bool forceEncrypt, CancellationToken ct = default)Sends packet while explicitly overriding encryption (forceEncrypt).
ReplyAsyncValueTask ReplyAsync(IPacket response, CancellationToken ct = default)Automatically stamps response.SequenceId = context.Packet.SequenceId before sending so session.RequestAsync<T>() correlates the reply.

Supporting Packet & Primitive Contracts

  • IPacketStaticOpcode: public static abstract ushort StaticOpCode { get; } — binds a packet class to its compile-time 16-bit opcode for PacketRegistryGenerator.
  • IPacketDeserializer<out TPacket>: public static abstract TPacket Deserialize(ReadOnlySpan<byte> buffer) — zero-reflection static factory implemented by PacketBase<TSelf>.
  • PacketDeserializer: public delegate IPacket PacketDeserializer(ReadOnlySpan<byte> raw) — delegate stored in PacketRegistry.
  • IPacketTimestamped: Exposes long Timestamp { get; set; } and long MonoTicks { get; set; } for latency and time-sync packets.
  • IPacketReasoned: Exposes ProtocolReason Reason { get; } for control and diagnostic packets.
  • IPacketValidatable: Exposes bool Validate([NotNullWhen(false)] out string? failureReason) for structural packet validation.
  • IPacketStreamable & IPacketStreamTerminator: Contracts for server-to-client streaming packets (bool IsEndOfStream { get; set; } on IPacketStreamable, and bool IsTerminator { get; } on IPacketStreamTerminator).
  • Bytes32 (Nalix.Abstractions.Primitives): Fixed 32-byte (Bytes32.Size = 32) stack-allocated value type ([StructLayout(LayoutKind.Explicit)] with 4 × ulong fields, implementing IEquatable<Bytes32> and IFixedSizeSerializable) used for X25519 keys, nonces, Keccak-256 digests, and HMAC proofs (Bytes32.Zero, IsZero, CopyFrom, WriteTo, TryWriteTo, AsSpan, ToByteArray(), Parse(string hex), Wipe(ref Bytes32)).

Responsibility Boundaries

  • Nalix.Abstractions: Interfaces, attributes, headers, and zero-dependency value primitives.
  • Nalix.Codec: Concrete PacketBase<TSelf> frame model, PacketRegistry, and binary LiteSerializer.
  • Nalix.Runtime: Pooled PacketContext<TPacket>, PacketSender, and PacketDispatchChannel.
  • Nalix.SDK: Client sessions (TcpSession, UdpSession, WebSocketSession) consuming the same packet contracts.