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/linyacool/WebServer 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 — Stale — last commit 3y ago

• 2 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 3y ago
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 97% 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 linyacool/WebServer repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/linyacool/WebServer.

What it runs against: a local clone of linyacool/WebServer — 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 linyacool/WebServer | 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 ≤ 985 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "linyacool/WebServer(\\.git)?\\b" \\
  && ok "origin remote is linyacool/WebServer" \\
  || miss "origin remote is not linyacool/WebServer (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 "WebServer/Main.cpp" \\
  && ok "WebServer/Main.cpp" \\
  || miss "missing critical file: WebServer/Main.cpp"
test -f "WebServer/Server.h" \\
  && ok "WebServer/Server.h" \\
  || miss "missing critical file: WebServer/Server.h"
test -f "WebServer/EventLoop.h" \\
  && ok "WebServer/EventLoop.h" \\
  || miss "missing critical file: WebServer/EventLoop.h"
test -f "WebServer/HttpData.h" \\
  && ok "WebServer/HttpData.h" \\
  || miss "missing critical file: WebServer/HttpData.h"
test -f "WebServer/Epoll.h" \\
  && ok "WebServer/Epoll.h" \\
  || miss "missing critical file: WebServer/Epoll.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 985 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~955d)"
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/linyacool/WebServer"
  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).

A C++11 high-performance web server implementing the Reactor pattern with epoll-based edge-triggered I/O multiplexing, non-blocking sockets, and a thread pool for handling concurrent HTTP requests. It parses GET/HEAD requests, serves static resources, supports HTTP keep-alive and pipelined requests, and includes an asynchronous logging system using double-buffering. Monolithic structure: WebServer/ contains the core server code (Channel, Epoll, EventLoop, EventLoopThread, EventLoopThreadPool, HttpData, Server, ThreadPool, Timer classes), Main.cpp as entry point, and a base/ subdirectory for AsyncLogging. WebBench/ is a separate load-testing tool. Build system uses both Makefile and CMakeLists.txt.

Systems engineers and C++ developers learning high-performance server design patterns, concurrent programming, and production-grade I/O handling. Also useful for students studying epoll, Reactor architecture, and thread pool implementations.

Actively developed but not production-hardened: has CI via Travis CI (shown in .travis.yml), clear documentation in Chinese covering concurrency model and architecture, but appears to be a teaching/portfolio project rather than a widely-deployed system. Last activity and maintainer status are not visible from file metadata alone, but the polished documentation and complete implementation suggest solid intermediate maturity.

Single maintainer risk (linyacool) with no visible dependency management files (no package.json, conanfile, etc.). Written for Ubuntu 14.04 with g++ 4.8, so there may be compatibility gaps with modern C++ standards and systems. No unit test suite visible in file listing, only a WebBench load-testing tool included. The codebase lacks automated test coverage and modern C++ safety patterns.

Unable to determine active work from file listing alone—no git log, PR list, or issue tracker visible. The presence of build artifacts (WebBench/bin/webbench, WebBench/tags) and Makefile.bak suggests some iteration, but commit history is not shown.

git clone https://github.com/linyacool/WebServer.git
cd WebServer
./build.sh
./WebServer -t 4 -p 8080 -l /tmp/server.log

Then load-test with: ./WebBench/bin/webbench -c 100 -t 5 http://localhost:8080/

Daily commands: Build: ./build.sh. Run: ./WebServer [-t thread_numbers] [-p port] [-l log_file_path]. Default: 4 threads, port 8080, log to /tmp/log. Load-test: ./WebBench/bin/webbench -c connections -t seconds -k (keep-alive) http://localhost:8080/

• WebServer/Main.cpp — Entry point that initializes Server, EventLoop, and ThreadPool—every contributor must understand the startup sequence
• WebServer/Server.h — Core Server abstraction managing socket binding, listening, and connection dispatch—essential for understanding request handling architecture
• WebServer/EventLoop.h — Central event loop coordinator using epoll; manages all I/O multiplexing and timer callbacks—fundamental to the reactor pattern
• WebServer/HttpData.h — HTTP request/response parsing and state machine; handles GET/HEAD requests and keep-alive logic—critical for HTTP semantics
• WebServer/Epoll.h — Low-level epoll wrapper encapsulating system I/O multiplexing—boundary between application logic and OS kernel
• WebServer/EventLoopThreadPool.h — Thread pool abstraction distributing EventLoops across multiple threads—enables horizontal scalability
• WebServer/base/Logging.h — Asynchronous logging framework used throughout server for diagnostics—critical for production debugging

