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/yuesong-feng/30dayMakeCppServer 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.

AVOID — Stale and unlicensed — last commit 1y ago

• 9 active contributors
• Tests present
• ⚠ Stale — last commit 1y ago
• ⚠ Single-maintainer risk — top contributor 88% of recent commits
• ⚠ No license — legally unclear to depend on
• ⚠ 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 yuesong-feng/30dayMakeCppServer repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/yuesong-feng/30dayMakeCppServer.

What it runs against: a local clone of yuesong-feng/30dayMakeCppServer — 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 yuesong-feng/30dayMakeCppServer | Confirms the artifact applies here, not a fork | | 2 | Default branch main exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 439 days ago | Catches sudden abandonment since generation |

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

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

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "code/day06/src/EventLoop.h" \\
  && ok "code/day06/src/EventLoop.h" \\
  || miss "missing critical file: code/day06/src/EventLoop.h"
test -f "code/day06/src/Epoll.h" \\
  && ok "code/day06/src/Epoll.h" \\
  || miss "missing critical file: code/day06/src/Epoll.h"
test -f "code/day08/src/Connection.h" \\
  && ok "code/day08/src/Connection.h" \\
  || miss "missing critical file: code/day08/src/Connection.h"
test -f "code/day09/src/Buffer.h" \\
  && ok "code/day09/src/Buffer.h" \\
  || miss "missing critical file: code/day09/src/Buffer.h"
test -f "code/day04/Socket.h" \\
  && ok "code/day04/Socket.h" \\
  || miss "missing critical file: code/day04/Socket.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 439 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~409d)"
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/yuesong-feng/30dayMakeCppServer"
  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 30-day progressive tutorial and codebase teaching Linux C++ server development from socket basics to production-ready high-concurrency architecture. Each day (day01–day16+) builds a working TCP server that handles thousands of concurrent connections using epoll, event loops, thread pools, and the Master-Worker Reactor pattern. Linear daily progression: code/day01/ through code/day16/ each contain standalone server.cpp/client.cpp plus supporting classes (Socket, Epoll, Channel, EventLoop, Server, Connection, Buffer, ThreadPool). Early days (01–03) are monolithic; day04+ refactor into .h/.cpp class pairs; day06+ introduce a src/ subdirectory pattern with Server/EventLoop/Channel abstractions. Each day compiles independently via local Makefile.

C++ developers and systems programmers who want to understand the foundational principles of high-concurrency backend services by building a production-grade server from scratch, moving beyond language tutorials into OS-level networking and architectural patterns used in real-world services like Nginx and Redis.

Actively maintained but incomplete by original author (stops at day16, acknowledges lack of time to finish 30 days). Appears to be a well-used educational resource (~270KB C++ code across 16+ days), but the README explicitly states the author abandoned further development and invites community continuation (see Wlgls/30daysCppWebServer fork). Educational quality is high but codebase has acknowledged 'defects and imperfections'; treat as learning material rather than production reference.

Single-author educational project with no CI/CD pipeline, no test suite visible, and significant single-point-of-failure risk for maintenance. Code quality varies across early simple days (day01–day03) versus later architectural days; later code relies on C++11 features and smart pointers but lacks comprehensive error handling in places. No dependencies listed beyond stdlib and system calls (epoll), making portability the main risk—code is Linux/macOS only, with day15 being first macOS attempt.

Project is in long-term maintenance mode. The original author is not actively developing beyond day16; the README directs ongoing development interest to the forked Wlgls/30daysCppWebServer project. Updates are minimal—mostly bug reports and educational clarifications. No active PR queue or roadmap visible.

git clone https://github.com/yuesong-feng/30dayMakeCppServer.git
cd 30dayMakeCppServer/code/day01
make
./server &
./client

Each day's directory is self-contained; cd into day01–day16 and make to build. Requires Linux (epoll) or macOS (kqueue, day15+); no external dependencies beyond system headers.

Daily commands:

