warp: composable Filters, optional crates, and a commented out TLS dependency

The Filter is the API, and a failed requirement becomes a rejection

Everything in warp is expressed through one type. The Filter is described as the fundamental building block, and the point of it is that filters combine and compose to express rich requirements on a request, which is why a single builder chain can carry a path pattern, a body type and a return value together. What that buys you is a handler that only runs when every requirement in the chain matched.

The other half of the model is what happens when one does not match. The filter chain produces a rejection instead of calling your closure, and the README never mentions rejections: the feature list covers path routing and parameter extraction, header requirements and extraction, query string deserialization, JSON and Form bodies, multipart form data, static files and directories, websockets, access logging, and gzip, Deflate and Brotli compression, and stops there. The error path is documented by a file instead, examples/rejections.rs. Consequence for a reader: the behaviour you will spend the most time on, telling a client why a request was refused, is the part with the least written guidance. Plan to read that example before you decide how to shape API errors.

Most of the advertised capabilities are optional crates you must name

The dependency block is where the advertised feature list stops being free. Crates that back several headline capabilities are marked optional: async-compression at 0.4.5 with the tokio feature, futures-channel, hyper, hyper-util, multer at 3, and tokio-tungstenite at 0.29. The ungated dependencies are the plain ones, bytes, headers, http, http-body, serde, serde_json, serde_urlencoded, mime, mime_guess, percent-encoding, scoped-tls, log, tokio, tokio-util, tracing and tower-service.

The dependency snippet in the README turns on a single feature:

tokio = { version = "1", features = ["full"] }
warp = { version = "0.4", features = ["server"] }

Consequence for a reader following that line: websockets, multipart form data and the gzip, Deflate and Brotli support each rely on their own optional crate, so check the manifest's features to see what the "server" feature enables. You find out which flag maps to which capability by reading the manifest, not the README, and a project that assumed the full list was present will discover the gap at compile time when the import does not resolve.

The TLS dependencies are commented out while a TLS example ships

The manifest shows the TLS stack present but disabled. Both lines are commented rather than deleted, tokio-rustls at 0.26 with default-features off and the features logging, tls12 and ring, plus rustls-pemfile at 2.0. Both are marked optional in the commented text, which means the authors kept the intended shape rather than removing it.

Meanwhile the example set contains examples/tls.rs and a examples/tls/ directory. Consequence for a reader: the README's dependency snippet never mentions TLS, so check the manifest's features and examples/tls.rs before assuming HTTPS works out of the box.

The published crate ships src only, so examples live on GitHub

The include list in Cargo.toml is short: Cargo.toml, LICENSE and everything under src. The examples/ and tests/ directories in the repository are not part of the published artifact, even though both exist at the top level of the tree, and autotests and autoexamples are both set to true so the repository's own checks discover them.

Consequence for a reader is a split between what you install and what you study. Whoever adds warp gets the library and its documentation on docs.rs, where the metadata is configured to build with all-features so every gated capability is visible in the docs. Nobody gets the twenty or so example programs, the examples/README.md index, or the integration tests in the package they downloaded. The README handles this by pointing at docs.rs and at the examples directory in the GitHub tree, which means the tutorial material is a browsing step you do at the repository rather than something that arrives with your dependency.

Server-sent events, unix sockets and templating exist as code, not as claims

Compare the README's list of what you get with what the examples directory holds, and three capabilities have code but no line in the list. There are examples/sse.rs and examples/sse_chat.rs, so server-sent events are implemented as example programs. There is examples/unix_socket.rs, so binding away from a TCP address is demonstrated. There is examples/handlebars_template.rs, so a template engine has a place in the story. None of the three appears in the out-of-the-box list.

The rest of the directory maps cleanly onto the list and is worth using as an index for it: examples/routing.rs and examples/query_string.rs for routing and query deserialization, examples/headers.rs for header requirements, examples/body.rs for bodies, examples/multipart.rs for multipart, examples/compression.rs for the compression codecs, examples/websockets.rs and examples/websockets_chat.rs, examples/dir.rs and examples/file.rs for static files, examples/tls.rs, examples/tracing.rs and examples/futures.rs for logging and async composition, examples/hello.rs, examples/todos.rs, examples/returning.rs and examples/rejections.rs. Consequence: treat the examples directory as the real feature index and assume the README list is a summary rather than a boundary.

The manifest reads 0.4.3 while the newest listed tag is v0.4.1

Versioning is where a reader can get caught out. The manifest declares version 0.4.3 for the crate named warp, authored by Sean McArthur, licensed MIT, on edition 2021, categorised under web-programming::http-server. The release tags listed for the repository stop at v0.4.1, dated August 2025, after v0.4.0 and v0.3.7 in the preceding days.

Consequence for a reader: the dependency line in the README, version 0.4, resolves within the 0.4 series and can land you on any patch in it, and the manifest version is not a reliable proxy for which tag you are reading when the two disagree. Since the project sits in a 0.x line, the usual semver signal that minor bumps stay compatible does not apply, so pin an exact version if reproducibility matters to you and read CHANGELOG.md before upgrading. The manifest also carries documentation pointing at docs.rs and a repository field pointing at GitHub, which are the two places to look when the release note you need is not in the README.

The HTTP layer and the runtime are both fixed by the dependency block

warp does not let you pick its HTTP implementation, and it says so: it builds on top of hyper, so HTTP/1, HTTP/2 and asynchrony come from that layer rather than from warp code. The manifest pins hyper at 1 and hyper-util at 0.1.12 with a specific feature set, namely server, server-graceful, server-auto, http1, http2, service and tokio.

The runtime is likewise not abstract. tokio is a required dependency at 1.0 with io-util, fs, sync and time, and tokio-util at 0.7.1 with io sits beside it, so a warp application runs on Tokio whether or not you chose it, which is also why the README's main function is annotated with it. Consequence for a reader evaluating the framework: the two decisions most frameworks leave open, HTTP stack and async runtime, are made for you here. That is a reasonable trade for a small service, and a poor fit if the surrounding system already runs on a different executor or expects to swap HTTP implementations.

Editorial conclusion

warp suits Rust teams that want routing, extraction and rejection handling to compose into one type and that are already committed to Tokio, since warp depends on it directly rather than abstracting it away. It does not suit codebases needing a different async runtime, or teams that expect HTTPS, server-sent events or multipart handling to be present after a single dependency line. Before adopting it, read Cargo.toml for which crates are optional, check how TLS is enabled if you need it, and read the examples directory on GitHub rather than in the published crate.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. seanmonstar/warp on GitHub