Beskar.Networking.Abstractions 3.0.5

<h1> <p align="center"> <img src="https://github.com/MarvinDrude/Beskar.Networking/blob/master/Resources/banner.png" alt="Logo" width="256" /> <br /> Beskar.Networking </p> </h1> <p align="center"> Fast, <code>.NET 10</code> native, high-performance, low-allocation networking library.<br/> Built for modern <code>C#</code> includes TCP, WebSockets, QUIC, UDP, UDS, Named Pipes, Memory, and MQTT.<br/> No external runtime dependencies besides <b>Beskar</b>.<br/><br/> <a href="#about">About</a> · <a href="#quick-start">Quick Start</a> · <a href="#api-overview">API Overview</a> · <a href="#roslyn-source-generators">Source Generators</a> · <a href="#transport-comparison">Transports</a> · <a href="#examples">Examples</a> · <a href="#documentation">Documentation</a> · <a href="#performance-benchmarks">Performance</a> </p> <br/>

<br/>

About

Main reasons for why you should consider using Beskar.Networking for your next Networking, IPC, or MQTT use case:

• Made with passion and love for the craft.
• Built for modern .NET 10 using C# and designed to be highly performant, low-allocation, and easy to use.
• Extreme Performance: From 100,000 up to 12,700,000 messages/packets per second with zero/near-zero allocations via System.IO.Pipelines.
• Roslyn Incremental Source Generators: Compile-time protocol framing and zero-allocation MQTT topic byte generation.
• Built-in Chaos Engineering: Test network resiliency with built-in fault injection (latency jitter, packet drops, bandwidth caps, abrupt teardowns).
• Transport Independence: Run MQTT or Resilient protocols seamlessly over TCP, WebSockets, QUIC, UDP, Unix Domain Sockets (UDS), Named Pipes, or In-Memory.
• Native OpenTelemetry & Metrics: Built-in System.Diagnostics.Metrics meters across all transports, resilient protocol, and MQTT broker/client.
• Full MQTT v3.1.1 & v5.0 Support: High-performance broker and client with retained message persistence, offline crash-safe queuing, and user properties.
• No external runtime dependencies besides .NET and Beskar.

NuGet packages overview

Package / Project	Description	NuGet Link
Beskar.Mqtt.Server	High-performance, low-allocation MQTT broker/server support for v3.1.1 and v5.0 over any transport.
Beskar.Mqtt.Client	Lightweight and efficient MQTT client supporting v3.1.1 and v5.0 over any transport.
Beskar.Networking.Resilient.Server	High-performance, event-driven resilient server wrapper supporting keep-alives, handshakes, and custom framing over any transport.
Beskar.Networking.Resilient.Client	High-performance resilient client wrapper supporting automatic reconnection, keep-alives, handshakes, and custom framing.
Beskar.Networking.Transports.Tcp	High-performance, native TCP transport implementation supporting TLS.
Beskar.Networking.Transports.Ws	WebSocket (WS/WSS) transport adapter wrapping custom framed duplex pipelines.
Beskar.Networking.Transports.Quic	Multiplexed and secure QUIC transport implementation built on native .NET libraries.
Beskar.Networking.Transports.Udp	High-performance, virtualized session-multiplexed UDP transport implementation.
Beskar.Networking.Transports.Uds	Native Unix Domain Sockets (UDS) local transport implementation.
Beskar.Networking.Transports.NamedPipes	Native local Inter-Process Communication (IPC) Named Pipes transport implementation.
Beskar.Networking.Transports.Memory	Fast, zero-allocation local in-memory transport implementation for tests and local IPC.

Quick Start

Beskar.Networking provides 3 distinct levels of abstraction depending on your application needs.

Bare-Metal Transport API (Low-Level)

What it's worth: Maximum speed and total control over raw bytes using System.IO.Pipelines. Zero framework overhead. Ideal for building custom wire protocols, high-performance proxy gateways, or specialized network microservices.

var endPoint = new IPEndPoint(IPAddress.Loopback, 9000);

// Server Listener
await using var listener = new TcpNetworkListener(endPoint, new TcpTransportOptions());
await listener.BindAsync();

var serverTask = Task.Run(async () =>
{
   // ReSharper disable once AccessToDisposedClosure
   var sessionResult = await listener.AcceptSessionAsync();
   if (sessionResult.Failed) return;

   await using var session = sessionResult.Success;
   var streamResult = await session.AcceptStreamAsync();
   if (streamResult.Failed) return;

   var stream = streamResult.Success;

   // Read raw pipeline input
   var readResult = await stream.Transport.Input.ReadAsync();
   Console.WriteLine($"Received: {Encoding.UTF8.GetString(readResult.Buffer.FirstSpan)}");
});

