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.js 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 the board

• Last commit 2d ago
• 7 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 63% 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.js repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/uNetworking/uWebSockets.js.

What it runs against: a local clone of uNetworking/uWebSockets.js — 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.js | 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 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "uNetworking/uWebSockets.js(\\.git)?\\b" \\
  && ok "origin remote is uNetworking/uWebSockets.js" \\
  || miss "origin remote is not uNetworking/uWebSockets.js (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"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
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.js"
  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.js is a high-performance Node.js native V8 addon wrapping ~10,000 lines of C++ that delivers a standards-compliant HTTP/WebSocket server. It solves the latency and throughput crisis in Node.js real-time applications by achieving 10x the performance of Socket.IO and 8.5x that of Fastify, while maintaining full HTTP/1.1 and WebSocket RFC compliance. Hybrid native+JavaScript structure: the core engine is monolithic C++ (uWebSocket.js wraps uNetworking/uWebSockets), exposed as a Node.js addon; src/ likely contains binding code, build.c handles compilation, docs/generated/ contains TypeScript definitions auto-generated from C++ (App, SSLApp, TemplatedApp are the main API surfaces). Examples and tests are separate.

Backend engineers building high-concurrency real-time applications (chat, gaming, financial feeds) who need to serve 100k+ simultaneous WebSocket connections on resource-constrained hardware (e.g., Raspberry Pi); also used as the core networking layer in Bun, the JavaScript runtime.

Production-ready and battle-tested: established in 2016, powers Bun's networking stack, passes OSS-Fuzz continuous fuzzing (Chromium oss-fuzz), documented with generated TypeScript definitions and API reference. CI pipelines run on every commit (build.yml, build-asan.yml). This is not experimental—it's a hardened, actively maintained foundation library.

Minimal risk surface: single C++ codebase with no npm dependencies (installs directly from GitHub), but maintenance is concentrated in a small core team. The binding layer (Node.js addon) can break with major Node.js releases, so test compatibility across Node versions. No open breaking changes visible in the data, but this is a low-level library—kernel/OS-level bugs are harder to debug.

Actively maintained: v20.66.0 is the current release (visible in README), CI runs with ASAN (AddressSanitizer) for memory safety, and fuzzing is continuous. The project focuses on performance regressions and RFC compliance—no major refactors visible, but incremental hardening and optimization.

git clone https://github.com/uNetworking/uWebSockets.js.git
cd uWebSockets.js
npm install
make  # builds native addon

Daily commands: See Makefile for native build targets. For a quick test: node examples/ (examples directory would contain standalone .js files). No npm start—this is a library, not an app. Consumers import via require('uWebSockets.js') and instantiate App() or SSLApp() (per docs/generated/functions/).

• build.c: C/C++ build script that compiles the native addon; essential for understanding how the C++ engine integrates with Node.js
• .gitmodules: Declares the uNetworking/uWebSockets C++ submodule—the actual core engine that must be checked out for builds to work
• Makefile: Orchestrates native addon compilation, linking, and platform-specific build flags (Linux, macOS, Windows)
• docs/generated/interfaces/TemplatedApp.html: Auto-generated TypeScript definition for the main App and SSLApp classes—the primary API surface a developer interacts with
• docs/generated/interfaces/WebSocketBehavior.html: Defines the handler callbacks (onOpen, onMessage, onClose, onDrain) for WebSocket connections—critical for understanding event-driven patterns
• .github/workflows/build.yml: CI pipeline showing which Node.js versions are tested; reveals compatibility constraints and build configuration

Start here: (1) C++ engine changes: modify source under the C++ submodule (uNetworking/uWebSockets, linked via .gitmodules), rebuild with make; (2) Node.js binding changes: edit build.c or addon entry points; (3) TypeScript definitions: see docs/generated/interfaces/ (likely auto-generated from C++, so edit source, not .html); (4) Examples: add to examples/ directory with runnable .js files showing real App/SSLApp usage.

