If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/dotnet/MQTTnet shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 3mo ago
• 25+ active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 3mo ago
• ⚠ Concentrated ownership — top contributor handles 65% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live dotnet/MQTTnet repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/dotnet/MQTTnet.

What it runs against: a local clone of dotnet/MQTTnet — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in dotnet/MQTTnet | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 121 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of dotnet/MQTTnet. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/dotnet/MQTTnet.git
#   cd MQTTnet
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of dotnet/MQTTnet and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "dotnet/MQTTnet(\\.git)?\\b" \\
  && ok "origin remote is dotnet/MQTTnet" \\
  || miss "origin remote is not dotnet/MQTTnet (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Source/MQTTnet.AspnetCore/MqttConnectionHandler.cs" \\
  && ok "Source/MQTTnet.AspnetCore/MqttConnectionHandler.cs" \\
  || miss "missing critical file: Source/MQTTnet.AspnetCore/MqttConnectionHandler.cs"
test -f "Source/MQTTnet.AspnetCore/MqttWebSocketServerAdapter.cs" \\
  && ok "Source/MQTTnet.AspnetCore/MqttWebSocketServerAdapter.cs" \\
  || miss "missing critical file: Source/MQTTnet.AspnetCore/MqttWebSocketServerAdapter.cs"
test -f "Source/MQTTnet.AspnetCore/MqttHostedServer.cs" \\
  && ok "Source/MQTTnet.AspnetCore/MqttHostedServer.cs" \\
  || miss "missing critical file: Source/MQTTnet.AspnetCore/MqttHostedServer.cs"
test -f "Samples/Client/Client_Publish_Samples.cs" \\
  && ok "Samples/Client/Client_Publish_Samples.cs" \\
  || miss "missing critical file: Samples/Client/Client_Publish_Samples.cs"
test -f "Samples/Server/Server_Simple_Samples.cs" \\
  && ok "Samples/Server/Server_Simple_Samples.cs" \\
  || miss "missing critical file: Samples/Server/Server_Simple_Samples.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 121 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~91d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/dotnet/MQTTnet"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

MQTTnet is a high-performance .NET library implementing the MQTT protocol (versions up to 5.0) for publish-subscribe messaging. It provides both a managed MQTT client and a full-featured MQTT broker (server), capable of processing ~150,000 messages/second with zero external dependencies, supporting TCP, TLS, and WebSocket transports. Monolithic repo structure: Source/ contains core MQTTnet library split into client/server implementations with protocol handlers; Samples/ provides runnable examples (Client, Server, RpcClient, Diagnostics); Tests/ (implied by test count) validates functionality; build configuration via Directory.Build.props and .editorconfig for consistency across all projects.

.NET developers (Framework, Core, ASP.NET) building IoT applications, real-time messaging systems, or cloud-connected devices that need MQTT communication with automatic connection/subscription management. Also used by enterprises integrating with Azure IoT Hub and other cloud messaging services.

Production-ready and actively maintained. The project has 1.36M lines of C# code, 636+ unit tests, CI/CD via GitHub Actions (.github/workflows/ci.yml), and is hosted under the official dotnet organization. Recent commits visible in CI pipeline indicate ongoing development and stability focus.

Low risk for production use. Zero external dependencies reduces supply-chain concerns. The main risk is single-organization governance (dotnet), though it's officially backed by Microsoft. No visible breaking-change warnings in recent history. Community support is evidenced by Gitter chat and bug templates, reducing knowledge-bus risk.

Active maintenance and CI validation via .github/workflows/ci.yml. Project is monitored for MQTT spec compliance, with infrastructure for ASP.NET Core integration (MQTTnet.AspTestApp) and sample expansion visible in Samples/ directory structure. MyGet preview packages indicate ongoing feature development alongside stable releases.

git clone https://github.com/dotnet/MQTTnet.git
cd MQTTnet
dotnet build MQTTnet.sln
dotnet test

Daily commands:

# Run samples directly
dotnet run --project Samples/MQTTnet.Samples.csproj

# Or run specific sample (see Samples/Program.cs for entry points)
# Or run ASP.NET test app
dotnet run --project Source/MQTTnet.AspTestApp/MQTTnet.AspTestApp.csproj