// Client Connection
await using var client = new TcpNetworkClient(new TcpTransportOptions());
var connectResult = await client.ConnectAsync(endPoint);
if (!connectResult.Failed)
{
   var session = connectResult.Success;
   var streamResult = await session.AcceptStreamAsync();
   if (!streamResult.Failed)
   {
      var clientStream = streamResult.Success;

      // Write directly to pipeline output
      var bytes = "Hello Bare Metal!"u8.ToArray();
      await clientStream.Transport.Output.WriteAsync(bytes);
   }
}

// Wait for server task to finish processing received message
await serverTask;

Full MQTT Broker & Client (v3.1.1 & v5.0)

What it's worth: Full-featured, enterprise-grade MQTT pub/sub engine over any transport (TCP, WebSockets, UDS, Named Pipes, or Memory). Features QoS 0/1/2, Retained message persistence, offline crash-safe queuing, Topic Aliases, and User Properties trace contexts. Ideal for IoT fleets, event-driven microservices, and telemetry pipelines.

var endPoint = new IPEndPoint(IPAddress.Loopback, 1883);

// 1. Spin up MQTT Server / Broker
var broker = MqttServerFactory.CreateBuilder()
   .WithDefaultClientIdGenerator()
   .UseTcp(endPoint.Port)
   .Build();
var startResult = await broker.StartAsync();

// 2. Subscriber Client
await using var subClient = MqttClientFactory.CreateTcp();
subClient.AddMessageReceiveHandler((ctx, ct) => {
    Console.WriteLine($"Received [{ctx.Message.Topic}]: {Encoding.UTF8.GetString(ctx.Message.Payload.Span)}");
    return ValueTask.CompletedTask;
});
var connectResult = await subClient.ConnectAsync(new ConnectOptions { EndPoint = endPoint, ProtocolVersion = MqttProtocolVersion.V50 });
await subClient.SubscribeAsync(SubscribeOptions.Create().WithTopicFilter("sensors/temp", QualityOfServiceType.AtLeastOnce).Build());

// 3. Publisher Client
await using var pubClient = MqttClientFactory.CreateTcp();
var pubConnResult = await pubClient.ConnectAsync(new ConnectOptions { EndPoint = endPoint, ProtocolVersion = MqttProtocolVersion.V50 });
var pubResult = await pubClient.PublishAsync(PublishOptions.Create()
    .WithTopic("sensors/temp")
    .WithPayload("{ \"celsius\": 22.5 }")
    .WithQualityOfService(QualityOfServiceType.AtLeastOnce)
    .Build());

await Task.Delay(500);

await subClient.DisconnectAsync(new DisconnectOptions());
await pubClient.DisconnectAsync(new DisconnectOptions());
await broker.StopAsync();

Resilient Managed Engine (High-Level Event-Driven)

What it's worth: Production-ready real-time networking without connection handling boilerplate. Out-of-the-box auto-reconnection, ping-pong heartbeats with live RTT latency monitoring, HMAC challenge-response security, and framing serialization. Ideal for multiplayer games, chat applications, and financial streaming.

var endPoint = new IPEndPoint(IPAddress.Loopback, 9005);

// 1. Resilient Server
var server = ResilientServerFactory.CreateBuilder().UseTcp(endPoint).Build();
server.Events.FrameReceived.Add((ctx, ct) =>
{
   var text = Encoding.UTF8.GetString(ctx.Frame.GetPayloadSequence().ToArray());
   Console.WriteLine($"Server received: {text}");

   // Echo response frame back
   return ctx.Client.SendAsync(BeskarPacket.CreateMessage("Pong!"u8.ToArray()), ct);
});
await server.StartAsync();

// 2. Resilient Client (with Auto-Reconnect enabled)
var client = ResilientClientFactory.CreateTcp<BeskarPacket>(clientOptions: new ResilientClientOptions
{
   Reconnecting = new ResilientClientReconnectionOptions { AutoReconnect = true }
});

client.Events.FrameReceived.Add((ctx, ct) =>
{
   Console.WriteLine($"Client received: {Encoding.UTF8.GetString(ctx.Frame.GetPayloadSequence().ToArray())}");
   return ValueTask.CompletedTask;
});

