Add observability, bench, presets & replay support

Introduce observability and benchmarking workflows and CLI ergonomics: add new `bench` and `observability` commands, surface observability assets, and wire a benchmark runner. Expand the `doctor` command to scan workspace signals (health, shutdown, tracing, rate-limit, body limits, etc.), emit structured checks/warnings/failures, and support a --strict mode.

Add project presets and template wiring: introduce ProjectPreset (prod-api, ai-api, realtime-api), recommended feature bundles, CLI --preset support for `cargo rustapi new`, and related tests. Enable the `replay` feature by default for the cargo CLI and export replay, streaming multipart, and RateLimitStrategy types in the public API files.

Library tweaks: expose RateLimitStrategy and extend rate-limit internals to support multiple strategies; clarify multipart usage (drop/consume previous field before next). Update docs/README examples and CLI README entries, add tests for new commands, and update .gitignore to ignore markdown files.

Author: Tuntii

.gitignore

@@ -18,3 +18,5 @@ docs/PRODUCTION_CHECKLIST.md
 /.github/instructions
 /.github/prompts
 /.github/skills
+*.md
+tasks.md

README.md

@@ -68,21 +68,32 @@ All error responses include a unique `error_id` (`err_{uuid}`) for log correlati
 Record and replay HTTP request/response pairs for production debugging:
 
 ```rust
+use rustapi_rs::extras::replay::{ReplayConfig, ReplayLayer};
+use rustapi_rs::prelude::*;
+
 RustApi::new()
-    .layer(ReplayLayer::new(store, config))
-    .run("0.0.0.0:8080").await;
+  .layer(
+    ReplayLayer::new(
+      ReplayConfig::new()
+        .enabled(true)
+        .admin_token("local-replay-token"),
+    ),
+  )
+  .run("0.0.0.0:8080")
+  .await?;
 ```
 
 ```sh
-cargo rustapi replay list
-cargo rustapi replay run <id> --target http://localhost:8080
-cargo rustapi replay diff <id> --target http://staging
+cargo rustapi replay list -t local-replay-token
+cargo rustapi replay run <id> -t local-replay-token --target http://localhost:8080
+cargo rustapi replay diff <id> -t local-replay-token --target http://staging
 ```
 
 - Middleware-based recording; no application code changes
 - Sensitive header redaction; disabled by default
 - In-memory (dev) or filesystem (production) storage with TTL
 - `ReplayClient` for programmatic test automation
+- Full incident workflow: [`docs/cookbook/src/recipes/replay.md`](docs/cookbook/src/recipes/replay.md)
 
 ### Dual-Stack HTTP/1.1 + HTTP/3
 

api/public/rustapi-rs.all-features.txt

@@ -42,6 +42,8 @@ pub use rustapi_rs::MethodRouter
 pub use rustapi_rs::Multipart
 pub use rustapi_rs::MultipartConfig
 pub use rustapi_rs::MultipartField
+pub use rustapi_rs::StreamingMultipart
+pub use rustapi_rs::StreamingMultipartField
 pub use rustapi_rs::NoContent
 pub use rustapi_rs::OAuth2Client
 pub use rustapi_rs::OAuth2Config
@@ -56,6 +58,7 @@ pub use rustapi_rs::Path
 pub use rustapi_rs::Provider
 pub use rustapi_rs::Query
 pub use rustapi_rs::RateLimitLayer
+pub use rustapi_rs::RateLimitStrategy
 pub use rustapi_rs::Redirect
 pub use rustapi_rs::RedisSessionStore
 pub use rustapi_rs::Request
@@ -171,6 +174,8 @@ pub use rustapi_rs::core::MethodRouter
 pub use rustapi_rs::core::Multipart
 pub use rustapi_rs::core::MultipartConfig
 pub use rustapi_rs::core::MultipartField
+pub use rustapi_rs::core::StreamingMultipart
+pub use rustapi_rs::core::StreamingMultipartField
 pub use rustapi_rs::core::NoContent
 pub use rustapi_rs::core::Path
 pub use rustapi_rs::core::Query
