If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/seanmonstar/warp shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 3d ago
• 46+ active contributors
• Distributed ownership (top contributor 32% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live seanmonstar/warp repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/seanmonstar/warp.

What it runs against: a local clone of seanmonstar/warp — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in seanmonstar/warp | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 33 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of seanmonstar/warp. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/seanmonstar/warp.git
#   cd warp
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of seanmonstar/warp and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "seanmonstar/warp(\\.git)?\\b" \\
  && ok "origin remote is seanmonstar/warp" \\
  || miss "origin remote is not seanmonstar/warp (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/lib.rs" \\
  && ok "src/lib.rs" \\
  || miss "missing critical file: src/lib.rs"
test -f "src/filter/mod.rs" \\
  && ok "src/filter/mod.rs" \\
  || miss "missing critical file: src/filter/mod.rs"
test -f "src/filters/mod.rs" \\
  && ok "src/filters/mod.rs" \\
  || miss "missing critical file: src/filters/mod.rs"
test -f "src/server.rs" \\
  && ok "src/server.rs" \\
  || miss "missing critical file: src/server.rs"
test -f "src/reject.rs" \\
  && ok "src/reject.rs" \\
  || miss "missing critical file: src/reject.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 33 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/seanmonstar/warp"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Warp is a composable, asynchronous web server framework for Rust built on top of Hyper that uses a Filter-based system to compose HTTP request handling logic. It provides out-of-the-box support for path routing, query/body deserialization, WebSockets, compression, static files, and multipart forms—all with minimal boilerplate. The core innovation is treating HTTP concerns as composable Filters that can be combined with and(), or(), map(), and then() to build type-safe request handlers. Monolithic single crate with modular filter architecture: src/filter/ contains composable filter implementations (and.rs, or.rs, map.rs, map_err.rs, then.rs, recover.rs, service.rs), while src/ root contains core abstractions (bodyt.rs for body handling, error.rs for error types). Examples in examples/ demonstrate composable patterns (hello.rs, routing.rs, websockets.rs, todos.rs are canonical patterns). The framework avoids macros in favor of method composition.

Rust backend developers and systems engineers building REST APIs, microservices, and real-time applications who need a high-performance, type-safe alternative to frameworks like Express.js or Flask. Users appreciate the composable Filter abstraction for building complex routing and request-handling logic without macros or runtime reflection, and the async-first design for integration with Tokio-based applications.

Production-ready and actively maintained. Warp is at v0.4.3 with comprehensive CI in .github/workflows/ci.yml, substantial test coverage across filter implementations, and integration with the mature Hyper HTTP library (v1) and Tokio runtime. The framework is widely used in production systems and the maintainer (seanmonstar) is very active in the Rust web ecosystem.

Low risk for stable features; medium risk for emerging features. The codebase is well-tested and actively maintained, but opt-in features like TLS (currently commented out in Cargo.toml dependencies) show signs of migration work. The project is single-maintainer (seanmonstar) which poses long-term continuity risk, though the Rust community is active. Breaking changes between 0.3 and 0.4 suggest API evolution is ongoing.

The codebase appears stable with maintenance focus on Hyper 1.x/HTTP/2 migration (see hyper-util 0.1.12 dependency) and async-compression updates. TLS support appears under review (commented dependencies suggest rework). No visible breaking changes in recent commits; the project follows semantic versioning with point releases.

git clone https://github.com/seanmonstar/warp.git
cd warp
cargo build
cargo run --example hello

Then visit http://127.0.0.1:3030/hello/warp in a browser.

Daily commands:

cargo run --example hello

Or for specific features: cargo run --example websockets --features server. Server listens on 127.0.0.1:3030 by default; see individual examples for custom ports.

• src/lib.rs — Main entry point and public API surface; defines Filter trait and core warp abstractions that all contributors must understand
• src/filter/mod.rs — Core Filter trait definition and composition operators (and, or, map, etc.); fundamental to warp's composable design philosophy
• src/filters/mod.rs — Re-exports all built-in filters (path, query, body, ws, etc.); shows the breadth of provided abstractions
• src/server.rs — HTTP server builder and runtime setup; critical for understanding how filters are executed and served
• src/reject.rs — Error handling and rejection system; essential for proper error propagation and response generation
• src/reply.rs — Response building and serialization trait; shows how filters produce HTTP responses
• Cargo.toml — Dependency configuration including hyper, tokio, and optional features; defines integration surface with ecosystem

Add a new custom filter

1. Define a filter function that returns a boxed Filter implementation (src/filters/mod.rs)
2. Implement the Filter trait or compose existing filters using .and(), .or(), .map() combinators (src/filter/mod.rs)
3. Return a tuple of extracted values or reject with Rejection if preconditions fail (src/reject.rs)
4. Add tests in tests/filter.rs or a dedicated test file exercising the new filter's happy path and error cases (tests/filter.rs)

Add a new HTTP route handler

1. Compose path, method, header, and body filters using .and() in your handler setup (examples/routing.rs)
2. Chain with .map() or .and_then() to transform extracted values into your business logic (src/filter/map.rs)
3. Return a Reply (JSON, string, file, etc.) from the handler closure (src/reply.rs)
4. Combine route filters with .or() and pass to Server::run() in src/server.rs (src/server.rs)

Add request/response middleware or wrapper

1. Use .wrap() combinator to add pre/post processing around an existing filter (src/filter/wrap.rs)
2. Or implement a custom Filter that wraps another filter's output and transformation (src/filter/mod.rs)
3. For error handling, use .recover() to catch Rejections and convert to custom responses (src/filter/recover.rs)
4. Examples: logging (src/filters/log.rs), compression (src/filters/compression.rs), CORS (src/filters/cors.rs) (src/filters/mod.rs)

Add a new content-type or body parser

1. Create a new filter function in src/filters/body.rs or a dedicated module (src/filters/body.rs)
2. Extract the body using warp::body::bytes() or stream, then deserialize/parse to your type (src/bodyt.rs)
3. Return Result<T, Rejection> to enable proper error signaling (invalid format, size limits) (src/reject.rs)
4. Test with examples/body.rs and add test cases in tests/body.rs (tests/body.rs)

• hyper (HTTP client/server library) — Provides high-performance, production-grade HTTP/1 and HTTP/2 support; warp builds composable filters on top
• Tokio (async runtime) — Enables efficient async I/O and concurrent request handling; warp filters are all async by default
• futures-util and futures-channel — Provides Combinators (map, then, or) and stream abstractions for filter composition and async chaining
• serde (serialization framework) — Powers JSON and form deserialization in body and query filters; optional for flexibility
• async-compression — Provides gzip/deflate/brotli compression for responses; optional feature

• Filter trait as core abstraction instead of middleware chain or handler functions

  • Why: Enables elegant composition (combining unrelated concerns) and type-safe extraction of request data
  • Consequence: Steeper learning curve but more powerful for complex routing; requires understanding trait bounds and tuple types

• Async-first design (all filters are async Futures)

  • Why: Leverages Tokio for concurrent request handling and naturally integrates with async Rust ecosystem
  • Consequence: Cannot be used in blocking sync contexts; requires tokio runtime; not suitable for long-lived blocking I/O

• Rejection-based error handling (not panics or early returns)

  • Why: Allows filters to fail gracefully and chain error handlers; enables recovery and custom error responses
  • Consequence: Requires explicit .recover() or .or() chains; errors not automatically converted to 500s

• Reply trait for response conversion instead of fixed response type

  • Why: Enables multiple response types (JSON, HTML, streams, files) without boilerplate or match statements
  • Consequence: Type erasure and trait objects in some contexts; less explicit about available responses

• No built-in authentication or authorization filters

  • Why: Scope is HTTP routing/serving; auth is domain-specific and better left to middleware/libraries
  • Consequence: Users must compose custom filters or use external crates; requires explicit security consideration

• Authentication and authorization (users must implement or bring external crates)
• Database ORM or query builders (routing/serving only, not data access)
• Template rendering (except external integrations like handlebars example)
• Session management (must be added via custom filters or middleware)

1. Filter type signatures: Composing filters with different output types requires .unify() or .boxed() (see src/filter/boxed.rs, unify.rs) or the type checker explodes—not obvious from README. 2. Request-local state: Use scoped_tls (scoped-tls crate) rather than thread-local storage; warp handlers are task-spawned. 3. Graceful shutdown: hyper-util's graceful shutdown feature is available but requires explicit GracefulShutdown wrapping—not automatic. 4. Body streaming: bodyt.rs uses http-body 1.x trait; direct Body manipulation requires understanding the streaming abstraction.

• Filter Combinator Pattern — Filters are the fundamental abstraction in warp; understanding how and(), or(), map(), then() compose is prerequisite for using the framework at all—this is not a typical web framework API
• Type-Level Routing (path!() macro) — Warp routes are compiled to type-safe extractors via the path!() macro rather than runtime pattern matching; understanding this explains why warp handles validation at compile-time instead of runtime
• Tower Service Trait — Filters implement tower::Service trait; understanding this trait is necessary for writing middleware, authentication filters, and integrating external services
• Rejection Handling (recover combinator) — Warp's error model relies on the recover() filter to transform rejections into HTTP responses; this is how 400/401/500 errors are generated rather than panic!() or Result<T,E>
• Scoped Thread-Local State — Warp uses scoped_tls crate for request-scoped state (logging spans, user context) rather than thread-locals because spawned tasks aren't on the same OS thread; critical for tracing integration
• WebSocket Upgrade Protocol (RFC 6455) — The websockets example uses tokio-tungstenite to implement the HTTP 101 Upgrade handshake; understanding this protocol explains why WebSocket support requires special handling vs. regular routes
• Async Trait Bounds and Higher-Rank Trait Bounds (HRTB) — Warp's Filter trait uses complex async trait bounds; reading impl blocks in filter/*.rs requires understanding HRTB and async fn in traits to follow the type signatures

• tokio-rs/axum — Direct successor framework from tokio team; more macro-driven routing, different composition model but targets same problem space
• hyperium/hyper — Underlying HTTP engine that warp builds on; understanding hyper::Request/Response is essential for warp internals
• tower-rs/tower — Middleware/service abstraction that warp filters leverage via tower-service 0.3; critical for understanding filter composition
• tokio-rs/tokio — Async runtime that powers warp's async/await execution; required dependency for understanding executor behavior
• seanmonstar/http-body — Core HTTP body abstraction trait by same maintainer; bodyt.rs in warp depends on understanding this trait

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for CORS filter edge cases and security scenarios

The src/filters/cors.rs filter is exposed but there are no dedicated integration tests in the examples or test suite for CORS scenarios. Given that CORS is security-sensitive (preflight requests, origin validation, credential handling), comprehensive tests would prevent regressions and help contributors understand correct usage. This is a high-value addition that directly impacts security.

• [ ] Create a new test file or section in tests/ (or alongside examples) for CORS scenarios
• [ ] Add test cases for: preflight OPTIONS requests, multiple allowed origins, credentials with wildcard prevention, missing origin header, invalid origin rejection
• [ ] Add an example file examples/cors_advanced.rs demonstrating various CORS configurations
• [ ] Verify tests run in CI via cargo test and document findings in CHANGELOG.md

Add comprehensive error handling tests for src/error.rs and rejections

The src/error.rs module and rejection system are core to warp's error handling, but examples/rejections.rs only shows basic usage. There's a missing integration test suite covering custom rejection types, error recovery, and the recover filter (src/filter/recover.rs). This helps new contributors understand the rejection pipeline and ensures error paths are well-tested.

• [ ] Create tests/rejections_integration.rs with test cases for: custom rejection types, rejection composition, error recovery with recover(), JSON error responses
• [ ] Expand examples/rejections.rs to show advanced patterns like custom error formatting and conditional recovery
• [ ] Verify that all rejection types in src/error.rs are covered by at least one test case
• [ ] Add documentation comments to src/error.rs explaining the rejection trait and recovery patterns

Add tests and documentation for multipart form data edge cases and streaming

The src/filters/multipart.rs filter wraps the multer crate but lacks comprehensive tests for real-world scenarios: large file uploads, multiple file fields, text field ordering, and malformed boundaries. The example examples/multipart.rs is minimal. Adding integration tests and an advanced example would help contributors understand streaming safety and memory efficiency.

• [ ] Create tests/multipart_integration.rs with test cases for: multiple files, mixed text/file fields, large file handling, boundary edge cases, rejections on malformed data
• [ ] Create examples/multipart_advanced.rs demonstrating: file size limits, streaming writes to disk, field validation before processing
• [ ] Add unit tests in src/filters/multipart.rs or nearby for any custom stream-handling logic
• [ ] Document known limitations and recommendations in code comments (e.g., memory buffering, file size guidance)

• Add integration tests for compression combinations (gzip + deflate + brotli filter chains); currently examples/compression.rs exists but src/ lacks comprehensive test suite for async-compression integration
• Document the .boxed() and .unify() patterns with a new example examples/filter_unification.rs showing how to return different filter types from match statements (common source of type errors for newcomers)
• Implement missing examples: add examples/graceful_shutdown.rs and examples/cors.rs using warp filters to match common real-world patterns, with tests in tests/

• Medium · Potential Path Traversal in Static File Serving — src/filters/fs.rs, examples/dir.rs. The codebase includes static file serving functionality (src/filters/fs.rs). Without proper validation, path traversal attacks could allow attackers to access files outside intended directories via directory traversal sequences (../). Fix: Ensure all file path inputs are canonicalized and validated to prevent directory traversal. Use tokio::fs::canonicalize() and verify the resolved path is within the intended directory. Implement strict path validation before serving any static files.
• Medium · Multipart Form Data Handling - Potential DoS — src/filters/multipart.rs. The multipart form data handler (src/filters/multipart.rs) uses the 'multer' crate. Without configurable size limits, attackers could send extremely large multipart uploads causing memory exhaustion or DoS attacks. Fix: Implement and enforce strict file size limits and total body size limits for multipart uploads. Configure multer with appropriate limits for field count, file size, and total body size. Make these limits configurable per application requirements.
• Medium · WebSocket Implementation Security — src/filters/ws.rs, examples/websockets_chat.rs. WebSocket support is provided via tokio-tungstenite (src/filters/ws.rs, examples/websockets.rs). WebSocket connections may not properly validate origin headers, and the chat example could be vulnerable to message injection or improper authorization checks. Fix: Implement origin header validation for WebSocket connections. Ensure proper authentication and authorization before establishing WebSocket connections. Validate and sanitize all messages passed through WebSocket connections to prevent injection attacks.
• Low · Missing Security Headers by Default — src/filters/header.rs, src/filters/reply.rs. While warp provides header handling capabilities, there's no built-in enforcement of security headers like HSTS, X-Content-Type-Options, X-Frame-Options, or CSP by default. Developers may forget to add these. Fix: Provide middleware or built-in filters that make it easy to add common security headers. Document security best practices prominently. Consider creating a security headers filter that can be easily composed into routes.
• Low · CORS Implementation Completeness — src/filters/cors.rs. CORS filter exists (src/filters/cors.rs) but misconfiguration could allow unauthorized cross-origin requests. Developers might set overly permissive CORS policies. Fix: Document CORS security implications clearly. Implement sensible defaults (e.g., explicitly list allowed origins rather than wildcard). Provide validation helpers to warn against insecure CORS configurations. Consider adding a secure-by-default CORS configuration option.
• Low · TLS Configuration - Commented Out — Cargo.toml, src/tls.rs, examples/tls.rs. TLS support via tokio-rustls is commented out in Cargo.toml (see #tokio-rustls and #rustls-pemfile dependencies). This might indicate incomplete or deprecated TLS support. Fix: Either fully implement and enable TLS support with latest secure defaults, or clearly document that TLS should be handled by a reverse proxy. If TLS is supported, ensure it uses modern cipher suites and TLS 1.2+ only. Update documentation accordingly.
• Low · Query String Deserialization - Type Confusion Risk — src/filters/query.rs. Query string deserialization (src/filters/query.rs) uses serde_urlencoded which could lead to type confusion if not carefully implemented. Attackers might send unexpected types. Fix: Implement strict type validation for deserialized query parameters. Use custom error handling to reject unexpected types. Document the importance of validating query parameters. Consider providing validation helpers.
• Low · Logging May Expose Sensitive Data — src/filters/log.rs, src/filters/trace.rs. The logging filter (src/filters/log.rs) and access logging could potentially log sensitive request data like authentication tokens, API keys, or PII from headers and bodies. Fix: Implement filtering in the logging mechanism to redact sensitive headers (Authorization, Set-Cookie, etc.) and parameter values. Document security implications of logging. Provide

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.