satay_codegen/render/
mod.rs

1use proc_macro2::{Span, TokenStream};
2use quote::quote;
3use syn::{Ident, LitStr, parse_quote};
4use tracing::info;
5
6use crate::model::{Api, Field, IntegerType, Operation, ParseAs, RangeScalar, TypeRef};
7use crate::{GenerateOptions, RootModule};
8
9const PREAMBLE: &str = "\
10//! @generated by satay. Do not edit by hand.
11
12";
13
14#[derive(Debug)]
15pub struct GeneratedFile {
16    pub relative_path: String,
17    pub contents: String,
18}
19
20pub(crate) fn render_api(api: &Api, options: GenerateOptions) -> Vec<GeneratedFile> {
21    info!(
22        components = api.components.len(),
23        operations = api.operations.len(),
24        "rendering API"
25    );
26    let mut files = vec![];
27
28    let root_module = match options.root_module {
29        RootModule::ModRs => "mod.rs",
30        RootModule::LibRs => "lib.rs",
31    };
32    let top_mod = render_top_mod(api);
33    files.push(GeneratedFile {
34        relative_path: root_module.to_owned(),
35        contents: format_file(top_mod),
36    });
37
38    if !api.components.is_empty() || !api.constrained_types.is_empty() {
39        let types_file = types::render_types_file(api);
40        files.push(GeneratedFile {
41            relative_path: "types.rs".to_owned(),
42            contents: format_file(types_file),
43        });
44    }
45
46    let api_file = api::render_api_file(api);
47    files.push(GeneratedFile {
48        relative_path: "api.rs".to_owned(),
49        contents: format_file(api_file),
50    });
51
52    for operation in &api.operations {
53        let dir = &operation.fn_name;
54        let endpoint_mod = endpoint::render_endpoint_mod(operation);
55        files.push(GeneratedFile {
56            relative_path: format!("{dir}/mod.rs"),
57            contents: format_file(endpoint_mod),
58        });
59
60        let parts_file = endpoint::render_endpoint_parts_file(api, operation);
61        files.push(GeneratedFile {
62            relative_path: format!("{dir}/parts.rs"),
63            contents: format_file(parts_file),
64        });
65
66        let json_file = endpoint::render_endpoint_json_file(api, operation);
67        files.push(GeneratedFile {
68            relative_path: format!("{dir}/json.rs"),
69            contents: format_file(json_file),
70        });
71    }
72
73    info!(files = files.len(), "rendered API");
74    files
75}
76
77fn format_file(file: syn::File) -> String {
78    let code = prettyplease::unparse(&file);
79    let mut formatted = String::with_capacity(PREAMBLE.len() + code.len());
80    formatted.push_str(PREAMBLE);
81    formatted.push_str(&code);
82    formatted
83}
84
85fn render_top_mod(api: &Api) -> syn::File {
86    let mut items: Vec<syn::Item> = vec![];
87    let server_url = lit_str(&api.server_url);
88    items.push(parse_quote!(pub const SERVER_URL: &str = #server_url;));
89
90    let has_types = !api.components.is_empty() || !api.constrained_types.is_empty();
91    if has_types {
92        items.push(parse_quote!(
93            pub mod types;
94        ));
95        items.push(parse_quote!(
96            pub use types::*;
97        ));
98    }
99
100    items.push(parse_quote!(
101        #[cfg(feature = "json")]
102        mod api;
103    ));
104    items.push(parse_quote!(
105        #[cfg(feature = "json")]
106        pub use api::*;
107    ));
108
109    for operation in &api.operations {
110        let module = ident(&operation.fn_name);
111        items.push(parse_quote!(pub mod #module;));
112        items.push(parse_quote!(pub use #module::*;));
113    }
114
115    syn::File {
116        shebang: None,
117        attrs: vec![],
118        items,
119    }
120}
121
122pub fn ident(value: &str) -> Ident {
123    Ident::new(value, Span::call_site())
124}
125
126pub fn lit_str(value: &str) -> LitStr {
127    LitStr::new(value, Span::call_site())
128}
129
130pub fn doc_attrs(description: Option<&str>) -> Vec<syn::Attribute> {
131    let Some(description) = description.filter(|description| !description.trim().is_empty()) else {
132        return vec![];
133    };
134
135    description
136        .lines()
137        .map(|line| {
138            let doc_line = if line.is_empty() {
139                String::new()
140            } else {
141                format!(" {line}")
142            };
143            let doc_line = lit_str(&doc_line);
144            parse_quote!(#[doc = #doc_line])
145        })
146        .collect()
147}
148
149pub fn rust_type(ty: &TypeRef) -> syn::Type {
150    match ty {
151        TypeRef::String => parse_quote!(String),
152        TypeRef::ParsedString(parse_as) | TypeRef::ParsedInteger(parse_as) => {
153            parse_as_rust_type(*parse_as)
154        }
155        TypeRef::Integer(integer_type) => integer_rust_type(*integer_type),
156        TypeRef::F32 => parse_quote!(f32),
157        TypeRef::F64 => parse_quote!(f64),
158        TypeRef::Bool => parse_quote!(bool),
159        TypeRef::Array(item) => {
160            let item = rust_type(item);
161            parse_quote!(Vec<#item>)
162        }
163        TypeRef::Range(range_type) => {
164            let name = ident(&range_type.rust_name);
165            parse_quote!(#name)
166        }
167        TypeRef::Named(name)
168        | TypeRef::Constrained {
169            rust_name: name, ..
170        } => {
171            let name = ident(name);
172            parse_quote!(#name)
173        }
174        TypeRef::Option(inner) => {
175            let inner = rust_type(inner);
176            parse_quote!(Option<#inner>)
177        }
178    }
179}
180
181pub fn range_scalar_rust_type(scalar: RangeScalar) -> syn::Type {
182    match scalar {
183        RangeScalar::Integer(integer_type) => integer_rust_type(integer_type),
184        RangeScalar::F32 => parse_quote!(f32),
185        RangeScalar::F64 => parse_quote!(f64),
186    }
187}
188
189pub fn integer_rust_type(integer_type: IntegerType) -> syn::Type {
190    match integer_type {
191        IntegerType::U8 => parse_quote!(u8),
192        IntegerType::U16 => parse_quote!(u16),
193        IntegerType::U32 => parse_quote!(u32),
194        IntegerType::U64 => parse_quote!(u64),
195        IntegerType::I8 => parse_quote!(i8),
196        IntegerType::I16 => parse_quote!(i16),
197        IntegerType::I32 => parse_quote!(i32),
198        IntegerType::I64 => parse_quote!(i64),
199    }
200}
201
202pub fn parse_as_rust_type(parse_as: ParseAs) -> syn::Type {
203    match parse_as {
204        ParseAs::U8 => parse_quote!(u8),
205        ParseAs::U16 => parse_quote!(u16),
206        ParseAs::U32 => parse_quote!(u32),
207        ParseAs::U64 => parse_quote!(u64),
208        ParseAs::I8 => parse_quote!(i8),
209        ParseAs::I16 => parse_quote!(i16),
210        ParseAs::I32 => parse_quote!(i32),
211        ParseAs::I64 => parse_quote!(i64),
212        ParseAs::F32 => parse_quote!(f32),
213        ParseAs::F64 => parse_quote!(f64),
214        ParseAs::Bool => parse_quote!(bool),
215        ParseAs::Date => parse_quote!(satay_runtime::Date),
216        ParseAs::NaiveDateTime => parse_quote!(satay_runtime::PrimitiveDateTime),
217        ParseAs::OffsetDateTime => parse_quote!(satay_runtime::OffsetDateTime),
218        ParseAs::Time => parse_quote!(satay_runtime::Time),
219        ParseAs::IntegerRange | ParseAs::NumberRange => {
220            unreachable!("range parse-as uses generated range types")
221        }
222    }
223}
224
225pub fn parse_as_string_serde_module(parse_as: ParseAs) -> &'static str {
226    match parse_as {
227        ParseAs::U8 => "satay_runtime::serde_string::as_u8",
228        ParseAs::U16 => "satay_runtime::serde_string::as_u16",
229        ParseAs::U32 => "satay_runtime::serde_string::as_u32",
230        ParseAs::U64 => "satay_runtime::serde_string::as_u64",
231        ParseAs::I8 => "satay_runtime::serde_string::as_i8",
232        ParseAs::I16 => "satay_runtime::serde_string::as_i16",
233        ParseAs::I32 => "satay_runtime::serde_string::as_i32",
234        ParseAs::I64 => "satay_runtime::serde_string::as_i64",
235        ParseAs::F32 => "satay_runtime::serde_string::as_f32",
236        ParseAs::F64 => "satay_runtime::serde_string::as_f64",
237        ParseAs::Bool => "satay_runtime::serde_string::as_bool",
238        ParseAs::Date => "satay_runtime::serde_string::as_date",
239        ParseAs::NaiveDateTime => "satay_runtime::serde_string::as_naive_datetime",
240        ParseAs::OffsetDateTime => "satay_runtime::serde_string::as_offset_datetime",
241        ParseAs::Time => "satay_runtime::serde_string::as_time",
242        ParseAs::IntegerRange | ParseAs::NumberRange => {
243            unreachable!("range parse-as uses generated range types")
244        }
245    }
246}
247
248pub fn parse_as_integer_serde_module(parse_as: ParseAs) -> &'static str {
249    match parse_as {
250        ParseAs::Bool => "satay_runtime::serde_integer::as_bool",
251        ParseAs::U8
252        | ParseAs::U16
253        | ParseAs::U32
254        | ParseAs::U64
255        | ParseAs::I8
256        | ParseAs::I16
257        | ParseAs::I32
258        | ParseAs::I64
259        | ParseAs::F32
260        | ParseAs::F64
261        | ParseAs::Date
262        | ParseAs::NaiveDateTime
263        | ParseAs::OffsetDateTime
264        | ParseAs::Time
265        | ParseAs::IntegerRange
266        | ParseAs::NumberRange => unreachable!("only bool can parse from integer"),
267    }
268}
269
270pub fn rust_field_type(ty: &TypeRef, required: bool, treat_error_as_none: bool) -> syn::Type {
271    if (required && !treat_error_as_none) || ty.is_option() {
272        rust_type(ty)
273    } else {
274        let ty = rust_type(ty);
275        parse_quote!(Option<#ty>)
276    }
277}
278
279pub fn input_fields(operation: &Operation) -> Vec<Field> {
280    let mut input_fields = Vec::with_capacity(
281        operation.parameters.len() + usize::from(operation.request_body.is_some()),
282    );
283    input_fields.extend(operation.parameters.iter().map(|parameter| Field {
284        wire_name: parameter.wire_name.clone(),
285        rust_name: parameter.rust_name.clone(),
286        description: parameter.description.clone(),
287        ty: parameter.ty.clone(),
288        required: parameter.required,
289        treat_error_as_none: false,
290    }));
291    if let Some(body) = &operation.request_body {
292        input_fields.push(Field {
293            wire_name: body.field_name.clone(),
294            rust_name: body.field_name.clone(),
295            description: body.description.clone(),
296            ty: body.ty.clone(),
297            required: body.required,
298            treat_error_as_none: false,
299        });
300    }
301
302    input_fields
303}
304
305pub fn input_setter_name(field: &Field) -> Ident {
306    if field.rust_name == "new" {
307        ident("with_new")
308    } else {
309        ident(&field.rust_name)
310    }
311}
312
313pub fn input_builder_arg_type(ty: &TypeRef) -> TokenStream {
314    if ty == &TypeRef::String {
315        quote!(impl Into<String>)
316    } else {
317        let ty = rust_type(ty);
318        quote!(#ty)
319    }
320}
321
322pub fn input_builder_value(value: TokenStream, ty: &TypeRef) -> TokenStream {
323    if ty == &TypeRef::String {
324        quote!(#value.into())
325    } else {
326        value
327    }
328}
329
330pub fn request_from_parts_expr(operation: &Operation) -> syn::Expr {
331    match &operation.request_body {
332        Some(body) if body.required => parse_quote!(satay_runtime::into_json_request(parts)),
333        Some(_) => parse_quote!(satay_runtime::into_optional_json_request(parts)),
334        None => parse_quote!(satay_runtime::into_empty_request(parts)),
335    }
336}
337
338pub fn input_field(field: &str) -> syn::Expr {
339    let field = ident(field);
340    parse_quote!(input.#field)
341}
342
343mod api;
344mod endpoint;
345mod types;
346
347#[cfg(test)]
348mod tests {
349    use super::*;
350    use crate::model::PathSegment;
351    use crate::model::{Component, ComponentKind, HttpMethod, RequestBody, ResponseCase};
352    use quote::{ToTokens, quote};
353    use syn::{Fields, GenericArgument, Item, PathArguments, Type};
354
355    #[test]
356    fn render_file_exposes_struct_ast_without_source_comparison() {
357        let api = Api::new(
358            String::new(),
359            vec![],
360            vec![Component {
361                rust_name: "Pet".to_owned(),
362                description: None,
363                kind: ComponentKind::Struct(vec![
364                    Field {
365                        wire_name: "id".to_owned(),
366                        rust_name: "id".to_owned(),
367                        description: None,
368                        ty: TypeRef::String,
369                        required: true,
370                        treat_error_as_none: false,
371                    },
372                    Field {
373                        wire_name: "tag_count".to_owned(),
374                        rust_name: "tag_count".to_owned(),
375                        description: None,
376                        ty: TypeRef::Integer(IntegerType::I32),
377                        required: false,
378                        treat_error_as_none: false,
379                    },
380                ]),
381            }],
382            vec![],
383            vec![],
384        );
385
386        let file = types::render_types_file(&api);
387        assert_eq!(file.items.len(), 1);
388        let Item::Struct(item) = &file.items[0] else {
389            panic!("expected struct item");
390        };
391        assert_eq!(item.ident, "Pet");
392        let Fields::Named(fields) = &item.fields else {
393            panic!("expected named fields");
394        };
395        assert_eq!(fields.named.len(), 2);
396
397        let mut fields = fields.named.iter();
398        let id = fields.next().expect("id field");
399        assert_eq!(id.ident.as_ref().expect("field ident"), "id");
400        assert!(type_path_is(&id.ty, "String"));
401
402        let tag_count = fields.next().expect("tag_count field");
403        assert_eq!(tag_count.ident.as_ref().expect("field ident"), "tag_count");
404        let Some(inner) = option_inner(&tag_count.ty) else {
405            panic!("optional field should render as Option<T>");
406        };
407        assert!(type_path_is(inner, "i32"));
408    }
409
410    #[test]
411    fn render_file_exposes_operation_items_without_source_comparison() {
412        let api = Api::new(
413            String::new(),
414            vec![],
415            vec![],
416            vec![],
417            vec![Operation {
418                fn_name: "create_pet".to_owned(),
419                description: None,
420                input_name: "CreatePetInput".to_owned(),
421                response_name: "CreatePetResponse".to_owned(),
422                method: HttpMethod::Post,
423                path: "/pets".to_owned(),
424                path_segments: vec![PathSegment::Literal("/pets".to_owned())],
425                parameters: vec![],
426                request_body: Some(RequestBody {
427                    field_name: "body".to_owned(),
428                    description: None,
429                    content_type: "application/json".to_owned(),
430                    ty: TypeRef::Named("Pet".to_owned()),
431                    required: true,
432                }),
433                responses: vec![ResponseCase {
434                    status: 201,
435                    variant_name: "Created".to_owned(),
436                    description: None,
437                    body: Some(TypeRef::Named("Pet".to_owned())),
438                }],
439            }],
440        );
441
442        let files = render_api(&api, GenerateOptions::default());
443        assert!(files.iter().any(|f| f.relative_path == "mod.rs"));
444        assert!(files.iter().any(|f| f.relative_path == "create_pet/mod.rs"));
445        assert!(
446            files
447                .iter()
448                .any(|f| f.relative_path == "create_pet/parts.rs")
449        );
450        assert!(
451            files
452                .iter()
453                .any(|f| f.relative_path == "create_pet/json.rs")
454        );
455    }
456
457    #[test]
458    fn rust_field_type_wraps_optional_and_treat_error_as_none_fields() {
459        assert_eq!(
460            rust_field_type(&TypeRef::String, true, false)
461                .to_token_stream()
462                .to_string(),
463            "String"
464        );
465        assert_eq!(
466            rust_field_type(&TypeRef::String, false, false)
467                .to_token_stream()
468                .to_string(),
469            "Option < String >"
470        );
471        assert_eq!(
472            rust_field_type(&TypeRef::String, true, true)
473                .to_token_stream()
474                .to_string(),
475            "Option < String >"
476        );
477        assert_eq!(
478            rust_field_type(&TypeRef::Option(Box::new(TypeRef::String)), true, false)
479                .to_token_stream()
480                .to_string(),
481            "Option < String >"
482        );
483    }
484
485    #[test]
486    fn input_builder_arguments_convert_strings_only() {
487        assert_eq!(
488            input_builder_arg_type(&TypeRef::String).to_string(),
489            "impl Into < String >"
490        );
491        assert_eq!(
492            input_builder_arg_type(&TypeRef::Integer(IntegerType::I32)).to_string(),
493            "i32"
494        );
495        assert_eq!(
496            input_builder_value(quote!(value), &TypeRef::String).to_string(),
497            "value . into ()"
498        );
499        assert_eq!(
500            input_builder_value(quote!(value), &TypeRef::Integer(IntegerType::I32)).to_string(),
501            "value"
502        );
503    }
504
505    #[test]
506    fn request_conversion_mode_matches_body_requirement() {
507        assert_eq!(
508            request_from_parts_expr(&operation_with_body(None))
509                .to_token_stream()
510                .to_string(),
511            "satay_runtime :: into_empty_request (parts)"
512        );
513        assert_eq!(
514            request_from_parts_expr(&operation_with_body(Some(true)))
515                .to_token_stream()
516                .to_string(),
517            "satay_runtime :: into_json_request (parts)"
518        );
519        assert_eq!(
520            request_from_parts_expr(&operation_with_body(Some(false)))
521                .to_token_stream()
522                .to_string(),
523            "satay_runtime :: into_optional_json_request (parts)"
524        );
525    }
526
527    fn operation_with_body(required: Option<bool>) -> Operation {
528        Operation {
529            fn_name: "create_pet".to_owned(),
530            description: None,
531            input_name: "CreatePetInput".to_owned(),
532            response_name: "CreatePetResponse".to_owned(),
533            method: HttpMethod::Post,
534            path: "/pets".to_owned(),
535            path_segments: vec![PathSegment::Literal("/pets".to_owned())],
536            parameters: vec![],
537            request_body: required.map(|required| RequestBody {
538                field_name: "body".to_owned(),
539                description: None,
540                content_type: "application/json".to_owned(),
541                ty: TypeRef::Named("Pet".to_owned()),
542                required,
543            }),
544            responses: vec![],
545        }
546    }
547
548    fn type_path_is(ty: &syn::Type, expected: &str) -> bool {
549        let Type::Path(path) = ty else {
550            return false;
551        };
552        path.path.is_ident(expected)
553    }
554
555    fn option_inner(ty: &syn::Type) -> Option<&syn::Type> {
556        let Type::Path(path) = ty else {
557            return None;
558        };
559        let segment = path.path.segments.first()?;
560        if segment.ident != "Option" {
561            return None;
562        }
563        let PathArguments::AngleBracketed(arguments) = &segment.arguments else {
564            return None;
565        };
566        let GenericArgument::Type(inner) = arguments.args.first()? else {
567            return None;
568        };
569        Some(inner)
570    }
571}
satay_codegen/render/mod.rs

satay_codegen/render/
mod.rs
