Skip to main content

hyprstream_rpc_derive/codegen/
scoped.rs

1//! Scoped client generation (e.g., RepositoryClient, ModelSessionClient).
2//!
3//! Uses a recursive approach with `ancestors` to support N-depth nesting.
4
5use proc_macro2::TokenStream;
6use quote::{format_ident, quote};
7
8use crate::codegen::client::{
9    generate_parse_match_arm, generate_portable_request_method,
10    generate_response_enum_from_variants, ScopedMethodContext,
11};
12use crate::resolve::ResolvedSchema;
13use crate::schema::types::*;
14use crate::util::*;
15
16/// Generate portable scoped client structs using `Arc<dyn RpcClient>`.
17/// No ZMQ deps, no jwt_token field — compiles on all targets.
18pub fn generate_portable_scoped_clients(
19    service_name: &str,
20    resolved: &ResolvedSchema,
21    types_crate: Option<&syn::Path>,
22) -> TokenStream {
23    let mut tokens = TokenStream::new();
24    let pascal = to_pascal_case(service_name);
25    let rust_service_name = service_name.replace('-', "_");
26    let capnp_mod_ident = format_ident!("{}_capnp", to_snake_case(&rust_service_name));
27    let capnp_mod: TokenStream = match types_crate {
28        Some(tc) => quote! { #tc::#capnp_mod_ident },
29        None => quote! { crate::#capnp_mod_ident },
30    };
31
32    for sc in &resolved.raw.scoped_clients {
33        walk_portable_scoped(
34            &mut tokens,
35            service_name,
36            &pascal,
37            &capnp_mod,
38            sc,
39            &[],
40            resolved,
41            types_crate,
42        );
43    }
44
45    tokens
46}
47
48/// Generate only the response enums and parse functions for scoped clients.
49/// No client structs, no transport deps — compiles on all targets including wasm32.
50pub fn generate_scoped_response_types(
51    service_name: &str,
52    resolved: &ResolvedSchema,
53    types_crate: Option<&syn::Path>,
54) -> TokenStream {
55    let mut tokens = TokenStream::new();
56    let pascal = to_pascal_case(service_name);
57    let capnp_mod_ident = format_ident!("{}_capnp", service_name);
58    let capnp_mod: TokenStream = match types_crate {
59        Some(tc) => quote! { #tc::#capnp_mod_ident },
60        None => quote! { crate::#capnp_mod_ident },
61    };
62
63    for sc in &resolved.raw.scoped_clients {
64        walk_scoped_response_types(
65            &mut tokens,
66            &pascal,
67            &capnp_mod,
68            sc,
69            &[],
70            resolved,
71            types_crate,
72        );
73    }
74
75    tokens
76}
77
78fn walk_scoped_response_types(
79    tokens: &mut TokenStream,
80    pascal: &str,
81    capnp_mod: &TokenStream,
82    sc: &ScopedClient,
83    ancestors: &[&ScopedClient],
84    resolved: &ResolvedSchema,
85    types_crate: Option<&syn::Path>,
86) {
87    tokens.extend(generate_scoped_response_only(
88        pascal,
89        capnp_mod,
90        sc,
91        ancestors,
92        resolved,
93        types_crate,
94    ));
95    let mut next_ancestors: Vec<&ScopedClient> = ancestors.to_vec();
96    next_ancestors.push(sc);
97    for nested in &sc.nested_clients {
98        walk_scoped_response_types(
99            tokens,
100            pascal,
101            capnp_mod,
102            nested,
103            &next_ancestors,
104            resolved,
105            types_crate,
106        );
107    }
108}
109
110/// Generate response enum + parse_scoped_response for one scoped client level.
111fn generate_scoped_response_only(
112    pascal: &str,
113    capnp_mod: &TokenStream,
114    sc: &ScopedClient,
115    ancestors: &[&ScopedClient],
116    resolved: &ResolvedSchema,
117    types_crate: Option<&syn::Path>,
118) -> TokenStream {
119    let _client_name = format_ident!("{}Client", to_pascal_case(&sc.client_name));
120    let response_type = format_ident!("{}ResponseVariant", to_pascal_case(&sc.client_name));
121
122    let response_enum = generate_response_enum_from_variants(
123        &response_type.to_string(),
124        &sc.inner_response_variants,
125        resolved,
126        types_crate,
127    );
128
129    // Build parse_scoped_response
130    let outer_resp_type = format_ident!("{}", to_snake_case(&format!("{pascal}Response")));
131    let full_chain: Vec<&ScopedClient> = ancestors
132        .iter()
133        .copied()
134        .chain(std::iter::once(sc))
135        .collect();
136
137    let mut levels = Vec::new();
138    for (i, level_sc) in full_chain.iter().enumerate() {
139        let resp_module = if i == 0 {
140            format_ident!("{}", to_snake_case(&format!("{pascal}Response")))
141        } else {
142            format_ident!("{}", full_chain[i - 1].capnp_inner_response)
143        };
144        let variant = format_ident!(
145            "{}",
146            to_pascal_case(&format!("{}Result", level_sc.factory_name))
147        );
148        let which_alias = format_ident!("__W{}", i);
149        levels.push(UnwrapLevel {
150            resp_module,
151            variant,
152            which_alias,
153        });
154    }
155
156    let inner_which = format_ident!("__WInner");
157    let inner_match_arms: Vec<TokenStream> = sc
158        .inner_response_variants
159        .iter()
160        .map(|v| {
161            generate_parse_match_arm(
162                &response_type,
163                capnp_mod,
164                v,
165                resolved,
166                &inner_which,
167                types_crate,
168            )
169        })
170        .collect();
171
172    let inner_resp_mod = format_ident!("{}", sc.capnp_inner_response);
173    let mut body = quote! {
174        use #capnp_mod::#inner_resp_mod::Which as __WInner;
175        match resp.which()? {
176            #(#inner_match_arms)*
177            #[allow(unreachable_patterns)]
178            _ => Err(anyhow::anyhow!("unexpected inner response variant")),
179        }
180    };
181
182    for level in levels.iter().rev() {
183        let which_alias = &level.which_alias;
184        let variant = &level.variant;
185        let resp_module = &level.resp_module;
186        body = quote! {
187            use #capnp_mod::#resp_module::Which as #which_alias;
188            match resp.which()? {
189                #which_alias::#variant(resp) => {
190                    let resp = resp?;
191                    #body
192                }
193                #which_alias::Error(err) => {
194                    let err = err?;
195                    let msg = err.get_message()?.to_str()?.to_string();
196                    Err(anyhow::anyhow!(msg))
197                }
198                _ => Err(anyhow::anyhow!("unexpected response variant")),
199            }
200        };
201    }
202
203    quote! {
204        #response_enum
205
206        impl #response_type {
207            /// Parse a scoped response from raw bytes.
208            pub fn parse_scoped_response(bytes: &[u8]) -> anyhow::Result<#response_type> {
209                let reader = capnp::serialize::read_message(
210                    &mut std::io::Cursor::new(bytes),
211                    capnp::message::ReaderOptions::new(),
212                )?;
213                let resp = reader.get_root::<#capnp_mod::#outer_resp_type::Reader>()?;
214                #body
215            }
216        }
217    }
218}
219
220/// Build a `ScopedMethodContext` chain from ancestors + current scope.
221fn build_scope_context(
222    sc: &ScopedClient,
223    ancestors: &[&ScopedClient],
224    resolved: &ResolvedSchema,
225) -> ScopedMethodContext {
226    let root_name = ancestors
227        .first()
228        .map_or(sc.factory_name.as_str(), |root| root.factory_name.as_str());
229    let root_method_discriminator = resolved
230        .raw
231        .request_struct
232        .as_ref()
233        .and_then(|request| request.union_fields().find(|field| field.name == root_name))
234        .map(|field| field.discriminant_value)
235        .or_else(|| {
236            resolved
237                .raw
238                .request_variants
239                .iter()
240                .position(|variant| variant.name == root_name)
241                .and_then(|index| u16::try_from(index).ok())
242        })
243        .unwrap_or(0);
244    let mut parent_ctx: Option<Box<ScopedMethodContext>> = None;
245    for ancestor in ancestors {
246        parent_ctx = Some(Box::new(ScopedMethodContext {
247            factory_name: ancestor.factory_name.clone(),
248            scope_fields: ancestor.scope_fields.clone(),
249            parent: parent_ctx,
250            root_method_discriminator,
251        }));
252    }
253    ScopedMethodContext {
254        factory_name: sc.factory_name.clone(),
255        scope_fields: sc.scope_fields.clone(),
256        parent: parent_ctx,
257        root_method_discriminator,
258    }
259}
260
261/// Intermediate representation for response unwrap levels.
262struct UnwrapLevel {
263    resp_module: syn::Ident,
264    variant: syn::Ident,
265    which_alias: syn::Ident,
266}
267
268// ============================================================================
269// Portable scoped clients (Arc<dyn RpcClient>, no ZMQ deps)
270// ============================================================================
271
272fn walk_portable_scoped(
273    tokens: &mut TokenStream,
274    service_name: &str,
275    pascal: &str,
276    capnp_mod: &TokenStream,
277    sc: &ScopedClient,
278    ancestors: &[&ScopedClient],
279    resolved: &ResolvedSchema,
280    types_crate: Option<&syn::Path>,
281) {
282    tokens.extend(generate_portable_scoped_client_recursive(
283        service_name,
284        pascal,
285        capnp_mod,
286        sc,
287        ancestors,
288        resolved,
289        types_crate,
290    ));
291    let mut next_ancestors: Vec<&ScopedClient> = ancestors.to_vec();
292    next_ancestors.push(sc);
293    for nested in &sc.nested_clients {
294        walk_portable_scoped(
295            tokens,
296            service_name,
297            pascal,
298            capnp_mod,
299            nested,
300            &next_ancestors,
301            resolved,
302            types_crate,
303        );
304    }
305}
306
307/// Generate a portable scoped client struct using `Arc<dyn RpcClient>`.
308fn generate_portable_scoped_client_recursive(
309    service_name: &str,
310    pascal: &str,
311    capnp_mod: &TokenStream,
312    sc: &ScopedClient,
313    ancestors: &[&ScopedClient],
314    resolved: &ResolvedSchema,
315    types_crate: Option<&syn::Path>,
316) -> TokenStream {
317    let client_name = format_ident!("{}", sc.client_name);
318    let response_type = format_ident!("{}ResponseVariant", sc.client_name);
319    let outer_req_type = format_ident!("{}", to_snake_case(&format!("{pascal}Request")));
320    let doc = format!(
321        "Scoped client for {} operations (transport-agnostic).",
322        sc.factory_name
323    );
324
325    // Struct fields: all ancestor scope fields + own scope fields
326    let all_scope_field_defs: Vec<TokenStream> = ancestors
327        .iter()
328        .flat_map(|a| &a.scope_fields)
329        .chain(&sc.scope_fields)
330        .map(|f| {
331            let name = format_ident!("{}", to_snake_case(&f.name));
332            let ty =
333                rust_type_tokens(&CapnpType::classify_primitive(&f.type_name).rust_owned_type());
334            quote! { #name: #ty }
335        })
336        .collect();
337
338    // Build parse_scoped_response body (same as native — pure capnp parsing)
339    let outer_resp_type = format_ident!("{}", to_snake_case(&format!("{pascal}Response")));
340    let full_chain: Vec<&ScopedClient> = ancestors
341        .iter()
342        .copied()
343        .chain(std::iter::once(sc))
344        .collect();
345
346    let mut levels = Vec::new();
347    for (i, level_sc) in full_chain.iter().enumerate() {
348        let resp_module = if i == 0 {
349            format_ident!("{}", to_snake_case(&format!("{pascal}Response")))
350        } else {
351            format_ident!("{}", full_chain[i - 1].capnp_inner_response)
352        };
353        let variant = format_ident!(
354            "{}",
355            to_pascal_case(&format!("{}Result", level_sc.factory_name))
356        );
357        let which_alias = format_ident!("__W{}", i);
358        levels.push(UnwrapLevel {
359            resp_module,
360            variant,
361            which_alias,
362        });
363    }
364
365    let inner_which = format_ident!("__WInner");
366    let inner_match_arms: Vec<TokenStream> = sc
367        .inner_response_variants
368        .iter()
369        .map(|v| {
370            generate_parse_match_arm(
371                &response_type,
372                capnp_mod,
373                v,
374                resolved,
375                &inner_which,
376                types_crate,
377            )
378        })
379        .collect();
380
381    let inner_resp_mod = format_ident!("{}", sc.capnp_inner_response);
382    let mut body = quote! {
383        use #capnp_mod::#inner_resp_mod::Which as __WInner;
384        match resp.which()? {
385            #(#inner_match_arms)*
386            #[allow(unreachable_patterns)]
387            _ => Err(anyhow::anyhow!("unexpected inner response variant")),
388        }
389    };
390
391    for level in levels.iter().rev() {
392        let which_alias = &level.which_alias;
393        let variant = &level.variant;
394        let resp_module = &level.resp_module;
395        body = quote! {
396            use #capnp_mod::#resp_module::Which as #which_alias;
397            match resp.which()? {
398                #which_alias::#variant(resp) => {
399                    let resp = resp?;
400                    #body
401                }
402                #which_alias::Error(err) => {
403                    let err = err?;
404                    let msg = err.get_message()?.to_str()?.to_string();
405                    Err(anyhow::anyhow!(msg))
406                }
407                _ => Err(anyhow::anyhow!("unexpected response variant")),
408            }
409        };
410    }
411
412    // Request methods (portable mode)
413    let scope_ctx = build_scope_context(sc, ancestors, resolved);
414    let request_methods: Vec<TokenStream> = sc
415        .inner_request_variants
416        .iter()
417        .map(|v| {
418            generate_portable_request_method(
419                capnp_mod,
420                &outer_req_type,
421                &response_type,
422                v,
423                resolved,
424                Some(&scope_ctx),
425                Some(&sc.inner_response_variants),
426                true,
427                types_crate,
428            )
429        })
430        .collect();
431
432    // Nested factory methods (portable — no jwt_token)
433    let nested_factory_methods: Vec<TokenStream> = sc
434        .nested_clients
435        .iter()
436        .map(|nested| generate_portable_nested_factory_method(nested, ancestors, sc))
437        .collect();
438
439    quote! {
440        #[doc = #doc]
441        #[derive(Clone)]
442        pub struct #client_name {
443            client: std::sync::Arc<dyn hyprstream_rpc::RpcClient>,
444            call_options: hyprstream_rpc::CallOptions,
445            #(#all_scope_field_defs,)*
446        }
447
448        impl #client_name {
449            /// Get the next request ID.
450            pub fn next_id(&self) -> u64 {
451                self.client.next_id()
452            }
453
454            /// Send a raw request and return the raw response bytes.
455            pub async fn call(&self, payload: Vec<u8>) -> anyhow::Result<Vec<u8>> {
456                self.client.call_with_options_for_service(
457                    #service_name, payload, self.call_options.clone()).await
458            }
459
460            /// Send a generated request with its canonical root method id.
461            async fn call_with_method(
462                &self,
463                method_discriminator: u16,
464                payload: Vec<u8>,
465            ) -> anyhow::Result<Vec<u8>> {
466                self.client
467                    .call_with_options_for_service_with_method(
468                        #service_name, method_discriminator, payload,
469                        self.call_options.clone())
470                    .await
471            }
472
473            /// Send a streaming request with ephemeral DH pubkey.
474            pub async fn call_streaming(&self, payload: Vec<u8>, ephemeral_pubkey: [u8; 32]) -> anyhow::Result<Vec<u8>> {
475                self.client
476                    .call_streaming_with_options_for_service(
477                        #service_name, payload, ephemeral_pubkey,
478                        self.call_options.clone())
479                    .await
480            }
481
482            /// Send a generated streaming request with its canonical root method id.
483            async fn call_streaming_with_method(
484                &self,
485                method_discriminator: u16,
486                payload: Vec<u8>,
487                ephemeral_pubkey: [u8; 32],
488            ) -> anyhow::Result<Vec<u8>> {
489                self.client
490                    .call_streaming_with_options_for_service_with_method(
491                        #service_name,
492                        method_discriminator,
493                        payload,
494                        ephemeral_pubkey,
495                        self.call_options.clone(),
496                    )
497                    .await
498            }
499
500            /// Parse a scoped response from raw bytes.
501            pub fn parse_scoped_response(bytes: &[u8]) -> anyhow::Result<#response_type> {
502                let reader = capnp::serialize::read_message(
503                    &mut std::io::Cursor::new(bytes),
504                    capnp::message::ReaderOptions::new(),
505                )?;
506                let resp = reader.get_root::<#capnp_mod::#outer_resp_type::Reader>()?;
507                #body
508            }
509
510            #(#request_methods)*
511
512            #(#nested_factory_methods)*
513        }
514    }
515}
516
517/// Portable nested factory method (no jwt_token).
518fn generate_portable_nested_factory_method(
519    nested: &ScopedClient,
520    ancestors: &[&ScopedClient],
521    parent: &ScopedClient,
522) -> TokenStream {
523    let method_name = format_ident!("{}", to_snake_case(&nested.factory_name));
524    let client_name_ident = format_ident!("{}", nested.client_name);
525    let doc = format!("Create a scoped {} client.", nested.factory_name);
526
527    let params: Vec<TokenStream> = nested
528        .scope_fields
529        .iter()
530        .map(|f| {
531            let name = format_ident!("{}", to_snake_case(&f.name));
532            let ty =
533                rust_type_tokens(&CapnpType::classify_primitive(&f.type_name).rust_param_type());
534            quote! { #name: #ty }
535        })
536        .collect();
537
538    let all_parent_field_inits: Vec<TokenStream> = ancestors
539        .iter()
540        .flat_map(|a| &a.scope_fields)
541        .chain(&parent.scope_fields)
542        .map(|f| {
543            let name = format_ident!("{}", to_snake_case(&f.name));
544            quote! { #name: self.#name.clone() }
545        })
546        .collect();
547
548    let own_field_inits: Vec<TokenStream> = nested
549        .scope_fields
550        .iter()
551        .map(|f| {
552            let name = format_ident!("{}", to_snake_case(&f.name));
553            match f.type_name.as_str() {
554                "Text" => quote! { #name: #name.to_owned() },
555                _ => quote! { #name },
556            }
557        })
558        .collect();
559
560    quote! {
561        #[doc = #doc]
562        pub fn #method_name(&self #(, #params)*) -> #client_name_ident {
563            #client_name_ident {
564                client: std::sync::Arc::clone(&self.client),
565                call_options: self.call_options.clone(),
566                #(#all_parent_field_inits,)*
567                #(#own_field_inits,)*
568            }
569        }
570    }
571}
572
573#[cfg(test)]
574mod canonical_service_authority_tests {
575    use super::*;
576
577    #[test]
578    fn hyphenated_scoped_service_keeps_original_authority() {
579        let schema = ParsedSchema {
580            request_variants: Vec::new(),
581            response_variants: Vec::new(),
582            structs: Vec::new(),
583            scoped_clients: vec![ScopedClient {
584                factory_name: "document".to_owned(),
585                client_name: "DocumentClient".to_owned(),
586                scope_fields: Vec::new(),
587                inner_request_variants: Vec::new(),
588                inner_response_variants: Vec::new(),
589                capnp_inner_response: "document_response".to_owned(),
590                nested_clients: Vec::new(),
591            }],
592            enums: Vec::new(),
593            request_struct: None,
594            response_struct: None,
595        };
596        let resolved = ResolvedSchema::from(&schema);
597        let generated =
598            generate_portable_scoped_clients("text-generation", &resolved, None).to_string();
599
600        assert!(generated.contains("text-generation"));
601        assert!(!generated.contains("text_generation\""));
602        assert!(generated.contains("text_generation_capnp"));
603    }
604}