cd code/dayNN  # where NN is 01–16
make
./server      # terminal 1: binds to localhost:8888
./client      # terminal 2: connects and sends test data

Server prints accepted connections and received bytes; client sends hardcoded test strings and displays echoed responses. No CLI arguments or config files.

• code/day06/src/EventLoop.h — Core event loop abstraction that drives the entire server architecture—all I/O multiplexing and callback execution flows through this.
• code/day06/src/Epoll.h — Linux epoll wrapper providing the high-performance I/O multiplexing mechanism that enables concurrent connection handling.
• code/day08/src/Connection.h — Manages individual TCP connection lifecycle and state—essential for understanding how the server tracks and handles client connections.
• code/day09/src/Buffer.h — Network I/O buffer abstraction for receiving and sending data—critical for proper message framing and protocol handling.
• code/day04/Socket.h — Low-level socket API wrapper encapsulating bind, listen, accept, and read/write operations—foundation for all network communication.
• code/day07/src/Acceptor.h — Handles incoming connection acceptance and integration with the event loop—necessary for understanding the connection initialization flow.

• Socket (POSIX socket API, file descriptors) — Encapsulates raw socket syscalls: creation, binding, listening, accepting, and data transfer
  • Failure mode: Connection refused, port in use, insufficient file descriptors—causes server startup failure or accept() rejection
• Epoll (Linux epoll, event masks) — Polls multiple file descriptors for readiness events (EPOLLIN, EPOLLOUT, EPOLLERR); returns ready list to event loop
  • Failure mode: Spurious wakeups or missed events lead to stalled connections; incorrect fd state in epoll internal tables
• EventLoop (Single-threaded event dispatch, callback queues) — Main reactor: loops infinitely polling epoll, dispatches ready events to Channel callbacks, serializes all I/O for thread-safety
  • Failure mode: Blocking callback (e.g., synchronous disk I/O) freezes all connections; unhandled exception crashes server
• Connection (Channel, Buffer, TCP socket) — Wraps one TCP connection: manages Channel, Buffer, and application message callbacks; coordinates read/write events
  • Failure mode: Memory leak if Connection not properly deleted; buffer overflow on oversized message; half-open connection consumes fd
• Buffer (Circular queue, dynamic allocation (day09 onward)) — Circular read/write buffer staging data between socket recv() and application message parsing; tracks read/write indices
  • Failure mode: Index wrap-around bugs cause data corruption; exceeding capacity truncates or loses partial messages
• **** — undefined

Add a Custom Message Handler

1. Define your message protocol parser in a new class (e.g., MyProtocol.h) with a parse() method (code/day09/src/Buffer.h)
2. In server.cpp, set a custom onMessage callback in Server::newConnectionCallback() (code/day08/server.cpp)
3. The callback receives the Connection and Buffer; read from Buffer::readIndex() and call Buffer::retrieveAll() after processing (code/day09/src/Buffer.h)

Add Logging or Metrics to the Event Loop

1. Extend EventLoop::loop() to track loop iteration count and latency using system clock (code/day06/src/EventLoop.cpp)
2. Call a metrics callback before Epoll::poll() to record event loop statistics (code/day06/src/Epoll.h)
3. Store metrics in a thread-local or shared data structure accessible from main() (code/day08/server.cpp)

Implement Multi-Threaded Event Loop (EventLoopThread)

1. Create EventLoopThread.h spawning a worker thread that owns one EventLoop instance (code/day06/src/EventLoop.h)
2. Use pthread_create() in EventLoopThread::start() and pass the EventLoop to Connection initialization (code/day08/src/Connection.h)
3. Modify Server to distribute connections round-robin across multiple EventLoopThread instances (code/day06/src/Server.h)