Add a new HTTP request handler or extend static file serving

1. Examine HttpData::handleRequest() in WebServer/HttpData.cpp to understand request dispatch (WebServer/HttpData.cpp)
2. Add condition branch for your new URL pattern (e.g., /api/status) before static file fallback (WebServer/HttpData.cpp)
3. Generate HTTP response via sendResponse() or write directly to m_outBuffer (WebServer/HttpData.cpp)
4. Test with HTTPClient or WebBench by hitting your new endpoint (WebServer/tests/HTTPClient.cpp)

Tune concurrency: adjust thread pool size and connection limits

1. Modify thread count in Main.cpp: server.start(thread_count) parameter (WebServer/Main.cpp)
2. Adjust EventLoopThreadPool thread allocation in Server.cpp constructor (WebServer/Server.cpp)
3. Edit config.h for connection timeouts, backlog size, or buffer sizes (WebServer/config.h)
4. Review timer wheel bucket size in Timer.cpp if timeout precision changes (WebServer/Timer.cpp)

Add custom logging or diagnostics to monitor server behavior

1. Use LOG_INFO/LOG_ERROR macros from WebServer/base/Logging.h throughout your code (WebServer/base/Logging.h)
2. Async logging is configured in Main.cpp; adjust flush interval and file rollover (WebServer/Main.cpp)
3. Review AsyncLogging.cpp buffer strategy if you need higher throughput or lower latency (WebServer/base/AsyncLogging.cpp)
4. Logs are written asynchronously; check LogFile.cpp for file rotation policies (WebServer/base/LogFile.cpp)

• Linux epoll — O(1) I/O readiness notification for thousands of concurrent connections; superior to select/poll
• C++11 threads + condition variables — Standard library concurrency primitives enable portable thread pool and timer management without Boost dependency
• Asynchronous logging with background thread — Prevents log writes from blocking request handlers; critical for high-frequency logging under load
• Timer wheel — Efficient O(1) connection timeout tracking without per-connection syscalls or priority queues
• EventLoop-per-thread model — Lock-free event dispatch within each thread reduces contention; scales linearly to CPU cores

• HTTP request parsing in application code (not a library like http-parser)

  • Why: Full control over parsing logic and error handling; enables custom optimizations (e.g., pipelining)
  • Consequence: Higher maintenance burden; potential RFC compliance gaps; must manually test edge cases

• Keep-alive + pipelining with single-threaded per-connection parsing

  • Why: Reuses connections to amortize TCP handshake; pipelining allows batch request processing
  • Consequence: Parser must maintain state across multiple requests; head-of-line blocking if one request stalls

• Static file serving via synchronous open/read in EventLoop thread

  • Why: Simple, avoids thread pool overhead for small files; direct mmap potential
  • Consequence: Large files or slow disks can block EventLoop; no sendfile(2) optimization observed

• Epoll one-shot level-triggered (implicit) per-fd

  • Why: Simpler semantics than edge-triggered; fewer event drops
  • Consequence: Syscall overhead if fd repeatedly becomes readable; inefficient for very high throughput

• TLS/HTTPS support (no SSL/TLS implementation)
• POST request body handling or form submission (parses GET/HEAD only)
• Dynamic content generation (static file serving only, no CGI/FastCGI)
• Load balancing or reverse proxy (single-instance server)
• Cross-platform portability beyond Linux (epoll is Linux-specific; no Windows IOCP support)

Linux-only: epoll is not portable—will not compile on macOS or Windows. Hardcoded paths: log paths must begin with '/' per usage string. No HTTPS: only plain HTTP supported. Static file serving only: no dynamic handlers or CGI. No memory pooling for connections: HttpData objects allocated individually. eventfd for wakeup: requires Linux 2.6.30+ for reliable behavior. g++ 4.8 assumptions: may have C++11 compatibility issues with modern compilers (e.g., deleted copy constructors not enforced). Test tool requires modification: WebBench is modified to add -k flag, but not all modern load testing tools compatible.

