http-server-from-scratch

A multi-threaded HTTP/1.1 server built from raw TCP sockets in C++ with zero dependencies. No Boost, no libevent, no frameworks — just POSIX sockets and the C++ standard library.

Features

• Raw TCP Sockets — Direct socket(), bind(), listen(), accept() with POSIX APIs. No networking libraries.
• HTTP/1.1 Parser — Parses request line, headers, body with chunked reading and Content-Length support.
• Thread Pool — Fixed-size worker pool with lock-free task queue for concurrent connection handling.
• Router — Express-style route registration with method matching and parameterized paths (/users/:id).
• Middleware — Chainable middleware with next() pattern (CORS, logging, auth).
• Static File Server — Serves files with MIME type detection (25+ types) and directory traversal protection.
• Keep-Alive — Persistent connections per HTTP/1.1 spec, with configurable timeouts.
• URL Decoding — Handles percent-encoded paths and + for spaces.

Architecture

Client request
  │
  ▼
┌──────────────────┐
│   TCP Listener   │   socket() → bind() → listen() → accept()
│   (main thread)  │
└────────┬─────────┘
         │ dispatch
         ▼
┌──────────────────┐
│   Thread Pool    │   N worker threads pulling from task queue
│  ┌──┐ ┌──┐ ┌──┐ │
│  │W1│ │W2│ │W3│ │   std::mutex + std::condition_variable
│  └──┘ └──┘ └──┘ │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  Request Parser  │   Method, path, headers, body, query string
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│   Middleware      │   CORS → Logging → ... → next()
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│     Router       │   Pattern matching with :param capture
└────────┬─────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌────────┐ ┌──────────┐
│  API   │ │  Static  │
│Handler │ │  Files   │
└────────┘ └──────────┘
         │
         ▼
┌──────────────────┐
│ Response Builder │   Status line, headers, Content-Length, body
└──────────────────┘

Usage

# Build
make

# Run server
./build/server

# Custom port and thread count
./build/server --port 3000 --threads 8

# Custom static directory
./build/server --static ./public

# Run tests (46 tests)
make test

Try it

# Start the server
./build/server --port 8080

# In another terminal:
curl http://localhost:8080/api/health
curl http://localhost:8080/api/items
curl http://localhost:8080/api/items/1
curl -X POST -d "name=NewItem&description=test" http://localhost:8080/api/items
curl -X DELETE http://localhost:8080/api/items/1

# Or open http://localhost:8080 in a browser for the interactive UI

Server output

[info]  http-server-from-scratch v1.0
[info]  Listening on http://localhost:8080
[info]  Thread pool: 4 workers
[info]  Press Ctrl+C to stop

14:23:01  GET  /              200  1.2KB  0.3ms
14:23:01  GET  /api/items     200  284B   0.1ms
14:23:02  POST /api/items     201  52B    0.2ms
14:23:03  GET  /api/items/1   200  78B    0.1ms

API

Method	Path	Description
GET	/api/health	Server status
GET	/api/items	List all items
GET	/api/items/:id	Get item by ID
POST	/api/items	Create new item
DELETE	/api/items/:id	Delete item
GET	/api/echo	Echo request back

Testing

make test

46 tests covering:

• Request Parser — HTTP methods, headers, body, query strings, URL decoding, keep-alive, incomplete request handling
• Response Builder — Status codes, content types, custom headers, connection management
• Router — Method matching, 404 handling, route parameters, middleware chain, short-circuiting
• Static Files — MIME type detection, directory traversal prevention
• Thread Pool — Task execution, concurrency verification
• Integration — Full request → parse → route → response → serialize cycles

Project Structure

http-server-from-scratch/
├── src/
│   ├── main.cpp           # Entry point, demo routes, CLI args
│   ├── server.hpp         # TCP listener, accept loop, connection handler
│   ├── request.hpp        # HTTP request parser with state machine
│   ├── response.hpp       # HTTP response builder with reason phrases
│   ├── router.hpp         # Route matching, params, middleware chain
│   ├── static_files.hpp   # File serving with MIME detection
│   ├── thread_pool.hpp    # Worker pool with mutex + condition variable
│   └── logger.hpp         # Color-coded request logging
├── static/
│   └── index.html         # Interactive API explorer
├── tests/
│   └── test_all.cpp       # 46 unit + integration tests
├── Makefile
└── README.md

Zero Dependencies

Built entirely with C++17 and POSIX APIs. The only requirements are a C++ compiler and a POSIX-compatible OS (macOS, Linux).