await client.ConnectAsync(endPoint);
await client.SendAsync(BeskarPacket.CreateMessage("Ping!"u8.ToArray()));

await Task.Delay(500);

await client.DisposeAsync();
await server.DisposeAsync();

API Overview

Beskar.Networking offers different levels of abstraction depending on your application needs:

Low-Level Transports

The core library features protocol-agnostic, low-level interfaces:

• INetworkListener - The Server listener that accepts incoming connections and manages sessions.
• INetworkClient - The client that initiates connections and manages sessions.
• INetworkSession - Represents a single connection between a client and server.
• INetworkStream - Provides transport-agnostic handling (supporting TCP, WebSockets, QUIC, UDP, UDS, Named Pipes, or Memory).

These interfaces provide transport-agnostic handling. Because they are low-level, you are responsible for managing execution tasks yourself, such as starting your own accept loops, launching read/write tasks, and supervising session lifecycles.

For more details, see the Basics Documentation.

High-Level Managed APIs

For protocols like MQTT, or connection-resilient networking, Beskar.Networking provides fully managed implementations:

• Fully Managed Broker & Client (MQTT): Pre-built wrappers that manage the connection, session, and stream states automatically.
• Resilient Client & Server: Connection-resilient managed wrappers (ResilientClient<TFrame> and ResilientServer<TFrame>) that handle transient disconnect supervision, automatic pings/pongs (keep-alive), protocol control handshakes, custom challenge-response authentication, and pluggable framing protocol generation.
• Event-Driven: Fully event-driven design with convenient events to react to incoming messages, client connections, and status updates, eliminating the need to write custom accept loops or pipeline plumbing.

For more details, see the Resilient Documentation and Mqtt Documentation.

Roslyn Source Generators

Beskar.Networking comes equipped with Roslyn Incremental Source Generators to shift runtime reflections and string formatting overhead to compile-time:

• [GenerateFramingProtocol] (FramingProtocolGenerator): Zero-boilerplate compilation of custom wire framing protocols.
• [GeneratedMqttTopic] (MqttTopicGenerator): Compile-time MQTT topic path validation and generation of zero-allocation ReadOnlySpan<byte> publishing overloads.

Transport Comparison

Swap underlying transports dynamically without altering high-level business logic:

Examples

We provide both basic and advanced example projects demonstrating how to use Beskar.Networking across various transports:

All examples: Root Folder

• Simple Ping-Pong Message (Bare-metal): Demonstrates low-level server listener binding, client connection, and raw bidirectional message exchange using length-prefixed framing over System.IO.Pipelines using TCP.
• Advanced Multi-Transport Chat Application: A complete chat application consisting of:
  • Common: Reusable packet serialization and custom packet framing utilities.
  • Server: Integrates a unified ChatServerBuilder to listen and accept chat sessions concurrently on TCP (9000), WebSockets (11000), and QUIC (12000).
  • Client: An interactive console application allowing users to connect via their choice of protocol (TCP/WS/QUIC), receive recent chat history, and chat in real-time under a random username.
• MQTT Managed Examples: A set of projects demonstrating the high-level managed MQTT APIs:
  • Simple Publish-Subscribe: A complete pub-sub flow showing how to spin up an MQTT broker, connect a sensor client (publisher) and dashboard client (subscriber) over TCP using MQTT v5.0.
  • Generated Pub-Sub (Source Generator): Showcases how to use the high-performance MQTT Topic Source Generator to define compile-time validated topics and perform zero-allocation publishing using the generated byte[] format overloads.
  • Quality of Service (QoS) Levels: Demonstrates publishing and subscribing messages with different QoS levels (QoS 0: At Most Once, QoS 1: At Least Once, QoS 2: Exactly Once) using wildcard topic filters.
  • Authentication (v3 & v5 Challenges): Highlights both simple username/password validation for MQTT v3.1.1 and advanced challenge-response authentication for MQTT v5.0.
  • Client Reconnection & Event Handling: Shows how to register connection status events and implement custom auto-reconnection loops when connections are unexpectedly lost.
  • Disconnection Safety & Persistence: Demonstrates persistent sessions, server-side JSON serialization/restoration of retained messages, and client-side offline queuing (FIFO and Last Message Buffering) with crash safety.
  • Last Will and Testament (LWT): Shows how to configure client Will messages and verify that the server automatically delivers them upon ungraceful connection loss while ignoring them on graceful disconnects.
  • User Properties (Metadata): Demonstrates how to send and receive custom metadata headers (like trace context spans) using MQTT v5.0 User Properties.
  • Topic Aliases (Bandwidth Optimization): Illustrates how client and server negotiate and employ Topic Aliases to dramatically decrease packet sizes by substituting long topic paths with short integer codes.
  • Acknowledged Publish (Request-Response): Demonstrates how a publishing client sends a request message with ResponseTopic and CorrelationData requiring the receiving subscriber to acknowledge receipt and processing with an application-level response.
