How unetworking/uwebsockets works
Project type and purpose
• µWebSockets is a high-performance, embeddable C/C++ library that implements a standards-compliant HTTP/WebSocket server.
• It sits on top of µSockets (eventing, networking, crypto) and offers a simple URL router, pub/sub for WebSockets, and Node.js bindings.
• The repository contains the core library (src/), examples (examples/), benchmarks (benchmarks/), fuzz tests (fuzzing/), spec tests (autobahn/, h1spec/), and CI workflows.
File structure
• Top-level modules:
• src/ – core C++ headers, classes and protocol implementations (App, HttpParser, WebSocket, Router, etc.)
• uSockets/ – the submodule implementing raw event loops (epoll/kqueue), networking and crypto layers (OpenSSL/WolfSSL)
• examples/ – sample applications showing how to wire routes and WebSocket handlers
• benchmarks/ – performance tests driving design decisions
• fuzzing/ – harnesses for daily OSS-Fuzz coverage on parsers, extensions, topic trees, etc.
• tests/ – unit and smoke tests validating individual components
• cluster/ – helper for running one app instance per CPU core
• build files – Makefile, GNUmakefile, build.{c,h}, .github/workflows
README for additional insights
• The README emphasizes a layered architecture:
• µWebSockets (HTTP, WebSocket, Router, Pub/Sub)
• µSockets (event loop, socket I/O, TLS/crypto)
• Flexible build flags for SSL backends (OpenSSL/WolfSSL) and event‐loop integrations (libuv, ASIO, GCD, raw epoll/kqueue)
• It calls out Autobahn compliance, OSS-Fuzz integration, and benchmark-driven development.
a. Main components
1. External Clients (HTTP browsers, WebSocket clients, Node.js scripts)
2. Networking & Crypto Layer (µSockets)
– Event loop implementations (raw epoll/kqueue, libuv, ASIO, GCD)
– TLS backends (OpenSSL, WolfSSL)
3. µWebSockets Core (src/)
– App/SSLApp orchestration
– HTTP layer: HttpParser, ChunkedEncoding, HttpContext, Router
– WebSocket layer: WebSocketHandshake, WebSocketProtocol, Extensions, Pub/Sub (TopicTree)
4. Application Layer (user callbacks)
– Route handlers (.get, .post)
– WebSocket event handlers (open, message, close)
5. Tooling & Testing
– Examples harness (examples/)
– Benchmarks (benchmarks/)
– Fuzzing suite (fuzzing/)
– Spec tests (autobahn/, h1spec/)
– CI/CD pipelines (.github/workflows/)
b. Relationships & interactions
• Build-time feature flags branching the Networking layer to different event loops or TLS backends.
• Flow inside the core: raw bytes → HttpParser → Router → user callback → HttpResponseData → write to socket.
• For WebSockets: handshake → protocol framing → Extensions → Pub/Sub subscription → message dispatch.
c. Architectural patterns & design principles
• Layered architecture with clear separation of concerns (I/O, protocol parsing, routing, application logic).
• Plugin-style extensibility via template parameters and build flags.
• One-app-per-thread model with shared listening socket for multi-core scaling.
• Test harnesses to ensure protocol compliance (fuzzing, spec tests) and performance (benchmarks).
d. Key technologies & libraries
• C/C++17 (headers in src/)
• µSockets submodule (C) with TLS options (OpenSSL/WolfSSL)
• Autobahn Testsuite, OSS-Fuzz, libdeflate for compression
• Make/GNUmake build system, GitHub Actions for CI
Detail without over-complication
• Build flags and CI steps alongside the relevant layers.
• How examples, benchmarks, fuzzing and tests hook into the core library for validation, compliance, and performance measurement.
• You convey both runtime behavior (request handling) and build-time configurability (flag-driven module inclusion).