Optimize

Author: owjs3901

.gitignore

@@ -26,3 +26,4 @@ node_modules
 
 # Generated OpenAPI artifacts at workspace root
 /openapi*.json
+.retry-now/

README.md

@@ -656,6 +656,10 @@ pub struct CategoryInArticle {
 
 schema_type!(
     ArticleResponse from crate::models::article::Model,
+    relation_adapters = [
+        ("user", UserInArticle),
+        ("category", CategoryInArticle),
+    ],
     add = [("article_review_users": Vec<ArticleReviewUserInArticle>)]
 );
 
@@ -670,14 +674,14 @@ Ok(ArticleResponse {
 
 How it works:
 
-- `schema_type!` looks for same-file DTOs named `{RelationNamePascal}In{ResponseBase}`
-  - `user` on `ArticleResponse` → `UserInArticle`
-  - `category` on `ArticleResponse` → `CategoryInArticle`
-- It generates local compile adapters so `Option<Model>.into()` works unchanged in the handler
+- `relation_adapters = [("field", AdapterStruct)]` is an explicit opt-in for single-value relation fields (`HasOne` / `BelongsTo`)
+- The adapter struct name is used verbatim; Vespera does not infer adapter names by convention
+- If an explicitly named adapter struct cannot be found in the same file, compilation fails instead of silently falling back
+- Vespera generates local compile adapters so `Option<Model>.into()` works unchanged in the handler
 - The internal `__Vespera…Relation` wrapper type stays private to Rust typing
 - OpenAPI references the **adapter DTO's own schema** (`UserInArticle`, `CategoryInArticle`) — so the documented response shape matches exactly what the handler serializes, instead of over-promising the base relation schema (`UserSchema`, `CategorySchema`)
 
-Use this when you want route-local response DTOs for single-value relations (`HasOne` / `BelongsTo`) without rewriting the route construction logic.
+Use this when you want route-local response DTOs for single-value relations without rewriting the route construction logic. Relation fields not listed in `relation_adapters` keep the default base-schema relation type.
 
 ### Multipart Mode
 

SKILL.md

@@ -531,6 +531,10 @@ pub struct CategoryInArticle {
 
 schema_type!(
     ArticleResponse from crate::models::article::Model,
+    relation_adapters = [
+        ("user", UserInArticle),
+        ("category", CategoryInArticle),
+    ],
     add = [("article_review_users": Vec<ArticleReviewUserInArticle>)]
 );
 
@@ -545,11 +549,12 @@ Ok(ArticleResponse {
 Rules:
 
 - Only applies to single-value relations (`HasOne` / `BelongsTo`)
-- The local DTO name must follow `{RelationNamePascal}In{ResponseBase}`
-  - `user` on `ArticleResponse` → `UserInArticle`
-  - `category` on `ArticleResponse` → `CategoryInArticle`
+- Must be opted in explicitly with `relation_adapters = [("field", AdapterStruct)]`
+- The adapter struct name is used verbatim; Vespera does not infer adapter names by convention
+- Missing explicitly named adapter structs are compile errors
 - Vespera generates local compile adapters so `Option<Model>.into()` works without changing the route
-- The adapter wrapper is hidden from OpenAPI; the spec still references the original related schema (`UserSchema`, `CategorySchema`)
+- OpenAPI references the adapter DTO's own schema (`UserInArticle`, `CategoryInArticle`), honoring any `#[schema(name = "...")]` override
+- Single-value relations not listed in `relation_adapters` keep the default base-schema relation type
 - `HasMany` relations remain excluded by default unless explicitly `pick`ed or `add`ed
 
 ### Complete Example

crates/vespera/src/lib.rs

@@ -22,6 +22,31 @@ pub use vespera_core::openapi::OpenApi;
 // Re-export macros from vespera_macro
 pub use vespera_macro::{Multipart, Schema, cron, export_app, route, schema, schema_type, vespera};
 
+/// Marker trait implemented by every `#[derive(Schema)]` type.
+///
+/// The derive macro auto-implements this trait, which is intentionally
+/// empty — it carries no methods.  Its purpose is to anchor the
+/// compile-time leaf-type assertions emitted by `#[derive(Schema)]`:
+/// for every field whose type is not a builtin OpenAPI primitive,
+/// not `serde_json::Value`, and not marked `#[schema(any)]`, the
+/// derive emits a `T: ::vespera::Schema` bound assertion against the
+/// field's leaf type.  An unbound leaf — typically a custom struct
+/// that forgot its own `#[derive(Schema)]` — becomes a compile error
+/// at the field site instead of silently emitting `{type:object}`
+/// into the OpenAPI document.
+///
+/// Users normally never name this trait directly — `#[derive(Schema)]`
+/// is the entire user surface.  If you intentionally want a field to
+/// stay as opaque `{type:object}` (arbitrary JSON), mark it with
+/// `#[schema(any)]` to skip the assertion AND lock the schema to
+/// `object`.  `serde_json::Value` fields are allowlisted automatically.
+///
+/// The trait and the `vespera::Schema` derive macro share the same
+/// name but live in different namespaces (trait vs. derive-macro), so
+/// the existing `#[derive(Schema)]` syntax continues to work
+/// unchanged.
+pub trait Schema {}
+
 // Re-export serde_json for merge feature (runtime spec merging)
 pub use serde_json;
 

crates/vespera/src/multipart.rs

@@ -419,7 +419,7 @@ impl<'a> MeteredField<'a> {
 
     /// Read the whole field into owned bytes, metering every chunk against the
     /// aggregate cap.
-    pub async fn bytes(self) -> Result<axum::body::Bytes, TypedMultipartError> {
+    pub async fn bytes(mut self) -> Result<axum::body::Bytes, TypedMultipartError> {
         self.bytes_with_limit_inner(None, 0)
             .await
             .map(axum::body::Bytes::from)
@@ -430,7 +430,7 @@ impl<'a> MeteredField<'a> {
     /// The limit is checked before copying each chunk into the accumulator, and
     /// every chunk is still counted against the request-wide aggregate cap.
     pub async fn bytes_with_limit(
-        self,
+        mut self,
         limit_bytes: usize,
         initial_capacity: usize,
     ) -> Result<axum::body::Bytes, TypedMultipartError> {
@@ -440,7 +440,7 @@ impl<'a> MeteredField<'a> {
     }
 
     async fn bytes_with_limit_inner(
-        mut self,
+        &mut self,
         limit: Option<usize>,
         initial_capacity: usize,
     ) -> Result<Vec<u8>, TypedMultipartError> {
@@ -848,20 +848,24 @@ where
 ///
 /// When a limit is set the cumulative size is checked after each chunk
 /// and an over-limit chunk is rejected *before* it is copied in.
+struct FieldBytes<'a> {
+    field: MeteredField<'a>,
+    data: Vec<u8>,
+}
+
 async fn read_field_data(
-    field: MeteredField<'_>,
+    mut field: MeteredField<'_>,
     limit: Option<usize>,
     initial_capacity: usize,
-) -> Result<(String, Vec<u8>), TypedMultipartError> {
+) -> Result<FieldBytes<'_>, TypedMultipartError> {
     // Part counting now happens once per part in the derived loop
     // (`register_multipart_part`), so the field parsers no longer count.
     // Initial capacity is independent from the hard byte limit: tiny scalar
     // fields keep the 256B cap without preallocating 256B per bool/number.
-    let field_name = field.name().unwrap_or_default().to_string();
     let buf = field
         .bytes_with_limit_inner(limit, initial_capacity)
         .await?;
-    Ok((field_name, buf))
+    Ok(FieldBytes { field, data: buf })
 }
 
 /// Default cap for tiny scalar multipart fields when no explicit

crates/vespera/src/multipart/scalar_parsers.rs

@@ -25,10 +25,10 @@ impl<S: Send + Sync> TryFromFieldWithState<S> for String {
         // `Some(usize::MAX)` (set by the derive macro) and stays unbounded;
         // an explicit byte size wins as `Some(n)`.
         let limit = limit_bytes.unwrap_or(DEFAULT_STRING_FIELD_LIMIT_BYTES);
-        let (field_name, data) =
-            read_field_data(field, Some(limit), STRING_INITIAL_CAPACITY_BYTES).await?;
+        let field_data = read_field_data(field, Some(limit), STRING_INITIAL_CAPACITY_BYTES).await?;
+        let super::FieldBytes { field, data } = field_data;
         Self::from_utf8(data).map_err(|e| TypedMultipartError::WrongFieldType {
-            field_name,
+            field_name: field.name().unwrap_or_default().to_string(),
             wanted: Cow::Borrowed("String"),
             source: e.to_string(),
         })
@@ -43,19 +43,20 @@ impl<S: Send + Sync> TryFromFieldWithState<S> for bool {
         limit_bytes: Option<usize>,
         _state: &S,
     ) -> Result<Self, TypedMultipartError> {
-        let (field_name, data) = read_field_data(
+        let field_data = read_field_data(
             field,
             Some(tiny_scalar_limit(limit_bytes)),
             TINY_SCALAR_INITIAL_CAPACITY_BYTES,
         )
         .await?;
+        let super::FieldBytes { field, data } = field_data;
         let text = std::str::from_utf8(&data).map_err(|e| TypedMultipartError::WrongFieldType {
-            field_name: field_name.clone(),
+            field_name: field.name().unwrap_or_default().to_string(),
             wanted: Cow::Borrowed("bool"),
             source: e.to_string(),
         })?;
         str_to_bool(text).ok_or_else(|| TypedMultipartError::WrongFieldType {
-            field_name,
+            field_name: field.name().unwrap_or_default().to_string(),
             wanted: Cow::Borrowed("bool"),
             source: format!(
                 "invalid boolean value: `{}`",
@@ -76,21 +77,22 @@ macro_rules! impl_try_from_field_for_number {
                     limit_bytes: Option<usize>,
                     _state: &S,
                 ) -> Result<Self, TypedMultipartError> {
-                    let (field_name, data) = read_field_data(
+                    let field_data = read_field_data(
                         field,
                         Some(tiny_scalar_limit(limit_bytes)),
                         TINY_SCALAR_INITIAL_CAPACITY_BYTES,
                     ).await?;
+                    let super::FieldBytes { field, data } = field_data;
                     let text = std::str::from_utf8(&data).map_err(|e| {
                         TypedMultipartError::WrongFieldType {
-                            field_name: field_name.clone(),
+                            field_name: field.name().unwrap_or_default().to_string(),
                             wanted: Cow::Borrowed(stringify!($ty)),
                             source: e.to_string(),
                         }
                     })?;
                     text.trim().parse::<$ty>().map_err(|e| {
                         TypedMultipartError::WrongFieldType {
-                            field_name,
+                            field_name: field.name().unwrap_or_default().to_string(),
                             wanted: Cow::Borrowed(stringify!($ty)),
                             source: e.to_string(),
                         }
@@ -113,22 +115,23 @@ impl<S: Send + Sync> TryFromFieldWithState<S> for char {
         limit_bytes: Option<usize>,
         _state: &S,
     ) -> Result<Self, TypedMultipartError> {
-        let (field_name, data) = read_field_data(
+        let field_data = read_field_data(
             field,
             Some(tiny_scalar_limit(limit_bytes)),
             TINY_SCALAR_INITIAL_CAPACITY_BYTES,
         )
         .await?;
+        let super::FieldBytes { field, data } = field_data;
         let text = std::str::from_utf8(&data).map_err(|e| TypedMultipartError::WrongFieldType {
-            field_name: field_name.clone(),
+            field_name: field.name().unwrap_or_default().to_string(),
             wanted: Cow::Borrowed("char"),
             source: e.to_string(),
         })?;
         let mut chars = text.chars();
         match (chars.next(), chars.next()) {
             (Some(c), None) => Ok(c),
             _ => Err(TypedMultipartError::WrongFieldType {
-                field_name,
+                field_name: field.name().unwrap_or_default().to_string(),
                 wanted: Cow::Borrowed("char"),
                 source: "expected exactly one character".to_string(),
             }),

crates/vespera/src/validated.rs

@@ -30,8 +30,8 @@
 
 use ::axum::{
     Json,
-    extract::{FromRequest, Request},
-    http::{StatusCode, header::CONTENT_TYPE},
+    extract::{FromRequest, FromRequestParts, Request},
+    http::{HeaderValue, StatusCode, header::CONTENT_TYPE, request::Parts},
     response::{IntoResponse, Response},
 };
 use ::garde::Validate;
@@ -185,65 +185,44 @@ impl<C, T> DerefMut for ValidatedWith<C, T> {
     }
 }
 
-impl<U> ValidatePayload for Json<U>
+impl<T> ValidatePayload for T
 where
-    U: Validate<Context = ()>,
+    T: ValidatePayloadWith<()>,
 {
-    type Inner = U;
-    fn payload(&self) -> &U {
-        &self.0
-    }
-}
+    type Inner = <T as ValidatePayloadWith<()>>::Inner;
 
-impl<U> ValidatePayload for ::axum::Form<U>
-where
-    U: Validate<Context = ()>,
-{
-    type Inner = U;
-    fn payload(&self) -> &U {
-        &self.0
+    fn payload(&self) -> &Self::Inner {
+        <Self as ValidatePayloadWith<()>>::payload(self)
     }
 }
 
-impl<U> ValidatePayload for ::axum::extract::Query<U>
-where
-    U: Validate<Context = ()>,
-{
-    type Inner = U;
-    fn payload(&self) -> &U {
-        &self.0
-    }
-}
-
-impl<U> ValidatePayload for ::axum::extract::Path<U>
+impl<S, T> FromRequest<S> for Validated<T>
 where
-    U: Validate<Context = ()>,
+    S: Send + Sync,
+    T: FromRequest<S> + ValidatePayload + Send,
 {
-    type Inner = U;
-    fn payload(&self) -> &U {
-        &self.0
-    }
-}
+    type Rejection = Response;
 
-impl<U> ValidatePayload for crate::multipart::TypedMultipart<U>
-where
-    U: Validate<Context = ()>,
-{
-    type Inner = U;
-    fn payload(&self) -> &U {
-        &self.0
+    async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection> {
+        let extracted = T::from_request(req, state)
+            .await
+            .map_err(IntoResponse::into_response)?;
+        match extracted.payload().validate() {
+            Ok(()) => Ok(Self(extracted)),
+            Err(report) => Err(build_validation_response(&report)),
+        }
     }
 }
 
-impl<S, T> FromRequest<S> for Validated<T>
+impl<S, T> FromRequestParts<S> for Validated<T>
 where
     S: Send + Sync,
-    T: FromRequest<S> + ValidatePayload + Send,
+    T: FromRequestParts<S> + ValidatePayload + Send,
 {
     type Rejection = Response;
 
-    async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection> {
-        let extracted = T::from_request(req, state)
+    async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+        let extracted = T::from_request_parts(parts, state)
             .await
             .map_err(IntoResponse::into_response)?;
         match extracted.payload().validate() {
@@ -275,6 +254,28 @@ where
     }
 }
 
+impl<S, C, T> FromRequestParts<S> for ValidatedWith<C, T>
+where
+    S: Send + Sync + ValidationContext<C>,
+    C: Send + Sync + 'static,
+    T: FromRequestParts<S> + ValidatePayloadWith<C> + Send,
+{
+    type Rejection = Response;
+
+    async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+        let extracted = T::from_request_parts(parts, state)
+            .await
+            .map_err(IntoResponse::into_response)?;
+        match extracted
+            .payload()
+            .validate_with(state.validation_context())
+        {
+            Ok(()) => Ok(Self::new(extracted)),
+            Err(report) => Err(build_validation_response(&report)),
+        }
+    }
+}
+
 /// Build the canonical `422 Unprocessable Entity` response from a
 /// [`garde::Report`].
 ///
@@ -374,10 +375,10 @@ fn build_validation_response(report: &::garde::Report) -> Response {
         br#"{"errors":[{"message":"request validation failed","path":""}]}"#.to_vec()
     });
 
-    let mut response = (StatusCode::UNPROCESSABLE_ENTITY, body).into_response();
-    response.headers_mut().insert(
-        CONTENT_TYPE,
-        ::axum::http::HeaderValue::from_static("application/json"),
-    );
-    response
+    (
+        StatusCode::UNPROCESSABLE_ENTITY,
+        [(CONTENT_TYPE, HeaderValue::from_static("application/json"))],
+        body,
+    )
+        .into_response()
 }