Skip to content
Tutorials Center
My learning

Topics

Lesson 120 of 132 ยท Projects

Project: A Tiny HTTP Server

Build an HTTP/1.1 server from scratch in Rust: parse requests safely, write responses, route paths with parameters, run a thread pool and test it with a client in the same program.

Every web framework hides the same small machine: a program listens on a TCP port, reads some text that follows the HTTP rules, decides what to do, and writes some text back. Building that machine yourself, once, is one of the most instructive Rust projects, because it touches networking, parsing untrusted input, error handling, trait objects, threads and shutdown, all in about 350 lines.

We use only the standard library and the loopback address 127.0.0.1, so everything runs inside the lesson editor. The server and the client live in the same program: the server runs on background threads, and main plays the browser. In five stages we will parse requests, build responses and a router (without any sockets, so it is easy to check), write a thread pool, and finally put it all on the network.

This is a learning server. It speaks one request per connection, has no TLS, no HTTP/2, no streaming bodies and no protection against slow-loris style attacks beyond a read timeout. Real services use a mature library (hyper, axum, actix-web) behind a reverse proxy. The point here is to understand what those libraries do, and to practise the safety habits that matter whenever you read bytes from the network: limit every size, time out every read, never trust a length or a name.

What an HTTP request looks like

HTTP/1.1 is a text protocol. A request is a request line, a number of header lines, an empty line, and an optional body. Lines end in \r\n:

TEXT
POST /echo?lang=rust HTTP/1.1
Host: localhost
Content-Length: 5

hello

The first line holds the method (GET, POST), the target (path plus optional query string) and the protocol version. Headers are Name: value pairs, and their names are case-insensitive. A body exists only if Content-Length says how many bytes follow. The response has the same shape: a status line (HTTP/1.1 200 OK), headers, an empty line, and a body.

Stage 1: parsing a request safely

Parsing is where servers get hurt, because the bytes come from strangers. So the parser enforces limits from the first line: a maximum line length, a maximum number of headers and a maximum body size. It returns a typed error for everything that is wrong, and it never panics on bad input.

The parser reads from any BufRead, which means we can test it with plain byte strings and, later, with a TcpStream.

Rust Stage 1: the request parser

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Study the defensive details, because they are the point of the stage:

  • reader.by_ref().take(MAX_LINE + 1).read_until(...) is the bounded way to read a line. A plain read_line would happily buffer gigabytes if a client sent a line without a newline. take caps how much the call may read, and the extra + 1 lets us tell "exactly at the limit" from "over the limit".
  • let (Some(a), Some(b), Some(c), None) = (โ€ฆ) else { โ€ฆ } is a let-else with a tuple pattern. The fourth None rejects request lines with extra words.
  • Content-Length is checked before allocating. vec![0; length] with an attacker-chosen length would be a trivial memory attack. The check against MAX_BODY happens first, and the case Content-Length: 9999999 is refused without reading anything.
  • read_exact returns an error on a short body. The case with 50 promised bytes and 5 delivered is rejected as an I/O error ("unexpected end of file"). On a real socket, the read timeout turns a stalled client into an error as well, which stage 4 answers with 408 Request Timeout.
  • percent_decode works on bytes and then converts to a String with from_utf8_lossy, so a malformed %FF cannot crash it. It uses text.get(i + 1..i + 3), which returns None instead of panicking when the range cuts a multi-byte character.
  • Header names are lowercased so lookups are case-insensitive, and the map is a BTreeMap so the output order is stable.

Stage 2: responses and a router

The next two pieces involve no networking at all, so they can be exercised with plain function calls.

A Response knows its status code, content type and body, and turns itself into the exact bytes that go on the wire. A Router stores routes. A route has a method, a pattern such as /hello/:name, and a handler: a function from a request and the captured parameters to a response. Handlers are stored as Box<dyn Fn(...) + Send + Sync>, because routes of different shapes (plain functions, closures that capture state) must live in one Vec, and because the router will be shared between threads.