• Reactor Pattern — Core architectural pattern of this server—epoll demultiplexes I/O, EventLoop reacts to events, callbacks execute handlers; understanding this is prerequisite for modifying event processing
• Edge-Triggered vs. Level-Triggered (epoll) — Server uses edge-triggered mode (EPOLLET)—requires non-blocking I/O and drains sockets fully per event; missing this causes requests to hang or drop
• Min-Heap Timer Queue — Timer.cpp uses a priority queue to efficiently manage connection timeouts in O(log n) rather than scanning all connections; understand this for adding new timeout behaviors
• Double-Buffering for Async Logging — AsyncLogging.cpp swaps buffers without locks between event loop and logger thread; demonstrates lock-free pattern for high-throughput I/O without stalling request processing
• eventfd Synchronization Primitive — Used to wake sleeping event loops from other threads without mutex; efficient cross-thread signaling on Linux—required for distributing connections to thread pool
• HTTP Request Pipelining — Server handles multiple HTTP requests on one connection in sequence; state machine in HttpData must parse multiple requests from a single recv() buffer
• Round-Robin Load Balancing — Main thread distributes accepted connections to worker threads in round-robin order to balance load and minimize contention; key to the concurrency model's scalability

• chenshuo/muduo — Industry-standard C++ high-performance network library using similar Reactor pattern, epoll, and thread pool; excellent reference for production-grade patterns and thread-safe designs this project could adopt
• torvalds/linux — Kernel source for epoll(2) implementation and syscall behavior; essential for understanding edge-triggered semantics and EPOLLONESHOT pitfalls
• linyacool/WebBench — Modified webbench load-testing tool in this repo with Keep-Alive support—same author's companion repo for benchmarking this server
• lighttpd/lighttpd1.4 — Production web server also using epoll and event loops; reference for real-world HTTP handling, security hardening, and static file serving optimizations
• nodejs/node — Uses libuv (abstraction over epoll/kqueue) for similar async I/O patterns; reference for portable event loop design and callback-heavy architecture

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 unit tests for core components (Channel, Epoll, EventLoop, HttpData)

The repo lacks a dedicated test suite for its critical I/O multiplexing and HTTP parsing components. The WebServer/base/tests directory exists but appears empty. Adding unit tests for Channel.cpp/h, Epoll.cpp/h, EventLoop.cpp/h, and HttpData.cpp/h would catch regressions early and make the codebase more maintainable. This is especially important for a high-performance server where correctness under concurrent load is critical.

• [ ] Create tests/ChannelTest.cpp to verify event masking, callback registration, and enable/disable operations
• [ ] Create tests/EpollTest.cpp to test epoll_wait behavior, fd registration/removal, and edge-triggered vs level-triggered modes
• [ ] Create tests/HttpDataTest.cpp to validate HTTP request parsing (GET, HEAD, pipelining), header parsing, and edge cases (malformed requests, incomplete headers)
• [ ] Update WebServer/CMakeLists.txt to build and run the test suite as part of the build pipeline
• [ ] Document test execution in README.md

Migrate from .travis.yml to GitHub Actions workflow

The repo uses Travis CI (.travis.yml) which has been deprecated/transitioned. GitHub Actions is now the standard for GitHub-hosted projects. Adding a .github/workflows/ci.yml would provide faster builds, better integration, and easier maintenance. This also aligns with modern C++ CI practices (testing with multiple GCC/Clang versions).

• [ ] Create .github/workflows/build-and-test.yml with: build step (cmake + make), optional static analysis (clang-tidy), and test execution
• [ ] Test the workflow against multiple compiler versions (GCC 7, 8, 9 and Clang 10+) to catch portability issues
• [ ] Add GitHub Actions badge to README.md and consider deprecating/removing .travis.yml
• [ ] Ensure CMakeLists.txt properly exposes build and test targets for CI consumption

Add comprehensive integration tests using WebBench and document performance benchmarks

The repo includes WebBench (a load testing tool) but lacks documented integration tests that validate server functionality under realistic load. Currently only WebBench/test.sh exists with minimal documentation. Creating a reproducible benchmark suite would help maintainers catch performance regressions and give users confidence in the 'High Performance' claim.

• [ ] Create a new tests/integration/ directory with scripts that: start the WebServer, run WebBench with various concurrency levels (100, 1000, 10000 clients), validate response correctness, and measure throughput/latency
• [ ] Document in a new BENCHMARKING.md file: test setup, expected performance metrics, how to interpret results, and hardware requirements for reproducibility
• [ ] Add a GitHub Actions workflow step (or separate workflow) that runs these integration tests and reports performance trends
• [ ] Update CMakeLists.txt to build the server with necessary flags for testing (e.g., debug symbols for profiling)