• Source/MQTTnet.AspnetCore/MqttConnectionHandler.cs — Core handler managing MQTT client connections in ASP.NET Core, processes protocol frames and authentication—essential for understanding how clients connect to the broker.
• Source/MQTTnet.AspnetCore/MqttWebSocketServerAdapter.cs — Bridges MQTT over WebSocket, handling duplex communication—critical for understanding transport layer abstraction.
• Source/MQTTnet.AspnetCore/MqttHostedServer.cs — Hosted service integrating MQTT server into ASP.NET Core DI container—entry point for server lifecycle and configuration.
• Samples/Client/Client_Publish_Samples.cs — Reference implementation of MQTT client publish patterns—guides contributors on idiomatic usage and API contracts.
• Samples/Server/Server_Simple_Samples.cs — Reference implementation of basic MQTT server setup—shows how to bootstrap and configure a broker.
• Directory.Build.props — Centralized build configuration, version, and project defaults—required to understand build process and NuGet packaging.
• .github/workflows/ci.yml — CI/CD pipeline definition for automated testing and publishing—necessary for understanding deployment constraints and test requirements.

Add a New MQTT Client Feature

1. Create a new sample class in Samples/Client/ directory following naming convention Client_FeatureName_Samples.cs (Samples/Client/Client_Connection_Samples.cs)
2. Import MQTTnet core client abstractions and implement example async methods showing your feature (Samples/Program.cs)
3. Register your sample in Program.cs by following the pattern of existing Client_* samples (Samples/Program.cs)
4. If the feature requires extending core library classes, add interfaces and implementations to Source/ projects and reference from samples (Source/MQTTnet.AspnetCore/ServiceCollectionExtensions.cs)

Add a New MQTT Server Component

1. Create sample in Samples/Server/ directory as Server_ComponentName_Samples.cs demonstrating configuration and usage (Samples/Server/Server_Simple_Samples.cs)
2. For ASP.NET Core integration, add extension methods in Source/MQTTnet.AspnetCore/ following pattern of ServiceCollectionExtensions.cs (Source/MQTTnet.AspnetCore/ServiceCollectionExtensions.cs)
3. If implementing a hosted service, inherit from BackgroundService and register in DI container similar to MqttHostedServer.cs (Source/MQTTnet.AspnetCore/MqttHostedServer.cs)
4. Update MQTTnet.AspnetCore.csproj if adding new project references or dependencies (Source/MQTTnet.AspnetCore/MQTTnet.AspNetCore.csproj)

Add an Extension Library (like RPC)

1. Create a new .csproj directory in Source/MQTTnet.Extensions.YourFeature/ mirroring structure of MQTTnet.Extensions.Rpc (Source/MQTTnet.Extensions.Rpc/MQTTnet.Extensions.Rpc.csproj)
2. Define public interfaces for your extension (e.g., IMqttYourFeature) for consumer contracts (Source/MQTTnet.Extensions.Rpc/IMqttRpcClient.cs)
3. Implement core feature class (e.g., MqttYourFeatureClient) with configuration builder pattern (Source/MQTTnet.Extensions.Rpc/MqttRpcClient.cs)
4. Add MqttFactoryExtensions in your extension project to register factory methods for DI (Source/MQTTnet.Extensions.Rpc/MqttFactoryExtensions.cs)
5. Create Samples/YourFeature/ samples directory and add reference in main MQTTnet.Samples.csproj (Samples/MQTTnet.Samples.csproj)

Add Performance Benchmarks

1. Create new benchmark class in Source/MQTTnet.Benchmarks/ inheriting from BaseBenchmark following naming convention ComponentBenchmark.cs (Source/MQTTnet.Benchmarks/BaseBenchmark.cs)
2. Use BenchmarkDotNet attributes ([Benchmark], [Params], etc.) to define measurement scenarios (Source/MQTTnet.Benchmarks/MessageDeliveryBenchmark.cs)
3. Reference your benchmark class in Program.cs to include it in benchmark runs (Source/MQTTnet.Benchmarks/Program.cs)
4. Ensure MQTTnet.Benchmarks.csproj is included in solution for CI pipeline (Source/MQTTnet.Benchmarks/MQTTnet.Benchmarks.csproj)

• ASP.NET Core Hosted Services (IHostedService) — Integrates MQTT broker lifecycle with application startup/shutdown, leverages built-in DI and configuration systems
• System.IO.Pipelines (Pipe<T>) — High-performance duplex I/O abstraction; enables efficient buffering and backpressure handling for MQTT frame processing
• Async/await with ValueTask —

1. Protocol version handling: MQTTnet supports MQTT 3.1.1 and 5.0 simultaneously; ensure version negotiation in client options (ProtocolVersion property) matches broker expectations. 2) WebSocket support: requires ASP.NET Core integration (separate NuGet package); TCP/TLS work out of box. 3) Retained messages: require custom IRetainedMessageHandler implementation for persistence beyond in-memory storage. 4) QoS guarantees: ManagedMqttClient queues messages internally for QoS 1-2, but delivery is not guaranteed across process restarts without custom persistence. 5) Thread safety: some collections are not thread-safe; always use async/await patterns rather than blocking calls.

