Merge pull request #38 from Tuntii/feature/framework-ergonomics-update

Add TypedPath and ApiError derive macros with typed routing

Author: Tuntii

.github/workflows/ci.yml

@@ -154,15 +154,5 @@ jobs:
         env:
           RUSTDOCFLAGS: -D warnings
 
-  semver:
-    name: SemVer Checks
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - name: Install Rust
-        uses: dtolnay/rust-toolchain@stable
-      - name: Install cargo-semver-checks
-        uses: taiki-e/install-action@cargo-semver-checks
-      - name: Check for breaking changes
-        run: cargo semver-checks check-release
+
 

Cargo.lock

@@ -211,8 +211,31 @@ rustapi-rs = { version = "0.1.9", features = ["jwt", "cors", "toon", "ws", "view
 | `audit` | GDPR/SOC2 audit logging |
 | `full` | All features enabled |
 
+
+### ✨ New Ergonomic Features
+
+**Declarative Error Handling:**
+```rust
+#[derive(ApiError)]
+pub enum UserError {
+    #[error(status = 404, message = "User not found")]
+    NotFound(i32),
+    #[error(status = 400, code = "validation_error")]
+    InvalidInput(String),
+}
+```
+
+**Fluent Testing:**
+```rust
+let client = TestClient::new(app);
+client.get("/users").await
+    .assert_status(200)
+    .assert_json(&expected_users);
+```
+
 ---
 
+
 ## 📂 Examples
 
 All examples are production-ready and follow best practices.

README.md

@@ -70,6 +70,7 @@ rustapi-openapi = { workspace = true, default-features = false }
 [dev-dependencies]
 tokio = { workspace = true, features = ["macros", "rt-multi-thread"] }
 proptest = "1.4"
+rustapi-testing = { workspace = true }
 [features]
 default = ["swagger-ui", "tracing"]
 swagger-ui = ["rustapi-openapi/swagger-ui"]

crates/rustapi-core/Cargo.toml

@@ -390,6 +390,11 @@ impl RustApi {
         self
     }
 
+    /// Add a typed route
+    pub fn typed<P: crate::typed_path::TypedPath>(self, method_router: MethodRouter) -> Self {
+        self.route(P::PATH, method_router)
+    }
+
     /// Mount a handler (convenience method)
     ///
     /// Alias for `.route(path, method_router)` for a single handler.

crates/rustapi-core/src/app.rs

@@ -340,6 +340,50 @@ impl<T> Deref for Path<T> {
     }
 }
 
+/// Typed path extractor
+///
+/// Extracts path parameters and deserializes them into a struct implementing `Deserialize`.
+/// This is similar to `Path<T>`, but supports complex structs that can be deserialized
+/// from a map of parameter names to values (e.g. via `serde_json`).
+///
+/// # Example
+///
+/// ```rust,ignore
+/// #[derive(Deserialize)]
+/// struct UserParams {
+///     id: u64,
+///     category: String,
+/// }
+///
+/// async fn get_user(Typed(params): Typed<UserParams>) -> impl IntoResponse {
+///     // params.id, params.category
+/// }
+/// ```
+#[derive(Debug, Clone)]
+pub struct Typed<T>(pub T);
+
+impl<T: DeserializeOwned + Send> FromRequestParts for Typed<T> {
+    fn from_request_parts(req: &Request) -> Result<Self> {
+        let params = req.path_params();
+        let mut map = serde_json::Map::new();
+        for (k, v) in params.iter() {
+            map.insert(k.to_string(), serde_json::Value::String(v.to_string()));
+        }
+        let value = serde_json::Value::Object(map);
+        let parsed: T = serde_json::from_value(value)
+            .map_err(|e| ApiError::bad_request(format!("Invalid path parameters: {}", e)))?;
+        Ok(Typed(parsed))
+    }
+}
+
+impl<T> Deref for Typed<T> {
+    type Target = T;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
 /// State extractor
 ///
 /// Extracts shared application state.
@@ -851,6 +895,13 @@ impl<T> OperationModifier for Path<T> {
     }
 }
 
+// Typed - Same as Path, parameters are documented by route pattern
+impl<T> OperationModifier for Typed<T> {
+    fn update_operation(_op: &mut Operation) {
+        // No-op, managed by route registration
+    }
+}
+
 // Query - Extracts query params using IntoParams
 impl<T: IntoParams> OperationModifier for Query<T> {
     fn update_operation(op: &mut Operation) {

crates/rustapi-core/src/extract.rs

@@ -333,37 +333,6 @@ mod tests {
         }
     }
 
-    /// A request interceptor that modifies a header
-    #[derive(Clone)]
-    struct HeaderModifyingRequestInterceptor {
-        header_name: &'static str,
-        header_value: String,
-    }
-
-    impl HeaderModifyingRequestInterceptor {
-        fn new(header_name: &'static str, header_value: impl Into<String>) -> Self {
-            Self {
-                header_name,
-                header_value: header_value.into(),
-            }
-        }
-    }
-
-    impl RequestInterceptor for HeaderModifyingRequestInterceptor {
-        fn intercept(&self, mut request: Request) -> Request {
-            // Store the value in extensions since we can't modify headers directly
-            // In a real implementation, we'd need mutable header access
-            request
-                .extensions_mut()
-                .insert(format!("{}:{}", self.header_name, self.header_value));
-            request
-        }
-
-        fn clone_box(&self) -> Box<dyn RequestInterceptor> {
-            Box::new(self.clone())
-        }
-    }
-
     /// A response interceptor that modifies a header
     #[derive(Clone)]
     struct HeaderModifyingResponseInterceptor {

crates/rustapi-core/src/interceptor.rs

@@ -70,10 +70,9 @@ mod server;
 pub mod sse;
 pub mod static_files;
 pub mod stream;
+pub mod typed_path;
 #[macro_use]
 mod tracing_macros;
-#[cfg(any(test, feature = "test-utils"))]
-mod test_client;
 
 /// Private module for macro internals - DO NOT USE DIRECTLY
 ///
@@ -94,25 +93,25 @@ pub use error::{get_environment, ApiError, Environment, FieldError, Result};
 pub use extract::Cookies;
 pub use extract::{
     Body, BodyStream, ClientIp, Extension, FromRequest, FromRequestParts, HeaderValue, Headers,
-    Json, Path, Query, State, ValidatedJson,
+    Json, Path, Query, State, Typed, ValidatedJson,
 };
 pub use handler::{
     delete_route, get_route, patch_route, post_route, put_route, Handler, HandlerService, Route,
     RouteHandler,
 };
 pub use health::{HealthCheck, HealthCheckBuilder, HealthCheckResult, HealthStatus};
+pub use http::StatusCode;
 pub use interceptor::{InterceptorChain, RequestInterceptor, ResponseInterceptor};
 #[cfg(feature = "compression")]
 pub use middleware::CompressionLayer;
 pub use middleware::{BodyLimitLayer, RequestId, RequestIdLayer, TracingLayer, DEFAULT_BODY_LIMIT};
 #[cfg(feature = "metrics")]
 pub use middleware::{MetricsLayer, MetricsResponse};
 pub use multipart::{Multipart, MultipartConfig, MultipartField, UploadedFile};
-pub use request::Request;
+pub use request::{BodyVariant, Request};
 pub use response::{Created, Html, IntoResponse, NoContent, Redirect, Response, WithStatus};
-pub use router::{delete, get, patch, post, put, MethodRouter, Router};
+pub use router::{delete, get, patch, post, put, MethodRouter, RouteMatch, Router};
 pub use sse::{sse_response, KeepAlive, Sse, SseEvent};
 pub use static_files::{serve_dir, StaticFile, StaticFileConfig};
 pub use stream::{StreamBody, StreamingBody, StreamingConfig};
-#[cfg(any(test, feature = "test-utils"))]
-pub use test_client::{TestClient, TestRequest, TestResponse};
+pub use typed_path::TypedPath;

crates/rustapi-core/src/lib.rs

@@ -47,7 +47,7 @@ use hyper::body::Incoming;
 use std::sync::Arc;
 
 /// Internal representation of the request body state
-pub(crate) enum BodyVariant {
+pub enum BodyVariant {
     Buffered(Bytes),
     Streaming(Incoming),
     Consumed,
@@ -65,7 +65,7 @@ pub struct Request {
 
 impl Request {
     /// Create a new request from parts
-    pub(crate) fn new(
+    pub fn new(
         parts: Parts,
         body: BodyVariant,
         state: Arc<Extensions>,

crates/rustapi-core/src/request.rs

@@ -43,6 +43,7 @@
 
 use crate::handler::{into_boxed_handler, BoxedHandler, Handler};
 use crate::path_params::PathParams;
+use crate::typed_path::TypedPath;
 use http::{Extensions, Method};
 use matchit::Router as MatchitRouter;
 use rustapi_openapi::Operation;
@@ -331,6 +332,11 @@ impl Router {
         }
     }
 
+    /// Add a typed route using a TypedPath
+    pub fn typed<P: TypedPath>(self, method_router: MethodRouter) -> Self {
+        self.route(P::PATH, method_router)
+    }
+
     /// Add a route
     pub fn route(mut self, path: &str, method_router: MethodRouter) -> Self {
         // Convert {param} style to :param for matchit
@@ -573,7 +579,7 @@ impl Router {
     }
 
     /// Match a request and return the handler + params
-    pub(crate) fn match_route(&self, path: &str, method: &Method) -> RouteMatch<'_> {
+    pub fn match_route(&self, path: &str, method: &Method) -> RouteMatch<'_> {
         match self.inner.at(path) {
             Ok(matched) => {
                 let method_router = matched.value;
@@ -598,7 +604,7 @@ impl Router {
     }
 
     /// Get shared state
-    pub(crate) fn state_ref(&self) -> Arc<Extensions> {
+    pub fn state_ref(&self) -> Arc<Extensions> {
         self.state.clone()
     }
 
@@ -620,7 +626,7 @@ impl Default for Router {
 }
 
 /// Result of route matching
-pub(crate) enum RouteMatch<'a> {
+pub enum RouteMatch<'a> {
     Found {
         handler: &'a BoxedHandler,
         params: PathParams,
@@ -1024,7 +1030,7 @@ mod tests {
     #[test]
     fn test_state_tracking() {
         #[derive(Clone)]
-        struct MyState(String);
+        struct MyState(#[allow(dead_code)] String);
 
         let router = Router::new().state(MyState("test".to_string()));
 
@@ -1088,7 +1094,7 @@ mod tests {
     #[test]
     fn test_state_type_ids_merged_on_nest() {
         #[derive(Clone)]
-        struct NestedState(String);
+        struct NestedState(#[allow(dead_code)] String);
 
         async fn handler() -> &'static str {
             "handler"
@@ -1905,7 +1911,7 @@ mod property_tests {
             has_nested_state in any::<bool>(),
         ) {
             #[derive(Clone)]
-            struct TestState(i32);
+            struct TestState(#[allow(dead_code)] i32);
 
             async fn handler() -> &'static str { "handler" }