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/qinguoyi/TinyWebServer 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 2y ago

• 8 active contributors
• Apache-2.0 licensed
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 88% of recent commits
• ⚠ No CI workflows 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 qinguoyi/TinyWebServer repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/qinguoyi/TinyWebServer.

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "qinguoyi/TinyWebServer(\\.git)?\\b" \\
  && ok "origin remote is qinguoyi/TinyWebServer" \\
  || miss "origin remote is not qinguoyi/TinyWebServer (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 702 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~672d)"
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/qinguoyi/TinyWebServer"
  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).

TinyWebServer is a lightweight C++ HTTP server for Linux that handles concurrent connections through a thread pool, non-blocking sockets, and epoll (supporting both ET and LT modes). It implements HTTP request parsing (GET/POST), user registration/login via MySQL, static file serving (images, videos), and synchronous/asynchronous logging—achieving 90k+ QPS under pressure testing. Monolithic structure: main.cpp is the entry point; http/http_conn.{h,cpp} handles request parsing with a state machine; lock/locker.h wraps pthreads synchronization; log/ implements async logging with block_queue.h; CGImysql/ provides connection pooling; threadpool/ (referenced but not listed) implements the half-sync/half-reactive pattern; root/ contains static assets and HTML templates for registration/login.

C++ network programming learners and junior engineers who want hands-on experience building a production-adjacent web server with thread synchronization, event-driven I/O, and database integration. Also used by interviewees preparing for backend/systems engineering roles.

Actively maintained educational project (65KB+ C++ codebase, GitHub stars suggest high visibility). Well-documented with README, structured directories, and included pressure testing tools. No visible CI/automated test suite, relying on manual Webbench testing. Mature enough for learning but positioned as educational rather than production hardening.

Single-author maintenance model creates knowledge silos; README explicitly warns against paid repackaging. No automated tests or CI pipeline visible. MySQL connection pool implementation (CGImysql/) needs careful review for SQL injection in user input handling. Last activity not determinable from provided data, but educational focus means breaking changes are possible. Dependency on system MySQL and epoll limits portability.

No recent commit data provided, but repo appears stable as an educational reference. Focus is on demonstrating concurrency patterns (Reactor vs Proactor implementations) and database integration rather than adding new features.

git clone https://github.com/qinguoyi/TinyWebServer.git
cd TinyWebServer
./build.sh
# Server starts; access via http://localhost:port

Daily commands:

make          # Build via makefile
./server      # Start server (port config in config.h/config.cpp)
# Test: ./test_pressure/webbench-1.5/webbench -c 100 -t 10 http://localhost:port/

• http/http_conn.cpp: Core HTTP state machine parsing GET/POST requests and generating responses; ~500 LOC implementing the protocol layer
• CGImysql/sql_connection_pool.cpp: Database connection pooling and user authentication (register/login); critical for SQL injection vulnerabilities and concurrency bugs
• log/log.cpp: Async logging system with block queue; demonstrates producer-consumer pattern and thread safety
• lock/locker.h: Pthreads wrapper classes (mutex, condition variable, semaphore); foundation for all synchronization in the server
• main.cpp: Server initialization, epoll setup, thread pool creation, and main event loop; entry point to understand overall control flow
• config.cpp: Command-line argument parsing for port, thread count, ET/LT mode selection, Reactor/Proactor choice

HTTP request handling: edit http/http_conn.cpp (state machine logic) and http/http_conn.h (request struct). Concurrency: modify threadpool/ thread count/queue size. Logging: adjust log/log.h macros. Database queries: update CGImysql/sql_connection_pool.cpp prepared statements. Routes: add handlers in http_conn.cpp's do_request() method.

MySQL setup required: CGImysql/sql_connection_pool.cpp hardcodes database connection parameters (host, user, password, database name)—must match local MySQL config or registration/login fails silently. Port binding: default port and number of threads set in config.h (no env var override visible). Static files: root/ directory must exist and be readable from execution directory or 404 errors on all image/video requests. Buffer sizes: HTTP request parsing uses fixed-size buffers in http_conn.h—oversized requests cause parsing failure. ET mode gotcha: edge-triggered epoll requires reading all available data in one call or events are lost.