• Linux epoll — Provides O(1) event notification for thousands of concurrent connections—required for high-concurrency server performance vs. blocking select() which is O(n)
• Event-driven reactor pattern — Single-threaded event loop eliminates context-switch overhead and simplifies synchronization—core pattern for modern C++ servers (muduo, Boost.Asio)
• Circular Buffer (day09) — Prevents memory reallocation during partial reads and allows zero-copy data staging between network and application layers
• Channel abstraction — Decouples file descriptors from event callbacks, enabling clean composition of multiple I/O sources in single event loop

• Single-threaded event loop (days 1–9)

  • Why: Simplicity and avoiding mutex contention for educational clarity
  • Consequence: Cannot leverage multi-core CPUs; CPU-intensive work in callbacks blocks all connections

• Manual memory management (no smart pointers in core days)

  • Why: Pedagogical emphasis on explicit resource lifecycle understanding
  • Consequence: Potential memory leaks if error paths not carefully audited; production code would use shared_ptr

• Fixed circular buffer size (day09)

  • Why: Predictable memory footprint and cache locality
  • Consequence: Cannot handle messages larger than buffer capacity; applications must implement fragmentation protocol or increase buffer size

• No heartbeat/keep-alive mechanism (early days)

  • Why: Reduces complexity for learning fundamentals
  • Consequence: Half-open connections consume resources; production requires TCP_KEEPALIVE or application-level ping/pong

• Multi-threaded scaling (addressed in later unfinished days; single EventLoop only)
• TLS/HTTPS support (raw TCP only)
• HTTP protocol parsing (echo server pattern, not HTTP-specific handler)
• Connection pooling or persistence
• Windows compatibility (Linux/epoll-only)
• Dynamic library compilation (Makefile assumes gcc/Linux environment)

1. Each day is standalone: day06 Server class is not the same as day12's; day16 uses smart pointers while earlier days use raw pointers—no single 'final' version exists. 2. epoll is Linux-only: day15 adds macOS kqueue support but code paths diverge; earlier days will fail on macOS. 3. No error recovery in business logic: tutorial omits signal handling, graceful shutdown, and SIGPIPE for closed sockets—production code must add these. 4. Hardcoded port 8888: client/server both hardcode localhost:8888; no CLI args to change. 5. Memory management shifts: day16 introduces std::shared_ptr late; memory leaks possible in day01–day15 if connections don't close cleanly. 6. Single-threaded I/O event loop until day10: day01–day09 cannot handle concurrent clients properly on multi-core systems.

• epoll (Linux event notification) — Core kernel mechanism enabling thousands of concurrent connections without a thread per connection; day03 introduces it, all subsequent days rely on it as the bottleneck-free I/O multiplexing engine
• Reactor pattern (event-driven architecture) — Architectural pattern where a single event loop waits for I/O events and dispatches callbacks—replaces multi-threaded blocking I/O; day06 EventLoop is the reactor, day12 is Master-Worker variant
• Ring buffer (circular buffer) — Memory-efficient data structure used in day09 Buffer to avoid reallocation during repeated reads/writes; critical for minimizing latency in high-frequency I/O
• Master-Worker (thread pool architecture) — Multi-threaded variant where main thread accepts connections, worker threads process I/O; day12 refactors to this to scale across CPU cores without blocking the acceptor
• TCP state machine (three-way handshake, FIN_WAIT, TIME_WAIT) — Understanding Connection lifecycle (day08) requires knowing when sockets move between ESTABLISHED → FIN_WAIT → CLOSED; mishandling causes resource leaks and 'Address already in use' errors on restart
• Callback (function pointer / std::function) — day06+ Channel and Connection use callbacks to decouple I/O events from business logic; day14 enables custom user callbacks for protocol handling, core to extensible event-driven design
• RAII (Resource Acquisition Is Initialization) — day16 shifts from manual delete to std::shared_ptr; without RAII, Connection/Buffer cleanup is error-prone in event-driven code with multiple code paths; foundational C++ pattern

