docs: cookbook + learning path improvements (maintenance run 2026-02-24)

docs/.agent/docs_inventory.md

@@ -5,9 +5,11 @@
 | `README.md` | Project overview, key features, quick start | Root | OK |
 | `docs/README.md` | Documentation landing page | Docs | OK |
 | `docs/cookbook/src/SUMMARY.md` | Cookbook navigation structure | Docs | OK |
-| `docs/cookbook/src/learning/curriculum.md` | Structured learning path | Docs | Updated (Mini Projects) |
-| `docs/cookbook/src/recipes/file_uploads.md` | Recipe for File Uploads | Docs | Updated (Buffered) |
-| `docs/cookbook/src/recipes/websockets.md` | Recipe for Real-time Chat | Docs | Updated (Extractors) |
+| `docs/cookbook/src/learning/curriculum.md` | Structured learning path | Docs | Updated (Advanced Testing) |
+| `docs/cookbook/src/recipes/file_uploads.md` | Recipe for File Uploads | Docs | Updated (Streaming) |
+| `docs/cookbook/src/recipes/db_integration.md` | Recipe for DB Integration | Docs | Updated (Pagination) |
+| `docs/cookbook/src/recipes/error_handling.md` | Recipe for Error Handling | Docs | New |
+| `docs/cookbook/src/recipes/websockets.md` | Recipe for Real-time Chat | Docs | OK |
 | `docs/cookbook/src/recipes/background_jobs.md` | Recipe for Background Jobs | Docs | OK |
 | `docs/cookbook/src/recipes/tuning.md` | Performance Tuning | Docs | DELETED |
 | `docs/cookbook/src/recipes/new_feature.md` | New Feature Guide | Docs | DELETED |

docs/.agent/last_run.json

@@ -1,5 +1,5 @@
 {
   "last_processed_ref": "v0.1.335",
-  "date": "2026-02-23",
-  "notes": "Fixed MockServer examples in testing recipe. Added Graceful Shutdown recipe. Enhanced Learning Path with 'The Email Worker' mini-project."
+  "date": "2026-02-24",
+  "notes": "Added Error Handling recipe, updated File Uploads with streaming warning, enhanced DB Integration with pagination, and improved Learning Path with Advanced Testing module."
 }

docs/.agent/run_report_2026-02-24.md

@@ -0,0 +1,28 @@
+# Docs Maintenance Run: 2026-02-24
+
+## 1. Version Detection
+- **Target Version**: v0.1.335
+- **Status**: No version change since last run (2026-02-23).
+- **Mode**: Continuous Improvement.
+
+## 2. Changes
+### Learning Path
+- Added **Module 11.5: Advanced Testing** to `docs/cookbook/src/learning/curriculum.md` covering `MockServer` and property testing concepts.
+- Refined **Module 6.5: File Uploads** in `docs/cookbook/src/learning/curriculum.md` to explicitly warn about the buffering behavior of the `Multipart` extractor.
+
+### Recipes
+- **File Uploads**: Updated `docs/cookbook/src/recipes/file_uploads.md` with a prominent warning about memory usage for large files and suggested `multer` or raw body streaming as alternatives.
+- **Database Integration**: Enhanced `docs/cookbook/src/recipes/db_integration.md` with a new section on **Pagination**, demonstrating `LIMIT/OFFSET` queries and integration with `rustapi_core::hateoas::PageInfo`.
+- **Error Handling**: Created a new recipe `docs/cookbook/src/recipes/error_handling.md` detailing:
+    - Custom `ApiError` enum implementation.
+    - `IntoResponse` for structured JSON errors.
+    - Best practices for masking internal server errors in production.
+
+## 3. Improvements
+- Addressed a gap in documentation regarding advanced error handling patterns.
+- Clarified performance implications of file uploads to prevent user issues with large files.
+- Connected database concepts with pagination features for a more cohesive learning experience.
+
+## 4. TODOs
+- [ ] Investigate if `rustapi-core` can support streaming multipart parsing natively in a future release.
+- [ ] Add a full end-to-end example of the "High-Scale Event Platform" capstone project.