@@ -268,8 +273,27 @@ pub use rustapi_rs::extras::oauth2::TokenResponse
 pub use rustapi_rs::extras::oauth2::oauth2
 pub mod rustapi_rs::extras::rate_limit
 pub use rustapi_rs::extras::rate_limit::RateLimitLayer
+pub use rustapi_rs::extras::rate_limit::RateLimitStrategy
 pub use rustapi_rs::extras::rate_limit::rate_limit
 pub mod rustapi_rs::extras::replay
+pub use rustapi_rs::extras::replay::FsReplayStore
+pub use rustapi_rs::extras::replay::FsReplayStoreConfig
+pub use rustapi_rs::extras::replay::InMemoryReplayStore
+pub use rustapi_rs::extras::replay::RecordedRequest
+pub use rustapi_rs::extras::replay::RecordedResponse
+pub use rustapi_rs::extras::replay::ReplayAdminAuth
+pub use rustapi_rs::extras::replay::ReplayClient
+pub use rustapi_rs::extras::replay::ReplayClientError
+pub use rustapi_rs::extras::replay::ReplayConfig
+pub use rustapi_rs::extras::replay::ReplayEntry
+pub use rustapi_rs::extras::replay::ReplayId
+pub use rustapi_rs::extras::replay::ReplayLayer
+pub use rustapi_rs::extras::replay::ReplayMeta
+pub use rustapi_rs::extras::replay::ReplayQuery
+pub use rustapi_rs::extras::replay::ReplayStore
+pub use rustapi_rs::extras::replay::ReplayStoreError
+pub use rustapi_rs::extras::replay::ReplayStoreResult
+pub use rustapi_rs::extras::replay::RetentionJob
 pub use rustapi_rs::extras::replay::replay
 pub mod rustapi_rs::extras::retry
 pub use rustapi_rs::extras::retry::retry
@@ -354,6 +378,8 @@ pub use rustapi_rs::prelude::Message
 pub use rustapi_rs::prelude::Multipart
 pub use rustapi_rs::prelude::MultipartConfig
 pub use rustapi_rs::prelude::MultipartField
+pub use rustapi_rs::prelude::StreamingMultipart
+pub use rustapi_rs::prelude::StreamingMultipartField
 pub use rustapi_rs::prelude::Negotiate
 pub use rustapi_rs::prelude::NoContent
 pub use rustapi_rs::prelude::OAuth2Client
@@ -364,6 +390,7 @@ pub use rustapi_rs::prelude::PkceVerifier
 pub use rustapi_rs::prelude::Provider
 pub use rustapi_rs::prelude::Query
 pub use rustapi_rs::prelude::RateLimitLayer
+pub use rustapi_rs::prelude::RateLimitStrategy
 pub use rustapi_rs::prelude::Redirect
 pub use rustapi_rs::prelude::RedisSessionStore
 pub use rustapi_rs::prelude::Request

api/public/rustapi-rs.default.txt

@@ -25,6 +25,8 @@ pub use rustapi_rs::MethodRouter
 pub use rustapi_rs::Multipart
 pub use rustapi_rs::MultipartConfig
 pub use rustapi_rs::MultipartField
+pub use rustapi_rs::StreamingMultipart
+pub use rustapi_rs::StreamingMultipartField
 pub use rustapi_rs::NoContent
 pub use rustapi_rs::Path
 pub use rustapi_rs::Query
@@ -97,6 +99,8 @@ pub use rustapi_rs::core::MethodRouter
 pub use rustapi_rs::core::Multipart
 pub use rustapi_rs::core::MultipartConfig
 pub use rustapi_rs::core::MultipartField
+pub use rustapi_rs::core::StreamingMultipart
+pub use rustapi_rs::core::StreamingMultipartField
 pub use rustapi_rs::core::NoContent
 pub use rustapi_rs::core::Path
 pub use rustapi_rs::core::Query
@@ -165,6 +169,8 @@ pub use rustapi_rs::prelude::KeepAlive
 pub use rustapi_rs::prelude::Multipart
 pub use rustapi_rs::prelude::MultipartConfig
 pub use rustapi_rs::prelude::MultipartField