• Add unit tests for HttpData state machine: create WebServer/test/HttpDataTest.cpp with test cases for chunked encoding, malformed requests, and pipelined request parsing—currently no test suite exists for the core HTTP parser.
• Document the round-robin distribution in EventLoopThreadPool: add inline comments and a brief ASCII diagram in EventLoopThreadPool.h explaining how index_ wraps and why this minimizes lock contention versus queue-based distribution.
• Extend HTTP method support: modify HttpData.cpp to parse POST, PUT, DELETE requests (currently only GET/HEAD)—requires parsing body length and adding request type to HttpData struct, useful for understanding state machine extension.

The WebServer codebase demonstrates reasonable architectural patterns with multi-threaded event-driven design, but lacks critical security hardening. Primary concerns include: (1) Absence of HTTPS/TLS encryption, (2) Insufficient input validation and path traversal protection for static file serving, (3) Missing security headers and DOS protections, and (4) Potential buffer overflow risks in HTTP parsing. The project appears educational/developmental rather than production-ready. Immediate priorities should be implementing TLS support, comprehensive input validation, and security headers. Medium-term improvements include rate limiting, better error handling, and security audit of HTTP parsing logic.

• Medium · Potential Buffer Overflow in HTTP Request Parsing — WebServer/HttpData.cpp, WebServer/HttpData.h. The HttpData.cpp component handles HTTP request parsing in C++. Without visible bounds checking in the file structure, there's risk of buffer overflow vulnerabilities when parsing malformed or excessively long HTTP headers and request bodies. Fix: Implement strict input validation and buffer size limits for HTTP headers and request bodies. Use safe string handling functions and validate all parsed data before processing.
• Medium · Missing HTTPS/TLS Support — WebServer/Server.cpp, WebServer/Server.h, WebServer/Channel.cpp. The web server appears to support only HTTP without evidence of HTTPS/TLS encryption. Communications with clients will be transmitted in plaintext, exposing sensitive data. Fix: Implement TLS/SSL support using OpenSSL or similar libraries. Enforce HTTPS for all connections, especially for any sensitive data transmission.
• Medium · Potential Path Traversal Vulnerability — WebServer/HttpData.cpp, WebServer/Util.cpp. The server handles static resource requests. Without visible path sanitization in the file structure, attackers could potentially use path traversal attacks (e.g., '../../../etc/passwd') to access files outside intended directories. Fix: Implement strict path validation to prevent directory traversal. Use canonical path resolution and validate that all requested files are within the designated static file directory.
• Medium · Insufficient Input Validation for HTTP Methods — WebServer/HttpData.cpp, WebServer/HttpData.h. The README mentions support for GET and HEAD requests, but there's no visible validation against HTTP method confusion attacks or unsupported methods that could cause unexpected behavior. Fix: Implement whitelist-based HTTP method validation. Only allow explicitly supported methods (GET, HEAD) and reject all others with appropriate 405 Method Not Allowed responses.
• Low · Missing Security Headers — WebServer/HttpData.cpp, WebServer/Server.cpp. No evidence of security headers (Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, etc.) in the response handling code. Fix: Add security headers to all HTTP responses including: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Content-Security-Policy, and appropriate Cache-Control headers.
• Low · Potential Information Disclosure in Error Messages — WebServer/base/Logging.cpp, WebServer/base/Logging.h. Error handling and logging mechanisms may expose sensitive system information through verbose error messages or stack traces. Fix: Implement generic error messages for users while logging detailed errors server-side. Avoid exposing system paths, version information, or internal state in HTTP responses.
• Low · Missing Rate Limiting and DOS Protection — WebServer/EventLoop.cpp, WebServer/Server.cpp. No visible rate limiting, connection throttling, or DOS protection mechanisms in the event loop or server architecture. Fix: Implement rate limiting per IP address, connection limits, timeout mechanisms, and request throttling to prevent denial-of-service attacks.
• Low · Potential Resource Exhaustion in Thread Pool — WebServer/ThreadPool.cpp, WebServer/ThreadPool.h. The ThreadPool implementation may be vulnerable to resource exhaustion if task queue grows unbounded without proper limits. Fix: Implement bounded task queues with maximum size limits and reject or queue excess tasks with appropriate backpressure mechanisms.

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.