olai-codegen 0.0.4

//! Low-level HTTP client generation.
//!
//! This is part of the **Generation** stage of the Analysis → Planning → Generation → Output
//! pipeline (see [`super`]). For each service it emits a low-level client struct holding a
//! transport client plus a base [`Url`](url::Url), with one async method per RPC that builds the
//! request URL, serializes the body, and dispatches through the configured transport. The client
//! is written to each service's `client.rs` and is the foundation that the request builders in
//! [`super::builder`] and the ergonomic resource clients in [`super::resource_client`] build upon.
//!
//! The transport type is configurable (`transport_type_path`): the default cloud transport and the
//! WASM browser transport are both selected here. URL routing, parameter sources, and body shape
//! all come from the per-method [`GenerationPlan`](crate::analysis::GenerationPlan) produced during
//! Planning; the emitted token stream is pretty-printed via `super::format_tokens`.

use itertools::Itertools;
use proc_macro2::TokenStream;
use quote::{format_ident, quote};

use super::{doc_tokens, extract_type_ident, format_tokens};
use crate::Result;
use crate::codegen::{MethodHandler, Runtime, ServiceHandler};
use crate::parsing::types::BaseType;

/// Generate client code for a service
pub(crate) fn generate(service: &ServiceHandler<'_>) -> Result<String> {
    let mut method_tokens = Vec::new();

    for method in service.methods() {
        let method_code = client_method(method);
        method_tokens.push(method_code);
    }

    let client_ident = service.low_level_client_type();
    let mod_path = service.models_path();
    let result_path: syn::Path =
        syn::parse_str(&service.config.result_type_path).expect("valid result_type_path");
    let (transport_import, transport_ident) = transport_tokens(service.config);

    let tokens = quote! {
        // `use #mod_path::*` is a convenience-wide model glob; a service that
        // references only some model types (common under buffa) would otherwise
        // trip `unused_imports` under `-D warnings`.
        #![allow(unused_imports)]
        #transport_import
        use url::Url;
        use #result_path;
        use #mod_path::*;

        /// HTTP client for service operations
        #[derive(Clone)]
        pub struct #client_ident {
            pub(crate) client: #transport_ident,
            pub(crate) base_url: Url,
        }

        impl #client_ident {
            /// Create a new client instance
            pub fn new(client: #transport_ident, mut base_url: Url) -> Self {
                if !base_url.path().ends_with('/') {
                    base_url.set_path(&format!("{}/", base_url.path()));
                }
                Self { client, base_url }
            }

            #(#method_tokens)*
        }
    };

    format_tokens(tokens)
}

/// The transport import + the identifier generated client code refers to it by.
///
/// - **Single transport** (default): emit `use <transport_type_path>;` and refer
///   to the transport by its final segment (`CloudClient`), keeping native-only
///   output simple.
/// - **Dual transport** ([`CodeGenConfig::dual_transport`], i.e. WASM output is
///   enabled): emit a `cfg(target_arch = "wasm32")`-gated alias so the one client
///   crate builds natively against `CloudClient` and for the browser against
///   `olai_http_wasm::WasmClient`, and refer to it by the alias `Transport`.
pub(crate) fn transport_tokens(
    config: &crate::codegen::CodeGenConfig,
) -> (TokenStream, proc_macro2::Ident) {
    if config.dual_transport() {
        let import = quote! {
            #[cfg(not(target_arch = "wasm32"))]
            use ::olai_http::CloudClient as Transport;
            #[cfg(target_arch = "wasm32")]
            use ::olai_http_wasm::WasmClient as Transport;
        };
        (import, format_ident!("Transport"))
    } else {
        let transport_path: syn::Path =
            syn::parse_str(&config.transport_type_path).expect("valid transport_type_path");
        let ident = transport_path
            .segments
            .last()
            .expect("transport_type_path has at least one segment")
            .ident
            .clone();
        (quote! { use #transport_path; }, ident)
    }
}

/// Generate client method implementation
pub fn client_method(method: MethodHandler<'_>) -> TokenStream {
    let doc_attrs = doc_tokens(method.plan.metadata.documentation.as_deref());
    let method_name = method.plan.base_method_ident();
    let input_type_ident = method.input_type();
    let http_method = format_ident!("{}", method.plan.http_method.to_lowercase());
    let has_query_params = method.plan.query_parameters().next().is_some();
    let url_formatting = generate_url_formatting(&method, has_query_params);
    let query_handling = generate_query_parameters(&method);

    let body_handling = if method.plan.has_request_body {
        quote! { .json(request) }
    } else {
        quote! {}
    };

    if let Some(output_type) = method.output_type() {
        quote! {
            #doc_attrs
            pub async fn #method_name(&self, request: &#input_type_ident) -> Result<#output_type> {
                #url_formatting
                #query_handling
                let response = self.client.#http_method(url)#body_handling.send().await?;
                if !response.status().is_success() {
                    return Err(crate::error::parse_error_response(response).await);
                }
                let result = response.bytes().await?;
                Ok(serde_json::from_slice(&result)?)
            }
        }
    } else {
        quote! {
            #doc_attrs
            pub async fn #method_name(&self, request: &#input_type_ident) -> Result<()> {
                #url_formatting
                #query_handling
                let response = self.client.#http_method(url)#body_handling.send().await?;
                if !response.status().is_success() {
                    return Err(crate::error::parse_error_response(response).await);
                }
                Ok(())
            }
        }
    }
}

