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/rwf2/Rocket 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.

WAIT — Slowing — last commit 4mo ago

• Last commit 4mo ago
• 26+ active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 4mo ago
• ⚠ Concentrated ownership — top contributor handles 65% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{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 rwf2/Rocket repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/rwf2/Rocket.

What it runs against: a local clone of rwf2/Rocket — 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 rwf2/Rocket | Confirms the artifact applies here, not a fork | | 2 | License is still Other | 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 ≤ 160 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of rwf2/Rocket. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/rwf2/Rocket.git
#   cd Rocket
#
# 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 rwf2/Rocket and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other 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 "core/lib/Cargo.toml" \\
  && ok "core/lib/Cargo.toml" \\
  || miss "missing critical file: core/lib/Cargo.toml"
test -f "core/lib/src/lib.rs" \\
  && ok "core/lib/src/lib.rs" \\
  || miss "missing critical file: core/lib/src/lib.rs"
test -f "core/codegen/src/lib.rs" \\
  && ok "core/codegen/src/lib.rs" \\
  || miss "missing critical file: core/codegen/src/lib.rs"
test -f "core/http/src/lib.rs" \\
  && ok "core/http/src/lib.rs" \\
  || miss "missing critical file: core/http/src/lib.rs"
test -f "contrib/db_pools/lib/src/lib.rs" \\
  && ok "contrib/db_pools/lib/src/lib.rs" \\
  || miss "missing critical file: contrib/db_pools/lib/src/lib.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 160 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~130d)"
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/rwf2/Rocket"
  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).

Rocket is an async web framework for Rust that provides type-safe routing, request guards, and response handling with compile-time validation. It solves the problem of building fast, secure HTTP APIs in Rust by offering ergonomic macros like #[get()] and #[post()] that automatically parse route parameters, validate types, and reject invalid requests before handler code runs—eliminating entire classes of runtime errors. Monorepo with workspace members: core/lib/ contains the async runtime and router, core/codegen/ holds procedural macros for route decorators, core/http/ wraps HTTP primitives, contrib/ adds optional integrations (db_pools with connection pooling, ws for WebSockets, dyn_templates for template engines). benchmarks/ includes routing performance tests against real-world route files like bitwarden_rs.routes.

Rust developers building REST APIs, web services, and microservices who want compile-time safety, fast async execution, and minimal boilerplate. Contributors are typically Rust systems programmers familiar with async/await patterns and procedural macros who care about API ergonomics.

Production-ready and actively maintained. The project has significant GitHub activity (2.4M+ lines of Rust code), comprehensive CI/CD via GitHub Actions (.github/workflows/ci.yml), dual licensing (Apache 2.0 + MIT), and examples in the examples/ directory. Documented versioning strategy with per-version docs at rocket.rs/v${x} indicates stable release cycles.

Low-to-moderate risk. Single primary maintainer (rwf2) could impact velocity, but the framework is used in production by numerous projects. The monorepo structure across core/, contrib/, and benchmarks/ spreads maintenance surface. No obvious deprecated dependencies visible, though the workspace includes nightly Rust feature gates (cfg(nightly)) which may require tracking compiler changes.

The repository is actively developed with CI workflows validating commits. The presence of both ui-fail-nightly and ui-fail-stable test suites in contrib/db_pools/codegen/tests/ suggests ongoing work on macro error messages and compiler compatibility. Documentation is continuously deployed (indicated by per-branch API docs at api.rocket.rs/${branch}).

git clone https://github.com/rwf2/Rocket.git
cd Rocket
cargo build
cd examples/hello
cargo run

Then visit http://localhost:8000/. Requires Rust toolchain (1.56+) and Cargo.

Daily commands: For the core framework: cargo build from workspace root. For examples: cd examples/{name} && cargo run. To run benchmarks: cd benchmarks && cargo run --release. Tests: cargo test --workspace. Docs: cargo doc --open (opens generated rustdocs).

