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/Azure/DotNetty 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.

WAIT — Slowing — last commit 4mo ago

• Last commit 4mo ago
• 30+ active contributors
• Distributed ownership (top contributor 19% of recent commits)
• Other licensed
• ⚠ Slowing — last commit 4mo ago
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{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 Azure/DotNetty repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Azure/DotNetty.

What it runs against: a local clone of Azure/DotNetty — 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 Azure/DotNetty | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch dev exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 147 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Azure/DotNetty. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Azure/DotNetty.git
#   cd DotNetty
#
# 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 Azure/DotNetty and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "DotNetty.sln" \\
  && ok "DotNetty.sln" \\
  || miss "missing critical file: DotNetty.sln"
test -f "build.cake" \\
  && ok "build.cake" \\
  || miss "missing critical file: build.cake"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "examples/Examples.Common/ExampleHelper.cs" \\
  && ok "examples/Examples.Common/ExampleHelper.cs" \\
  || miss "missing critical file: examples/Examples.Common/ExampleHelper.cs"
test -f "CONTRIBUTING.MD" \\
  && ok "CONTRIBUTING.MD" \\
  || miss "missing critical file: CONTRIBUTING.MD"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 147 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~117d)"
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/Azure/DotNetty"
  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).

DotNetty is a C# port of the Java Netty framework, providing an event-driven asynchronous network application framework for building high-performance protocol servers and clients. It eliminates boilerplate around socket handling, threading, and buffer management by offering composable channel pipelines, codec abstractions, and non-blocking I/O patterns for rapid protocol implementation. Monorepo structure: DotNetty.sln is the root solution file; core framework likely under unshown /src directories (inferred from build.cake, Directory.Build.targets patterns); /examples contains runnable Echo.Server, Echo.Client, Discard.Server, Discard.Client, and Factorial.Client demonstrating different protocol patterns; build orchestration via Cake (build.cake) and PowerShell (build.ps1).

C# and .NET developers building network servers (game servers, IoT gateways, real-time systems) or clients who need to handle thousands of concurrent connections efficiently without managing raw socket pools and threading primitives themselves.

