Skip to content

Nalix.Codec

Nalix.Codec handles the transformation of data between objects and wire formats. It includes serialization, compression, and security transforms.

Key Responsibilities

  • Serialization: Fast, low-allocation binary serialization for packets.
  • Compression: Integrated LZ4 compression for reducing network bandwidth.
  • Security: Framed packet encryption and hashing.
  • Memory: Efficient buffer leasing and IO primitives (DataReader, DataWriter).

Where it fits

flowchart LR
    A["Nalix.Codec"] --> B["Serialization"]
    A --> C["Transforms"]
    A --> D["Memory"]
    B --> E["Nalix.Network"]
    B --> F["Nalix.SDK"]

Core Components

LiteSerializer

A high-performance binary serializer that uses attributes to define layout.

BufferLease

A lightweight wrapper around pooled memory that ensures safe disposal and reuse.

FrameCipher and FrameCompression

Helpers for applying encryption and compression to framed packets.

LZ4Codec

A pooled implementation of the LZ4 compression algorithm.

Registry flow

flowchart LR
    A["PacketRegistryFactory"] --> B["Include assemblies / namespaces"]
    B --> C["CreateCatalog()"]
    C --> D["PacketRegistry"]
    D --> E["Nalix.Network"]
    D --> F["Nalix.SDK"]

Purpose

  • Define built-in frames.
  • Build an immutable packet registry.
  • Provide shared serialization helpers.
  • Provide pooled LZ4 compression primitives.
  • Provide shared framed packet transform helpers (FrameCipher and FrameCompression).

Key components

  • FrameBase / PacketBase<TSelf> — base abstractions for headers, auto-magic, serialization, and pooling.
  • SerializePackableAttribute / SerializeOrderAttribute / SerializeIgnoreAttribute / SerializeHeaderAttribute / SerializeDynamicSizeAttribute — low-level serialization layout controls.
  • LiteSerializer / FormatterProvider / IFormatter<T> — serializer entry points and formatter resolution.
  • DataReader / DataWriter / HeaderExtensions — low-level read/write and header inspection helpers.
  • PacketRegistryFactory — scans packet types and binds deserialize function pointers.
  • PacketRegistry — frozen catalog of deserializers/transformers.
  • Handshake — default handshake frame used to exchange ephemeral keys, nonces, proofs, and transcript hash.
  • SessionResume — unified session signal packet for resume request/response flows (uses SessionResumeStage for stage disambiguation).
  • Control — built-in frame type.
  • PacketProvider<TPacket> — packet initialization and pooling helpers.
  • FragmentHeader / FragmentAssembler / FragmentOptions — chunk large payloads and reassemble them safely.
  • FrameCipher / FrameCompression — framed packet encrypt/decrypt and compress/decompress helpers.
  • LZ4Codec — pooled block compression and decompression.

Quick example

using Nalix.Codec.DataFrames;
using Nalix.Codec.DataFrames.SignalFrames;
using Nalix.Codec.Memory;

// Build and register the shared catalog
PacketRegistryFactory factory = new();
PacketRegistry registry = factory.CreateCatalog();
PacketRegistry.Configure(poolManager); // optional: enable packet pooling
InstanceManager.Instance.Register<IPacketRegistry>(registry);

// Handshake frame
Handshake hs = new(
    HandshakeStage.CLIENT_HELLO,
    new Bytes32(publicKeyBytes),
    new Bytes32(nonceBytes),
    flags: PacketFlags.SYSTEM | PacketFlags.RELIABLE);
hs.UpdateTranscriptHash("nalix-default-handshake"u8);
byte[] bytes = hs.Serialize();

Registry build flow

  • Add assemblies or namespaces if you have custom packets.
  • Call CreateCatalog() once and reuse the result in listeners and clients.

Quick example

PacketRegistryFactory factory = new();
factory.IncludeNamespaceRecursive("MyApp.Packets");
PacketRegistry catalog = factory.CreateCatalog();

Key API pages