• muduo/muduo — Production C++ network library that inspired this tutorial's architecture (EventLoop, Channel, Connection patterns are simplified muduo design); README explicitly states 'after this tutorial you can easily read muduo source'
• Wlgls/30daysCppWebServer — Community fork that continues the original project beyond day16 with HTTP protocol support and further refactoring; direct continuation of this codebase
• chenshuo/muduo — Original muduo repository (by Chen Shuo, the mentor behind structured C++ server design); reference implementation of patterns taught in this tutorial
• libevent/libevent — Industry-standard event loop library predating and inspiring tutorial's EventLoop design; shows production-grade handling of edge cases this tutorial simplifies
• antirez/redis — Real-world example of a single-threaded Reactor server using epoll; demonstrates how tutorial patterns scale to a production database engine

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 CMake build system alongside Makefile for cross-platform compilation

The repo currently uses Makefiles for each day's code (day01/Makefile through day07/Makefile), which is Linux-centric. A CMake configuration would enable Windows and macOS developers to contribute and test. This is particularly valuable since the README emphasizes this is for learning, and students on different OSes should be able to follow along. CMake would also simplify dependency management as the project grows beyond day07.

• [ ] Create root CMakeLists.txt that finds epoll (Linux-specific) and provides fallbacks for other OSes
• [ ] Convert each day's Makefile (day01-day07) into CMakeLists.txt files in their respective directories
• [ ] Add .gitignore entries for CMake build artifacts (build/, CMakeFiles/, *.cmake)
• [ ] Test compilation on Linux, macOS, and Windows to ensure cross-platform compatibility
• [ ] Update README.md with CMake build instructions: 'mkdir build && cd build && cmake .. && make'

Add integration tests validating server-client interaction for each day's implementation

Currently each day has client.cpp and server.cpp, but there are no automated tests verifying they actually communicate correctly. Days 1-3 appear to test basic socket communication, day04 introduces Epoll, day05 adds Channel abstraction, and day06+ refactors into Server/EventLoop. Without tests, regressions go undetected. A bash or Python test script for each day would validate: (1) server starts, (2) client connects, (3) messages are exchanged correctly, (4) graceful shutdown.

• [ ] Create tests/ directory with subdirectories tests/day01 through tests/day07
• [ ] Write bash script tests/day01/test.sh that: spawns server in background, connects with client, sends 'hello', validates response, kills server
• [ ] Repeat for days 2-3 (basic socket variants), then days 4-7 (epoll/event loop based)
• [ ] Add timeout logic to prevent hanging tests (use 'timeout 5s' command)
• [ ] Create Makefile target 'make test' in root that runs all day tests sequentially and reports pass/fail

Document architecture progression and add architecture diagrams for day04+ code refactoring

The README mentions 'learn muduo source', and the code shows clear evolution: days 1-3 are raw socket code, day04 introduces Epoll/Socket/InetAddress abstractions, day05 adds Channel, day06 adds EventLoop/Server, day07 adds Acceptor. However, there's no documentation explaining why each refactoring was done or how components interact. New contributors don't understand: what does Channel encapsulate? Why is Acceptor separate from Server? How does EventLoop differ from raw Epoll polling? Adding architecture docs would clarify the design journey.

• [ ] Create docs/architecture/ directory
• [ ] Write docs/architecture/overview.md explaining the 3-phase evolution: (1) raw sockets (day1-3), (2) Epoll abstraction (day4-5), (3) event loop pattern (day6-7)
• [ ] Add ASCII or Mermaid diagrams showing component relationships for day04 (Epoll → Socket → InetAddress), day05 (+ Channel), day06 (+ EventLoop, Server), day07 (+ Acceptor)
• [ ] Document each key class's responsibility in 2-3 sentences (e.g., 'Channel wraps a socket fd and associates it with event callbacks for EventLoop to dispatch')
• [ ] Link each tutorial markdown file (day01-.md through day07-.md) to corresponding architecture doc section