Actively maintained (AppVeyor CI visible, NuGet packages published regularly, examples and RELEASE_NOTES.md present). The codebase is substantial (~4.8MB of C# code), has structured examples (Echo, Discard, Factorial servers), and follows Microsoft Azure contribution guidelines, suggesting production-ready status.

Single upstream maintainer risk (nayato on AppVeyor suggests concentrated ownership). No visible test directory in the top 60 files is concerning for a network framework. Last commit age not provided in data, so currency unknown. Being a port of Java Netty means architecture decisions are inherited rather than originally designed for C# idioms, which can create impedance mismatches.

Unable to determine from file metadata alone—check appveyor.yml for current CI status, RELEASE_NOTES.md for recent version highlights, and the GitHub Issues/PR tab for active work. The presence of .vscode/launch.json and .vscode/tasks.json suggests recent Visual Studio Code tooling investment.

git clone https://github.com/Azure/DotNetty.git && cd DotNetty && ./build.ps1 (on Windows) or ./build.sh (on Linux/macOS). Or: dotnet build DotNetty.sln. Official releases are on NuGet (Install-Package DotNetty.Common) or nightly builds on MyGet.

Daily commands: cd examples/Echo.Server && dotnet run (or use appsettings.json to configure host/port). Then in another terminal: cd examples/Echo.Client && dotnet run. Inspect appsettings.json files in each example for configuration (port, address, timing).

• DotNetty.sln — Master solution file that organizes all core and example projects; essential for understanding the repo structure and build configuration.
• build.cake — Cake build script defining compilation, packaging, and release workflows; required reading for CI/CD and local builds.
• README.md — High-level project overview, NuGet/MyGet distribution info, and contribution guidelines; starting point for all new contributors.
• examples/Examples.Common/ExampleHelper.cs — Common helper utilities shared across all example implementations; demonstrates idiomatic DotNetty usage patterns.
• CONTRIBUTING.MD — Community contribution guidelines and coding standards; mandatory for submitting PRs or patches.
• Directory.Build.targets — Central MSBuild configuration applied to all projects; controls versioning, packaging, and compiler settings across the codebase.
• SECURITY.md — Security policy and vulnerability disclosure procedures; critical for understanding supported versions and reporting issues.

Add a new example server/client handler pair

1. Create new handler class extending ChannelHandlerAdapter to implement message processing logic (channelRead, exceptionCaught, etc.) (examples/Echo.Server/EchoServerHandler.cs)
2. Create Program.cs entry point in new example folder, using ServerBootstrap from DotNetty.Transport to bind port and initialize pipeline (examples/Echo.Server/Program.cs)
3. Reference the Examples.Common project utilities for shared configuration and client/server settings loading (examples/Examples.Common/ExampleHelper.cs)
4. Create appsettings.json configuration file with host, port, and protocol-specific settings (examples/Echo.Server/appsettings.json)
5. Create .csproj project file in new folder, referencing DotNetty NuGet packages (DotNetty.Transport, DotNetty.Codecs, etc.) (examples/Echo.Server/Echo.Server.csproj)
6. Add new project reference to main DotNetty.sln so it builds with the solution (DotNetty.sln)

Add a new custom protocol codec (encoder/decoder)

1. Create decoder class extending ByteToMessageDecoder, implementing Decode() to parse raw bytes into message objects (examples/Factorial/BigIntegerDecoder.cs)
2. Create encoder class extending MessageToByteEncoder, implementing Encode() to serialize message objects back to bytes (examples/Factorial/NumberEncoder.cs)
3. Add both encoder and decoder to the channel pipeline in your handler's ChannelActive() or in a ChannelInitializer (examples/Echo.Server/Program.cs)
4. Write unit tests for codec behavior (frame boundaries, error handling, edge cases) (examples/Factorial/Factorial.csproj)

Add SSL/TLS support to an existing server

1. Create certificate files (PEM format) and store paths in appsettings.json or hardcode in Program.cs (examples/SecureChat.Server/appsettings.json)
2. In Program.cs, load certificate and create SslHandler using TlsHandler.Client() or TlsHandler.Server() (examples/SecureChat.Server/Program.cs)
3. Add SslHandler as first handler in the pipeline before your custom handlers (examples/SecureChat.Server/SecureChatServerHandler.cs)
4. Update client connection code to use TlsHandler.Client() and trust the server certificate (examples/SecureChat.Client/Program.cs)

Release a new version to NuGet

1. Update version numbers in Directory.Build.targets under <VersionPrefix> tag (Directory.Build.targets)
2. Document changes in RELEASE_NOTES.md with version, date, and feature/fix summaries (RELEASE_NOTES.md)
3. Run ./build.ps1 (Windows) or ./build.sh (Unix) to compile and create NuGet packages (build.cake)
4. Verify AppVeyor CI passes in appveyor.yml, then manually push .nupkg files to NuGet.org with API key (appveyor.yml)

• .NET / C# — Primary implementation language; DotNetty is a faithful .NET port of Java Netty, enabling high-performance async I/O in the .NET ecosystem.
• Async/await & Task-based concurrency — Core to DotNetty's event-driven model; allows non-blocking I/O and efficient thread utilization via CLR thread pool.
• NuGet package distribution — Standard .NET dependency management; DotNetty is published as modular NuGet packages (DotNetty.Common, DotNetty.Transport, DotNetty.Codecs) for granular consumption.
• Cake build automation — Cross-platform build orchestration; Cake scripts in build.cake handle compilation, testing, and packaging uniformly on Windows, macOS, and Linux.

• Port of Java Netty rather than ground-up redesign

  • Why: Netty is battle-tested and widely adopted; porting preserves architectural patterns and domain knowledge.
  • Consequence: Some idioms remain Java-flavored (e.g., handler names, pipeline concepts); not fully idiomatic to C# but familiar to Java developers.

• Event-driven handler-based pipeline architecture

  • Why: Scales efficiently; allows one thread to manage thousands of connections via non-blocking I/O and callbacks.
  • Consequence: Steeper learning curve; developers must understand async/await and callback chains; not beginner-friendly.

• Modular package structure (Common, Transport, Codecs, Handlers, TLS)

  • Why: Reduces dependencies for minimal projects; users only pull in needed packages.
  • Consequence: Requires careful version alignment across packages; missing a dependency can cause silent failures.

• Examples included in main repo rather than separate

  • Why: Easier to keep examples in sync with library changes; encourages learning by imitation.
  • Consequence: Larger repo footprint; examples must be maintained alongside core library.

• Does not provide high-level HTTP/REST server abstractions; users must build on raw codec/handler primitives.
• Does not include built-in authentication or authorization mechanisms; security is delegated to TLS handlers and custom logic.
• Not a web framework; no routing, templating, or middleware stack (unlike ASP.NET Core).
• Does not handle database connectivity or persistence; network I/O only.
• No real-time bidirectional communication frameworks (e.g., WebSocket server) in core; users extend with custom codecs.

Strong naming enabled (DotNetty.snk file present)—assemblies must be signed for use in certain contexts; do not skip signing in custom builds. Examples use appsettings.json for configuration; default ports (5555, 9999 inferred from file names) may conflict locally. Build system uses Cake and PowerShell, not pure dotnet CLI; ensure build.ps1 execution policy is permissive. No visible test project in top 60 files—test discovery path is unclear.

• Event-driven asynchronous I/O (IOCP / epoll) — Core to DotNetty's design; EventLoop abstracts OS-level completion ports (Windows IOCP, Linux epoll) to handle thousands of sockets without threads per connection.
• Channel Pipeline (composite handler chain) — DotNetty's backbone for request/response processing; understanding inbound vs. outbound handlers and their ordering is essential for writing correct protocol handlers.
• ByteBuf (zero-copy pooled buffers) — Memory-efficient buffer abstraction in DotNetty; avoids garbage collection pressure and enables efficient protocol parsing without copying data between byte arrays.
• Codec abstraction (encoders/decoders) — Separates protocol serialization logic from I/O; DotNetty provides base classes for encoding application objects to ByteBuf and decoding ByteBuf to objects.
• Bootstrap pattern (fluent channel initialization) — DotNetty's way to configure and start servers (ServerBootstrap) and clients (Bootstrap); encapsulates EventLoopGroup, ChannelFactory, and handler setup in a clean API.
• Strong naming (assembly signing) — DotNetty.snk is used to sign assemblies for GAC deployment and enterprise contexts; required for interop with Windows security policies and certain corporate environments.

• netty/netty — The original Java Netty framework; DotNetty is a direct C# port, so understanding Netty's channel model, handler pipeline, and codec design clarifies DotNetty's architecture.
• reactive-streams/reactive-streams-dotnet — Provides Reactive Streams interfaces for .NET; complementary async/streaming patterns that can integrate with DotNetty's event-driven model.
• dotnet/runtime — Core .NET async/await, Task, and Socket APIs that DotNetty depends on; source reference for understanding EventLoop task scheduling and I/O completion ports.
• Azure/azure-sdk-for-net — Sibling Azure SDK project using similar MSBuild patterns, strong naming, and AppVeyor CI; good reference for build and release practices.

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 Examples.Common shared utilities

The Examples.Common project (examples/Examples.Common/) contains shared ClientSettings.cs and ServerSettings.cs classes used across multiple example projects (Echo, Discard, Factorial). Currently, there's no evidence of dedicated unit tests for these utility classes. Adding tests would ensure configuration parsing, validation, and default values work correctly across all examples, improving code reliability and serving as documentation for new contributors.

• [ ] Create a new test project: examples/Examples.Common.Tests/Examples.Common.Tests.csproj
• [ ] Add unit tests for ClientSettings.cs covering initialization, property validation, and JSON deserialization from appsettings.json
• [ ] Add unit tests for ServerSettings.cs covering port binding, address resolution, and configuration edge cases
• [ ] Add test cases that verify consistency across different example projects (Echo, Discard, Factorial)
• [ ] Update DotNetty.sln to include the new test project
• [ ] Reference the test suite in CONTRIBUTING.MD as an example for contributors

Migrate AppVeyor CI configuration to GitHub Actions workflow

The repo currently uses AppVeyor (appveyor.yml) for CI/CD, which is external infrastructure. Given that the code is on GitHub and modern projects prefer GitHub Actions for better integration and visibility, migrating the build, test, and package publishing pipeline would improve maintainability and reduce dependency on external services. This would benefit new contributors who can see CI directly in the repo.

• [ ] Create .github/workflows/build-and-test.yml with jobs for: dotnet restore, build (build.cake or build.ps1), unit test execution, and artifact publishing
• [ ] Create .github/workflows/publish-nuget.yml for publishing releases to NuGet (triggered on tag creation)
• [ ] Ensure both Windows and Linux build matrices are covered (corresponding to appveyor.yml's current setup)
• [ ] Update CONTRIBUTING.MD to reference GitHub Actions status badges instead of AppVeyor
• [ ] Document the migration decision and instructions for maintainers in CONTRIBUTING.MD

Add integration tests for example projects (Echo, Discard, Factorial server-client pairs)

The examples directory contains multiple server-client pairs (Echo.Server/Echo.Client, Discard.Server/Discard.Client, Factorial.Server/Factorial.Client) but there's no apparent integration test suite that verifies these pairs actually communicate correctly end-to-end. Adding automated integration tests would validate the framework's networking capabilities and serve as living documentation for how to properly use DotNetty's APIs.

• [ ] Create examples/Examples.Integration.Tests/Examples.Integration.Tests.csproj
• [ ] Implement EchoServerClientIntegrationTest that: starts Echo.Server, connects Echo.Client, sends/receives messages, verifies correctness
• [ ] Implement DiscardServerClientIntegrationTest that: starts Discard.Server, connects Discard.Client, verifies data is discarded
• [ ] Implement FactorialServerClientIntegrationTest that: starts Factorial.Server, connects Factorial.Client, sends numbers, verifies factorial computation
• [ ] Add timeout and cleanup mechanisms to prevent hanging tests
• [ ] Include the integration test project in appveyor.yml and future GitHub Actions CI configuration

• Add unit tests for examples/Examples.Common/ExampleHelper.cs covering ServerBootstrap and ClientBootstrap initialization edge cases (null channels, invalid addresses)—improves test coverage for foundational APIs.
• Document the channel pipeline lifecycle and ChannelHandler ordering in examples/ with inline comments or a HANDLERS.md guide—reduces friction for new contributors understanding handler composition.
• Extend the Echo example to support TLS/SSL configuration (add certificate paths to appsettings.json and SslHandler setup in EchoServerHandler.cs)—demonstrates real-world secure protocol patterns.

DotNetty demonstrates reasonable security posture as an open-source Microsoft project with established security reporting processes. Primary concerns include the inability to assess dependency vulnerabilities due to missing package manifest contents, and ensuring example applications follow security best practices. The project properly maintains security documentation and uses strong naming for assemblies. No hardcoded secrets or obvious injection vulnerabilities were detected in the file structure provided. Recommendations focus on dependency management automation, completing security documentation, and hardening example applications.

• Medium · Missing Dependency Vulnerability Assessment — Dependencies/Package file content. The provided package dependency file is empty, making it impossible to perform dependency scanning for known vulnerabilities. NuGet packages used by DotNetty should be regularly audited for CVEs. Fix: Provide the actual packages.config, .csproj, or project.json file contents. Implement automated dependency scanning using tools like OWASP Dependency-Check, Snyk, or NuGet Package Vulnerability Scanner in the CI/CD pipeline.
• Low · Incomplete Security Documentation — SECURITY.md. The SECURITY.md file appears to be truncated in the provided content. The security reporting section is incomplete, which may confuse users attempting to report vulnerabilities. Fix: Ensure SECURITY.md is complete and clearly documents the vulnerability disclosure process, expected response times, and safe communication channels.
• Low · Strong Naming Key Exposure Consideration — DotNetty.snk. The repository contains DotNetty.snk (strong name key file). While this is typical for .NET projects, ensure this file is kept secure and not accidentally committed with sensitive metadata. Fix: Verify the SNK file is properly protected. If it contains sensitive data, consider using Azure Key Vault or similar secure storage. Ensure it's not exposed in public builds. Review git history to confirm no credentials were ever committed alongside this file.
• Low · Network Example Applications May Require Security Hardening — examples/. The repository contains multiple example applications (Echo, Discard, HttpServer, SecureChat) that demonstrate network functionality. These examples may not include security best practices and could serve as templates for insecure code. Fix: Review all example applications for security best practices. Ensure examples include proper input validation, error handling, and document security considerations. Add security-focused examples demonstrating TLS/SSL usage, authentication, and authorization patterns.
• Low · AppVeyor Configuration Exposure — appveyor.yml. The appveyor.yml file is present in the repository. While this is normal for CI/CD, ensure it doesn't contain exposed secrets or overly permissive credentials. Fix: Review appveyor.yml to ensure no hardcoded credentials, API keys, or secrets are present. Use encrypted environment variables for any sensitive values. Rotate any credentials that may have been exposed in version history.
• Low · Build Scripts Should Validate Sources — build.cake, build.ps1, build.sh, .nuget/NuGet.Config. The repository contains build scripts (build.cake, build.ps1, build.sh). These should validate package sources and ensure dependencies are fetched securely. Fix: Ensure NuGet.Config uses HTTPS sources only. Verify build scripts validate package integrity and use authenticated feeds when necessary. Implement source pinning for critical dependencies.

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.