• Resilient Managed Examples: A set of projects demonstrating the high-level connection-resilient server and client wrappers:
  • Resilient Chat Application: A complete chat application using the resilient wrappers with default BeskarPacket framing and automated JSON serialization:
    • Common: Contains shared message payloads and a JSON ChatSerializer implementing IResilientSerializer.
    • Server: Integrates ResilientServer<BeskarPacket> to accept, track, and broadcast chat messages over TCP port 9000.
    • Client: Interactive chat client using ResilientClient<BeskarPacket> that reconnects and re-authenticates/joins automatically when connection is lost.
  • Simple Ping-Pong: Demonstrates basic ping-pong message exchange using ResilientServer and ResilientClient with default framing over TCP port 9001.
  • Authentication Challenge-Response: Highlights pre-handshake HMAC-SHA256 signature challenge-response authentication, showing both success and server-denial test cases on TCP port 9002.
• Telemetry & OpenTelemetry Console: Demonstrates how to subscribe to all native telemetry meters using MeterListener or OpenTelemetry exporters, showing real-time event streaming and a live metrics summary dashboard as operations occur.

Documentation

You can find detailed documentation for Beskar.Networking here.

• Basics & Architecture: Overview of core interfaces (INetworkListener, INetworkClient, INetworkSession, INetworkStream).
• Dedicated Transport Guides:
  • TCP Transport Guide
  • WebSocket Transport Guide
  • QUIC Transport Guide
  • UDP Transport Guide
  • Unix Domain Sockets (UDS) Guide
  • Named Pipes Guide
  • In-Memory Transport Guide
• Telemetry Meters Reference: Detailed reference of all OpenTelemetry and System.Diagnostics.Metrics meters, instruments, types, units, and descriptions across MQTT, Resilient, and Transports.

Or you can find examples directly here.

Performance Benchmarks

<a href="https://www.http-arena.com/#scope=ws&type=experimental,flagship"> <img src="https://cdn.jsdelivr.net/gh/MDA2AV/httparena-badge/wordmark.svg" alt="Benchmarked by HttpArena" height="44"> </a>

Engineered from the ground up for maximum throughput and minimum allocation overhead.

[!NOTE]
Computer Specs:<br/> CPU: AMD Ryzen 9 7950X3D, Memory: 64 GB DDR5

Method: Payload does not include protocol, Local Loopback Benchmark<br /> Note: Benchmarks are subject to change as the library evolves.

Key Aspects

Beskar.Networking is a high-performance, low-allocation networking library built for modern .NET 10 using C#. It provides a unified, pipe-based interface abstraction (INetworkListener, INetworkClient, INetworkSession, INetworkStream) for building extremely fast network applications across multiple transport protocols.

• Unified Abstractions: Write your network layer once and swap between TCP, WebSockets, QUIC, UDP, UDS, Named Pipes, or Memory dynamically.
• Modern .NET 10 Stack: Heavily leverages System.IO.Pipelines (decoupling IO thread queues from application processing), Span<T>, ReadOnlySpan<T>, and direct memory pooling to achieve zero/near-zero allocations.
• Roslyn Incremental Source Generators: Zero-allocation MQTT topic formatting and compile-time framing protocol compilation.
• Built-in Chaos Simulator: Battle-tested against latency jitter, packet loss, bandwidth caps, and data corruption.
• TLS/SSL Encryption: Full native SSL/TLS wrapping for TCP and WebSocket transports out of the box.
• Non-blocking IO Queueing: Highly-optimized custom IO queues (like TcpIoQueueRegistry / TcpIoQueue) to handle asynchronous reading and writing concurrently.
• Native OpenTelemetry & Metrics: Built-in System.Diagnostics.Metrics meters tracking live active connections, streams, byte throughput, MQTT broker sessions/retries/retained messages, and resilient RTT/reconnections. See Telemetry Meters Reference.
• Full MQTT: Complete MQTT v3.1.1 and v5.0 server broker and client support over any transport.