API Reference

This page provides a high-level overview of the warp API. For detailed, item-specific documentation, please refer to the official crate documentation on docs.rs.

Core Trait: Filter

The most important trait in warp is warp::Filter. It is the foundation of the entire framework. Filters are composable units that can inspect requests, extract values, and either proceed or reject. All routing and request processing logic is built by combining filters.

Top-Level Functions

These are some of the most commonly used functions available at the root of the warp crate:

  • warp::serve(filter): Creates a server to run the given filter.
  • warp::any(): A filter that matches any request, often used as a starting point for a filter chain.
  • warp::reply(): Creates a default 200 OK reply.
  • warp::redirect(uri): Creates a 301 Moved Permanently redirect reply.
  • warp::reject(): Rejects a request, typically resulting in a 404 Not Found if no other filters handle it.
  • warp::service(filter): Converts a Filter into a tower::Service, allowing integration with the broader Tower and Tokio ecosystem.

Main Modules

warp's functionality is organized into several modules, each providing a specific set of filters.

warp::path

Contains filters for matching and extracting values from the request URL path.

  • path(segment): Matches a static path segment.
  • param<T>(): Extracts a path segment and deserializes it into type T.
  • end(): Matches the end of the path.
  • tail(): Extracts the rest of the unmatched path.
  • path! (macro): A convenient macro for combining path segments and parameters.

warp::header

Contains filters for matching and extracting request headers.

  • header<T>(name): Extracts a header and deserializes it.
  • optional<T>(name): Extracts a header if it exists.
  • exact(name, value): Requires a header to have an exact value.

warp::query

Contains filters for deserializing the request's query string.

  • query<T>(): Deserializes the query string into a struct T.
  • raw(): Extracts the raw query string.

warp::body

Contains filters for extracting the request body.

  • json<T>(): Deserializes a JSON body into a struct T.
  • form<T>(): Deserializes a URL-encoded form body.
  • bytes(): Extracts the raw body as bytes::Bytes.
  • stream(): Provides the body as a Stream of chunks.

warp::fs

Contains filters for serving the local filesystem.

  • file(path): Serves a single file.
  • dir(path): Serves a directory of static assets.

warp::ws

Provides the ws() filter for handling WebSocket upgrades.

warp::sse

Provides utilities like sse::reply() and sse::Event for Server-Sent Events.

warp::cors

Provides a configurable cors() wrapper for handling Cross-Origin Resource Sharing.

warp::log & warp::trace

Provides wrappers for logging requests and integrating with the tracing crate for diagnostics.