• core/lib/Cargo.toml — Root workspace manifest defining all core and contrib members; essential for understanding the overall project structure and dependencies.
• core/lib/src/lib.rs — Main entry point for the Rocket framework library; orchestrates macros, routing, and request/response handling.
• core/codegen/src/lib.rs — Procedural macro implementation for route attributes (#[get], #[post]) and #[launch]; critical for framework's declarative API.
• core/http/src/lib.rs — HTTP abstraction layer handling requests, responses, and status codes; foundational for all web interactions.
• contrib/db_pools/lib/src/lib.rs — Database connection pooling abstraction; demonstrates how contrib modules extend core with async db support.
• contrib/dyn_templates/src/lib.rs — Template engine integration (Tera, Handlebars, MiniJinja); shows contrib pattern for adding rendering features.
• CONTRIBUTING.md — Development guidelines, testing procedures, and contribution workflow for all contributors.

Add a New Route Handler

1. Define a function and apply a route macro (#[get], #[post], etc.) with a path pattern (core/codegen/src/lib.rs)
2. Use type extractors (path params, query, guards) as function arguments; they are validated at compile-time and request-time (core/http/src/lib.rs)
3. Return a Responder (String, JSON, custom struct); Rocket serializes it automatically (core/lib/src/lib.rs)
4. Register the route in the #[launch] function using routes![handler_name] (README.md)

Integrate a Database

1. Add db_pools or sync_db_pools to Cargo.toml and enable the appropriate database feature (contrib/db_pools/lib/Cargo.toml)
2. Declare a database in Rocket.toml with pool size and URL (contrib/db_pools/lib/src/config.rs)
3. Use the #[database(...)] macro on a database guard struct to auto-generate connection acquisition (contrib/db_pools/codegen/src/database.rs)
4. Inject the guard into route handlers; it implements FromRequest for automatic connection pooling (contrib/db_pools/lib/src/pool.rs)

Add Template Rendering

1. Add dyn_templates to Cargo.toml and enable a template engine feature (tera, handlebars, minijinja) (contrib/dyn_templates/Cargo.toml)
2. Place template files in templates/ directory with appropriate extensions (.html.tera, .html.hbs, etc.) (contrib/dyn_templates/tests/templates)
3. Attach the Template fairing in #[launch] to enable template discovery and hot-reload (contrib/dyn_templates/src/fairing.rs)
4. Return Template::render(name, context) from a route handler; context is a struct implementing Serialize (contrib/dyn_templates/src/template.rs)

Create a Custom Responder or Guard

1. Implement the Responder trait for custom response serialization, or FromRequest for request extraction (core/lib/src/lib.rs)
2. Responders must convert to a Response; FromRequest must return an outcome (Success, Failure, or Forward) (core/http/src/lib.rs)
3. Use generics and lifetimes to support Rocket's async and type-safe patterns (core/codegen/src/lib.rs)
4. Add tests in contrib module tests/ to validate your implementation with #[rocket::async_test] (contrib/db_pools/lib/tests/databases.rs)

• Tokio (async runtime) — Enables non-blocking concurrent request handling with minimal overhead; essential for modern web scalability.
• Procedural macros (syn, quote) — Provides compile-time route and handler validation, reducing runtime errors and enabling static type checking for web handlers.
• Serde (serialization) — Universal JSON/form data serialization; allows handlers to accept and return strongly-typed Rust structs with minimal boilerplate.
• r2d2 / sqlx (connection pooling) — Manages database connections efficiently; reduces connection overhead and enforces safe concurrent access patterns.
• Template engines (Tera, Handlebars, MiniJinja) — Separates view logic from handlers; supports dynamic templating with hot-reload for faster development cycles.

• Compile-time route macros vs. runtime route registration

  • Why: Catch routing errors early and enable static analysis; trade-off is inflexibility in dynamic route generation.
  • Consequence: Routes must be known at compile time; cannot register routes from config files or plugins at runtime.

• Type-safe request extractors (guards) vs. untyped middleware

  • Why: Prevent invalid requests from reaching handlers; each guard type-checks its input before injection.
  • Consequence: Slightly more verbose handler signatures, but eliminates null-checks and type coercions in handler bodies.

• Async-first with no blocking I/O support in core

  • Why: Avoids thread starvation and enables high concurrency with a single async runtime.
  • Consequence: Blocking operations require explicit blocking context (tokio::task::block_in_place); discourages synchronous libraries.

• Contrib modules for database and templating (not in core)

  • Why: Keeps core lightweight and avoids forcing dependency choices on users.
  • Consequence: Database integration is opt-in; users must explicitly add and configure contrib libraries.

• Does not provide built-in authentication or authorization; delegates to contrib libraries or user-defined guards.
• Does not handle WebSocket connections in core (contrib/ws exists but separate); primary focus is HTTP.
• Does not support synchronous request handlers in async runtime; all handlers must be async-compatible.
• Does not include an ORM; users must choose Diesel, SQLx, or others via contrib modules.
• Does not provide a built-in admin panel or scaffolding tools; minimal magic approach.

Macro expansion timing: Route validation happens at compile-time via codegen; typos in route paths or type mismatches won't show until cargo build. Async trait trait objects: The workspace allows async_fn_in_trait to work around Rust limitation; guards using impl Trait may not be object-safe. Nightly gating: Tests conditionally compile for nightly Rust (cfg(nightly) in lints)—contrib features may require specific compiler versions. Database pool generics: The #[database] macro requires explicit type parameters in struct definitions; missing types cause cryptic macro errors (see ui-fail-*/ test cases). Feature flag interactions: contrib/db_pools/codegen/ is a separate crate from contrib/db_pools/lib/ to avoid circular dependencies during macro expansion.

• Type-driven request routing — Rocket's killer feature—route handler parameter types (u8, String, custom structs) automatically gate execution; understanding this paradigm is essential to writing safe Rocket handlers
• Request Guards — Middleware pattern in Rocket: types implementing FromRequest trait intercept and validate requests before handlers run, used for auth, rate-limiting, and dependency injection
• Procedural macros for DSL generation — Core/codegen uses syn/quote to generate boilerplate at compile-time; understanding macro expansion is crucial for modifying route decorators or adding new contrib features
• Async trait desugaring — Rocket allows async fn in traits (via async_fn_in_trait lint allowance) which requires specific compiler support; impacts how handlers and guards are written
• Connection pooling for databases — contrib/db_pools provides pooled database connections injected via request guards; understanding pool lifecycle and thread-safety is critical for stateful applications
• Compile-time route validation — Route conflicts, malformed paths, and type mismatches are caught at compile-time, not runtime—fundamentally different from Python/Node.js frameworks and reduces production bugs

• actix/actix-web — Direct competitor: async Rust web framework with actor model, similar routing and middleware system but different concurrency model
• tokio-rs/axum — Lighter-weight alternative: minimalist async web framework built on Tokio, contrasts with Rocket's opinionated ergonomics and type-driven approach
• hyperium/hyper — Lower-level dependency: Rocket builds on Hyper for HTTP primitives; understanding Hyper's types helps debug protocol-level issues
• rwf2/rocket_ws — Companion crate: WebSocket support for Rocket, maintained by same author; shows how to extend Rocket with contrib libraries
• diesel-rs/diesel — Ecosystem complement: popular ORM for Rust; many Rocket apps use Diesel in handlers alongside Rocket's db_pools contrib

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 comprehensive UI tests for database pool codegen macro error cases

The contrib/db_pools/codegen/tests directory has UI test infrastructure with separate nightly and stable test suites, but coverage appears incomplete. There are only 2 test cases (database-syntax.rs and database-types.rs) in ui-fail directories. A contributor could expand these with additional edge cases like missing generics, invalid trait bounds, conflicting database names, and malformed config structures to improve macro robustness and provide clearer error messages to users.

• [ ] Review existing tests in contrib/db_pools/codegen/tests/ui-fail/ and contrib/db_pools/codegen/tests/ui-fail-stable/
• [ ] Identify missing error scenarios by analyzing contrib/db_pools/codegen/src/database.rs macro implementation
• [ ] Add 5-8 new .rs test files for uncovered error cases (e.g., missing #[database] attribute, invalid pool config)
• [ ] Generate corresponding .stderr files with expected compiler error messages
• [ ] Run contrib/db_pools/codegen/tests/ui-fail.rs to verify new tests pass

Add integration tests for dyn_templates engine auto-detection and fallback behavior

contrib/dyn_templates/src/engine/ contains multiple template engines (handlebars.rs, tera.rs, minijinja.rs) but the tests directory appears sparse. A contributor should add integration tests that verify: (1) correct engine selection based on file extension, (2) template reloading in development mode, (3) graceful fallback when an engine dependency is missing, and (4) performance characteristics across engines. This would improve reliability for users selecting template engines.

• [ ] Review contrib/dyn_templates/src/engine/mod.rs to understand engine selection logic
• [ ] Create contrib/dyn_templates/tests/engine_selection.rs with tests for each template engine
• [ ] Add test cases for missing engine dependencies (feature-gated tests)
• [ ] Add tests for concurrent template rendering across different engine types
• [ ] Document template testing patterns in contrib/dyn_templates/README.md

Add CI workflow for database pool integration tests with real database services

The .github/workflows/ci.yml runs standard Rust tests, but contrib/db_pools/lib/tests/databases.rs likely requires actual database services (Postgres, MySQL, SQLite, Redis, etc.). Currently, there's no dedicated workflow for running these integration tests. A contributor should create a new GitHub Actions workflow that spins up database containers (using Docker Compose or services) and runs database-specific tests, ensuring the database pool abstractions work correctly against real systems.

• [ ] Examine contrib/db_pools/lib/tests/databases.rs to identify required database services and feature flags
• [ ] Create .github/workflows/db-integration-tests.yml with matrix strategy for different databases
• [ ] Configure services block for PostgreSQL, MySQL, Redis, and other database backends
• [ ] Add conditional feature flags (e.g., postgres, mysql, sqlite) to test command
• [ ] Document setup in CONTRIBUTING.md with instructions for local database testing

• Add missing documentation examples to core/http/src/ for less-common HTTP primitives like Cookies, ContentType, and Accept header parsing. Currently the rustdocs exist but have no runnable examples.: Improves usability for new contributors learning Rocket's HTTP layer; existing files are well-structured, just need doc comment examples
• Expand benchmarks/static/ with route files from additional real-world Rust projects (e.g., reqwest, sqlx, or tokio) to broaden routing benchmark coverage beyond bitwarden_rs.routes and rust-lang.routes.: Performance regression testing is critical for a web framework; new route files help ensure routing scales across diverse real-world apps without adding significant complexity
• Add UI tests for error cases in contrib/db_pools/codegen/tests/ where users forget the #[derive(...)] attribute on connection types or use conflicting pool names. Create corresponding .stderr files documenting the expected error message.: Improves error message clarity for end users; the test infrastructure is already in place (ui-fail-nightly, ui-fail-stable), just needs more scenarios

Rocket demonstrates a generally secure architecture as a web framework with attention to Rust idioms and async safety. However, several medium-severity concerns exist around XSS protection in templating engines and SQL injection prevention in database abstractions. These risks are partially mitigated by Rocket's type-safe design but rely on proper developer usage. The project would benefit from an explicit security policy, stricter linting of public APIs, and clearer security documentation for contrib modules. No hardcoded credentials, obvious injection patterns, or Docker misconfigurations were detected in the static analysis.

• Medium · Multiple Templating Engines Without Built-in XSS Protection Guarantee — contrib/dyn_templates/src/engine/. The dyn_templates contrib module supports multiple templating engines (Handlebars, Tera, Minijinja) without explicit evidence of enforced auto-escaping or XSS protection mechanisms. User-controlled input rendered in templates could lead to XSS vulnerabilities if auto-escaping is not properly configured by default. Fix: Ensure all templating engines are configured with auto-escaping enabled by default. Document XSS protection requirements prominently. Consider enforcing safe defaults at the framework level rather than relying on application developers to enable escaping.
• Medium · Database Abstraction Layer SQL Injection Risk — contrib/db_pools/lib/src/. The db_pools contrib module provides database connection pooling for multiple database drivers (Diesel, etc.). Without visible parameterized query enforcement or ORM abstraction validation in the static analysis, raw SQL queries could be vulnerable to SQL injection if developers bypass the ORM. Fix: Enforce parameterized queries or prepared statements at the framework level. Provide clear documentation and examples discouraging raw SQL. Consider implementing compile-time checks or runtime query validation where feasible.
• Low · Missing Security-Related Linter Warnings — Cargo.toml - workspace.lints.rust section. The workspace linter configuration has several security-relevant lints commented out: unreachable_pub, single_use_lifetimes, and missing_docs. These could help identify unintended API exposure and incomplete security documentation. Fix: Uncomment and enable unreachable_pub and missing_docs lints. Review the codebase for any unintended public API exposure and ensure critical security-sensitive functions have comprehensive documentation.
• Low · No Visible Security Policy or Vulnerability Disclosure Process — .github/. While a CODE_OF_CONDUCT exists, there is no visible SECURITY.md or security policy file in the repository structure for responsible vulnerability disclosure. Fix: Create a SECURITY.md file documenting how security vulnerabilities should be reported, expected response times, and the security release process. This is critical for a web framework used in production systems.
• Low · Workspace Configuration Allows Unchecked CFGs — Cargo.toml - workspace.lints.rust section. The workspace.lints configuration only checks for the 'nightly' cfg, but other potentially unsafe or mistyped cfgs could slip through undetected. Fix: Expand the check-cfg list to include other custom cfgs used in the project. Consider using check-cfg = ['cfg(any(...))', ...] for comprehensive coverage.

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.