Beskar.Mqtt.Server 3.0.1

<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</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="#examples">Examples</a> · <a href="#documenation">Documentation</a> · <a href="#performance-benchmarks">Performance</a> · <a href="#key-aspects">Key Aspects</a> </p> <br/>

<br/>

About

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

• Made with passion and love for the craft.
• Built for modern .NET using C# and designed to be highly performant, low-allocation, and easy to use.
• Purposefully designed to be lightweight and flexible.
• Performance-first approach with 100,000 - 10,800,000 messages/packets per second. (Depending on various factors)
• Many simple or more advanced example projects demonstrating how to use Beskar.Networking across various transports.
• Various Unit Tests to verify functionality and performance.
• Active development and steady progress towards a full feature set.
• Native OpenTelemetry and System.Diagnostics.Metrics telemetry support across all transports, resilient protocol, and MQTT. See Telemetry Meters.
• MQTT V3 and V5 support. (Server and Client) – Over any transport supported by Beskar.
• 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.

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 (supporting TCP, WebSockets, QUIC, UDP, UDS, Named Pipes, or Memory). 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.

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.
• 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.

• 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.
• 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 and instruments 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.