Author: suikammd ihciah
An HTTP Server contains many internal components: protocol implementation (h1, h2, compression, and so on), connection state management (keepalive), request dispatching, middleware, business logic, and more. Users could implement all of these themselves, but everything other than the business logic is a fairly general capability. Decoupling these general capabilities from the user’s business logic gives us an HTTP framework.
Because hyper already provides a fairly complete HTTP protocol implementation in the Rust ecosystem, building an HTTP framework on hyper only requires providing capabilities such as routing, shared state, and middleware.
From the perspective of HTTP framework design, this article uses the new version of Axum as an example to analyze how an HTTP framework in Rust can provide sound abstractions and type constraints. Rust’s powerful type system allows us to write efficient and correct code.
Handler Abstraction
Simple Routing
Usually, our behavior is independent for different Methods at different request Paths.
Dispatching based on Path and Method is one of the general capabilities an HTTP framework needs to provide. For example, we need to dispatch GET / and POST /login to different handler functions.
The simplest router can be implemented with a HashMap. As shown below, the Key is the Path and Method, and the Value is the corresponding handler function. We could represent Path and Method simply with String, but how should we represent the handler function?
1 | HashMap<(Path, Method), Handler> |
I will address the Handler problem first and return to more reasonable router designs later.
Since I need to store Handlers in a HashMap, I need a fixed type to represent them; otherwise, the size of the HashMap’s Value cannot be determined. In Rust, I often use Box<dyn Trait> to unify different concrete types into a single type (corresponding to pointers in other languages).
This means I need to define a Trait to describe the handling logic.
The Simplest Approach: Constraining Handlers to Implement a Fixed Fn
Because the handling logic must process an HTTP Request and produce an HTTP Response, an intuitive approach is to accept the HTTP Request structure decoded by hyper directly as an argument and require the function to return an HTTP Response.
If a handler needs a particular request parameter internally, it must extract that parameter from the HTTP Request itself and may need to perform deserialization and other processing itself (such as Json).
1 | add_route(handler: H, ...) |
A More User-Friendly Interface
The drawback of the previous approach is that it is cumbersome for users, who must extract parameters themselves. A more user-friendly implementation lets the framework handle parameter extraction, so users only need to declare what they need in the parameters and describe the business logic.
The result I want is:
1 | async fn index() -> &'static str { |
To implement a unified Trait for these Handlers, I need to solve several problems:
- Constrain every parameter so that it can be extracted from an HTTP Request.
- Constrain the function’s return value so that it can be converted into an HTTP Response.
- Support variable numbers of parameters (different Handlers may have different parameter counts).
- Support Async Fn.
Parameter Constraints
I want compile-time checks to ensure that these parameters can be extracted from the Request. I can define a Trait:
1 | // framework code |
For example, to extract parameters from the HTTP Query, users only need to implement code like this:
1 | // user code |
The framework implements the auxiliary Query structure to extract values from Query parameters.
1 | // framework code |
In addition to using built-in framework helpers such as Query and Form, users can implement FromRequest themselves.
This approach decouples request-parameter extraction from business logic and adds type constraints. They ensure that a function implements Handler and can be registered with the Router only when the relevant structure implements extraction from the Request.
Return Value Constraints
Return value constraints are similar to parameter constraints: I constrain return values so that they can be converted into Responses:
1 | pub trait IntoResponse { |
A framework can provide some implementations:
1 | impl IntoResponse for &'static str {...} |
IntoResponse allows user handlers to return custom structures and decouples Response construction from business logic.
Supporting Variable Numbers of Parameters
Some handlers need no input parameters (such as the index endpoint mentioned earlier, which returns “hello world”), while others need one or more parameters extracted from the Request.
How can I abstract over this kind of function uniformly? In Rust, my usual approach is to define a Trait and implement it for every Fn that satisfies the conditions. For Fn types with different parameter counts, I need to implement the Trait manually for each of them.
Because this work is tedious, boring, and repetitive, macros are often used for the implementations. The resulting block of code ends up looking like a “staircase.”
1 | // from axum |
I need a unified calling interface and will use macros to implement it:
1 | pub trait Handler { |
Ultimately, calls still pass in http::Request directly and return http::Response.
Request Ownership
In the preceding interface, I constrained request-parameter extractors to receive only a read-only reference to the Request because I may need to extract multiple parameters. A small optimization is possible here: if there is only one parameter extractor, pass it ownership; otherwise, pass ownership to the last extractor and references to the preceding ones.
Axum has two related traits: FromRequestParts and FromRequest. FromRequestParts can extract content from the HTTP Request Head (passing a reference), while FromRequest can extract from both the HTTP Request Head and Body (passing ownership of the entire Request). FromRequest is very useful for extractors that need to consume the Body, but it is applied only to the last extractor.
Supporting Async Fn
With the Handler Trait from the previous section, I can already define Handlers fairly ergonomically. However, handler processing often involves database reads and writes, downstream RPC calls, and similar operations. Since these network operations are asynchronous, handlers must be implemented as async fn.
Async Fn is fundamentally an Fn as well. Compared with an ordinary Fn, the difference is that async desugaring transforms the declared return value into an anonymous structure implementing Future. For example:
1 | // before desuger |
(Further reading: for some fundamentals of Rust’s asynchronous system, see this talk.)
To support async fn implementations of the Handler Trait, I need to make some changes:
1 | pub trait Handler { |
Because concrete Future types are involved, there are actually two approaches here. One is to make type Future: Future<Output = http::Response> an associated type of the Trait; the other is to erase the type directly with BoxFuture.
The choice mainly depends on whether to erase the type and where to perform type erasure. Generally, in scenarios that may involve nested calls (such as nested tower Services), it is best to perform type erasure at the end. This minimizes Box usage and enlarges the code segments that can be inlined, achieving better performance.
Having modified the Trait, I likewise need to modify its implementations. Below is a demo example after macro expansion:
1 | // illustrate for macro expand result |
Note: This restricts me to asynchronous interfaces. If I also implement Handler for structures returning T: IntoResponse, the implementations conflict because both are blanket impls.
In summary, this section has clearly defined the Handler Trait and automatically implemented Handler for user-defined async fn / fn functions meeting certain conditions. Users can apply extractors and generators to function parameters and return values, allowing the handler itself to focus on business logic.
Shared State
A Handler may need external values internally, such as an initialized db or a HashMap used as a cache. I generally allow users to attach a State (also called Data) when creating a Route and then extract that structure in the handler function’s parameters.
Extracting Shared State
I can treat shared state entirely as part of the Request.
This lets me reuse the FromRequest defined earlier. But how do I distinguish where the S I want to extract (a user-defined type) should come from? Or what if the S the user wants to extract is the same Query I use for request-parameter extraction? Putting S directly in the parameters would make the semantics ambiguous.
To resolve this ambiguity, I can define a State type.
1 | pub struct State<S>(pub S); |
When I subsequently implement FromRequest for State, I know that this S must be extracted from shared state.
Storing Shared State
Following my earlier reasoning, since shared state is treated as part of the Request, I must either store the state somewhere in the Request, define a new Request carrying state, or pass it in through an additional parameter.
Storing State in the Request Itself
Actix and earlier versions of Axum both stored state this way. The Request contains a type map called extension, into which I directly insert a KV: key = S; val = S{…}. During extraction, I use the S type as the key to retrieve the val inserted before the handler was called.
This looks convenient and easy to implement, but the approach gives up the opportunity for static type checking. If the State required in the user’s handler parameters does not match the State type attached to the Route, the mismatch can only be handled at runtime. As a result, erroneous code can compile but will fail 100% of the time at runtime.
Passing State through an Additional Parameter and Adding Type Constraints
Rust’s type system lets me expose the problem described earlier at compile time.
I can add the generic S to Handler, FromRequest, and Route and constrain routing registration on Route<S>:
1 | pub trait Handler<S> { |
This constrains the State type on the handler fn. Finally, I implement the State helper structure for parameter extraction:
1 | pub struct State<S>(pub S); |
And I am done! I can now use shared state confidently without worrying about passing the wrong type and causing runtime problems. If it compiles, it works.
More User-Friendly Shared State
As with extraction from the Request discussed earlier, users may need only part of the Request or State. To make this easier to use, I can allow users to accept only part of the State. For example:
1 | struct MyShared { |
Similar to FromRequest, I can define a Trait that allows a substructure to be derived from a larger structure.
1 | // in `from` style |
Comparing the FromRef and Param Styles
Just as with the relationship between From and Into, I can provide Traits in both styles. The two are equivalent, so I only need to choose one of them.
Axum uses the FromRef definition, while the Param style can be found in linkerd2-proxy.
Which of these two is better? The standard library encourages defining From rather than Into, but this does not mean I can blindly assume that the FromRef form is better.
The standard library gives From a backdoor around the orphan rule, whereas the framework-defined FromRef has no such backdoor. The following code violates the orphan rule and cannot compile:
1 | struct Example { |
However, using the Into style works:
1 | struct Example { |
I will use the Into-style Param Trait to implement this section’s functionality:
1 | impl<S, I> FromRequest<S> for State<I> |
Routing
Routing is a system for composing and dispatching Handlers.
Earlier, I introduced the Handler concept through the simplest possible router and described the Handler Trait constraints and macro-based automatic Handler implementations for user-defined functions. However, a truly easy-to-use router is still some distance away.
Route Lookup and Merging
For route lookup, I can use the existing matchit library. Matchit lets me register Paths and Values; when a request matches a path, it returns the Value corresponding to the matching Path. Matchit is based on a radix trie and, unlike HashMap, supports prefix matching and parameter extraction (such as /user/:id).
For a simple implementation, directly wrapping matchit provides path matching. However, matchit has the drawback of not supporting iteration to retrieve the Paths and Values supplied during registration. Therefore, to support additional features (such as merge), I also need to maintain a complete set of mappings myself.
In Axum, a Handler is represented by the Endpoint type. Router maintains two pieces of information:
- RouteId → Endpoint
- Node
- matchit
Router<RouteId>: used for path matching - RouteId → Path
- Path → RouteId
- matchit
When looking up a path, the path is passed directly to the matchit Router to find the corresponding RouteId, which is then used to find the Endpoint.
When merging routers, suppose I want to merge B into A. I iterate over the route information in B to obtain all (RouterId, Path, Endpoint) tuples, then try to merge them into entries with the same Path in A (for entries with the same Path but different Methods), creating a new entry if none exists.
For example, merging /login and /logout inserts the corresponding Paths and RouterIds into the matchit Router. Merging GET /login and POST /login, however, requires no modification to the matchit Router; the corresponding Endpoints can simply be merged.
Endpoint
Axum defines Endpoint to support nested Routes and dispatching by Method.
1 | enum Endpoint<S, B> { |

Route
1 | pub struct Route<B = Body, E = Infallible>(BoxCloneService<Request<B>, Response, E>); |
A Route is an async fn (Request) → Result<Response, Error> that can directly handle requests. When I do not need to dispatch by Method, or dispatching has already been completed, I can send the request directly to the corresponding Route for handling.
BoxedIntoRoute
1 | pub(crate) struct BoxedIntoRoute<S, B, E>(Box<dyn ErasedIntoRoute<S, B, E>>); |
BoxedIntoRoute erases the Handler type, so its generics contain no Handler-related markers, Handler associated types, and so on.
Its State remains to be supplied. I can think of BoxedIntoRoute as a Route without State attached. Once State is attached, it becomes an actual Route, which is the meaning of Into Route in its name.
MethodRouter
1 | pub struct MethodRouter<S = (), B = Body, E = Infallible> { |
A MethodRouter contains MethodEndpoints corresponding to different Methods. A MethodEndpoint may be None (nothing is configured for that Method), or it may be the Route or BoxedIntoRoute described earlier.
Route Composition
I will use an example copied from axum to see exactly how a Router is created:
1 | async fn main() { |
- First is
.route("/keys", get(list_keys)). Here, get boxes a function and converts it into aMethodRouter<S, B, Infallible>; route then inserts it intoEndpoint::MethodRouter. Because State has not yet been attached, its internal type corresponds toBoxedIntoRoute, the type lacking State. - Next, consider
.with_state(Arc::clone(&shared_state)):
1 | pub fn with_state<S2>(self, state: S) -> Router<S2, B> { ... } |
This attaches state of type S and rewrites the generic to the new type S2 (which has no constraints at this point).
Internally, with_state attaches State to every BoxedIntoRoute, converting it into the Route type.
.nestaccepts a prefix and a child router. The child router only needs to be inserted as a NestedRouter. Note that the prefix must also be removed before a request is passed to the child router.
Middleware
Tower Service
Tower is a general-purpose component for describing logic in the Rust ecosystem. Tower provides a Service Trait that describes asynchronous logic taking a Request as input and producing Result<Response, Error> as output. Essentially any logic with one input corresponding to one response can be described with this Trait.
1 | pub trait Service<Request> { |
Service not only helps align interfaces between different components; I can also use Tower’s auxiliary components to compose logic. Tower provides Layer for decorating Services and Stack for nesting Layers.
1 | pub trait Layer<S> { |
A simple summary is:
- Service describes the common logic of
async fn (Request) → Result<Response, Error>. - Layer is a Service decorator: pass in a Service and receive a decorated Service.
- Stack is a composition of Layers. It implements Layer itself, and
.layerinvokes all its internal layers in sequence.
Because I use Service middleware and Route itself implements Service, I only need to accept a layer to wrap a Route.
For a BoxedIntoRoute that still lacks State, I temporarily store the layers and wait until State has been supplied before wrapping it with those layers.
Creating and Using a Server
Combining the routing, Handlers, and middleware discussed above gives me a Server. Server lets users bind and serve a MakeService:
1 |
IntoMakeService<S> implements Service<T, Response = S, Error = Infallible>.
Server::bind(…).serve(…) creates a Server. Server implements Future, so it can be awaited directly. In its Future implementation, it first accepts a connection and uses IntoMakeService<S> to generate S, the Service used to process requests (my router).
The io (connection) and the processing Service are then wrapped together in a hyper::Connecting structure, which constructs a hyper::NewSvcTask and spawns that task.
Hyper handles connection reads and writes, decoding, and similar work. Finally, hyper calls the Service I supplied—that is, Router—with the decoded http::Request.

The Generic Trick for Router and State
This completes the main analysis of the article:
- How to constrain Handlers
- How to perform route lookup and route management
- How to support shared state
While reading the code, I noticed Axum’s trick involving State generics and found it quite novel.
If you read the earlier shared-state section carefully, you will have noticed that my approach looked like this:
1 | async fn index() -> String { ... } |
Axum, however, supports this approach:
1 | let route = Route::new() |
Axum can chain different Handlers and States in this way. How is this implemented?
Router’s new method places no direct constraint on S; in other words, S here can be understood as Any. When the route method is called, the Handler implementation may impose a constraint on S (or it may not). When with_state is called, the type of S is determined. At that point:
- It checks whether this S satisfies the preceding constraints.
- It resets the generic S to S2 (that is, it clears the association and the constraints).
Finally, when the router is used, into_make_service is called and Router is constrained to implement Service. Both implementations are for Router<()>, meaning that S can be ().
Consider the following cases:
- A previously registered handler constrains S, but there is no
with_state: S is constrained (and no reasonable person would write this constraint as (), because that would be meaningless), so S cannot be (). Therefore, forgetting to attach state or attaching the wrong state causes compilation to fail. - A previously registered handler does not constrain S, and there is no
with_state: S has no constraints, so it can be (). Compilation therefore succeeds even without calling with_state. - A previously registered handler constrains S, and
with_stateis called last: with_state clears the constraint on S, so S can be () and compilation succeeds. - Chained calls as in the previous example: every
with_stateclears the preceding constraints, and a subsequent.routeadds constraints again. As long as the final operation iswith_state, or the final series of.routecalls does not constrain S, S can be () and compilation succeeds.
Through this trick, Axum provides static State checking while also allowing State to be omitted when it is not used.