Skip to content
Tutorials Center
My learning

Topics

Lesson 115 of 132 ยท Advanced Rust

Web Services in Rust

Learn how Rust web frameworks work: path routing, extractor traits, IntoResponse, shared state with Arc and Mutex, middleware, and a loopback server built by hand.

Most Rust web services are written with a framework such as axum, actix-web or Rocket. Their handlers look almost too simple: an ordinary function that takes a few typed arguments (a path parameter, a query string, the shared database pool) and returns something that turns into a response. There is no request object to pick apart and no manual parsing. That convenience comes from a handful of traits and a clever use of generics, and once you have seen the trick you can read any framework's source and use its types with confidence.

In this lesson you will build a miniature framework with the same architecture: a router with path patterns, extractors that pull typed values out of a request, an IntoResponse trait for return values, shared state behind Arc, and middleware layers. Then you will run it for real on the loopback network, with a server thread and a client in the same program. The earlier Project: A Tiny HTTP Server built the raw HTTP parsing, a router and a thread pool step by step; this lesson sits one level above it and focuses on how handlers are typed. You will also need Traits, Trait Objects, Closures and Arc and Rc from earlier chapters.

Real frameworks are asynchronous (see Async Rust and Tokio and the Ecosystem) so that thousands of idle connections cost almost nothing. Our version is synchronous so it can run in the editor with only the standard library. The architecture, which is the part worth learning, is identical.

What a framework does with one request

Every request takes the same trip through the framework. The middleware layers wrap the whole thing like onion skins, so each one sees the request on the way in and the response on the way out:

sequenceDiagram
    participant C as Client
    participant M as Middleware
    participant R as Router
    participant H as Handler
    C->>M: GET /notes/2
    M->>R: request
    R->>R: match "/notes/:id", fill params
    R->>H: build Path and State extractors
    H-->>R: Result of String or ApiError
    R-->>M: Response via IntoResponse
    M-->>C: status line, headers, body

The router picks the handler, the extractors prepare its arguments, and IntoResponse converts whatever it returns.

Routing with path patterns

A route is a method plus a pattern such as /notes/:id. Segments that start with a colon capture whatever is in that position; other segments must match exactly. The router tries routes in order, so register specific routes (/notes/new) before patterns that would also match them (/notes/:id).

Notice the difference between the two failure cases. If no pattern matches the path, the answer is 404 Not Found. If a pattern matches but under a different method (a POST to a route that only accepts GET), the correct answer is 405 Method Not Allowed. Clients and API tools rely on that distinction.

Rust Path patterns, 404 and 405

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 static route /notes/new wins over /notes/:id only because it was listed first. A trailing slash is ignored here by trim_matches; real frameworks make this a setting. Production routers do not scan a list; they compile all patterns into a tree (a radix trie) so lookup time does not grow with the number of routes.

Handlers as ordinary functions

Here is the heart of the design. We want to register fn get_note(Path(id): Path<usize>, State(app): State) -> Result<String, ApiError> as a handler without writing any glue. Three traits make that work.

FromRequest (an extractor). Any type that can build itself from a &Request: the whole State, the query map, the body text, or a path parameter parsed into a type that implements FromStr (so Path<usize> works and Path<Uuid> would too). If extraction fails, it returns a ready-made error Response, such as 400 Bad Request, and the handler never runs. This is called a rejection.

IntoResponse. Anything a handler can return: a &'static str, a String, a (status, body) pair, a Response, or a Result<T, E> where both sides implement IntoResponse. Because Result itself implements it, a handler can use ? internally and return a custom error enum that decides its own status code (ApiError::NotFound becomes 404). This is the idiomatic way to map errors to HTTP in Rust frameworks, and it mirrors the error design from Designing Error Types.

Handler<Args>. This one is implemented for every function type Fn(A, B) -> R where each argument is a FromRequest and R is an IntoResponse. Rust has no variadic generics, so a small macro repeats the implementation for one, two and three arguments. The Args type parameter (here a tuple like (A, B)) exists only to keep the different implementations from overlapping, which is why Router::route takes a seemingly unused type parameter T.

The router stores each handler behind a trait object: Box<dyn Fn(&Request) -> Response>. Registering the route wraps the handler in a closure that calls handler.call(req), which extracts the arguments, calls your function and converts its return value. The generics are erased at that boundary, so all routes fit in one Vec.

flowchart LR
    F["fn get_note(Path, State)"] --> I["impl Handler for Fn(A, B)"]
    I --> X["A::from_request, B::from_request"]
    X -->|rejection| E["400 / 500 response"]
    X -->|ok| C["call your function"]
    C --> R["IntoResponse"]
    R --> W["Response"]

The blanket Handler impl turns any function with extractor arguments into something the router can store and call.

Shared state and middleware

A web service handles many requests that share things: a database pool, configuration, a cache, counters. Shared state lives in one value wrapped in Arc, and each request gets a cheap clone of the Arc through a State extractor. Anything mutable inside must be thread-safe: Mutex or RwLock for data, atomics for counters (see Mutex and RwLock and Atomics). Keep critical sections short; a handler that holds a lock while doing slow work serializes every request. In an async framework, never hold a standard MutexGuard across an .await.

