Production baseline

[Tuntii]

Description

This pull request introduces several important improvements to RustAPI's documentation, environment setup, and feature exports. Notably, it clarifies performance benchmarking methodology, adds standard health probe endpoints, and expands public exports for session management, OAuth2, jobs, and replay features. These changes make the framework easier to use in production and clarify how performance claims are maintained.

Documentation and Benchmarking Updates:

• Clarified that current benchmark methodology and canonical performance claims are maintained in docs/PERFORMANCE_BENCHMARKS.md, with historical numbers preserved as snapshots in release notes and referenced from README.md, CHANGELOG.md, and RELEASES.md. [1] [2] [3] [4]
• Updated feature comparison tables and documentation to reference benchmark methodology instead of static numbers. [1] [2]

Production and Health Probe Features:

• Added documentation and code examples for enabling standard health probe endpoints (/health, /ready, /live) via .health_endpoints() and HealthCheckBuilder, as well as a single-call production baseline preset with production_defaults(). [1] [2]
• Linked new guides for recommended production baseline and checklist.

Replay and Incident Workflow Enhancements:

• Improved documentation for request/response replay, including admin token usage, CLI changes, and linking to a full incident workflow recipe.

Environment Setup:

• Added a .env file with placeholder environment variables for local development and documentation examples.

Public API Expansion:

• Expanded public exports in api/public/rustapi-rs.all-features.txt and api/public/rustapi-rs.default.txt to include session management, OAuth2, jobs, replay, and streaming multipart features, making them available via prelude and extras modules. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16]

CI Workflow Improvements:

• Updated the benchmark CI workflow to run a performance snapshot example and upload results alongside standard benchmarks.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• Test addition or update
• CI/CD changes
• Other (please describe):

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules
• If api/public/* snapshots changed, this PR has breaking or feature label

[Copilot]

Pull request overview

This PR establishes a more production-oriented baseline for RustAPI by adding built-in health probes and a one-call production_defaults() preset, expanding rustapi-rs facade exports (sessions/OAuth2/jobs/replay/streaming multipart), and updating documentation + CLI workflows around benchmarking, observability, and replay.

Changes:

• Added built-in health endpoints (/health, /ready, /live) and a production_defaults() preset + tests.
• Expanded facade exports and added new examples/recipes for sessions, OAuth2, jobs, replay workflow, streaming APIs, and migrations.
• Introduced new cargo-rustapi commands (bench, observability) and updated benchmark CI to upload a perf snapshot output.

Reviewed changes

Copilot reviewed 60 out of 63 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
tasks.md	Task tracking placeholder (present in PR metadata).
docs/cookbook/src/reference/macro_attributes.md	New macro attribute reference page.
docs/cookbook/src/reference/README.md	Adds reference section intro + link to macro attribute reference.
docs/cookbook/src/recipes/session_auth.md	New session-auth recipe using facade exports.
docs/cookbook/src/recipes/replay.md	Updates replay docs into a workflow guide (now mixed-language).
docs/cookbook/src/recipes/oidc_oauth2_production.md	New production OAuth/OIDC guidance page.
docs/cookbook/src/recipes/observability.md	New observability baseline recipe referencing production defaults + layers.
docs/cookbook/src/recipes/oauth2_client.md	Updates OAuth2 client recipe to use facade exports + sessions.
docs/cookbook/src/recipes/middleware_debugging.md	New middleware debugging guide (layer order, checklist).
docs/cookbook/src/recipes/graceful_shutdown.md	Expands shutdown guidance, adds drain/readiness example.
docs/cookbook/src/recipes/error_handling.md	New error-handling recipe documenting ApiError patterns and wire format.
docs/cookbook/src/recipes/deployment.md	Adds probe recommendations + Kubernetes snippet + minimal production bootstrap.
docs/cookbook/src/recipes/db_integration.md	Expands DB guidance (SQLx vs Diesel vs SeaORM, pooling, migrations).
docs/cookbook/src/recipes/custom_extractors.md	New custom extractor patterns for parts vs body consumption.
docs/cookbook/src/recipes/axum_migration.md	New Axum→RustAPI migration guide.
docs/cookbook/src/recipes/actix_migration.md	New Actix-web→RustAPI migration guide.
docs/cookbook/src/recipes/README.md	Adds new recipe links (sessions/oauth/replay/observability/migrations/etc.).
docs/cookbook/src/learning/curriculum.md	Updates curriculum link to new error-handling recipe.
docs/cookbook/src/concepts/performance.md	Replaces static perf numbers with policy + benchmark doc pointers.
docs/cookbook/src/SUMMARY.md	Adds new reference/recipe pages to mdbook summary.
docs/README.md	Adds quick links to benchmark policy + production baseline/checklist + replay recipe.
docs/PERFORMANCE_BENCHMARKS.md	Adds benchmark policy + a “latest validated snapshot” section.
docs/GETTING_STARTED.md	Documents new health endpoints + production_defaults() usage.
crates/rustapi-rs/src/lib.rs	Expands core/prelude/extras re-exports (health, sessions, oauth2, jobs, replay, streaming multipart, sse_from_iter, etc.).
crates/rustapi-rs/examples/streaming_api.rs	New SSE streaming example using sse_from_iter.
crates/rustapi-rs/examples/jobs_api.rs	New jobs example gated on jobs feature.
crates/rustapi-rs/examples/full_crud_api.rs	New full CRUD example.
crates/rustapi-rs/examples/auth_api.rs	New session-auth example gated on session feature.
crates/rustapi-rs/examples/README.md	New examples index for facade crate.
crates/rustapi-rs/Cargo.toml	Adds rustapi-jobs + futures-util deps; introduces extras session/oauth/jobs features.
crates/rustapi-extras/src/rate_limit/mod.rs	Adds new rate limit strategies (fixed/sliding/token-bucket) + tests and exports.
crates/rustapi-extras/src/oauth2/tokens.rs	Adds PkceVerifier::new(...) to rebuild from stored verifier; adjusts generate.
crates/rustapi-extras/src/lib.rs	Re-exports session module/types + rate limit strategy.
crates/rustapi-extras/Cargo.toml	Adds redis dependency + session/session-redis features; updates full feature set.
crates/rustapi-core/tests/production_defaults.rs	New integration tests for production defaults preset + probe wiring.
crates/rustapi-core/tests/health_endpoints.rs	New integration tests for health endpoints and status codes.
crates/rustapi-core/src/multipart.rs	Adds streaming multipart extractor + field type + tests; adds multer integration.
crates/rustapi-core/src/lib.rs	Re-exports production defaults config, health endpoint config/response, streaming multipart, sse_from_iter.
crates/rustapi-core/src/health.rs	Adds HealthEndpointConfig, HealthResponse, and helper handlers + OpenAPI response modifier.
crates/rustapi-core/src/extract.rs	Adds OpenAPI OperationModifier for AsyncValidatedJson<T> (parity with ValidatedJson<T>).
crates/rustapi-core/src/app.rs	Adds health endpoint wiring and a ProductionDefaultsConfig + production_defaults* APIs.
crates/rustapi-core/examples/perf_snapshot.rs	New synthetic in-process perf snapshot example for CI/local runs.
crates/rustapi-core/Cargo.toml	Adds multer = "3" and enables tokio io-util feature.
crates/cargo-rustapi/tests/cli_tests.rs	Adds tests for presets and new commands’ help output.
crates/cargo-rustapi/src/templates/mod.rs	Adds ProjectPreset with recommended feature bundles.
crates/cargo-rustapi/src/commands/observability.rs	New observability command that surfaces workflow assets.
crates/cargo-rustapi/src/commands/new.rs	Adds --preset support and merges preset features with explicit features.
crates/cargo-rustapi/src/commands/mod.rs	Registers new bench and observability commands (and replay under feature).
crates/cargo-rustapi/src/commands/bench.rs	New bench command intended to run a repo benchmark script.
crates/cargo-rustapi/src/cli.rs	Wires new subcommands into CLI; changes replay wiring.
crates/cargo-rustapi/README.md	Documents new commands and presets.
crates/cargo-rustapi/Cargo.toml	Enables replay by default feature set.
api/public/rustapi-rs.default.txt	Updates public API snapshot for new exports (streaming multipart, sse_from_iter).
api/public/rustapi-rs.all-features.txt	Updates all-features snapshot for new exports (oauth2/session/jobs/replay/etc.).
RELEASES.md	Adds benchmark policy note pointing to canonical doc.
README.md	Adds probe and replay examples; replaces static perf number with benchmark-policy pointer.
Cargo.lock	Adds new dependency lock entries (multer, redis, etc.).
CHANGELOG.md	Adds note that old benchmark numbers are historical snapshots.
.gitignore	Adds ignores for production docs, internal GH assets, and *.md (very broad).
.github/workflows/benchmark.yml	Adds perf snapshot run and uploads perf_snapshot.txt artifact.
.env	Adds placeholder env vars for local docs/examples.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

ReplayArgs is imported behind #[cfg(feature = "replay")], but the Commands::Replay(ReplayArgs) variant (and its match arm) are unconditional. Building cargo-rustapi with default-features = false (or without replay) will fail to compile. Either gate the enum variant + match arm behind the same feature, or make the replay command always available and remove the conditional import/module gating.

[Copilot]

cargo rustapi bench hard-codes scripts/bench.ps1, but this repository currently has no scripts/ directory (so the command will always error). Consider either adding scripts/bench.ps1 in this PR, or updating the command to run cargo bench --workspace and the perf_snapshot example directly (matching docs/PERFORMANCE_BENCHMARKS.md and CI).

Suggested change

	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("Running `cargo bench --workspace` in").bold(),
	style(workspace_root.display()).cyan()
	);
	let mut bench_cmd = Command::new("cargo");
	bench_cmd
	.arg("bench")
	.arg("--workspace")
	.current_dir(&workspace_root);
	if let Some(warmup) = args.warmup {
	bench_cmd.env("RUSTAPI_PERF_WARMUP", warmup.to_string());
	}
	if let Some(iterations) = args.iterations {
	bench_cmd.env("RUSTAPI_PERF_ITERS", iterations.to_string());
	}
	let bench_status = bench_cmd
	.status()
	.await
	.context("Failed to run `cargo bench --workspace`")?;
	if !bench_status.success() {
	bail!("`cargo bench --workspace` exited with status {}", bench_status);
	}
	println!(
	"{} {}",
	style("Running `cargo run --example perf_snapshot --release` in").bold(),
	style(workspace_root.display()).cyan()
	);
	let mut perf_cmd = Command::new("cargo");
	perf_cmd
	.arg("run")
	.arg("--example")
	.arg("perf_snapshot")
	.arg("--release")
	.current_dir(&workspace_root);
	if let Some(warmup) = args.warmup {
	perf_cmd.env("RUSTAPI_PERF_WARMUP", warmup.to_string());
	}
	if let Some(iterations) = args.iterations {
	perf_cmd.env("RUSTAPI_PERF_ITERS", iterations.to_string());
	}
	let perf_status = perf_cmd
	.status()
	.await
	.context("Failed to run `cargo run --example perf_snapshot --release`")?;
	if !perf_status.success() {
	bail!(
	"`cargo run --example perf_snapshot --release` exited with status {}",
	perf_status
	);

[Copilot]

The observability command treats several paths as required assets (docs/PRODUCTION_BASELINE.md, scripts/bench.ps1, scripts/check_quality.ps1), but those files/directories are not present in the repo. As a result, cargo rustapi observability --check will reliably fail (and the output will always report missing assets). Either add these assets in this PR or adjust the asset list to match what actually exists (e.g., .github/workflows/benchmark.yml and the benchmark commands it runs).

[Copilot]

This doc instructs users to run ./scripts/bench.ps1, but the repository doesn't include that script right now. Either add the script in this PR, or update the docs to point at the actual benchmark entry points that exist (e.g., cargo bench --workspace and cargo run -p rustapi-core --example perf_snapshot --release).

[Copilot]

This section references ./scripts/bench.ps1, but the repository doesn't currently contain that script. To avoid sending users to a dead command, update this to the actual benchmark invocation(s) that exist in-repo (or add the script as part of this PR).

[Copilot]

The Kubernetes YAML example uses tab characters for indentation. YAML requires spaces, so as-written this snippet will fail to parse if copied into a manifest. Replace the tabs with spaces and keep indentation consistent (typically 2 spaces) so the example is valid.

[Copilot]

Committing a root .env file can cause accidental leakage if developers later add real secrets, and it can also unexpectedly affect local runs/CI that auto-load .env. Consider renaming this to .env.example (tracked) and adding .env to .gitignore, while keeping the docs pointing at the example file.

Suggested change

	OIDC_ISSUER_URL=https://accounts.google.com
	OIDC_ISSUER_URL=replace-me

[Copilot]

PRODUCTION_BASELINE.md and PRODUCTION_CHECKLIST.md are linked here, but those files are not present under docs/ in the repository. This creates broken links in the docs landing page; either add the missing documents in this PR or remove/adjust the links until they exist.

[Copilot]

This recipe switches from English to Turkish starting at the first section heading. If the cookbook is intended to be English-first, this makes the page inconsistent and harder to consume for most readers. Consider translating these sections to English (or splitting into localized copies with clear navigation/labels).