There is a subtle rule worth getting right: if the path matches a route but the method does not, the correct answer is 405 Method Not Allowed with an Allow header, not 404 Not Found.

Rust Stage 2: Response and Router without sockets

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

The last lines show exactly what a client would receive, with the \r\n line endings made visible: a status line, the headers and a blank line, then the body.

Points to notice:

  • Router::route takes &self. Handlers are Fn, not FnMut, so many threads can call the router at once without a lock. State that handlers need (a counter, a database handle) must therefore use interior mutability, such as an atomic or a Mutex, as we do in stage 4.
  • Segment::Literal(literal) if literal == part is a match guard; the next arm catches the failing literal case.
  • Path parameters are plain strings. Real routers also parse them into numbers, and decode percent escapes. A handler should still treat params["name"] as untrusted: never splice it into HTML or into a file path without escaping or validating.
  • The 405 response carries an Allow header. Clients and tools use it to learn what is possible.
  • A Response builder such as Response::text(404, format!(โ€ฆ)) is the whole "framework" most small services need.

Never copy user input into a response header without removing \r and \n. A name such as x\r\nSet-Cookie: โ€ฆ would let an attacker add headers of their own (response splitting). Our handlers only put fixed text into headers.

Stage 3: a thread pool

One thread per connection is the easiest design, and it is fine for a demo. But threads cost memory, and a flood of connections could create thousands of them. A thread pool starts a fixed number of workers up front and gives them jobs through a channel. When all workers are busy, new jobs wait in the queue.

The design has three parts:

  1. A Sender<Job> that the pool keeps. A job is Box<dyn FnOnce() + Send + 'static>.
  2. A Receiver<Job> shared by all workers. A receiver cannot be cloned, so it goes in an Arc<Mutex<โ€ฆ>>, and each worker locks it only to take the next job.
  3. Shutdown through Drop: when the pool is dropped, it drops the sender. Every worker's recv() then returns an error, the workers leave their loops, and the pool joins them.
Rust Stage 3: a thread pool with graceful shutdown

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

The order in which jobs finish is not guaranteed: three workers race for ten jobs. That is why the program sorts the results before printing. What is guaranteed is that when pool goes out of scope, every queued job has completed, because Drop joins the workers, and a worker only exits when the queue is empty and closed.

Two classic mistakes in this design:

  • Writing while let Ok(job) = receiver.lock().unwrap().recv() { job() }. The temporary guard in the while let condition lives for the whole loop body, so the lock is held while the job runs and the pool degenerates to one worker at a time. Our version takes the message in a separate let statement.
  • Forgetting that a panic in a job kills its worker thread. For a server you wrap each request in std::panic::catch_unwind, as stage 4 does, so one bad request cannot shrink the pool.

Stage 4: the complete server and client

Now everything goes on the network. The pieces:

  • handle_connection reads a request from the TcpStream (with a read timeout), routes it inside catch_unwind, writes the response and closes the connection.
  • Server::start binds to port 0, spawns an accept thread, and hands each connection to the pool.
  • Server::shutdown sets an atomic flag and connects to its own port once, which wakes up the blocked accept. The accept thread then leaves its loop and drops the pool, which waits for in-flight requests.
  • A tiny client sends raw requests and splits the reply into status and body.

The program sends sequential requests, then eight concurrent ones from eight client threads, and prints everything in a fixed order.