The C++ submodule must be initialized with git submodule update --init --recursive or cloning will fail silently. Building requires C++17 compiler and system OpenSSL headers (libssl-dev on Linux, Xcode on macOS). The library uses platform-specific I/O syscalls (epoll/kqueue/IOCP)—bugs in edge cases may not reproduce across platforms. TypeScript definitions are generated; manually editing .html files in docs/generated/ will be overwritten. No explicit Node.js version requirement listed in README, but check .github/workflows/build.yml for tested versions (likely node 16+).

• Native N-API addon (V8 binding) — µWebSockets.js is a C++ library exposed to Node.js via native bindings; understanding how build.c marshals data between V8 and C++ is essential for debugging performance issues or memory leaks in the addon layer.
• Backpressure and flow control (TCP writability) — WebSocket.onDrain and the streaming patterns in the library prevent memory exhaustion when sending large amounts of data; critical for real-time systems handling bursty clients.
• Event-driven I/O multiplexing (epoll/kqueue/IOCP) — µWebSockets' performance advantage comes from zero-copy, non-blocking event loops using platform-specific syscalls; the C++ engine selects the fastest multiplexer per OS.
• TLS/SSL session resumption and SNI — SSLApp supports secure WebSockets; understanding TLS handshake optimization and Server Name Indication (SNI) for multi-domain serving is important for production deployments.
• HTTP/1.1 Keep-Alive and pipelining — The library is standards-compliant with RFC 7230; connection reuse and header parsing correctness matter for interoperability with browsers and proxies.
• Multipart form data parsing — The MultipartField interface handles file uploads and form submissions; the parser must correctly handle boundary delimiters and malformed input without DOS vulnerabilities (hence the OSS-Fuzz integration).
• Compression negotiation (Brotli, Deflate, Zstd) — The library supports dynamic content compression via Accept-Encoding; understanding which compressor is chosen (via DEDICATED_COMPRESSOR_* singletons) affects latency vs. bandwidth trade-offs.

• oven-sh/bun — Bun uses µWebSockets.js as its core HTTP/WebSocket server; studying Bun's usage (src/bun.js/) reveals production patterns and integration strategies.
• nodejs/node — The native addon interface depends on Node.js N-API stability and V8 binding conventions; critical for debugging addon incompatibilities across Node.js versions.
• uNetworking/uWebSockets — The C++ parent repository—all engine improvements and the actual TLS/HTTP/WebSocket logic live here; the .js wrapper is a thin binding.
• fastify/fastify — Direct competitor mentioned in README; comparing performance profiles and examining how Fastify handles backpressure/streaming helps contextualize µWebSockets' design wins.
• socketio/socket.io — Another competitor mentioned in README; Socket.IO adds higher-level event abstractions on top of WebSockets, showing the trade-off between abstraction and speed.

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 test suite for multipart form parsing (MultipartField interface)

The repo exposes a MultipartField interface and getParts function in docs/generated, but there's no visible test directory for multipart parsing edge cases. This is a critical feature for file uploads that needs coverage for boundary conditions, large files, concurrent uploads, and malformed data.

• [ ] Create tests/multipart.test.js covering getParts() function
• [ ] Test edge cases: missing boundaries, incomplete uploads, large file handling, special characters in filenames
• [ ] Add tests for backpressure handling during multipart parsing (reference: examples/Backpressure.js pattern)
• [ ] Verify compatibility with examples/AsyncFunction.js patterns for multipart handlers

Add TypeScript integration tests validating generated type definitions

The repo has docs/index.d.ts (TypeScript definitions) and docs/tsconfig.json, but no visible CI workflow testing that the type definitions match the actual runtime behavior. This prevents type regressions when the C/native bindings change.

