docs: add v0.1.397 release notes and update changelog

Author: Tuntii

CHANGELOG.md

@@ -7,6 +7,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.397] - 2026-02-26
+
+### Added
+
+#### Compile-Time Extractor Safety (`rustapi-macros`)
+- **Body-consuming extractor ordering enforced at compile time**: `Json<T>`, `Body`, `ValidatedJson<T>` must now be the last handler parameter — otherwise you get a clear compiler error instead of a silent runtime failure.
+- Descriptive error messages: `"Body-consuming extractors must be the last parameter"`.
+- Detects multiple body-consuming extractors in the same handler.
+
+#### Typed Error Responses — OpenAPI Integration (`rustapi-macros`, `rustapi-core`)
+- New `#[errors(404 = "Not found", 403 = "Forbidden")]` attribute macro for route handlers.
+- Error types are automatically reflected in the OpenAPI spec with `ErrorSchema` references.
+- `Route::error_response()` builder method for programmatic error response registration.
+- Swagger UI now displays all possible error responses per endpoint.
+
+#### Pagination & HATEOAS Helpers (`rustapi-core`)
+- **`Paginate` extractor**: `?page=2&per_page=20` with sensible defaults (page=1, per_page=20, max=100).
+- **`Paginated<T>` response wrapper**: JSON body with `items`/`meta`/`_links`, RFC 8288 `Link` header, `X-Total-Count` & `X-Total-Pages` headers.
+- **`CursorPaginate` extractor**: `?cursor=abc&limit=20` for cursor-based pagination.
+- **`CursorPaginated<T>` response wrapper**: `items` + `next_cursor` + `has_more`.
+- Helper methods: `offset()`, `limit()`, `paginate()`, `after()`, `is_first_page()`.
+- All types re-exported in the `rustapi-rs` prelude.
+
+#### Built-in Caching Layer (`rustapi-extras`)
+- **Full rewrite of the caching system** with production-grade features:
+  - In-memory response cache with LRU eviction and configurable `max_entries` (default: 10,000).
+  - ETag generation via FNV-1a hash + automatic `If-None-Match` → 304 Not Modified.
+  - `Cache-Control` header awareness (`no-cache`, `no-store`).
+  - `Vary`-by-header cache key strategy.
+  - `CacheHandle` for programmatic invalidation (by path prefix, exact key, or clear all).
+  - `CacheBuilder` for ergonomic middleware configuration.
+
+#### Event System & Lifecycle Hooks (`rustapi-core`)
+- **`EventBus`**: In-process pub/sub with sync and async handlers.
+  - `on()` for sync handlers, `on_async()` for async handlers.
+  - `emit()` (fire-and-forget) and `emit_await()` (wait for all handlers).
+  - `handler_count()` and `topics()` introspection.
+- **Lifecycle hooks** on `RustApi` builder:
+  - `.on_start(async { ... })` — runs before the server starts accepting connections.
+  - `.on_shutdown(async { ... })` — runs on graceful shutdown.
+  - Integrated into both `run()` and `run_with_shutdown()`.
+- `EventBus` re-exported in the `rustapi-rs` prelude.
+
+#### Native Hot Reload / Watch Mode (`cargo-rustapi`, `rustapi-core`)
+- **Complete rewrite of `cargo rustapi watch`** using `notify` + `notify-debouncer-mini` — no more `cargo-watch` dependency.
+  - 300ms debounce, configurable extension filter, smart ignore paths.
+  - Build-before-restart: only restarts the server if `cargo build` succeeds.
+  - Graceful process shutdown (kill + 5s timeout), crash detection with "watching for changes" recovery.
+- `.hot_reload(true)` builder API on `RustApi` — prints a dev-mode banner with watcher hints.
+- `cargo rustapi run --watch` / `--reload` / `--hot` delegates to the native watcher.
+
+#### gRPC Support Published (`rustapi-grpc`)
+- **First crates.io release** of `rustapi-grpc v0.1.397`.
+- `run_rustapi_and_grpc()` for dual HTTP + gRPC server execution.
+- Re-exports `tonic` and `prost` for ergonomic proto service integration.
+- `protocol-grpc` feature flag in `rustapi-rs`.
+
 ### Changed
 - **Facade-first CORE stabilization**:
   - `rustapi-rs` public surface is now explicitly curated (`core`, `protocol`, `extras`, `prelude`).
