Zig Project: HTTP Server from Scratch

In the modern era, web developers rarely think about the "Wire." We use frameworks like Express, Spring, or Next.js that hide $100,000$ lines of code between us and the network. But if you want to be a world-class Systems Architect, you must understand the infrastructure.

For your Phase 4 project, you will build the "Engine" of the web. You will build a High-Performance HTTP/1.1 Server from the ground up using nothing but Zig's standard library.

You will handle TCP Sockets (Module 191).
You will parse raw HTTP Requests.
You will manage Thread Pools (Module 190) for concurrency.
The Performance Goal: Your server must handle $10,000$ "Hellos" per second on a single machine.

This 1,500+ word guide is your architectural blueprint for building the next "Nginx" in Zig.

1. The Physics of the Wire: TCP Windows and Packet Fragmentation

An HTTP server isn't just about "Strings"; it is about managing the Physical Packet Stream.

The Wire Mirror

TCP Windowing: The OS limits how much data can be "In-Flight" before an ACK is received.
Packet Fragmentation: A 1MB HTTP response isn't sent in one piece. It is broken into hundreds of ~1500 byte MTU (Maximum Transmission Unit) packets.
The Zig Strategy: To reach 10,000 req/s, we must avoid Write Stalls. We use non-blocking sockets and an Event Loop pattern (Module 20). By filling the TCP buffer as fast as the hardware allows, we minimize the "Back-Pressure" on the CPU and maximize the bandwidth of the network card.

2. Requirement 1: Zero-Copy Parsing

A typical HTTP request looks like this: GET /image.png HTTP/1.1.

The Slow Way: Copying the string /image.png into a new buffer. This triggers a heap allocation and burns CPU cycles.
The Zig Way: Slices. You use a pointer to the existing buffer where the socket received the data. No copying, no allocation, just high-speed pointer math. This is how Zig-based projects like Bun achieve world-leading speeds.

2. Requirement 2: The HTTP State Machine

Networking is unpredictable. Sometimes, the socket sends you the "First half" of a request and then pauses for $50$ms. Your server must be "State-Aware."

The Problem: You cannot assume read() returns a full HTTP header.
The Solution: A Stream Parser. You read the bytes into a fixed-size buffer ($8$ KB). If you don't see the closing \r\n\r\n, you "Suspend" that connection's state and wait for more data.
You will implement this using a custom RequestBuffer struct that manages partial reads with $0$ data loss.

4. The Parsing Mirror: State-Machine Buffer Cycles

When data arrives from the network, it doesn't arrive as a complete "Object." It arrives as a Stream of Bytes.

The Parsing Mirror

The Concept: We use a Deterministic Finite Automaton (DFA) to parse the HTTP verb (GET, POST) and headers.
The Physics: As the CPU reads each byte into its L1 cache, the state machine transitions. There is no back-tracking and no redundant memory scans.
The Result: This allows our server to parse a request in Nanoseconds, ensuring that the software never becomes the bottleneck for the high-speed Ethernet hardware.

5. Requirement 3: Multi-Threaded Dispatch

If one user is downloading a large file, they shouldn't "Block" other users from seeing the home page.

The Architecture: Use a Thread Pool.
The Flow: The "Master" thread accepts new connections. It pushes the socket handle into a "Work Queue." The worker threads (one for each CPU core) pull from the queue, parse the headers, and send the files.
This ensures your server stays "Responsive" even under heavy load.

4. Requirement 4: Security (The "Path-Traversal" Guard)

The most dangerous bug in a custom server is Path Traversal. A hacker might send a request for /../../etc/passwd.

If your server is "Dumb," it will resolve that path and serve the hacker your computer's private password file.
Requirement: You must implement a Path Sanitizer. You must strictly validate that every request stays inside your "Public" folder. If a path contains .. or starts with /, you must "Normalize" it before touching the file system.

This project is the transition from "Writing logic" to "Architecting Infrastructure." By mastering the movement of text across the network and the safety of the file-system boundary, you gain the ability to build the backbone of the entire internet. You graduate from "Web Developer" to "Architect of the Web Engine."

Phase 28: Server Architecture Checklist

Audit your Buffer Lifecycle: Ensure you are using fixed-size buffers for header parsing to prevent memory exhaustion attacks.
Implement Zero-Copy Slicing: Master the art of using []const u8 pointers to request-data instead of calling allocator.dupe().
Setup Async Ready-Signals: If targeting higher throughput, migrate your socket logic to use std.os.linux.io_uring for true asynchronous I/O.
Use Path Normalization: Strictly sanitize every incoming URL to resolve .. and . characters before they reaching the file system.
Verify Load Capacity: Use a tool like wrk to benchmark your server and identify the exact request count where latency begins to spike.

Part of the Zig Mastery Course — engineering the web.