+pub use rustapi_rs::prelude::StreamingMultipart
+pub use rustapi_rs::prelude::StreamingMultipartField
 pub use rustapi_rs::prelude::NoContent
 pub use rustapi_rs::prelude::Path
 pub use rustapi_rs::prelude::Query

crates/cargo-rustapi/Cargo.toml

@@ -53,6 +53,6 @@ assert_cmd = "2.0"
 predicates = "3.1"
 
 [features]
-default = ["remote-spec"]
+default = ["remote-spec", "replay"]
 remote-spec = ["dep:reqwest"]
 replay = ["dep:reqwest"]

crates/cargo-rustapi/README.md

@@ -18,10 +18,15 @@ cargo install cargo-rustapi
 | `cargo rustapi new <name>` | Create a new project with the perfect directory structure |
 | `cargo rustapi run` | Run the development server |
 | `cargo rustapi run --reload` | Run with hot-reload (auto-rebuild on file changes) |
+| `cargo rustapi bench` | Run the repository benchmark workflow via `scripts/bench.ps1` |
+| `cargo rustapi doctor [--strict]` | Validate toolchain availability and check project signals against the production checklist |
+| `cargo rustapi observability [--check]` | Surface observability docs, benchmark assets, and recommended baseline features |
+| `cargo rustapi new <name> --preset <preset>` | Start from opinionated `prod-api`, `ai-api`, or `realtime-api` feature bundles |
 | `cargo rustapi generate resource <name>` | Scaffold a new API resource (Model + Handlers + Tests) |
 | `cargo rustapi client --spec <path> --language <lang>` | Generate a client library (Rust, TS, Python) from OpenAPI spec |
 | `cargo rustapi deploy <platform>` | Generate deployment configs for Docker, Fly.io, Railway, or Shuttle |
 | `cargo rustapi migrate <action>` | Database migration commands (create, run, revert, status, reset) |
+| `cargo rustapi replay <subcommand>` | Work with time-travel replay entries from a running RustAPI service |
 
 ## 🚀 Quick Start
 
@@ -46,3 +51,8 @@ The templates used by the CLI are opinionated but flexible. They enforce:
 - `api`: REST API structure with separated `handlers` and `models`
 - `web`: Web application with HTML templates (`rustapi-view`)
 - `full`: Complete example with Database, Auth, and Docker support
+
+**Available Presets:**
+- `prod-api`: production-facing API defaults (`extras-config`, `extras-cors`, `extras-rate-limit`, `extras-security-headers`, `extras-structured-logging`, `extras-timeout`)
+- `ai-api`: AI-oriented API defaults with `protocol-toon`
+- `realtime-api`: realtime-oriented API defaults with `protocol-ws`

crates/cargo-rustapi/src/cli.rs

@@ -1,9 +1,11 @@
 //! CLI argument parsing
 
 use crate::commands::{
-    self, AddArgs, ClientArgs, DeployArgs, DoctorArgs, GenerateArgs, MigrateArgs, NewArgs, RunArgs,
-    WatchArgs,
+    self, AddArgs, BenchArgs, ClientArgs, DeployArgs, DoctorArgs, GenerateArgs, MigrateArgs,
+    NewArgs, ObservabilityArgs, RunArgs, WatchArgs,
 };
+#[cfg(feature = "replay")]
+use crate::commands::ReplayArgs;
 use clap::{Parser, Subcommand};
 
 /// The official CLI tool for the RustAPI framework. Scaffold new projects, run development servers, and manage database migrations.