@@ -17,19 +74,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Canonical naming is now `core-*`, `protocol-*`, `extras-*`.
   - Meta features standardized: `core`, `protocol-all`, `extras-all`, `full`.
   - Legacy feature names remain as compatibility aliases and are deprecated.
+- **Publish pipeline**: `rustapi-grpc` added to `smart_publish.ps1` and `publish.ps1` in correct dependency order.
 
-### Added
+### Fixed
+- Clippy lint: `.map_or(false, ...)` → `.is_some_and(...)` in cache middleware.
+- Clippy lint: Nested `format!` macros replaced with single `format!` in ETag generation.
+
+### Documentation
+- Expanded cookbook: gRPC, SSR, and AI skill recipes.
+- Learning path improvements across multiple maintenance runs.
+- Fixed SSR recipe and updated recipes index.
+
+### Added (Governance)
 - **Public API governance**:
   - Snapshot files under `api/public/` for `rustapi-rs` (default + all-features).
-  - New CI workflow `.github/workflows/public-api.yml`:
-    - snapshot drift check
-    - PR label gate requiring `breaking` or `feature` when snapshot changes.
-- **Compatibility contract**:
-  - New `CONTRACT.md` defining SemVer, MSRV (1.78), deprecation and feature policies.
+  - CI workflow for snapshot drift check and PR label gate.
+- **Compatibility contract**: New `CONTRACT.md` defining SemVer, MSRV (1.78), deprecation and feature policies.
 
 ### Deprecated
 - Legacy facade paths and feature aliases are soft-deprecated and scheduled for removal no earlier than two minor releases after announcement.
 
+## [0.1.335] - 2026-02-13
+
+### Added
+- Pagination cookbook recipe and synced docs to v0.1.335.
+- HATEOAS test schemas with manual `RustApiSchema` implementations.
+- RELEASES.md for release tracking.
+
+### Fixed
+- Lint formatting in `custom_messages.rs`.
+- Pagination size validation (PR review feedback).
+- Cumulative CI failure fixes.
+
 ## [0.1.300] - 2026-02-06
 
 ### Added
@@ -304,7 +380,16 @@ This release delivers a **12x performance improvement**, bringing RustAPI from ~
 - `extras` meta-feature for common optional features
 - `full` feature for all optional features
 
-[Unreleased]: https://github.com/Tuntii/RustAPI/compare/v0.1.4...HEAD
+[Unreleased]: https://github.com/Tuntii/RustAPI/compare/v0.1.397...HEAD
+[0.1.397]: https://github.com/Tuntii/RustAPI/compare/v0.1.335...v0.1.397
+[0.1.335]: https://github.com/Tuntii/RustAPI/compare/v0.1.300...v0.1.335
+[0.1.300]: https://github.com/Tuntii/RustAPI/compare/v0.1.202...v0.1.300
+[0.1.202]: https://github.com/Tuntii/RustAPI/compare/v0.1.15...v0.1.202
+[0.1.15]: https://github.com/Tuntii/RustAPI/compare/v0.1.11...v0.1.15
+[0.1.11]: https://github.com/Tuntii/RustAPI/compare/v0.1.10...v0.1.11
+[0.1.10]: https://github.com/Tuntii/RustAPI/compare/v0.1.9...v0.1.10
+[0.1.9]: https://github.com/Tuntii/RustAPI/compare/v0.1.8...v0.1.9
+[0.1.8]: https://github.com/Tuntii/RustAPI/compare/v0.1.4...v0.1.8
 [0.1.4]: https://github.com/Tuntii/RustAPI/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/Tuntii/RustAPI/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/Tuntii/RustAPI/compare/v0.1.1...v0.1.2