Rust Stage 4: the complete server and client

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Read the output from the top, and check each answer against the code:

  • The happy paths return 200 with the expected body, including a percent-encoded name that was decoded by the router.
  • POST /hello/Maya gives 405 and /missing gives 404: the router tells "wrong method" and "no such path" apart.
  • /boom panics inside the handler, yet the client receives a proper 500 and the server keeps running, because catch_unwind converted the panic into a value. Without it the worker thread would have died, and the pool would be one worker short.
  • The three malformed requests get 501, 400 and 413. A body that claims to be 99,999,999 bytes is refused before a single body byte is read.
  • The eight concurrent clients run on up to four pool workers. Their replies are printed in spawn order because we join the client threads in that order. The server's internal processing order is not deterministic, and the program does not depend on it.
  • /stats counts only requests that parsed successfully, because hits is incremented after parsing. The number is exact here because every earlier request has finished by the time we ask.
  • After shutdown, the listener is closed (the accept thread owned it), so connecting fails.

What would make it production-grade

This server shows the structure of real ones, but a service on the internet needs more:

  • Keep-alive. HTTP/1.1 connections normally stay open for several requests. We close after one for simplicity.
  • Timeouts everywhere. We set a read timeout; real servers also limit total request time, header time and idle time, and set write timeouts.
  • A bounded queue. mpsc::channel is unbounded, so a flood of connections piles up jobs in memory. Use sync_channel(n) and answer 503 Service Unavailable when the queue is full.
  • Backpressure and limits per client. Rate limits, connection caps.
  • Chunked bodies, compression, Expect: 100-continue, HEAD, OPTIONS.
  • TLS. Terminate it in a reverse proxy or use a TLS library; never write cryptography yourself.
  • Async I/O. A thread per busy connection does not scale to tens of thousands of idle ones. Async runtimes multiplex many connections on few threads; see async Rust and Tokio and the ecosystem.

Networking basics used here are explained in networking with std::net, and the channel and mutex patterns in channels and Mutex and RwLock.

Ideas to extend it

  1. Add Content-Type: application/json responses and a /items route with an in-memory Mutex<Vec<String>>.
  2. Serve static text from a BTreeMap<&str, &str> and add a safe /files/:name route that rejects names containing / or ...
  3. Support keep-alive: loop in handle_connection until the client sends Connection: close or the read times out.
  4. Replace the unbounded channel with sync_channel(16) and return 503 when try_send fails.
  5. Log each request with its status and duration (never print the durations in lesson output, but do log them in your own server).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does the parser read lines with reader.by_ref().take(MAX_LINE + 1).read_until(b'\n', &mut buffer) instead of read_line?

    An unbounded read_line would keep buffering until it found a newline. Limiting the read protects memory from hostile or broken clients.
  2. 2. A request arrives with Content-Length: 99999999. What does the parser do and why?

    The length is attacker-controlled, so it is compared to MAX_BODY first. The server answers 413 and never allocates.
  3. 3. Which status code should a router return when the path exists but only for another method?

    404 means no resource at that path. 405 means the resource exists but does not support this method, and Allow lists the methods that work.
  4. 4. What goes wrong with while let Ok(job) = receiver.lock().unwrap().recv() { job() } in a thread pool?

    A temporary in a while let scrutinee lives until the end of the loop body. Taking the message in a separate let statement releases the lock before the job runs.
  5. 5. Why does the server wrap routing in catch_unwind?

    A panic unwinds the worker thread. Catching it converts the failure to a value, answers the client with 500 and keeps the pool at full strength.

Summary

  • HTTP/1.1 is text: a request line, headers, an empty line and an optional body whose size comes from Content-Length.
  • Parse untrusted input defensively: bound every line, header count and body, return typed errors and never panic on bad bytes.
  • Keep parsing, routing and response building free of sockets so they can be checked with plain values.
  • Store handlers as Box<dyn Fn(...) + Send + Sync>; a shared router needs Fn handlers and interior mutability for state.
  • A thread pool is a channel of boxed jobs with a shared Arc<Mutex<Receiver>>; dropping the sender and joining the workers gives a graceful shutdown.
  • Use catch_unwind at the request boundary, read timeouts on sockets and port 0 plus local_addr() for tests.
  • Output from concurrent work is only deterministic if you join or sort; say so when it is not.

Next: Project: An Expression Interpreter