• Add comprehensive unit tests for Buffer class (code/day09/Buffer.cpp): currently no test file exists; write tests for push(), pop(), ringBuffer wraparound, and edge cases like full buffer.
• Document the state machine for Connection lifecycle (code/day08/Connection.h): add inline comments or a separate .md explaining connecting → reading → writing → closing states and which callbacks fire in which state.
• Implement cross-platform I/O abstraction for Epoll/kqueue (code/day15+): day15 macOS support is incomplete; refactor Epoll.h to use a common interface, with platform-specific implementations in Epoll_Linux.cpp and Epoll_macOS.cpp.

• High · Potential Buffer Overflow in Network Socket Handling — code/day01-day08 - Socket.cpp, Connection.cpp, client.cpp, server.cpp. Educational C++ server codebase that interfaces directly with sockets and network I/O. Without seeing the actual implementation details, typical patterns in basic socket servers (especially educational ones) often include fixed-size buffers for reading data without proper bounds checking. This is a common vulnerability in C/C++ network code. Fix: Implement strict buffer bounds checking, use safe string handling functions, validate all input sizes before copying to buffers, and consider using modern C++ containers like std::string or std::vector with automatic size management.
• High · Lack of Input Validation and Sanitization — code/day01-day08 - All socket read operations and message handling. Educational server code likely lacks comprehensive input validation on network data. Without validation, attackers could send malformed or malicious data to crash the server, cause unexpected behavior, or trigger memory corruption. Fix: Implement strict input validation for all data received from network sources. Validate message length, format, and content before processing. Implement protocol-level validation.
• High · Missing or Inadequate Error Handling — code/day01-day08 - util.cpp, Socket.cpp, Epoll.cpp, EventLoop.cpp. The README indicates this is educational code written during student years with 'numerous imperfections and flaws'. Typical patterns include inadequate error handling for system calls (socket, read, write, epoll operations), which could lead to undefined behavior, memory leaks, or information disclosure. Fix: Implement comprehensive error handling for all system calls. Check return values, properly handle errno, clean up resources in error paths, and avoid silent failures.
• Medium · Potential Information Disclosure via Error Messages — code/day01-day08 - util.cpp and all files with error handling. Educational codebases often output verbose error messages to stderr/stdout that could reveal internal implementation details, file paths, or system information to attackers. Fix: Implement proper logging infrastructure that distinguishes between user-facing errors and internal diagnostic information. Do not expose system details in error messages sent to clients.
• Medium · No Resource Limits or DoS Protection — code/day06/src/Server.cpp, code/day07/src/Acceptor.cpp, code/day08/src/Connection.cpp. As an educational server, there are likely no mechanisms to limit resource consumption per client (connections, bandwidth, memory), making it vulnerable to denial-of-service attacks. Fix: Implement connection limits, timeouts, rate limiting, and per-client resource quotas. Add maximum message size constraints and connection idle timeout mechanisms.
• Medium · Missing Memory Safety in Modern C++ — code/day01-day08 - All source files. The code predates widespread adoption of modern C++ memory safety practices. Likely uses raw pointers without RAII, manual memory management, and lacks use of smart pointers (std::unique_ptr, std::shared_ptr). Fix: Refactor to use modern C++ smart pointers, follow RAII principles, minimize raw pointer usage, and consider using static analysis tools like AddressSanitizer and MemorySanitizer during development.
• Medium · Lack of Protocol-Level Security — code/day01-day08 - Socket.cpp and all network communication. The server appears to use plain text communication without encryption (no TLS/SSL), making it vulnerable to eavesdropping and man-in-the-middle attacks. Fix: Implement TLS/SSL encryption for network communication. Use established libraries like OpenSSL or modern alternatives. Implement proper certificate validation.
• Low · No Authentication or Authorization — code/day01-day08 - Server.cpp, Acceptor.cpp. As an educational project, there are no access controls or authentication mechanisms, meaning all clients have unrestricted access. Fix: Implement authentication mechanisms appropriate for the use case. Add authorization checks before processing sensitive operations.
• Low · Missing Security Hardening in Build Process — undefined. Makefiles likely lack security compiler flags like stack canaries, ASL Fix: undefined

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.