@@ -33,9 +35,15 @@ enum Commands {
     /// Add a feature or dependency
     Add(AddArgs),
 
+    /// Run the benchmark workflow
+    Bench(BenchArgs),
+
     /// Check environment health
     Doctor(DoctorArgs),
 
+    /// Surface observability docs and baseline workflow assets
+    Observability(ObservabilityArgs),
+
     /// Generate code from templates
     #[command(subcommand)]
     Generate(GenerateArgs),
@@ -59,9 +67,8 @@ enum Commands {
     Deploy(DeployArgs),
 
     /// Replay debugging commands (time-travel debugging)
-    #[cfg(feature = "replay")]
     #[command(subcommand)]
-    Replay(commands::ReplayArgs),
+    Replay(ReplayArgs),
 }
 
 impl Cli {
@@ -72,13 +79,14 @@ impl Cli {
             Commands::Run(args) => commands::run_dev(args).await,
             Commands::Watch(args) => commands::watch(args).await,
             Commands::Add(args) => commands::add(args).await,
+            Commands::Bench(args) => commands::bench(args).await,
             Commands::Doctor(args) => commands::doctor(args).await,
+            Commands::Observability(args) => commands::observability(args).await,
             Commands::Generate(args) => commands::generate(args).await,
             Commands::Migrate(args) => commands::migrate(args).await,
             Commands::Docs { port } => commands::open_docs(port).await,
             Commands::Client(args) => commands::client(args).await,
             Commands::Deploy(args) => commands::deploy(args).await,
-            #[cfg(feature = "replay")]
             Commands::Replay(args) => commands::replay(args).await,
         }
     }

crates/cargo-rustapi/src/commands/bench.rs

@@ -0,0 +1,94 @@
+//! Benchmark workflow command.
+
+use anyhow::{bail, Context, Result};
+use clap::Args;
+use console::style;
+use std::path::{Path, PathBuf};
+use tokio::process::Command;
+
+/// Run the repository benchmark workflow.
+#[derive(Args, Debug, Clone)]
+pub struct BenchArgs {
+    /// Project or workspace path to inspect.
+    #[arg(long, default_value = ".", value_name = "PATH")]
+    pub path: PathBuf,
+    /// Override performance snapshot warmup iterations.
+    #[arg(long)]
+    pub warmup: Option<u32>,
+    /// Override performance snapshot measured iterations.
+    #[arg(long)]
+    pub iterations: Option<u32>,
+}
+
+pub async fn bench(args: BenchArgs) -> Result<()> {
+    let inspect_path = resolve_path(&args.path)?;
+    let workspace_root = find_workspace_root(&inspect_path)
+        .with_context(|| format!("No Cargo.toml found above {}", inspect_path.display()))?;
+    let script_path = workspace_root.join("scripts").join("bench.ps1");
+
+    if !script_path.exists() {
+        bail!(
+            "Benchmark script was not found at {}",
+            script_path.display()
+        );
+    }
+
+    let shell = if cfg!(windows) { "powershell" } else { "pwsh" };
+
+    println!(
+        "{} {}",
+        style("Running benchmark workflow from").bold(),
+        style(script_path.display()).cyan()
+    );
+
+    let mut command = Command::new(shell);
+    if cfg!(windows) {
+        command.args(["-ExecutionPolicy", "Bypass", "-File"]);
+    } else {
+        command.arg("-File");
+    }
+    command.arg(&script_path).current_dir(&workspace_root);
+
+    if let Some(warmup) = args.warmup {
+        command.env("RUSTAPI_PERF_WARMUP", warmup.to_string());
+    }
+    if let Some(iterations) = args.iterations {
+        command.env("RUSTAPI_PERF_ITERS", iterations.to_string());
+    }
+
+    let status = command.status().await.context("Failed to launch benchmark workflow")?;
+    if !status.success() {
+        bail!("Benchmark workflow exited with status {}", status);
+    }
+
+    println!("{}", style("Benchmark workflow finished.").green());
+    Ok(())
+}
+
+fn resolve_path(path: &Path) -> Result<PathBuf> {
+    if path.is_absolute() {
+        Ok(path.to_path_buf())
+    } else {
+        Ok(std::env::current_dir()
+            .context("failed to determine current directory")?
+            .join(path))
+    }
+}
+
+fn find_workspace_root(start: &Path) -> Option<PathBuf> {
+    let mut current = if start.is_dir() {
+        start.to_path_buf()
+    } else {
+        start.parent()?.to_path_buf()
+    };
+
+    loop {
+        if current.join("Cargo.toml").exists() {
+            return Some(current);
+        }
+
+        if !current.pop() {
+            return None;
+        }
+    }
+}