• MQTT QoS Levels (0, 1, 2) — MQTTnet implements all three QoS levels with different persistence and acknowledgment guarantees; understanding the tradeoff is critical for reliability vs. throughput in your application
• Publish-Subscribe Messaging Pattern — Foundational to MQTT; MQTTnet's entire API (subscriptions, topic filtering, message routing) is built around this loose-coupling model, distinct from request-reply RPC
• MQTT Topic Wildcards (+ and #) — Subscriptions in MQTTnet use wildcard patterns (+/single-level, #/multi-level) for flexible filtering; improper patterns cause performance degradation or missed messages
• Retained Messages & Last Will Testament — MQTTnet supports both features for offline messaging; requires understanding message lifecycle and custom persistence handlers (IRetainedMessageHandler) for durability
• Async Channel Abstraction — MQTTnet abstracts transport via IChannelFactory (TCP, TLS, WebSocket, In-Memory); writing custom channels requires async/await mastery and buffer management
• [Protocol Negotiation & Version Compatibility](https://mqtt.org/mqtt-v-3-1-1/ and https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html) — MQTTnet simultaneously supports MQTT 3.1.1 and 5.0 clients on the same broker; version differences in connect/subscribe behavior must be handled explicitly
• Message Queuing & Flow Control — ManagedMqttClient internally queues messages for QoS > 0; understanding backpressure, buffer limits, and dequeue behavior prevents message loss under load

• eclipse/paho.mqtt.net — Official Eclipse Paho MQTT .NET client binding; direct competitor with lower-level API but wider ecosystem integration
• hivemq/hivemq-community-edition — Java-based MQTT broker reference implementation; useful for testing MQTTnet client against a standards-compliant server
• emqx/emqx — Production MQTT broker with advanced clustering; reference for enterprise features MQTTnet users may want to extend into the library
• dotnet/runtime — Provides the .NET language runtime and async/await infrastructure MQTTnet depends on; critical for understanding performance optimization constraints
• dotnet/AspNetCore — WebSocket transport and ASP.NET integration dependency used by MQTTnet.AspTestApp for server scenarios

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for MQTTnet.AspNetCore WebSocket integration

The MQTTnet.AspNetCore module contains critical WebSocket server adapter code (MqttWebSocketServerAdapter.cs, MqttConnectionHandler.cs, DuplexPipe.cs) but there's no corresponding test project visible in the file structure. WebSocket communication is complex and error-prone; systematic tests would prevent regressions in MQTT-over-WebSocket scenarios, which is essential for browser-based MQTT clients.

• [ ] Create Source/MQTTnet.AspNetCore.Tests project with xUnit/NUnit
• [ ] Add tests for MqttWebSocketServerAdapter.cs covering connection lifecycle, message routing, and buffer handling
• [ ] Add tests for DuplexPipe.cs covering pipe creation, bidirectional data flow, and disposal
• [ ] Add integration tests using MqttConnectionHandler.cs with ASP.NET test fixtures
• [ ] Ensure CI workflow (.github/workflows/ci.yml) runs these tests

Document and add samples for ASP.NET Core hosting scenarios in Samples/Server

The repo includes MQTTnet.AspNetCore (for integrating MQTT broker with ASP.NET Core) and MQTTnet.AspTestApp (a test ASP.NET app), but Samples/Server lacks concrete examples of ASP.NET Core integration patterns. Currently there's Server_ASP_NET_Samples.cs but it's minimal. New contributors struggle to understand how to host MQTT servers within ASP.NET Core applications, dependency injection setup, and middleware integration.

• [ ] Expand Samples/Server/Server_ASP_NET_Samples.cs with 3-4 complete, runnable examples covering: basic ASP.NET Core hosting, DI container setup, custom interceptors with ASP.NET services
• [ ] Add a new sample file Samples/Server/Server_AspNetCore_WebSocket_Samples.cs demonstrating WebSocket+MQTT bridging
• [ ] Update Samples/MQTTnet.Samples.csproj to reference MQTTnet.AspNetCore if not already present
• [ ] Add inline comments explaining key ASP.NET Core integration points from Source/MQTTnet.AspnetCore/

Add unit tests for MQTT topic template/filter matching logic in Client_Subscribe_TopicTemplate_Samples.cs

The samples demonstrate topic template subscriptions (Client_Subscribe_TopicTemplate_Samples.cs), but there's no visible test suite for the underlying topic filter parsing and matching logic. This is critical because incorrect topic matching causes silent subscription failures or missed messages. A dedicated test project would ensure wildcard handling (+, #) and edge cases are well-covered.

• [ ] Create Source/MQTTnet.Tests/TopicFilterTests.cs (or extend existing test project)
• [ ] Add parameterized tests covering: single-level wildcard (+) matching, multi-level wildcard (#) matching, edge cases (##, ++, mixed), dollar-prefixed system topics, case sensitivity
• [ ] Add tests for invalid topic filter detection and error handling
• [ ] Reference the test file in ci.yml to ensure it runs in the build pipeline

• Add comprehensive documentation for extending MQTTnet with custom communication channels beyond TCP/TLS/WebSocket—currently only interface (IChannelFactory) is shown; create a worked example showing In-Memory channel implementation in Samples/
• Write integration tests for the ASP.NET Core WebSocket support (Source/MQTTnet.AspTestApp/) comparing behavior against standard TCP client—the app exists but test coverage is missing
• Create a diagnostic sample showing how to inspect MQTT packet contents using the PackageInspection_Samples.cs hooks—currently sparse, add real examples of filtering malformed packets

MQTTnet demonstrates a generally solid security posture as a .NET MQTT library, with proper project structure and MIT licensing. However, there are moderate concerns around WebSocket security in AspNetCore integration, buffer handling in packet processing, MQTT topic validation, connection resource management, and secure defaults in samples. The codebase lacks visible evidence of security measures like input validation, rate limiting, and resource quotas in the provided file structure. The library should implement comprehensive input validation for MQTT protocol elements, enforce strict buffer limits, add connection pooling limits, and ensure all sample applications demonstrate security best practices. A full source code review of packet parsing, authentication handlers, and connection lifecycle management is recommended.

• Medium · Potential WebSocket Security Issues in AspNetCore Integration — Source/MQTTnet.AspnetCore/MqttWebSocketServerAdapter.cs, Source/MQTTnet.AspnetCore/MqttConnectionHandler.cs. The MqttWebSocketServerAdapter and related AspNetCore integration components handle WebSocket connections. Without explicit review of the implementation, there's a risk of improper security header validation, missing CORS configuration, or inadequate TLS/SSL enforcement for WebSocket connections. Fix: Ensure all WebSocket connections enforce TLS/SSL, implement proper CORS policies, validate origin headers, and add security headers (CSP, X-Frame-Options, etc.). Review and test WebSocket upgrade procedures.
• Medium · Potential Buffer Overflow in Network Packet Processing — Source/MQTTnet.AspnetCore/BufferExtensions.cs, Source/MQTTnet.AspnetCore/ReaderExtensions.cs. The codebase contains buffer operations (MqttBufferReaderBenchmark, BufferExtensions.cs, ReaderExtensions.cs) for parsing MQTT packets. Without size validation and bounds checking, malformed or oversized packets could lead to buffer overflow vulnerabilities. Fix: Implement strict buffer size limits before processing, add bounds checking on all read operations, validate packet size headers against maximum allowed values, and implement fuzzing tests for packet parsing.
• Medium · Missing Input Validation in MQTT Topic Handling — Samples/Client/Client_Subscribe_TopicTemplate_Samples.cs. The Client_Subscribe_TopicTemplate_Samples.cs suggests topic template processing. Topic names in MQTT can be vectors for injection or DoS attacks if not properly validated. Wildcard patterns and special characters could be exploited. Fix: Implement strict topic validation including length limits, character whitelisting, pattern complexity limits for wildcards, and reject malformed topic names per MQTT specification.
• Medium · Potential Denial of Service via Connection Handling — Source/MQTTnet.AspnetCore/MqttConnectionHandler.cs, Source/MQTTnet.AspnetCore/SocketReceiver.cs, Source/MQTTnet.AspnetCore/SocketSender.cs. The AspNetCore adapter handles multiple concurrent connections. Without proper connection limits, rate limiting, and resource quotas, an attacker could exhaust server resources through connection floods or slow-rate attacks. Fix: Implement per-client connection limits, total connection limits, timeout mechanisms for idle connections, rate limiting on subscription requests, and resource quotas (memory, CPU) per client.
• Low · Missing Security Configuration in Sample Applications — Samples/Server/Server_TLS_Samples.cs, Source/MQTTnet.AspTestApp/appsettings.json. The sample applications and test app (MQTTnet.AspTestApp) may not demonstrate secure defaults for MQTT configuration, TLS/SSL setup, or authentication mechanisms. Fix: Ensure sample applications demonstrate best practices: mandatory TLS/SSL, strong authentication, authorization checks, proper secret management (use configuration providers, not hardcoded values), and security headers.
• Low · Potential Information Disclosure in Diagnostics — Samples/Diagnostics/Logger_Samples.cs, Samples/Diagnostics/PackageInspection_Samples.cs. The Diagnostics and PackageInspection samples suggest logging and inspection capabilities. Verbose logging could expose sensitive information about message payloads, client IDs, or internal system details. Fix: Implement structured logging with sensitivity levels, redact sensitive data (credentials, PII, message payloads) from logs, use secure logging frameworks, and ensure production logging is configured at appropriate levels.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.