Middleware wraps handlers with cross-cutting behavior: logging, authentication, timing, compression, request limits. In our framework a layer is a function that receives the request and a next closure representing the rest of the chain. It can act before calling next(req), after it, or answer on its own without calling it (an authentication layer returning 401). In axum the same idea is built from tower's Service and Layer traits.

The framework running on direct calls

First, drive the whole machine with direct calls to router.dispatch, with no network involved. This makes behavior easy to check: valid requests, a missing note, a bad path parameter, a wrong method, validation errors, and the shared counter that the middleware updates. The logging layer prints one line per request, so each result line is preceded by a [log] line.

Rust A mini web framework with extractors

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 results carefully, because each one shows a different part of the machinery working. The empty POST is rejected by the handler itself with a 400 through ApiError. /notes/two never reaches get_note: the Path<usize> extractor fails to parse two and returns 400 by itself. DELETE /notes/1 matches a pattern with another method, so it is 405. The last line shows the hit counter was incremented by the middleware for every request, including this one.

A real server on the loopback interface

Now the same router goes on the network. The server needs the four steps from any HTTP server: accept a TCP connection, read the request line, headers and body (using Content-Length to know how much body to read), call router.dispatch, and write a status line, headers and body back. The client does the reverse. Both run in the same program on 127.0.0.1 with port 0, which asks the operating system for any free port.

Two details matter. The router contains Box<dyn Fn> values that are not Send, so the server thread builds its own router inside the thread and only the Arc<AppState> crosses the thread boundary; this is also a good illustration of why shared state needs Arc. And the server answers a fixed number of connections and then returns, so main can join it and finish cleanly.

Rust The framework served over TCP on 127.0.0.1

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 [log] lines come from the server thread and the result lines from the client in main. Because the client waits for each response before sending the next request, the output is always in this order. After the join, main reads the same AppState the server mutated, through its own Arc handle, which is shared state across threads in a nutshell.

The same service with axum

With axum 0.8 on tokio the service looks very similar, which is the point. Handlers are async fns, Json is an extractor and a responder, and Path, Query and State work like ours. This snippet is read-only because the editor has no crates:

Rust
use axum::{
    extract::{Path, State},
    http::StatusCode,
    routing::get,
    Json, Router,
};
use serde::Serialize;
use std::sync::{Arc, Mutex};

#[derive(Clone, Default)]
struct AppState {
    notes: Arc<Mutex<Vec<String>>>,
}

#[derive(Serialize)]
struct Note {
    id: usize,
    text: String,
}

async fn get_note(
    Path(id): Path<usize>,
    State(app): State<AppState>,
) -> Result<Json<Note>, StatusCode> {
    let notes = app.notes.lock().unwrap();
    notes
        .get(id.wrapping_sub(1))
        .map(|text| Json(Note { id, text: text.clone() }))
        .ok_or(StatusCode::NOT_FOUND)
}

#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/notes/{id}", get(get_note))
        .with_state(AppState::default());
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

You can map every piece: Path and State are extractors, Result<Json<Note>, StatusCode> is an IntoResponse, and .route("/notes/{id}", get(get_note)) is our route("GET", ..., get_note). Serialization of Note to JSON uses the data-model design from Serialization and Data Formats by Hand.

Production concerns

Our toy server leaves out what a real deployment needs, and a framework gives you most of it:

  • Limits and timeouts on header size, body size and slow clients (the examples cap the body size, but a hostile client could still send an endless header line).
  • TLS, usually terminated by a reverse proxy such as nginx or a cloud load balancer in front of your service.
  • Graceful shutdown, finishing in-flight requests when the process is told to stop.
  • Input validation at the extractor layer, and no unwrap on anything that comes from a client.
  • Structured logging, metrics and request ids, as described in Building CLI Tools: Arguments, Logging and Errors for the logging part.
  • Async I/O so one thread can serve many sockets.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A route GET /notes/:id exists. What should the router answer for POST /notes/5?

    The path matches a known pattern but with a different method, so the correct answer is 405. 404 is for paths that match no route at all.
  2. 2. What is the job of an extractor such as Path<usize>?

    An extractor implements FromRequest. If it succeeds, the value becomes an argument of your function; if it fails, its rejection response is returned and the handler never runs.
  3. 3. Why can a handler return Result<String, ApiError>?

    The blanket implementation calls into_response on whichever side is present, so a handler can use ? and a custom error type decides its own status code.
  4. 4. Why does the example create the Router inside the server thread instead of building it in main and moving it in?

    Box<dyn Fn> is not Send unless declared so. Creating the router in the thread avoids moving it, while Arc<AppState> is Send and Sync and can be shared safely.

Summary

  • A web framework is a router plus conventions: path patterns with captured segments, 404 for unknown paths and 405 for known paths with the wrong method.
  • Extractors (FromRequest) turn the request into typed handler arguments and reject bad input with ready-made error responses.
  • IntoResponse converts return values, including Result<T, E> with custom error enums, into responses.
  • A blanket Handler implementation over Fn(A, B) -> R lets plain functions act as handlers; the router erases the generics behind Box<dyn Fn>.
  • Shared state is an Arc of thread-safe data (Mutex, RwLock, atomics); keep locks short and never hold a std lock across .await.
  • Middleware wraps the rest of the chain with a next call, for logging, authentication and limits.
  • A server is accept, read, dispatch, write; real services add limits, TLS, timeouts and async I/O, usually through axum, actix-web or Rocket.

Next: Project: Guessing Game