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/uNetworking/uWebSockets 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 2w ago
• 16 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 81% 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 uNetworking/uWebSockets repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/uNetworking/uWebSockets.

What it runs against: a local clone of uNetworking/uWebSockets — 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 uNetworking/uWebSockets | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | 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 ≤ 47 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 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 "src/App.h" \\
  && ok "src/App.h" \\
  || miss "missing critical file: src/App.h"
test -f "src/Loop.h" \\
  && ok "src/Loop.h" \\
  || miss "missing critical file: src/Loop.h"
test -f "src/HttpParser.h" \\
  && ok "src/HttpParser.h" \\
  || miss "missing critical file: src/HttpParser.h"
test -f "src/WebSocket.h" \\
  && ok "src/WebSocket.h" \\
  || miss "missing critical file: src/WebSocket.h"
test -f "src/HttpRouter.h" \\
  && ok "src/HttpRouter.h" \\
  || miss "missing critical file: src/HttpRouter.h"

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

µWebSockets is a high-performance C++/C web server optimized for real-time applications, handling HTTP/1.1, WebSockets, and HTTP/3 with TLS 1.3 encryption. It powers major cryptocurrency exchanges processing billions in daily trade volume by combining extreme speed (faster encrypted messaging than most competitors' unencrypted) with zero-compromise security through continuous OSS-Fuzz testing at ~95% coverage. Monolithic structure: core HTTP/WebSocket logic in root-level .cpp/.h files (implied from build.c, build.h), examples/ contains ~20 runnable demos (HelloWorld.cpp, BroadcastingEchoServer.cpp, Http3Server.cpp), benchmarks/ isolates performance tests (load_test.c, broadcast_test.c), fuzzing/ holds fuzz harnesses with .dict files, cluster/ has documentation on multi-instance setups.

Backend engineers and infrastructure teams building ultra-low-latency, high-throughput services (especially in fintech/crypto) who need WebSocket pub/sub, parameter routing, and can tolerate C++ rather than Node.js; also Node.js developers integrating via the uWebSockets.js binding for real-time features.

Highly mature and production-proven since 2016. Perfect Autobahn|Testsuite score for WebSocket standards compliance, LGTM A+ rating with zero CodeQL alerts, active CI/CD via GitHub Actions (.github/workflows/cpp.yml, codeql.yml), and deployed at scale in major exchanges. Code is battle-tested but actively maintained—check recent workflow runs for current build status.

Single-maintainer risk (uNetworking organization but likely concentrated) and no obvious visible issue backlog in file listing. C++ memory safety is a concern despite pedantic compilation flags—contributions require careful review. Upgrade risk is moderate: the codebase is stable but C++ breaking changes in core APIs could affect downstream consumers without semantic versioning clarity in README.

Active CI via .github/workflows/cpp.yml and CodeQL scanning. Recent work appears focused on HTTP/3 support (Http3Server.cpp example), async patterns (AsyncEpollHelloWorld.cpp, UpgradeAsync.cpp), and compression (Precompress.cpp). Fuzzing directory suggests ongoing security hardening. No PR/issue data in file listing, but workflow files indicate continuous integration is live.

Clone and build with: git clone https://github.com/uNetworking/uWebSockets.git && cd uWebSockets && make -f GNUmakefile (or make -f Makefile). Run an example: cd examples && g++ -std=c++17 HelloWorld.cpp -o hello && ./hello (adjust includes/flags per examples/README.md). Install dependencies may be needed (libuWS, OpenSSL for TLS)—check README.md for platform-specific setup.

Daily commands: Single-file examples compile standalone: g++ -std=c++17 -I../src examples/HelloWorld.cpp -o hello && ./hello listens on localhost:9001. Multi-feature example: g++ -std=c++17 -I../src -lssl -lcrypto examples/SecureGzipFileServer.cpp -o secure_server && ./secure_server for HTTPS+compression. For cluster mode, see cluster/README.md. Run benchmarks: cd benchmarks && make && ./load_test.

• src/App.h — Core application template class that orchestrates HTTP/WebSocket routing and lifecycle; all server logic extends from this.
• src/Loop.h — Event loop abstraction (epoll/IOCP) that drives all async I/O; understanding this is essential for performance optimization.
• src/HttpParser.h — HTTP request parser with strict RFC compliance; critical for security and correctness of incoming request handling.
• src/WebSocket.h — WebSocket frame parsing and message handling; core for real-time features and protocol compliance.
• src/HttpRouter.h — Request routing and matching engine; every HTTP handler registration and dispatch flows through this.
• src/PerMessageDeflate.h — WebSocket compression extension implementation; handles deflate/inflate for bandwidth optimization.
• src/AsyncSocket.h — Async socket abstraction layer for cross-platform I/O; bridges event loop to kernel socket operations.

Add a new HTTP route handler

1. In your application setup, call app.post(), app.get(), app.put(), etc. with a URL pattern and handler lambda (examples/HttpServer.cpp)
2. Access the HttpResponse object via the handler parameter to call .end(), .writeStatus(), .writeHeader(), etc. (src/HttpContext.h)
3. Use res.onAborted() to clean up if the client disconnects (src/HttpResponseData.h)

Add a WebSocket endpoint with pub/sub

1. Register with app.ws<T>("/path") where T is your per-socket user data struct (examples/BroadcastingEchoServer.cpp)
2. In the open handler, subscribe the socket to a topic via ws->subscribe(topic) (src/TopicTree.h)
3. Broadcast messages to all subscribers with ws->publish(topic, message) or send to a single socket with ws->send(message) (src/WebSocketContext.h)
4. Handle incoming messages in the message handler; call ws->unsubscribe() in close handler for cleanup (examples/BroadcastingEchoServer.cpp)

Implement per-message deflate compression

1. When setting up WebSocket with app.ws(), pass backpressure handler to socket configuration (src/WebSocketExtensions.h)
2. Compression is negotiated automatically during WebSocket upgrade if both client and server support RFC 7692 (src/PerMessageDeflate.h)
3. Messages are transparently compressed/decompressed; no changes needed to message handler logic (src/WebSocket.h)

Enable HTTPS/TLS

1. When creating the app, pass SSL options with certificate and key paths (PEM format) (examples/SecureGzipFileServer.cpp)
2. The socket layer automatically handles TLS handshake; no changes needed to application logic (src/AsyncSocket.h)
3. Access client cert info and handshake details via socket properties in context (src/AsyncSocketData.h)

• C++ templates (header-only) — Zero-cost abstractions and compile-time specialization for different socket/app types; no vtable overhead
• epoll/IOCP/libuv event loop abstraction — Cross-platform async I/O with minimal syscall overhead; scales to thousands of concurrent connections
• Incremental parsing with state machines — Streaming HTTP/WebSocket parsers avoid buffering full requests; memory-efficient for large payloads
• Topic-based pub/sub with bloom filters — O(1) broadcast to subscribers with minimal lock contention; bloom filter skips irrelevant topics
• Backpressure-aware send buffers — Prevents memory exhaustion when clients are slow; gracefully degrades under high load

• Header-only library instead of compiled binary

  • Why: Maximum flexibility for template specialization and zero-cost abstraction; inlining at compile time
  • Consequence: Longer compile times; requires C++17 compiler; no runtime plugin system

• No built-in authentication or authorization

  • Why: Keep core minimal and delegable; every app has different auth requirements (JWT, OAuth2, sessions, etc.)
  • Consequence: Applications must implement auth middleware; potential for misconfiguration if not careful

• Backpressure via send-buffer pausing instead of flow control frames

  • Why: Simpler implementation; TCP backpressure is usually sufficient for HTTP/WebSocket
  • Consequence: Slow clients can cause server-side memory growth if handler produces data faster than network drains

• Stateless request routing; no middleware pipeline

  • Why: Fastest path for hot requests; middleware adds per-request overhead
  • Consequence: Complex cross-cutting concerns (logging, rate-limiting) must be hand-rolled or composed outside

• Does not handle HTTP/2 Server Push (HTTP/1.1 and HTTP/3 only)
• Does not provide built-in authentication, sessions, or authorization
• Does not include ORM, database drivers, or persistence layers
• Does not provide request logging or structured monitoring; applications must integrate their own
• Does not support HTTP/1.0; requires HTTP/1.1 or higher
• Not suitable for extremely long-lived connections with infrequent activity (no connection pooling optimization)

No package.json—this is pure C++, not Node.js (uWebSockets.js is separate). Build requires C++17-capable compiler and POSIX OS (Linux/macOS/Windows with WSL). TLS/crypto optional but examples like SecureGzipFileServer.cpp silently fail if OpenSSL not installed. Fuzzing requires libFuzzer (LLVM). Autobahn tests in autobahn/ need Python + Autobahn library not listed as dependency—manual setup. Thread safety model not immediately obvious from file list; check AsyncEpollHelloWorld.cpp vs EchoServerThreaded.cpp for differences.

• Zero-copy message buffering — Core to µWebSockets' speed claim; understanding how messages avoid allocation on send/receive is key to writing efficient handlers
• Lock-free pub/sub — The library's pub/sub for WebSocket broadcast uses lock-free data structures; critical for understanding thread-safety guarantees
• HTTP/2 Server Push — Examples like Precompress.cpp leverage this for proactive asset delivery; subtle optimization opportunity in real-time apps
• Epoll/Kqueue reactor pattern — µWebSockets uses OS-level event multiplexing (epoll on Linux, kqueue on BSD/macOS); understanding this explains why it scales to thousands of concurrent connections
• TLS 1.3 session resumption — SecureGzipFileServer.cpp and Http3Server.cpp use modern TLS; session resumption is why the library can do encrypted messaging faster than others' unencrypted
• Autobahn|Testsuite WebSocket conformance — Perfect score since 2016 means all edge cases in RFC 6455 are handled; critical validation that this is production-safe for WebSocket applications
• Fuzzing with libFuzzer and OSS-Fuzz — The fuzzing/ directory shows continuous security testing at 95% coverage; understanding fuzzing harnesses helps identify new security-critical paths

• emscripten-core/emscripten — Compiles C++ projects like this to WebAssembly; relevant if µWebSockets needs to run in browser contexts or serverless
• uNetworking/uWebSockets.js — Official Node.js binding wrapping this C++ library, allowing rapid scripting while leveraging the core performance
• h2o/h2o — Alternative high-performance C web server with HTTP/2 & HTTP/3 support; direct competitor in same performance tier
• nginx/nginx — Industry-standard reverse proxy and web server; µWebSockets often deployed behind nginx for production workloads
• envoyproxy/envoy — Modern service proxy handling TLS termination and load balancing for µWebSockets deployments in microservice architectures

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 HTTP parser (fuzzing/Http.cpp)

The repo has fuzzing infrastructure but lacks structured unit tests for the HTTP parser. The fuzzing/Http.cpp file indicates parser complexity that deserves deterministic test coverage. This would improve code confidence, provide regression prevention, and serve as documentation for parser behavior with edge cases like malformed headers, chunked encoding, and various HTTP method types.

• [ ] Create tests/HttpParserTest.cpp with test cases for valid/invalid HTTP requests
• [ ] Reference fuzzing/Http.cpp test vectors as base cases
• [ ] Add tests for edge cases: oversized headers, missing CRLF, invalid methods, incomplete requests
• [ ] Integrate with existing Makefile build system (update GNUmakefile and Makefile)
• [ ] Run tests in CI via .github/workflows/cpp.yml

Add performance regression detection CI workflow

The repo has benchmarks/ directory with multiple performance test files (broadcast_test.c, load_test.c, scale_test.c) but no automated CI to detect performance regressions. This prevents unintended slowdowns from merging. A workflow would run benchmarks on PRs and compare against baseline branch, protecting the project's performance-critical positioning.

• [ ] Create .github/workflows/benchmarks.yml to run benchmarks/Makefile targets on PR events
• [ ] Add benchmark result storage (artifact or external DB) to enable baseline comparison
• [ ] Reference benchmarks/README.md for existing test setup and metrics
• [ ] Configure conditional triggering (e.g., on C++ file changes only to save CI time)
• [ ] Document baseline collection process in benchmarks/README.md

Add WebSocket compliance test documentation and CI integration

The repo references Autobahn test suite compliance in README (with PDF report link) and has autobahn/ directory with server-test.js, but there's no documented way for contributors to run or verify WebSocket RFC 6455 compliance. Adding a CI workflow and contributor guide would reduce friction and prevent compliance regressions.

• [ ] Create .github/workflows/autobahn.yml to run autobahn/fuzzingclient.json tests via server-test.js
• [ ] Add autobahn/SETUP.md documenting: installation, local test execution, interpreting test results
• [ ] Update examples/README.md to mention WebSocket compliance testing approach
• [ ] Add build dependency checks (e.g., Node.js, Python for Autobahn) to CI workflow
• [ ] Document expected passing test count and how to interpret failures in autobahn/SETUP.md

• Add integration tests in a new tests/ directory (currently missing) mirroring examples/ — e.g., test_HelloWorld.cpp validating HTTP GET responses, test_BroadcastingEchoServer.cpp validating pub/sub message delivery. Start with one example.
• Document the routing parameter syntax (seen in ParameterRoutes.cpp) with a new examples/README.md section including regex patterns, wildcard rules, and type coercion rules—currently inferred but not codified.
• Extend benchmarks/Makefile to build all examples/ as benchmark targets—currently benchmarks/ is isolated from examples/, making performance regressions in example patterns undetectable.

The uWebSockets codebase demonstrates strong security posture with emphasis on secure development practices (evidenced by CodeQL workflows and fuzz testing infrastructure). No critical vulnerabilities were identified in the static analysis. The main concerns are minor: hardcoded test certificates in version control and test/fuzzing artifacts that should remain isolated from production code. The project actively invests in security testing with comprehensive fuzzing harnesses and CI/CD security scans. Recommendations focus on best practices for development artifact management and ensuring test resources do not leak into production deployments.

• Medium · Hardcoded Test Certificates in Repository — misc/cert.pem, misc/key.pem. The repository contains hardcoded SSL/TLS certificates and private keys (misc/cert.pem and misc/key.pem) committed to version control. While these appear to be test certificates, this practice can lead to accidental exposure of sensitive cryptographic material if similar patterns are followed in production code. Fix: Move test certificates outside of version control or use a .gitignore rule. Use environment variables or secure configuration management for certificate paths in production. Consider documenting how to generate test certificates for development.
• Low · Fuzzing Dictionary Files May Leak Patterns — fuzzing/*.dict files (e.g., AsyncEpollHelloWorld.dict, QueryParser.dict). Multiple fuzzing dictionary files (.dict) contain patterns that could theoretically be used to understand input handling logic, though this is expected for fuzzing artifacts. Fix: Ensure fuzzing artifacts are not deployed to production. Keep fuzzing resources in a separate build target or branch that is not included in release builds.
• Low · Test/Example Files in Public Repository — examples/ directory, benchmarks/ directory, autobahn/ directory. The repository contains example and test files that demonstrate various features but could provide information useful for attackers to understand the application's behavior patterns. Fix: Audit example code for security best practices. Document security considerations in examples. Ensure example code is never used as a basis for production implementations without thorough security review.

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.