docs/cookbook/src/SUMMARY.md

@@ -35,6 +35,7 @@
     - [OAuth2 Client](recipes/oauth2_client.md)
     - [CSRF Protection](recipes/csrf_protection.md)
     - [Database Integration](recipes/db_integration.md)
+    - [Error Handling](recipes/error_handling.md)
     - [Testing & Mocking](recipes/testing.md)
     - [File Uploads](recipes/file_uploads.md)
     - [Background Jobs](recipes/background_jobs.md)

docs/cookbook/src/learning/curriculum.md

@@ -104,7 +104,7 @@ Create a `POST /register` endpoint that accepts a JSON body `{"username": "...",
 
 ### Module 5.5: Error Handling
 - **Prerequisites:** Module 5.
-- **Reading:** [Error Handling](../concepts/errors.md).
+- **Reading:** [Error Handling](../recipes/error_handling.md).
 - **Task:** Create a custom `ApiError` enum and implement `IntoResponse`. Return robust error messages.
 - **Expected Output:** `GET /users/999` returns `404 Not Found` with a structured JSON error body.
 - **Pitfalls:** Exposing internal database errors (like SQL strings) to the client.
@@ -131,11 +131,11 @@ Create a `POST /register` endpoint that accepts a JSON body `{"username": "...",
 - **Reading:** [File Uploads](../recipes/file_uploads.md).
 - **Task:** Create an endpoint `POST /upload` that accepts a file and saves it to disk.
 - **Expected Output:** `curl -F file=@image.png` uploads the file.
-- **Pitfalls:** Loading large files entirely into memory (use streaming).
+- **Pitfalls:** RustAPI currently **buffers the entire request body** into memory. For large files (e.g., >100MB), consider streaming alternatives.
 
 #### 🧠 Knowledge Check
 1. Which extractor is used for file uploads?
-2. Why should you use `field.chunk()` instead of `field.bytes()`?
+2. Why is buffering a potential issue for large files?
 3. How do you increase the request body size limit?
 
 ### 🏆 Phase 2 Capstone: "The Secure Blog Engine"
@@ -210,25 +210,31 @@ Create a `POST /register` endpoint that accepts a JSON body `{"username": "...",
 
 ### Module 11: Background Jobs & Testing
 - **Prerequisites:** Phase 3.
-- **Reading:** [Background Jobs Recipe](../recipes/background_jobs.md), [Testing Strategy](../concepts/testing.md).
+- **Reading:** [Background Jobs Recipe](../recipes/background_jobs.md).
 - **Task:**
     1. Implement a job `WelcomeEmailJob` that sends a "Welcome" email (simulated with `tokio::time::sleep`).
     2. Enqueue this job inside your `POST /register` handler.
-    3. Write an integration test using `TestClient` to verify the registration endpoint.
-- **Expected Output:** Registration returns 200 immediately (low latency); console logs show "Sending welcome email to ..." shortly after (asynchronous). Tests pass.
+- **Expected Output:** Registration returns 200 immediately (low latency); console logs show "Sending welcome email to ..." shortly after (asynchronous).
 - **Pitfalls:** Forgetting to start the job worker loop (`JobWorker::new(queue).run().await`).
 
-#### 🛠️ Mini Project: "The Email Worker"
-Create a system where users can request a "Report".
-1. `POST /reports`: Enqueues a `GenerateReportJob`. Returns `{"job_id": "..."}` immediately.
-2. The job simulates 5 seconds of work and then writes "Report Generated" to a file or log.
-3. (Bonus) Use Redis backend for persistence.
+### Module 11.5: Advanced Testing
+- **Prerequisites:** Module 11.
+- **Reading:** [Testing Strategy](../concepts/testing.md).
+- **Task:**
+    1. Use `TestClient` to perform integration testing on your API.
+    2. Use `MockServer` from `rustapi-testing` to mock an external currency exchange API.
+- **Expected Output:** Tests pass without requiring a real external server.
+- **Pitfalls:** Not isolating tests properly (sharing state between parallel tests).
+
+#### 🛠️ Mini Project: "The Mock Exchange"
+Create a service that converts currency by calling an external API.
+1. Write a test where `MockServer` responds with a fixed rate (e.g., 1 USD = 0.9 EUR).
+2. Verify your service calculates the correct amount based on the mock.
 
 #### 🧠 Knowledge Check
-1. Why should you offload email sending to a background job?
-2. Which backend is suitable for local development vs production?
-3. How do you enqueue a job from a handler?
-4. How can you test that a job was enqueued without actually running it?
+1. What is the difference between unit and integration tests?
+2. How does `MockServer` help with flaky external services?
+3. Why should you avoid hitting real APIs in your test suite?
 
 ### 🏆 Phase 3 Capstone: "The Real-Time Collaboration Tool"
 **Objective:** Build a real-time collaborative note-taking app.

docs/cookbook/src/recipes/db_integration.md

@@ -155,7 +155,60 @@ async fn transfer_credits(
 }
 ```
 
-## 4. Integration Testing with TestContainers
+## 4. Pagination with SQLx
+
+When listing resources, always use `LIMIT` and `OFFSET` to avoid fetching thousands of rows. RustAPI provides helpers for standard HATEOAS pagination.
+
+See the [Pagination Recipe](pagination.md) for more details on `ResourceCollection`.
+
+```rust
+use rustapi_rs::hateoas::{PageInfo, ResourceCollection};
+
+#[derive(Deserialize, Schema)]
+struct PaginationParams {
+    page: Option<usize>,
+    size: Option<usize>,
+}
+
+async fn list_users(
+    State(state): State<AppState>,
+    Query(params): Query<PaginationParams>,
+) -> Result<Json<ResourceCollection<User>>, ApiError> {
+    let page = params.page.unwrap_or(0);
+    let size = params.size.unwrap_or(20).clamp(1, 100);
+    let offset = (page * size) as i64;
+
+    // Fetch data
+    let users = sqlx::query_as!(
+        User,
+        "SELECT id, username, email FROM users ORDER BY id LIMIT $1 OFFSET $2",
+        size as i64,
+        offset
+    )
+    .fetch_all(&state.db)
+    .await
+    .map_err(ApiError::from)?;
+
+    // Get total count for pagination metadata
+    // Note: For very large tables, exact count(*) can be slow. Consider estimates.
+    let count_record = sqlx::query!("SELECT count(*) as count FROM users")
+        .fetch_one(&state.db)
+        .await
+        .map_err(ApiError::from)?;
+
+    let total = count_record.count.unwrap_or(0) as usize;
+
+    let page_info = PageInfo::calculate(total, size, page);
+
+    Ok(Json(
+        ResourceCollection::new("users", users)
+            .page_info(page_info)
+            .with_pagination("/users")
+    ))
+}
+```
+
+## 5. Integration Testing with TestContainers
 
 For testing, use `testcontainers` to spin up a real database instance. This ensures your queries are correct without mocking the database driver.
 

docs/cookbook/src/recipes/error_handling.md

@@ -0,0 +1,140 @@
+# Error Handling
+
+Effective error handling is critical for building robust APIs. RustAPI provides a standard `ApiError` type but encourages custom error handling for domain-specific logic.
+
+## The Standard `ApiError`
+
+RustAPI's `ApiError` is designed to be returned directly from handlers. It implements `IntoResponse`, so it is automatically converted to a JSON response.
+
+```rust
+use rustapi_rs::prelude::*;
+
+#[rustapi_rs::get("/users/{id}")]
+async fn get_user(Path(id): Path<i32>) -> Result<Json<User>, ApiError> {
+    if id < 0 {
+        // Returns 400 Bad Request
+        return Err(ApiError::bad_request("ID cannot be negative"));
+    }
+
+    if id == 99 {
+        // Returns 404 Not Found
+        return Err(ApiError::not_found("User not found"));
+    }
+
+    // Returns 500 Internal Server Error (and logs the details)
+    // The client sees "Internal Server Error" without the sensitive details
+    // return Err(ApiError::internal("Database connection failed"));
+
+    Ok(Json(User { id, name: "Alice".into() }))
+}
+```
+
+### Response Format
+
+By default, `ApiError` produces a standard JSON error response:
+
+```json
+{
+  "error": {
+    "code": 404,
+    "message": "User not found",
+    "id": "req_123abc" // Request ID for tracking (if tracing is enabled)
+  }
+}
+```
+
+## Custom Error Types
+
+For complex applications, you should define your own error enum to represent domain-specific failures. Implement `IntoResponse` to control how these errors are mapped to HTTP responses.
+
+```rust
+use rustapi_rs::prelude::*;
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum AppError {
+    #[error("User not found: {0}")]
+    UserNotFound(i32),
+
+    #[error("Insufficient funds")]
+    InsufficientFunds,
+
+    #[error("Database error: {0}")]
+    DatabaseError(#[from] sqlx::Error),
+
+    #[error("Invalid input: {0}")]
+    ValidationError(String),
+}
+
+// Map AppError to Response
+impl IntoResponse for AppError {
+    fn into_response(self) -> Response {
+        let (status, message) = match &self {
+            AppError::UserNotFound(_) => (StatusCode::NOT_FOUND, self.to_string()),
+            AppError::InsufficientFunds => (StatusCode::PAYMENT_REQUIRED, self.to_string()),
+            AppError::ValidationError(msg) => (StatusCode::BAD_REQUEST, msg.clone()),
+
+            // Mask internal errors in production!
+            AppError::DatabaseError(e) => {
+                tracing::error!("Database error: {:?}", e);
+                (StatusCode::INTERNAL_SERVER_ERROR, "Internal system error".to_string())
+            }
+        };
+
+        let body = Json(serde_json::json!({
+            "error": {
+                "message": message,
+                "code": status.as_u16()
+            }
+        }));
+
+        (status, body).into_response()
+    }
+}
+```
+
+### Using Custom Errors in Handlers
+
+Now you can return `Result<T, AppError>` from your handlers.
+
+```rust
+async fn transfer(
+    Json(payload): Json<TransferRequest>
+) -> Result<StatusCode, AppError> {
+    let user = find_user(payload.user_id).await?; // Returns AppError::UserNotFound
+
+    if user.balance < payload.amount {
+        return Err(AppError::InsufficientFunds);
+    }
+
+    // ...
+
+    Ok(StatusCode::OK)
+}
+```
+
+## Best Practices
+
+### 1. Mask Internal Errors
+Never expose raw database errors or stack traces to the client. This is a security risk. Log the full error on the server (using `tracing::error!`) and return a generic "Internal Server Error" message to the client.
+
+### 2. Use `thiserror`
+The `thiserror` crate is excellent for defining error hierarchies with minimal boilerplate.
+
+### 3. Structured Logging
+When an error occurs, ensure you log it with context.
+
+```rust
+AppError::DatabaseError(e) => {
+    // Log with structured fields
+    tracing::error!(
+        error.message = %e,
+        error.cause = ?e,
+        "Database transaction failed"
+    );
+    (StatusCode::INTERNAL_SERVER_ERROR, "Internal Error".into())
+}
+```
+
+### 4. Global Error Handling
+For errors that occur outside of handlers (e.g., in extractors or middleware), RustAPI has default handlers. You can customize 404 and 500 pages using `RustApi::handle_error` (if supported by your version) or by ensuring your extractors return your custom error type.