• Edge-Triggered (ET) vs Level-Triggered (LT) epoll — This repo implements both modes in main.cpp's epoll event handling; ET requires draining all available data in one read or events are lost, while LT re-fires until handled—critical for correctness and performance tuning
• Half-Sync/Half-Reactive Thread Pool — The concurrency model combines a synchronous thread pool (workers processing tasks sequentially) with asynchronous Reactor event loop (main thread multiplexing I/O); core pattern in threadpool/ and main.cpp
• HTTP State Machine Parsing — http_conn.cpp implements a finite state machine to incrementally parse HTTP request lines, headers, and body; essential for understanding how servers handle partial/pipelined requests
• Connection Pool Pattern — sql_connection_pool.cpp reuses MySQL connections via a queue to avoid expensive setup/teardown; demonstrates resource pooling for stateful services
• Async Logging with Lock-Free Queue — log/block_queue.h implements a bounded queue allowing worker threads to enqueue logs without blocking the main event loop; avoids latency spikes from disk I/O
• Graceful Connection Shutdown — timer/ (referenced in README) implements connection timeout detection to close idle clients; prevents resource exhaustion in long-lived servers
• Condition Variables for Thread Synchronization — lock/locker.h wraps pthread_cond_t; used in thread pool task queue to wake workers when jobs arrive—foundational for producer-consumer patterns

• linyacool/WebServer — Similar educational C++ web server with thread pool and epoll; alternative architecture for comparison
• markparticle/WebServer — Another C++ server project focused on concurrency patterns; useful for understanding different Reactor implementations
• chenshuo/muduo — Production-grade C++ networking library with event-driven architecture; shows how to scale TinyWebServer's patterns to real systems
• nginx/nginx — Industrial reference: high-performance HTTP server using similar epoll/event loop patterns; study nginx config and load balancing for production insights

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 HTTP request parsing state machine (http/http_conn.cpp)

The repo implements a state machine for parsing GET/POST HTTP requests, but there are no visible unit tests validating the parser's correctness. This is critical for a web server handling production traffic. Contributors could create tests for edge cases like malformed requests, missing headers, oversized payloads, and boundary conditions between different HTTP methods.

• [ ] Create a new test/ directory with a test_http_parser.cpp file
• [ ] Write unit tests using a C++ testing framework (Google Test recommended) for http_conn.h parse methods
• [ ] Test parsing of valid GET requests with query strings from root/ files
• [ ] Test parsing of POST requests with form data (login/register flows)
• [ ] Test error cases: malformed headers, missing Content-Length, invalid methods
• [ ] Add test compilation target to makefile and build.sh

Add GitHub Actions CI workflow for automated build and Webbench testing

The repo includes webbench pressure testing tools (test_pressure/webbench-1.5) but lacks automated CI/CD. A GitHub Actions workflow would validate builds on each PR, run the included Webbench tests, and provide performance regression detection—critical for a performance-focused web server project.

• [ ] Create .github/workflows/build-and-test.yml with Ubuntu Linux runner
• [ ] Add build steps using build.sh and makefile
• [ ] Add step to compile webbench from test_pressure/webbench-1.5/
• [ ] Run basic functionality tests (start server, hit an endpoint, verify response)
• [ ] Run Webbench pressure test with configured concurrent connections (e.g., 1000) and log results
• [ ] Add step to fail workflow if build errors or performance degrades significantly

Create detailed API documentation for database connection pool (CGImysql/sql_connection_pool.h/cpp)

The CGImysql module handles MySQL connection pooling for user registration/login but has only a minimal README.md. New contributors need clear documentation on the pool's thread-safety guarantees, configuration parameters, connection limits, and usage examples to properly integrate it.

• [ ] Expand CGImysql/README.md with class diagrams showing sql_connection_pool architecture
• [ ] Document public methods: getConnection(), releaseConnection(), destroyPool() with parameters and return values
• [ ] Add configuration details: max pool size, timeout behavior, thread-safety model
• [ ] Create code examples showing proper connection acquisition/release patterns
• [ ] Document the relationship between pool size and threadpool worker threads (from threadpool/)
• [ ] Add troubleshooting section for common issues (pool exhaustion, connection leaks)

• Add unit tests for HTTP state machine: http/http_conn.cpp has complex parsing logic but no test harness. Create a test file that feeds malformed requests (missing \r\n, incomplete headers, oversized payloads) and verifies parser state transitions.
• Implement HTTPS/TLS support: all connections in main.cpp are plaintext TCP. Add OpenSSL integration to wrap sockets and handle TLS handshake; start by modifying the epoll read callback in http_conn.cpp.
• Document SQL injection vulnerabilities: CGImysql/sql_connection_pool.cpp constructs queries by string concatenation (e.g., in login/register). Add prepared statement refactoring or at least input sanitization wrappers and document the risk in CGImysql/README.md.

Failed to generate security analysis.

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.