• [ ] Create .github/workflows/typescript-check.yml workflow (complement existing build.yml and build-asan.yml)
• [ ] Add tests/types.test.ts that imports from index.d.ts and validates: HttpResponse methods, WebSocketBehavior callbacks, AppOptions structure
• [ ] Test that CompressOptions and DEDICATED_COMPRESSOR_* exports are correctly typed
• [ ] Verify EnvironmentVariables (UWS_HTTP_MAX_HEADERS_COUNT, UWS_HTTP_MAX_HEADERS_SIZE) are documented and typed

Create benchmarking regression suite for performance-critical paths

The README emphasizes this is for 'the most demanding of applications' with benchmarks referenced, but no visible benchmark CI. Given examples/Benchmarker.cjs exists, a regression suite would catch performance regressions in HTTP parsing, WebSocket frame handling, and compression.

• [ ] Create benchmarks/regression.js using examples/Benchmarker.cjs as a template
• [ ] Add .github/workflows/benchmark.yml to track: HTTP request throughput, WebSocket message latency, compression ratios (SHARED_COMPRESSOR vs DEDICATED_COMPRESSOR_*)
• [ ] Benchmark AutomaticPortSelection (examples/AutomaticPortSelection.js) behavior under scale
• [ ] Store baseline metrics in benchmark-results/ and fail CI if regression > 5% on key paths

• Add integration tests for the multipart form parser (docs reference MultipartField interface but no test examples visible)—create tests/multipart/ with edge cases like nested boundaries and missing Content-Disposition headers.
• Expand examples/: the repo has a docs/ directory but examples directory is sparse in the file list—add a examples/chat-demo.js showing a simple pub/sub WebSocket chat and a examples/http-static.js for serving static files, with comments explaining TemplatedApp routing.
• Document the backpressure pattern in backpressure examples or a new docs/guide/backpressure.md—the WebSocket interface has an onDrain callback, but usage is not explained in the visible file list. This is critical for streaming large data.

The uWebSockets.js repository demonstrates a reasonably secure foundation as a well-maintained, standards-compliant web server framework. The project benefits from active security testing (as mentioned in README with OSS-Fuzz and fuzzing), and includes ASAN builds in CI/CD. However, critical information gaps prevent a complete security assessment: no dependency manifest was provided, making vulnerability analysis impossible; no SECURITY.md exists for responsible disclosure; and generated artifacts are tracked in git. The medium-rated issues (dependency management and disclosure policy) should be prioritized. Overall, the codebase appears security-conscious but could benefit from enhanced transparency and documentation around security practices.

• Medium · Missing SECURITY.md File — Repository root. The repository lacks a SECURITY.md file for responsible vulnerability disclosure. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file with clear instructions for reporting security vulnerabilities privately, following GitHub's security advisory guidelines.
• Medium · Dependency Transparency Unavailable — Repository root / package.json. No package.json or yarn.lock file was provided in the file structure. This makes it impossible to assess whether the project has vulnerable dependencies or uses pinned versions. Fix: Ensure all dependencies are explicitly listed with pinned versions in package.json. Use npm audit or similar tools to scan for known vulnerabilities. Implement automated dependency updates via Dependabot.
• Low · Documentation Generation Artifacts in Repo — docs/generated/. Generated documentation files (docs/generated/) are committed to the repository, which can bloat the repo size and may contain outdated security information if not regenerated. Fix: Add docs/generated/ to .gitignore and generate documentation during CI/CD pipeline or releases only. Ensure documentation is regenerated with each release.
• Low · Example Code Security Considerations — examples/. The examples/ directory contains multiple example applications. While not a vulnerability per se, example code should be audited to ensure it doesn't demonstrate insecure patterns that could be copied by users. Fix: Review all example files to ensure they follow security best practices. Include comments about security considerations (e.g., validation, authentication, CORS policies). Document secure patterns in README.
• Low · Missing Code Signing/Release Security — .github/workflows/build.yml, .github/workflows/build-asan.yml. No evidence of signed releases or code signing processes visible in the provided file structure. This could allow for supply chain attacks. Fix: Implement signed releases and commits. Use GitHub Actions to sign build artifacts. Document the verification process for users.

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.