Most developers learn HTTP through frameworks. They see app.get('/', handler) or @app.route('/') and develop a working mental model of the web that stops at that abstraction boundary. Tinyweb, a project that implements a functional HTTP server in around 1000 lines of C, is useful precisely because it dissolves that boundary entirely.
This is not a niche exercise in systems archaeology. Understanding what lives below the framework layer changes how you reason about latency, error handling, and the specific failure modes that surface in production but never show up in framework documentation.
The Socket Sequence
Every HTTP server, whether it is nginx serving millions of requests per second or a toy project serving a single file, executes the same POSIX socket sequence. The API has barely changed since BSD Sockets were introduced in 4.2BSD in 1983.
int sockfd = socket(AF_INET, SOCK_STREAM, 0);
struct sockaddr_in addr = {
.sin_family = AF_INET,
.sin_port = htons(8080),
.sin_addr.s_addr = INADDR_ANY
};
bind(sockfd, (struct sockaddr *)&addr, sizeof(addr));
listen(sockfd, SOMAXCONN);
while (1) {
int client = accept(sockfd, NULL, NULL);
handle_request(client);
close(client);
}This is the skeleton. socket() creates a file descriptor. bind() associates it with a local port. listen() marks it as passive, ready to accept incoming connections. accept() blocks until a client connects and returns a new file descriptor for that specific connection. Everything that makes your application useful lives inside handle_request().
The SO_REUSEADDR socket option deserves mention here. Without it, the kernel holds a port in TIME_WAIT state for up to two minutes after the server closes, which means restarting the server during development produces an Address already in use error. Any real implementation sets this option immediately after creating the socket:
int opt = 1;
setsockopt(sockfd, SOL_SOCKET, SO_REUSEADDR, &opt, sizeof(opt));TCP Is a Byte Stream, Not a Message Protocol
The most instructive gap between HTTP-as-conceptualized and HTTP-as-implemented appears the moment you try to read a request. recv() returns bytes, not HTTP messages. The kernel delivers data in segments as they arrive over the network, and there is no guarantee that a single recv() call gives you a complete request line, a complete set of headers, or even a complete header name.
The standard approach is to read into a buffer, accumulate data, and scan for the CRLF markers that delimit HTTP/1.1 structure. The request line ends with \r\n. Each header ends with \r\n. The header section ends with \r\n\r\n, a blank line. Parsing is fundamentally an incremental process:
char buf[8192];
int total = 0;
while (1) {
int n = recv(client_fd, buf + total, sizeof(buf) - total, 0);
if (n <= 0) break;
total += n;
if (memmem(buf, total, "\r\n\r\n", 4)) break;
}Once the header section is complete, you parse the request line to extract the method, path, and HTTP version. Then you iterate through headers line by line. The Content-Length header tells you how many bytes of body follow the blank line. If it is absent and the method is something like POST, you either have a malformed request or the client is using Transfer-Encoding: chunked, which is its own parsing problem.
This is where the 1000-line constraint gets interesting. A production HTTP parser handles chunked encoding, trailer headers, request smuggling mitigations, multi-value headers, and dozens of edge cases. llhttp, the parser used by Node.js (replacing the older http_parser), is a generated state machine designed specifically to handle the full complexity of HTTP/1.1 at high throughput. A minimal implementation in C can get away with handling the common cases and returning 400 Bad Request for anything unusual.
Serving Files
Static file serving sounds trivial until you enumerate what it actually requires. You need to:
- Open the requested path, being careful to reject path traversal attempts (
../../etc/passwd) - Determine the MIME type from the file extension
- Read and send the file contents
- Set the
Content-Lengthheader so the client knows when the response ends - Handle the case where the file does not exist (404) or cannot be read (403 or 500)
Path traversal is a non-trivial security concern. The naive approach of prepending the document root to the requested path fails if the path contains .. components that escape the root. A correct implementation resolves the full path with realpath() and then verifies that it starts with the document root before opening:
char full[PATH_MAX];
if (!realpath(requested, full)) { send_404(fd); return; }
if (strncmp(full, docroot, strlen(docroot)) != 0) { send_403(fd); return; }MIME types are typically handled with a lookup table mapping extensions to content type strings. The table does not need to be comprehensive; covering HTML, CSS, JavaScript, common image formats, and a few others handles the vast majority of real use cases. Unknown extensions default to application/octet-stream.
Sending the file itself uses read() and send() in a loop, or on Linux, sendfile(), which copies data directly from a file descriptor to a socket without passing through userspace buffers. For a small educational server the difference is negligible; at scale sendfile() is a meaningful optimization.
The Concurrency Question
The skeleton above handles one connection at a time. While handle_request() is running for one client, every other incoming connection queues in the kernel’s accept backlog and waits. For anything serving more than one user at a time, this is a problem.
The classical solutions are well-known. Fork a child process per connection (Apache’s original model). Spawn a thread per connection (many Java application servers). Use non-blocking I/O with select(), poll(), or epoll() to multiplex many connections on a single thread (nginx, Node.js, most modern high-performance servers). Each model has different resource overhead and different concurrency limits.
A 1000-line educational server typically picks the simplest option: fork() per connection. This keeps the code straightforward while actually supporting concurrent clients. The main process accepts and forks; the child handles the request and exits. The downside is that each connection costs a full process creation, which modern operating systems handle efficiently enough for low-to-moderate traffic.
The event-loop model requires restructuring the entire program around non-blocking I/O and state machines. It is the right choice for high throughput but significantly increases code complexity, which is why educational projects usually skip it.
HTTP Keep-Alive
HTTP/1.0 closed the connection after each response. HTTP/1.1 introduced persistent connections: by default, the connection stays open, and the client can send multiple requests over the same TCP connection. This matters for performance because TCP connection establishment has non-trivial overhead, especially when TLS is involved.
Supporting keep-alive in a minimal server means wrapping the request-response cycle in a loop inside handle_request(), continuing to read new requests until either the client closes the connection or the client sends a Connection: close header. The response must then include Connection: keep-alive (implicit in HTTP/1.1) and accurate Content-Length headers, because without Content-Length the client cannot tell where one response ends and the next begins on the same stream.
Dropping keep-alive support simplifies the implementation considerably but adds perceptible latency to any browser loading a page with multiple resources, since each image, stylesheet, and script would require a new TCP handshake.
What 1000 Lines Excludes
The boundary of the implementation is as instructive as what it includes. A server of this size will not handle TLS, HTTP/2, WebSockets, range requests, gzip compression, virtual hosting, CGI, URL-encoded query string parsing, or any form of authentication. It will not implement conditional GET requests with If-Modified-Since or ETag, which are essential for caching. It will probably not correctly handle all the ways HTTP headers can be malformed.
This is not a criticism. The point of the exercise is to understand the core, and the core is quite small. The original tinyhttpd by J. David Blackstone, written around 1999, demonstrated the same thing in about 500 lines. thttpd, a production-quality server from the same era, fit into a few thousand lines and was widely deployed. The relationship between code volume and capability is not linear; the first 1000 lines cover an enormous fraction of what the HTTP spec requires in the common case.
The Pedagogical Argument
The reason to write this, or to read it carefully, is that it makes the protocol concrete. When a framework developer encounters a 400 error, they look at framework documentation. When someone who has written an HTTP parser encounters the same error, they think about what was in the request bytes and why the parser rejected them. The mental model is different in kind, not just in detail.
The same applies to performance intuitions. Developers who have written the recv-parse-send loop understand why large request bodies have latency, why connection reuse matters, why headers have a cost, and why the Content-Type header is load-bearing. These are not facts you look up; they fall out naturally from the implementation.
C is not the only language where this exercise is productive. The same patterns exist in Rust with raw std::net::TcpListener, in Go with net.Conn, in Python with the socket module. But C makes the POSIX API surface unavoidable. There is no friendly wrapper to hide behind, which means the actual system calls appear in the code directly, named and visible. For understanding the foundations, that visibility is the point.
Tinyweb sits in a tradition of small, complete implementations designed to make a complex system legible. The HTTP spec across all its RFCs runs to hundreds of pages. One thousand lines of C do not replace that reading, but they give you a scaffold on which the spec’s requirements make practical sense.