/// Generate URL formatting code that properly substitutes path parameters.
///
/// `needs_mut` controls whether the generated `url` binding is declared `mut`.
/// Pass `true` only when query parameters will be appended via `url.query_pairs_mut()`.
fn generate_url_formatting(
    method: &MethodHandler<'_>,
    needs_mut: bool,
) -> proc_macro2::TokenStream {
    let path = method.plan.http_pattern.base_path();
    let path = path.trim_start_matches('/');
    let params = method.plan.path_parameters().collect_vec();

    // Only the binding's mutability differs between the two callers.
    let mut_kw = if needs_mut {
        quote! { mut }
    } else {
        quote! {}
    };

    let (format_string, format_args) = method.plan.http_pattern.to_format_string();

    // No path params (or a template with no args) -> direct join; otherwise format then join.
    if params.is_empty() || format_args.is_empty() {
        quote! {
            let #mut_kw url = self.base_url.join(#path)?;
        }
    } else {
        let field_idents: Vec<_> = format_args
            .iter()
            .map(|template_param| format_ident!("{}", template_param))
            .collect();
        quote! {
            let formatted_path = format!(#format_string, #(request.#field_idents),*);
            let #mut_kw url = self.base_url.join(&formatted_path)?;
        }
    }
}

/// Generate query parameter handling code
fn generate_query_parameters(method: &MethodHandler<'_>) -> proc_macro2::TokenStream {
    let mut param_assignments = Vec::new();
    for param in method.plan.query_parameters() {
        let field_ident = format_ident!("{}", param.name);
        let param_name = &param.name;
        let field_type = &param.field_type;

        if field_type.is_repeated {
            if let BaseType::Enum(enum_name) = &field_type.base_type {
                let enum_type_ident = extract_type_ident(enum_name);
                param_assignments.push(match method.config.runtime {
                    // prost: the field is `Vec<i32>`; recover the typed variant via `from_i32`.
                    Runtime::Prost => quote! {
                        for &raw in &request.#field_ident {
                            if let Some(v) = #enum_type_ident::from_i32(raw) {
                                url.query_pairs_mut().append_pair(#param_name, v.as_str_name());
                            }
                        }
                    },
                    // buffa: the field is `Vec<EnumValue<E>>`; emit only known variants by name.
                    Runtime::Buffa => quote! {
                        for v in &request.#field_ident {
                            if let Some(known) = v.as_known() {
                                use buffa::Enumeration as _;
                                url.query_pairs_mut().append_pair(#param_name, known.proto_name());
                            }
                        }
                    },
                });
            } else {
                param_assignments.push(quote! {
                    for value in &request.#field_ident {
                        url.query_pairs_mut().append_pair(#param_name, &value.to_string());
                    }
                });
            }
        } else if matches!(method.config.runtime, Runtime::Buffa)
            && matches!(field_type.base_type, BaseType::Enum(_))
        {
            // buffa singular enum: the field is `EnumValue<E>` (or `Option<EnumValue<E>>`), which
            // has no `Display`. Emit the known variant by its proto name; skip unknown/absent.
            if param.is_optional() {
                param_assignments.push(quote! {
                    if let Some(known) = request.#field_ident.and_then(|v| v.as_known()) {
                        use buffa::Enumeration as _;
                        url.query_pairs_mut().append_pair(#param_name, known.proto_name());
                    }
                });
            } else {
                param_assignments.push(quote! {
                    if let Some(known) = request.#field_ident.as_known() {
                        use buffa::Enumeration as _;
                        url.query_pairs_mut().append_pair(#param_name, known.proto_name());
                    }
                });
            }
        } else if param.is_optional() {
            param_assignments.push(quote! {
                if let Some(ref value) = request.#field_ident {
                    url.query_pairs_mut().append_pair(#param_name, &value.to_string());
                }
            });
        } else if matches!(field_type.base_type, BaseType::String) {
            // Required string param: always sent. Append the value directly (it is already a
            // `String`, so `.to_string()` would be redundant).
            param_assignments.push(quote! {
                url.query_pairs_mut().append_pair(#param_name, &request.#field_ident);
            });
        } else {
            // Required non-string scalar: always sent.
            param_assignments.push(quote! {
                url.query_pairs_mut().append_pair(#param_name, &request.#field_ident.to_string());
            });
        }
    }

    if param_assignments.is_empty() {
        return quote! {};
    }

    quote! {
        #(#param_assignments)*
    }
}