RELEASES.md

@@ -0,0 +1,201 @@
+# RustAPI v0.1.397 Release Notes
+
+**Release Date**: February 26, 2026
+**Full Changelog**: https://github.com/Tuntii/RustAPI/compare/v0.1.335...v0.1.397
+
+---
+
+## 🎯 Highlights
+
+This is the biggest feature release since v0.1.300. Seven major features land together, transforming RustAPI from a routing framework into a **production-ready application platform**.
+
+| Feature | Crate | Impact |
+|---------|-------|--------|
+| Compile-Time Extractor Safety | `rustapi-macros` | Zero runtime surprises from body-consuming extractors |
+| Typed Error Responses | `rustapi-macros` + `rustapi-core` | Errors auto-reflected in OpenAPI spec |
+| Pagination & HATEOAS | `rustapi-core` | Offset + cursor pagination with RFC 8288 Link headers |
+| Built-in Caching Layer | `rustapi-extras` | LRU + ETag + `304 Not Modified` out of the box |
+| Event System & Lifecycle Hooks | `rustapi-core` | In-process pub/sub + `on_start` / `on_shutdown` |
+| Native Hot Reload | `cargo-rustapi` | Zero-dependency file watcher, no `cargo-watch` needed |
+| gRPC Support | `rustapi-grpc` | First crates.io release — dual HTTP + gRPC server |
+
+---
+
+## ⚡ Compile-Time Extractor Safety
+
+Body-consuming extractors (`Json<T>`, `Body`, `ValidatedJson<T>`) **must** now be the last handler parameter. The macro emits a clear compile error instead of silently failing at runtime:
+
+```rust
+// ✅ Compiles
+#[get("/users")]
+async fn ok(State(db): State<Db>, body: Json<CreateUser>) -> Result<Json<User>> { ... }
+
+// ❌ Compile error: "Body-consuming extractors must be the last parameter"
+#[get("/users")]
+async fn bad(body: Json<CreateUser>, State(db): State<Db>) -> Result<Json<User>> { ... }
+```
+
+Multiple body-consuming extractors in the same handler are also detected at compile time.
+
+---
+
+## 🏷️ Typed Error Responses (OpenAPI)
+
+Declare possible error responses with `#[errors()]` — they appear automatically in Swagger UI:
+
+```rust
+#[get("/users/{id}")]
+#[errors(404 = "User not found", 403 = "Insufficient permissions")]
+async fn get_user(Path(id): Path<Uuid>) -> Result<Json<User>> { ... }
+```
+
+Programmatic alternative: `Route::error_response(404, "Not found")`.
+
+---
+
+## 📄 Pagination & HATEOAS
+
+### Offset Pagination
+```rust
+async fn list(paginate: Paginate, State(db): State<Db>) -> Paginated<User> {
+    let (users, total) = db.find_users(paginate.offset(), paginate.limit()).await;
+    paginate.paginate(users, total)
+}
+// GET /users?page=2&per_page=20
+// → { items: [...], meta: { page: 2, per_page: 20, total: 150, total_pages: 8 }, _links: {...} }
+// → Link: <...?page=3&per_page=20>; rel="next", <...?page=1&per_page=20>; rel="prev"
+```
+
+### Cursor Pagination
+```rust
+async fn feed(cursor: CursorPaginate) -> CursorPaginated<Post> {
+    let posts = db.posts_after(cursor.cursor(), cursor.limit()).await;
+    cursor.after(posts, next_cursor, has_more)
+}
+```
+
+Both include `X-Total-Count` and `X-Total-Pages` headers. All types in the prelude.
+
+---
+
+## 🗄️ Built-in Caching Layer
+
+Full rewrite with production-grade features:
+
+```rust
+use rustapi_rs::prelude::*;
+
+let app = RustApi::new()
+    .layer(
+        CacheBuilder::new()
+            .max_entries(5_000)
+            .default_ttl(Duration::from_secs(300))
+            .vary_by(&["Accept", "Authorization"])
+            .build()
+    );
+```
+
+- **LRU eviction** with configurable `max_entries`
+- **ETag** generation via FNV-1a hash + automatic `304 Not Modified`
+- **Cache-Control** awareness (`no-cache`, `no-store`)
+- **`CacheHandle`** for programmatic invalidation (by prefix, exact key, or clear all)
+
+---
+
+## 🔔 Event System & Lifecycle Hooks
+
+### EventBus
+```rust
+let bus = EventBus::new();
+bus.on("user.created", |data| { println!("New user: {data}"); });
+bus.emit("user.created", "alice@example.com");
+```
+
+Supports sync and async handlers, fire-and-forget (`emit`) and await-all (`emit_await`).
+
+### Lifecycle Hooks
+```rust
+RustApi::new()
+    .on_start(|| async { println!("🚀 Server starting..."); Ok(()) })
+    .on_shutdown(|| async { println!("👋 Graceful shutdown"); Ok(()) })
+    .run("0.0.0.0:8080").await;
+```
+
+---
+
+## 🔥 Native Hot Reload
+
+No more `cargo install cargo-watch`:
+
+```bash
+cargo rustapi watch          # Watch mode with 300ms debounce
+cargo rustapi run --watch    # Same via run subcommand
+```
+
+- **Build-before-restart**: Only restarts if `cargo build` succeeds
+- **Crash recovery**: Watches for changes even after build failure
+- **Smart filtering**: Ignores `target/`, `.git/`, non-Rust files
+- **`.hot_reload(true)`** builder API prints dev-mode banner
+
+---
+
+## 🌐 gRPC Support (First Release)
+
+`rustapi-grpc` is now on **crates.io** for the first time:
+
+```toml
+[dependencies]
+rustapi-rs = { version = "0.1.397", features = ["protocol-grpc"] }
+```
+
+```rust
+use rustapi_grpc::run_rustapi_and_grpc;
+
+run_rustapi_and_grpc(http_app, grpc_router, "[::]:8080", "[::]:50051").await;
+```
+
+Re-exports `tonic` and `prost` for seamless proto integration.
+
+---
+
+## 🏗️ Facade Stabilization & Governance
+
+- Public API surface explicitly curated under `core`, `protocol`, `extras`, `prelude` modules
+- API snapshot files (`api/public/`) with CI drift check
+- `CONTRACT.md` defining SemVer contract, MSRV (1.78), deprecation policy
+- Feature taxonomy: `core-*`, `protocol-*`, `extras-*` canonical names
+
+---
+
+## 🔧 Fixes & Maintenance
+
+- Clippy: `.map_or(false, ...)` → `.is_some_and(...)` in cache middleware
+- Clippy: Nested `format!` → single `format!` in ETag generation
+- Publish pipeline: `rustapi-grpc` added to both publish scripts
+
+---
+
+## 📦 Upgrade Guide
+
+```toml
+# Cargo.toml
+rustapi-rs = "0.1.397"
+
+# For new features:
+rustapi-rs = { version = "0.1.397", features = ["full"] }
+```
+
+No breaking changes. Deprecated legacy feature aliases still work and will be removed no earlier than two minor releases after this announcement.
+
+---
+
+## What's Changed (PRs)
+
+- Add lifecycle hooks, pagination, and cache (#139)
+- Fix review feedback: deduplication, pagination validation, cache correctness (#140)
+- docs: cookbook expansion and learning path improvements (#132)
+- core: stabilize facade API surface, feature taxonomy, and public-api CI gate (#122)
+- Add optional rustapi-grpc crate (tonic/prost) (#118)
+- docs: multiple learning path and cookbook improvements (#109, #112, #120, #121, #123-126, #129)
+
+**Full Changelog**: https://github.com/Tuntii/RustAPI/compare/v0.1.335...v0.1.397