Skip to main content

hyprstream_rpc_derive/codegen/
client.rs

1//! Client struct, response enum, request methods, parse_response, and trait generation.
2
3use proc_macro2::TokenStream;
4use quote::{format_ident, quote};
5
6use crate::resolve::ResolvedSchema;
7use crate::schema::types::*;
8use crate::util::*;
9
10/// Returns `true` if `type_name` is the canonical streaming `StreamInfo` from
11/// `streaming.capnp`, identified by `origin_file == Some("streaming")`.
12///
13/// This guards against false positives when a service schema defines its own
14/// `StreamInfo` struct with unrelated semantics (e.g., `tui.capnp`).
15fn is_rpc_stream_info(type_name: &str, resolved: &ResolvedSchema) -> bool {
16    type_name == "StreamInfo"
17        && resolved
18            .find_struct("StreamInfo")
19            .map(|s| s.origin_file.as_deref() == Some("streaming"))
20            .unwrap_or(false)
21}
22
23// ─────────────────────────────────────────────────────────────────────────────
24// Trait Generation (Phase 2a)
25// ─────────────────────────────────────────────────────────────────────────────
26
27/// Generate the top-level service trait and all scope traits.
28pub fn generate_service_traits(
29    service_name: &str,
30    resolved: &ResolvedSchema,
31    types_crate: Option<&syn::Path>,
32) -> TokenStream {
33    let mut tokens = TokenStream::new();
34
35    // Generate scope traits first (bottom-up: nested → parent → top-level)
36    for sc in &resolved.raw.scoped_clients {
37        tokens.extend(generate_scope_trait_recursive(sc, resolved, types_crate));
38    }
39
40    // Generate top-level service trait
41    tokens.extend(generate_top_level_trait(
42        service_name,
43        resolved,
44        types_crate,
45    ));
46
47    tokens
48}
49
50/// Generate a scope trait (e.g., RuntimeRpc, ContainerRpc) and recurse into nested scopes.
51fn generate_scope_trait_recursive(
52    sc: &ScopedClient,
53    resolved: &ResolvedSchema,
54    types_crate: Option<&syn::Path>,
55) -> TokenStream {
56    let mut tokens = TokenStream::new();
57
58    // Generate nested scope traits first
59    for nested in &sc.nested_clients {
60        tokens.extend(generate_scope_trait_recursive(
61            nested,
62            resolved,
63            types_crate,
64        ));
65    }
66
67    let trait_name = scope_trait_name(&sc.client_name);
68    let trait_ident = format_ident!("{}", trait_name);
69    let doc = format!("Generated RPC trait for {} scope.", sc.factory_name);
70
71    // Nested scope associated types + factory methods
72    let nested_assoc_types: Vec<TokenStream> = sc
73        .nested_clients
74        .iter()
75        .map(|nested| {
76            let assoc_name = format_ident!("{}", to_pascal_case(&nested.factory_name));
77            let nested_trait = format_ident!("{}", scope_trait_name(&nested.client_name));
78            quote! { type #assoc_name: #nested_trait; }
79        })
80        .collect();
81
82    let nested_factory_methods: Vec<TokenStream> = sc
83        .nested_clients
84        .iter()
85        .map(|nested| {
86            let method = format_ident!("{}", to_snake_case(&nested.factory_name));
87            let assoc_name = format_ident!("{}", to_pascal_case(&nested.factory_name));
88            let params = scope_factory_params(&nested.scope_fields, resolved);
89            quote! { fn #method(&self #(, #params)*) -> Self::#assoc_name; }
90        })
91        .collect();
92
93    // Trait methods from inner_request_variants
94    let trait_methods: Vec<TokenStream> = sc
95        .inner_request_variants
96        .iter()
97        .filter_map(|v| {
98            generate_trait_method(v, &sc.inner_response_variants, resolved, types_crate, true)
99        })
100        .collect();
101
102    tokens.extend(quote! {
103        #[doc = #doc]
104        #[cfg_attr(target_arch = "wasm32", async_trait::async_trait(?Send))]
105        #[cfg_attr(not(target_arch = "wasm32"), async_trait::async_trait)]
106        pub trait #trait_ident: Send + Sync {
107            #(#nested_assoc_types)*
108            #(#nested_factory_methods)*
109            #(#trait_methods)*
110        }
111    });
112
113    tokens
114}
115
116/// Generate the top-level service trait (e.g., WorkerRpc, ModelRpc).
117fn generate_top_level_trait(
118    service_name: &str,
119    resolved: &ResolvedSchema,
120    types_crate: Option<&syn::Path>,
121) -> TokenStream {
122    let pascal = to_pascal_case(service_name);
123    let trait_name = format_ident!("{}Rpc", pascal);
124    let doc = format!("Generated RPC trait for the {pascal} service.");
125
126    let scoped_variant_names: Vec<&str> = resolved
127        .raw
128        .scoped_clients
129        .iter()
130        .map(|sc| sc.factory_name.as_str())
131        .collect();
132
133    // Associated types for scoped clients
134    let assoc_types: Vec<TokenStream> = resolved
135        .raw
136        .scoped_clients
137        .iter()
138        .map(|sc| {
139            let assoc_name = format_ident!("{}", to_pascal_case(&sc.factory_name));
140            let scope_trait = format_ident!("{}", scope_trait_name(&sc.client_name));
141            quote! { type #assoc_name: #scope_trait; }
142        })
143        .collect();
144
145    // Factory methods for scoped clients
146    let factory_methods: Vec<TokenStream> = resolved
147        .raw
148        .scoped_clients
149        .iter()
150        .map(|sc| {
151            let method = format_ident!("{}", to_snake_case(&sc.factory_name));
152            let assoc_name = format_ident!("{}", to_pascal_case(&sc.factory_name));
153            let params = scope_factory_params(&sc.scope_fields, resolved);
154            quote! { fn #method(&self #(, #params)*) -> Self::#assoc_name; }
155        })
156        .collect();
157
158    // Non-scoped methods
159    let trait_methods: Vec<TokenStream> = resolved
160        .raw
161        .request_variants
162        .iter()
163        .filter(|v| !scoped_variant_names.contains(&v.name.as_str()))
164        .filter_map(|v| {
165            generate_trait_method(
166                v,
167                &resolved.raw.response_variants,
168                resolved,
169                types_crate,
170                false,
171            )
172        })
173        .collect();
174
175    quote! {
176        #[doc = #doc]
177        #[cfg_attr(target_arch = "wasm32", async_trait::async_trait(?Send))]
178        #[cfg_attr(not(target_arch = "wasm32"), async_trait::async_trait)]
179        pub trait #trait_name: Send + Sync {
180            #(#assoc_types)*
181            #(#factory_methods)*
182            #(#trait_methods)*
183        }
184    }
185}
186
187/// Generate a single trait method signature from a request variant.
188fn generate_trait_method(
189    variant: &UnionVariant,
190    response_variants: &[UnionVariant],
191    resolved: &ResolvedSchema,
192    types_crate: Option<&syn::Path>,
193    is_scoped: bool,
194) -> Option<TokenStream> {
195    let method_name = format_ident!("{}", to_snake_case(&variant.name));
196
197    // Determine return type
198    let return_type = determine_return_type(
199        &variant.name,
200        response_variants,
201        resolved,
202        is_scoped,
203        types_crate,
204    )?;
205
206    // Detect streaming — trait methods return StreamHandle directly (no ephemeral_pubkey param)
207    let is_streaming = response_variants
208        .iter()
209        .find(|v| {
210            let expected = if is_scoped {
211                variant.name.clone()
212            } else {
213                format!("{}Result", variant.name)
214            };
215            v.name == expected
216        })
217        .map(|v| is_rpc_stream_info(&v.type_name, resolved))
218        .unwrap_or(false);
219
220    // Streaming methods in the trait don't take ephemeral_pubkey — they return MoqStreamHandle
221    let return_type = if is_streaming {
222        quote! { hyprstream_rpc::moq_stream::MoqStreamHandle }
223    } else {
224        return_type
225    };
226    let stream_cfg = if is_streaming {
227        quote! { #[cfg(not(target_arch = "wasm32"))] }
228    } else {
229        TokenStream::new()
230    };
231
232    // Determine params from the request variant type
233    let params = match variant.type_name.as_str() {
234        "Void" => Vec::new(),
235        "Text" => vec![quote! { value: &str }],
236        "Data" => vec![quote! { value: &[u8] }],
237        "Bool" => vec![quote! { value: bool }],
238        t if CapnpType::classify_primitive(t).is_numeric() => {
239            let ty = rust_type_tokens(&CapnpType::classify_primitive(t).rust_owned_type());
240            vec![quote! { value: #ty }]
241        }
242        struct_name => {
243            let s = resolved.find_struct(struct_name)?;
244            let nuf: Vec<_> = s.non_union_fields().collect();
245            if nuf.is_empty() || (nuf.len() == 1 && nuf[0].type_name == "Void") {
246                Vec::new()
247            } else {
248                let data_name = format_ident!("{}", struct_name);
249                vec![quote! { request: &#data_name }]
250            }
251        }
252    };
253
254    Some(quote! {
255        #stream_cfg
256        async fn #method_name(&self #(, #params)*) -> anyhow::Result<#return_type>;
257    })
258}
259
260/// Determine the return type for a trait method.
261fn determine_return_type(
262    request_name: &str,
263    response_variants: &[UnionVariant],
264    resolved: &ResolvedSchema,
265    is_scoped: bool,
266    types_crate: Option<&syn::Path>,
267) -> Option<TokenStream> {
268    let expected_name = if is_scoped {
269        request_name.to_owned()
270    } else {
271        format!("{}Result", request_name)
272    };
273
274    let resp_variant = response_variants.iter().find(|v| v.name == expected_name)?;
275    let ct = resolved
276        .resolve_type(&resp_variant.type_name)
277        .capnp_type
278        .clone();
279
280    Some(match ct {
281        CapnpType::Void => quote! { () },
282        CapnpType::Bool => quote! { bool },
283        CapnpType::Text => quote! { String },
284        CapnpType::Data => quote! { Vec<u8> },
285        CapnpType::UInt8
286        | CapnpType::UInt16
287        | CapnpType::UInt32
288        | CapnpType::UInt64
289        | CapnpType::Int8
290        | CapnpType::Int16
291        | CapnpType::Int32
292        | CapnpType::Int64
293        | CapnpType::Float32
294        | CapnpType::Float64 => {
295            let rust_type = rust_type_tokens(&ct.rust_owned_type());
296            quote! { #rust_type }
297        }
298        CapnpType::ListText => quote! { Vec<String> },
299        CapnpType::ListData => quote! { Vec<Vec<u8>> },
300        CapnpType::ListPrimitive(ref inner) => {
301            let rust_inner = rust_type_tokens(&inner.rust_owned_type());
302            quote! { Vec<#rust_inner> }
303        }
304        CapnpType::ListStruct(ref inner) => {
305            let data_name = format_ident!("{}", inner);
306            quote! { Vec<#data_name> }
307        }
308        CapnpType::Struct(ref name) => {
309            let s = resolved.find_struct(name)?;
310            if let Some(ref dt) = s.domain_type {
311                resolve_domain_type(dt, types_crate)
312            } else {
313                let data_name = format_ident!("{}", name);
314                quote! { #data_name }
315            }
316        }
317        _ => return None,
318    })
319}
320
321/// Derive a scope trait name from a scoped client name.
322/// e.g., "RuntimeClient" → "RuntimeRpc", "ContainerClient" → "ContainerRpc"
323fn scope_trait_name(client_name: &str) -> String {
324    if let Some(base) = client_name.strip_suffix("Client") {
325        format!("{}Rpc", base)
326    } else {
327        format!("{}Rpc", client_name)
328    }
329}
330
331/// Generate scope factory method parameters.
332fn scope_factory_params(scope_fields: &[FieldDef], _resolved: &ResolvedSchema) -> Vec<TokenStream> {
333    scope_fields
334        .iter()
335        .map(|f| {
336            let name = format_ident!("{}", to_snake_case(&f.name));
337            let ty =
338                rust_type_tokens(&CapnpType::classify_primitive(&f.type_name).rust_param_type());
339            quote! { #name: #ty }
340        })
341        .collect()
342}
343
344// ─────────────────────────────────────────────────────────────────────────────
345// Trait Implementation Generation
346// ─────────────────────────────────────────────────────────────────────────────
347
348/// Generate trait impl for the top-level client + all scoped clients.
349pub fn generate_trait_impls(
350    service_name: &str,
351    resolved: &ResolvedSchema,
352    types_crate: Option<&syn::Path>,
353) -> TokenStream {
354    let mut tokens = TokenStream::new();
355
356    let pascal = to_pascal_case(service_name);
357    let client_ident = format_ident!("{}Client", pascal);
358    let trait_ident = format_ident!("{}Rpc", pascal);
359
360    let scoped_variant_names: Vec<&str> = resolved
361        .raw
362        .scoped_clients
363        .iter()
364        .map(|sc| sc.factory_name.as_str())
365        .collect();
366
367    // Associated type bindings
368    let assoc_bindings: Vec<TokenStream> = resolved
369        .raw
370        .scoped_clients
371        .iter()
372        .map(|sc| {
373            let assoc_name = format_ident!("{}", to_pascal_case(&sc.factory_name));
374            let scoped_client = format_ident!("{}", sc.client_name);
375            quote! { type #assoc_name = #scoped_client; }
376        })
377        .collect();
378
379    // Factory method impls
380    let factory_impls: Vec<TokenStream> = resolved
381        .raw
382        .scoped_clients
383        .iter()
384        .map(|sc| {
385            let method = format_ident!("{}", to_snake_case(&sc.factory_name));
386            let assoc_name = format_ident!("{}", to_pascal_case(&sc.factory_name));
387            let params = scope_factory_params(&sc.scope_fields, resolved);
388            let param_names: Vec<syn::Ident> = sc
389                .scope_fields
390                .iter()
391                .map(|f| format_ident!("{}", to_snake_case(&f.name)))
392                .collect();
393            quote! {
394                fn #method(&self #(, #params)*) -> Self::#assoc_name {
395                    #client_ident::#method(self #(, #param_names),*)
396                }
397            }
398        })
399        .collect();
400
401    // Non-scoped method delegation
402    let method_impls: Vec<TokenStream> = resolved
403        .raw
404        .request_variants
405        .iter()
406        .filter(|v| !scoped_variant_names.contains(&v.name.as_str()))
407        .filter_map(|v| {
408            generate_trait_method_impl(
409                v,
410                &resolved.raw.response_variants,
411                resolved,
412                types_crate,
413                false,
414            )
415        })
416        .collect();
417
418    tokens.extend(quote! {
419        #[cfg_attr(target_arch = "wasm32", async_trait::async_trait(?Send))]
420        #[cfg_attr(not(target_arch = "wasm32"), async_trait::async_trait)]
421        impl #trait_ident for #client_ident {
422            #(#assoc_bindings)*
423            #(#factory_impls)*
424            #(#method_impls)*
425        }
426    });
427
428    // Scoped client trait impls
429    for sc in &resolved.raw.scoped_clients {
430        tokens.extend(generate_scope_trait_impl_recursive(
431            sc,
432            resolved,
433            types_crate,
434        ));
435    }
436
437    tokens
438}
439
440fn generate_scope_trait_impl_recursive(
441    sc: &ScopedClient,
442    resolved: &ResolvedSchema,
443    types_crate: Option<&syn::Path>,
444) -> TokenStream {
445    let mut tokens = TokenStream::new();
446
447    let client_ident = format_ident!("{}", sc.client_name);
448    let trait_ident = format_ident!("{}", scope_trait_name(&sc.client_name));
449
450    // Nested associated type bindings + factory impls
451    let nested_assoc: Vec<TokenStream> = sc
452        .nested_clients
453        .iter()
454        .map(|nested| {
455            let assoc_name = format_ident!("{}", to_pascal_case(&nested.factory_name));
456            let nested_client = format_ident!("{}", nested.client_name);
457            quote! { type #assoc_name = #nested_client; }
458        })
459        .collect();
460
461    let nested_factory_impls: Vec<TokenStream> = sc
462        .nested_clients
463        .iter()
464        .map(|nested| {
465            let method = format_ident!("{}", to_snake_case(&nested.factory_name));
466            let assoc_name = format_ident!("{}", to_pascal_case(&nested.factory_name));
467            let params = scope_factory_params(&nested.scope_fields, resolved);
468            let param_names: Vec<syn::Ident> = nested
469                .scope_fields
470                .iter()
471                .map(|f| format_ident!("{}", to_snake_case(&f.name)))
472                .collect();
473            quote! {
474                fn #method(&self #(, #params)*) -> Self::#assoc_name {
475                    #client_ident::#method(self #(, #param_names),*)
476                }
477            }
478        })
479        .collect();
480
481    let method_impls: Vec<TokenStream> = sc
482        .inner_request_variants
483        .iter()
484        .filter_map(|v| {
485            generate_trait_method_impl(v, &sc.inner_response_variants, resolved, types_crate, true)
486        })
487        .collect();
488
489    tokens.extend(quote! {
490        #[cfg_attr(target_arch = "wasm32", async_trait::async_trait(?Send))]
491        #[cfg_attr(not(target_arch = "wasm32"), async_trait::async_trait)]
492        impl #trait_ident for #client_ident {
493            #(#nested_assoc)*
494            #(#nested_factory_impls)*
495            #(#method_impls)*
496        }
497    });
498
499    // Recurse into nested scoped clients
500    for nested in &sc.nested_clients {
501        tokens.extend(generate_scope_trait_impl_recursive(
502            nested,
503            resolved,
504            types_crate,
505        ));
506    }
507
508    tokens
509}
510
511/// Generate a trait method impl that delegates to the inherent method on the client.
512fn generate_trait_method_impl(
513    variant: &UnionVariant,
514    response_variants: &[UnionVariant],
515    resolved: &ResolvedSchema,
516    types_crate: Option<&syn::Path>,
517    is_scoped: bool,
518) -> Option<TokenStream> {
519    let method_name = format_ident!("{}", to_snake_case(&variant.name));
520
521    let return_type = determine_return_type(
522        &variant.name,
523        response_variants,
524        resolved,
525        is_scoped,
526        types_crate,
527    )?;
528
529    let is_streaming = response_variants
530        .iter()
531        .find(|v| {
532            let expected = if is_scoped {
533                variant.name.clone()
534            } else {
535                format!("{}Result", variant.name)
536            };
537            v.name == expected
538        })
539        .map(|v| is_rpc_stream_info(&v.type_name, resolved))
540        .unwrap_or(false);
541
542    // Streaming trait methods return MoqStreamHandle (no ephemeral_pubkey param)
543    let return_type = if is_streaming {
544        quote! { hyprstream_rpc::moq_stream::MoqStreamHandle }
545    } else {
546        return_type
547    };
548
549    // Build params and args
550    let (params, args) = match variant.type_name.as_str() {
551        "Void" => (Vec::new(), Vec::new()),
552        "Text" => (vec![quote! { value: &str }], vec![quote! { value }]),
553        "Data" => (vec![quote! { value: &[u8] }], vec![quote! { value }]),
554        "Bool" => (vec![quote! { value: bool }], vec![quote! { value }]),
555        t if CapnpType::classify_primitive(t).is_numeric() => {
556            let ty = rust_type_tokens(&CapnpType::classify_primitive(t).rust_owned_type());
557            (vec![quote! { value: #ty }], vec![quote! { value }])
558        }
559        struct_name => {
560            let s = resolved.find_struct(struct_name)?;
561            let nuf: Vec<_> = s.non_union_fields().collect();
562            if nuf.is_empty() || (nuf.len() == 1 && nuf[0].type_name == "Void") {
563                (Vec::new(), Vec::new())
564            } else {
565                let data_name = format_ident!("{}", struct_name);
566                (
567                    vec![quote! { request: &#data_name }],
568                    vec![quote! { request }],
569                )
570            }
571        }
572    };
573
574    if is_streaming {
575        // Streaming trait impl: generate ephemeral keypair, call raw method, construct MoqStreamHandle
576        Some(quote! {
577            #[cfg(not(target_arch = "wasm32"))]
578            async fn #method_name(&self #(, #params)*) -> anyhow::Result<hyprstream_rpc::moq_stream::MoqStreamHandle> {
579                let (client_secret, client_pubkey) = hyprstream_rpc::crypto::generate_ephemeral_keypair();
580                let client_pubkey_bytes: [u8; 32] = client_pubkey.to_bytes();
581                let info = Self::#method_name(self #(, #args)*, client_pubkey_bytes).await?;
582                if info.dh_public == [0u8; 32] {
583                    anyhow::bail!("Server did not provide DH public key for streaming");
584                }
585                if info.broadcast_path.is_empty() {
586                    anyhow::bail!("Server did not provide moq broadcast path — moq transport not initialized");
587                }
588                let (mac_key, enc_key, topic) = hyprstream_rpc::derive_client_stream_keys(
589                    &client_secret, &client_pubkey_bytes, &info.dh_public,
590                )?;
591                // #274: subscribe over the resolved `reach`; UDS is available
592                // only when the service advertised no dialable network reach.
593                // #358: pass the service-signed `qos` so direct-vs-relay topology
594                // is selected from it (relay-first for retained/fan-out streams).
595                // #321: enc_key opens the transport-AEAD-sealed Tagged blocks;
596                // retain the RPC-authenticated server witness for Iroh admission.
597                Ok(hyprstream_rpc::moq_stream::MoqStreamHandle::networked_with_server_identity(
598                    info.announced_at, &info.qos, info.broadcast_path, mac_key, enc_key, topic,
599                    info.moql_server_identity,
600                ))
601            }
602        })
603    } else {
604        Some(quote! {
605            async fn #method_name(&self #(, #params)*) -> anyhow::Result<#return_type> {
606                Self::#method_name(self #(, #args)*).await
607            }
608        })
609    }
610}
611
612// ─────────────────────────────────────────────────────────────────────────────
613// Constructor Generation (Phase 2b)
614// ─────────────────────────────────────────────────────────────────────────────
615
616/// Generate constructors that are safe to ship with the portable client.
617///
618/// Resolver authority is deliberately not linked into the contract crate. A
619/// host must use the explicit [`Client::from_provider`] API and supply its own
620/// deployment-specific provider.
621pub fn generate_portable_constructors(service_name: &str) -> TokenStream {
622    let pascal = to_pascal_case(service_name);
623    let client_name = format_ident!("{}Client", pascal);
624    let service_name_lit = service_name;
625
626    quote! {
627        #[cfg(not(target_arch = "wasm32"))]
628        impl #client_name {
629            /// Construct a client for a co-located service discovered through
630            /// the explicitly registered local endpoint.
631            pub fn for_local_bootstrap(
632                signing_key: hyprstream_rpc::crypto::SigningKey,
633                destination: hyprstream_rpc::crypto::VerifyingKey,
634                token: Option<String>,
635            ) -> anyhow::Result<Self> {
636                let registry = hyprstream_rpc::registry::try_global()
637                    .ok_or_else(|| anyhow::anyhow!(
638                        "EndpointRegistry not initialized — local bootstrap requires registry::init()"
639                    ))?;
640                let transport = registry.registered_endpoint(
641                    #service_name_lit,
642                    hyprstream_rpc::registry::SocketKind::Rep,
643                ).ok_or_else(|| anyhow::anyhow!(
644                    "local bootstrap requires an explicitly registered service endpoint"
645                ))?;
646                Self::for_local_transport_bootstrap(&transport, signing_key, destination, token)
647            }
648
649            /// Construct a client from an explicit local endpoint string.
650            pub fn for_local_endpoint_bootstrap(
651                endpoint: &str,
652                signing_key: hyprstream_rpc::crypto::SigningKey,
653                destination: hyprstream_rpc::crypto::VerifyingKey,
654                token: Option<String>,
655            ) -> anyhow::Result<Self> {
656                let transport = hyprstream_rpc::transport::TransportConfig::from_endpoint(endpoint);
657                Self::for_local_transport_bootstrap(&transport, signing_key, destination, token)
658            }
659
660            /// Construct a client from a typed local transport.
661            pub fn for_local_transport_bootstrap(
662                transport: &hyprstream_rpc::transport::TransportConfig,
663                signing_key: hyprstream_rpc::crypto::SigningKey,
664                destination: hyprstream_rpc::crypto::VerifyingKey,
665                token: Option<String>,
666            ) -> anyhow::Result<Self> {
667                anyhow::ensure!(
668                    matches!(
669                        &transport.endpoint,
670                        hyprstream_rpc::transport::EndpointType::Inproc { .. }
671                            | hyprstream_rpc::transport::EndpointType::Ipc { .. }
672                            | hyprstream_rpc::transport::EndpointType::SystemdFd { .. }
673                    ),
674                    "local bootstrap refuses network transport; use the identity-bound provider",
675                );
676                let signer = hyprstream_rpc::signer::LocalSigner::new(signing_key);
677                let rpc = hyprstream_rpc::dial::dial(transport, signer, Some(destination), token)?;
678                Ok(Self::new(rpc))
679            }
680        }
681    }
682}
683
684/// Generate `new` and `with_endpoint` constructors on the client struct.
685///
686/// Both constructors are `#[cfg(not(target_arch = "wasm32"))]` because `registry`
687/// and `zmq_context` are non-wasm only.
688pub fn generate_constructors(service_name: &str) -> TokenStream {
689    let pascal = to_pascal_case(service_name);
690    let client_name = format_ident!("{}Client", pascal);
691    let service_name_lit = service_name;
692
693    quote! {
694        #[cfg(not(target_arch = "wasm32"))]
695        impl #client_name {
696            /// Legacy explicit local/bootstrap adapter.
697            ///
698            /// This remains necessary for co-located bootstrap, but it is not
699            /// production resolution and carries no closure evidence.
700            ///
701            /// `destination` is the Ed25519 verifying key of the target service,
702            /// used to verify response envelope signatures. This must be the target service's
703            /// actual pubkey (obtained via service JWT / discovery), NOT the caller's key.
704            ///
705            /// `token` is an optional CA-signed JWT certificate for trust establishment.
706            /// When provided, the token is included in request envelopes so the server
707            /// can bind the caller's Ed25519 key to a subject.
708            pub fn for_local_bootstrap(
709                signing_key: hyprstream_rpc::crypto::SigningKey,
710                destination: hyprstream_rpc::crypto::VerifyingKey,
711                token: Option<String>,
712            ) -> anyhow::Result<Self> {
713                let registry = hyprstream_rpc::registry::try_global()
714                    .ok_or_else(|| anyhow::anyhow!(
715                        "EndpointRegistry not initialized — local bootstrap requires registry::init()"
716                    ))?;
717                let transport = registry.registered_endpoint(
718                    #service_name_lit,
719                    hyprstream_rpc::registry::SocketKind::Rep,
720                ).ok_or_else(|| anyhow::anyhow!(
721                    "local bootstrap requires an explicitly registered service endpoint"
722                ))?;
723                Self::dial_local_transport_bootstrap(&transport, signing_key, destination, token)
724            }
725
726            /// Create a new client connected to a specific endpoint string
727            /// (`inproc://…` / `ipc://…`). Parsed to a `TransportConfig` and routed
728            /// through [`hyprstream_rpc::dial::dial`] — the one place transport
729            /// selection happens. Networked targets must be constructed with
730            /// [`Self::from_provider`] and an application-owned provider.
731            pub fn for_local_endpoint_bootstrap(
732                endpoint: &str,
733                signing_key: hyprstream_rpc::crypto::SigningKey,
734                destination: hyprstream_rpc::crypto::VerifyingKey,
735                token: Option<String>,
736            ) -> anyhow::Result<Self> {
737                let transport = hyprstream_rpc::transport::TransportConfig::from_endpoint(endpoint);
738                Self::dial_local_transport_bootstrap(&transport, signing_key, destination, token)
739            }
740
741            /// Create a client for an already-resolved typed
742            /// [`hyprstream_rpc::transport::TransportConfig`] (the Inproc arm for
743            /// a co-located service, or a networked Quic/Iroh reach). Prefer this
744            /// over [`Self::for_local_endpoint_bootstrap`] when the caller already holds a typed
745            /// transport (e.g. the inference router, #320) — it skips string
746            /// parsing and routes straight through [`hyprstream_rpc::dial::dial`].
747            pub fn for_local_transport_bootstrap(
748                transport: &hyprstream_rpc::transport::TransportConfig,
749                signing_key: hyprstream_rpc::crypto::SigningKey,
750                destination: hyprstream_rpc::crypto::VerifyingKey,
751                token: Option<String>,
752            ) -> anyhow::Result<Self> {
753                Self::dial_local_transport_bootstrap(transport, signing_key, destination, token)
754            }
755
756            /// Local/bootstrap dial helper. It is deliberately unable to
757            /// manufacture production resolution evidence.
758            fn dial_local_transport_bootstrap(
759                transport: &hyprstream_rpc::transport::TransportConfig,
760                signing_key: hyprstream_rpc::crypto::SigningKey,
761                destination: hyprstream_rpc::crypto::VerifyingKey,
762                token: Option<String>,
763            ) -> anyhow::Result<Self> {
764                anyhow::ensure!(
765                    matches!(
766                        &transport.endpoint,
767                        hyprstream_rpc::transport::EndpointType::Inproc { .. }
768                            | hyprstream_rpc::transport::EndpointType::Ipc { .. }
769                            | hyprstream_rpc::transport::EndpointType::SystemdFd { .. }
770                    ),
771                    "local bootstrap refuses network transport; use the identity-bound resolver",
772                );
773                let signer = hyprstream_rpc::signer::LocalSigner::new(signing_key);
774                let rpc = hyprstream_rpc::dial::dial(transport, signer, Some(destination), token)?;
775                Ok(Self::new(rpc))
776            }
777
778            /// Create a client from an `IdentityProvider` with automatic endpoint resolution.
779            pub async fn from_local_bootstrap_provider(
780                provider: &dyn hyprstream_rpc::identity::IdentityProvider,
781            ) -> anyhow::Result<Self> {
782                let registry = hyprstream_rpc::registry::try_global()
783                    .ok_or_else(|| anyhow::anyhow!(
784                        "EndpointRegistry not initialized — local bootstrap requires registry::init()"
785                    ))?;
786                let transport = registry.registered_endpoint(
787                    #service_name_lit,
788                    hyprstream_rpc::registry::SocketKind::Rep,
789                ).ok_or_else(|| anyhow::anyhow!(
790                    "local bootstrap requires an explicitly registered service endpoint"
791                ))?;
792                Self::from_local_provider_at_transport(&transport, provider).await
793            }
794
795            /// Create a client from an `IdentityProvider` at a specific endpoint string.
796            pub async fn from_local_bootstrap_provider_at(
797                endpoint: &str,
798                provider: &dyn hyprstream_rpc::identity::IdentityProvider,
799            ) -> anyhow::Result<Self> {
800                let transport = hyprstream_rpc::transport::TransportConfig::from_endpoint(endpoint);
801                Self::from_local_provider_at_transport(&transport, provider).await
802            }
803
804            async fn from_local_provider_at_transport(
805                transport: &hyprstream_rpc::transport::TransportConfig,
806                provider: &dyn hyprstream_rpc::identity::IdentityProvider,
807            ) -> anyhow::Result<Self> {
808                anyhow::ensure!(
809                    matches!(
810                        &transport.endpoint,
811                        hyprstream_rpc::transport::EndpointType::Inproc { .. }
812                            | hyprstream_rpc::transport::EndpointType::Ipc { .. }
813                            | hyprstream_rpc::transport::EndpointType::SystemdFd { .. }
814                    ),
815                    "local bootstrap refuses network transport; use the identity-bound resolver",
816                );
817                let handle = provider.identity_open(concat!("hyprstream-", #service_name_lit, "-v1")).await?;
818                let pubkey = handle.pubkey();
819                let server_vk = hyprstream_rpc::crypto::VerifyingKey::from_bytes(&pubkey)
820                    .map_err(|e| anyhow::anyhow!("invalid derived pubkey: {}", e))?;
821                let signer = hyprstream_rpc::signer::IdentitySigner::new(handle);
822                let rpc = hyprstream_rpc::dial::dial(transport, signer, Some(server_vk), None)?;
823                Ok(Self::new(rpc))
824            }
825        }
826    }
827}
828
829// ─────────────────────────────────────────────────────────────────────────────
830// Domain Type Resolution
831// ─────────────────────────────────────────────────────────────────────────────
832
833/// Resolve a domain type path from a `$domainType` annotation value.
834fn resolve_domain_type(domain_path: &str, types_crate: Option<&syn::Path>) -> TokenStream {
835    let path: TokenStream = domain_path.parse().unwrap_or_else(|_| quote! { Vec<u8> });
836    match types_crate {
837        Some(tc) => quote! { #tc::#path },
838        None => quote! { crate::#path },
839    }
840}
841
842// ─────────────────────────────────────────────────────────────────────────────
843// Response Enum
844// ─────────────────────────────────────────────────────────────────────────────
845
846pub fn generate_response_enum(
847    service_name: &str,
848    resolved: &ResolvedSchema,
849    types_crate: Option<&syn::Path>,
850) -> TokenStream {
851    let pascal = to_pascal_case(service_name);
852    let enum_name_str = format!("{pascal}ResponseVariant");
853    generate_response_enum_from_variants(
854        &enum_name_str,
855        &resolved.raw.response_variants,
856        resolved,
857        types_crate,
858    )
859}
860
861pub fn generate_response_enum_from_variants(
862    enum_name_str: &str,
863    variants: &[UnionVariant],
864    resolved: &ResolvedSchema,
865    types_crate: Option<&syn::Path>,
866) -> TokenStream {
867    let enum_name = format_ident!("{}", enum_name_str);
868    let doc = format!("Response variants for the {} service.", enum_name_str);
869
870    let variant_tokens: Vec<TokenStream> = variants
871        .iter()
872        .map(|v| generate_enum_variant(v, resolved, types_crate))
873        .collect();
874
875    quote! {
876        #[doc = #doc]
877        #[derive(Debug, serde::Serialize)]
878        pub enum #enum_name {
879            #(#variant_tokens,)*
880        }
881    }
882}
883
884fn generate_enum_variant(
885    v: &UnionVariant,
886    resolved: &ResolvedSchema,
887    types_crate: Option<&syn::Path>,
888) -> TokenStream {
889    let variant_pascal = resolved.name(&v.name).pascal_ident.clone();
890
891    match v.type_name.as_str() {
892        "Void" => quote! { #variant_pascal },
893        "Bool" => quote! { #variant_pascal(bool) },
894        "Text" => quote! { #variant_pascal(String) },
895        "Data" => quote! { #variant_pascal(Vec<u8>) },
896        "UInt32" | "UInt64" | "Int32" | "Int64" | "Float32" | "Float64" | "UInt8" | "UInt16"
897        | "Int8" | "Int16" => {
898            let rust_type =
899                rust_type_tokens(&CapnpType::classify_primitive(&v.type_name).rust_owned_type());
900            quote! { #variant_pascal(#rust_type) }
901        }
902        type_name if type_name.starts_with("List(") => {
903            let inner = &type_name[5..type_name.len() - 1];
904            match inner {
905                "Text" => quote! { #variant_pascal(Vec<String>) },
906                "Data" => quote! { #variant_pascal(Vec<Vec<u8>>) },
907                _ => {
908                    let rt = resolved.resolve_type(inner);
909                    if rt.is_numeric {
910                        let rust_inner = rust_type_tokens(&rt.rust_owned);
911                        quote! { #variant_pascal(Vec<#rust_inner>) }
912                    } else if resolved.is_struct(inner) {
913                        let inner_data = format_ident!("{}", inner);
914                        quote! { #variant_pascal(Vec<#inner_data>) }
915                    } else {
916                        quote! { #variant_pascal(Vec<String>) }
917                    }
918                }
919            }
920        }
921        struct_name => {
922            if let Some(s) = resolved.find_struct(struct_name) {
923                if let Some(ref dt) = s.domain_type {
924                    let domain_path = resolve_domain_type(dt, types_crate);
925                    quote! { #variant_pascal(#domain_path) }
926                } else {
927                    let data_type = format_ident!("{}", struct_name);
928                    quote! { #variant_pascal(#data_type) }
929                }
930            } else {
931                quote! { #variant_pascal(Vec<u8>) }
932            }
933        }
934    }
935}
936
937// ─────────────────────────────────────────────────────────────────────────────
938// Client Struct + Impl
939// ─────────────────────────────────────────────────────────────────────────────
940
941pub fn generate_client(
942    service_name: &str,
943    resolved: &ResolvedSchema,
944    types_crate: Option<&syn::Path>,
945) -> TokenStream {
946    let pascal = to_pascal_case(service_name);
947    let client_name = format_ident!("{}Client", pascal);
948    let response_type = format_ident!("{}ResponseVariant", pascal);
949    let capnp_mod_ident = format_ident!("{}_capnp", service_name);
950    let capnp_mod: TokenStream = match types_crate {
951        Some(tc) => quote! { #tc::#capnp_mod_ident },
952        None => quote! { crate::#capnp_mod_ident },
953    };
954    let req_type = format_ident!("{}", to_snake_case(&format!("{pascal}Request")));
955    let doc = format!("Auto-generated client for the {pascal} service.");
956
957    let scoped_variant_names: Vec<&str> = resolved
958        .raw
959        .scoped_clients
960        .iter()
961        .map(|sc| sc.factory_name.as_str())
962        .collect();
963
964    // Request methods (portable, carrying immutable per-client call options).
965    let request_methods: Vec<TokenStream> = resolved
966        .raw
967        .request_variants
968        .iter()
969        .filter(|v| !scoped_variant_names.contains(&v.name.as_str()))
970        .map(|v| {
971            generate_request_method_inner(
972                &capnp_mod,
973                &req_type,
974                &response_type,
975                v,
976                resolved,
977                None,
978                Some(&resolved.raw.response_variants),
979                false,
980                types_crate,
981            )
982        })
983        .collect();
984
985    // parse_response method
986    let parse_response = generate_parse_response_fn(
987        &response_type,
988        &capnp_mod,
989        &format_ident!("{}", to_snake_case(&format!("{pascal}Response"))),
990        &resolved.raw.response_variants,
991        resolved,
992        types_crate,
993    );
994
995    // Factory methods for scoped clients
996    let factory_methods: Vec<TokenStream> = resolved
997        .raw
998        .scoped_clients
999        .iter()
1000        .map(generate_portable_scoped_factory_method)
1001        .collect();
1002
1003    quote! {
1004        #[doc = #doc]
1005        #[derive(Clone)]
1006        pub struct #client_name {
1007            client: std::sync::Arc<dyn hyprstream_rpc::RpcClient>,
1008            call_options: hyprstream_rpc::CallOptions,
1009        }
1010
1011        impl #client_name {
1012            /// Canonical service/destination domain used for cryptographic RPC binding.
1013            pub const SERVICE_NAME: &'static str = #service_name;
1014
1015            /// Create from any RpcClient implementation.
1016            pub fn new(client: std::sync::Arc<dyn hyprstream_rpc::RpcClient>) -> Self {
1017                Self { client, call_options: hyprstream_rpc::CallOptions::default() }
1018            }
1019
1020            /// Construct this typed client through an application-supplied
1021            /// [`hyprstream_rpc::RpcClientProvider`].  Resolver authority and
1022            /// endpoint policy stay outside the portable contract crate.
1023            pub fn from_provider(
1024                provider: &dyn hyprstream_rpc::RpcClientProvider,
1025                signing_key: hyprstream_rpc::crypto::SigningKey,
1026                token: Option<String>,
1027            ) -> anyhow::Result<Self> {
1028                Ok(Self::new(provider.rpc_client(Self::SERVICE_NAME, signing_key, token)?))
1029            }
1030            #[must_use]
1031            pub fn with_delegated_bearer(mut self, token: impl Into<String>) -> Self {
1032                self.call_options.delegated_bearer = Some(token.into());
1033                self
1034            }
1035
1036            /// Set this client's DIRECT bearer for every call.
1037            ///
1038            /// Unlike [`Self::with_delegated_bearer`], the token travels as the
1039            /// envelope's own JWT — the caller is asserting the token as ITS
1040            /// verified credential, and the receiving service's holder/cnf
1041            /// binding applies against this client's signing key. Used for
1042            /// caller-authored credentials (e.g. the Model→Inference
1043            /// `iw+jwt` internal work order); never for relaying a foreign
1044            /// holder's token.
1045            #[must_use]
1046            pub fn with_bearer(mut self, token: impl Into<String>) -> Self {
1047                self.call_options.jwt = Some(token.into());
1048                self
1049            }
1050
1051            /// Get the next request ID.
1052            pub fn next_id(&self) -> u64 {
1053                self.client.next_id()
1054            }
1055
1056            /// Create a per-call request builder for custom authentication options.
1057            ///
1058            /// The builder is Send+Sync and idempotent — it stores per-call auth
1059            /// context without mutating the shared client. Safe for use with
1060            /// connection pooling.
1061            pub fn request(&self) -> hyprstream_rpc::RequestBuilder<'_> {
1062                let builder =
1063                    hyprstream_rpc::RequestBuilder::for_service(&self.client, Self::SERVICE_NAME);
1064                let builder = match &self.call_options.jwt {
1065                    Some(token) => builder.jwt(token.clone()),
1066                    None => builder,
1067                };
1068                match &self.call_options.delegated_bearer {
1069                    Some(token) => builder.delegated_bearer(token.clone()),
1070                    None => builder,
1071                }
1072            }
1073
1074            /// Send a raw request and return the raw response bytes.
1075            pub async fn call(&self, payload: Vec<u8>) -> anyhow::Result<Vec<u8>> {
1076                self.client.call_with_options_for_service(
1077                    Self::SERVICE_NAME, payload, self.call_options.clone()).await
1078            }
1079
1080            /// Send a generated request with its canonical schema method id.
1081            pub async fn call_with_method(
1082                &self,
1083                method_discriminator: u16,
1084                payload: Vec<u8>,
1085            ) -> anyhow::Result<Vec<u8>> {
1086                self.client
1087                    .call_with_options_for_service_with_method(
1088                        Self::SERVICE_NAME, method_discriminator, payload,
1089                        self.call_options.clone())
1090                    .await
1091            }
1092
1093            /// Send a streaming request with ephemeral DH pubkey.
1094            pub async fn call_streaming(&self, payload: Vec<u8>, ephemeral_pubkey: [u8; 32]) -> anyhow::Result<Vec<u8>> {
1095                self.client.call_streaming_with_options_for_service(
1096                    Self::SERVICE_NAME, payload, ephemeral_pubkey,
1097                    self.call_options.clone()).await
1098            }
1099
1100            /// Send a generated streaming request with its schema method id.
1101            pub async fn call_streaming_with_method(
1102                &self,
1103                method_discriminator: u16,
1104                payload: Vec<u8>,
1105                ephemeral_pubkey: [u8; 32],
1106            ) -> anyhow::Result<Vec<u8>> {
1107                self.client
1108                    .call_streaming_with_options_for_service_with_method(
1109                        Self::SERVICE_NAME,
1110                        method_discriminator,
1111                        payload,
1112                        ephemeral_pubkey,
1113                        self.call_options.clone(),).await
1114            }
1115
1116            #(#request_methods)*
1117
1118            #parse_response
1119
1120            #(#factory_methods)*
1121        }
1122    }
1123}
1124
1125// ─────────────────────────────────────────────────────────────────────────────
1126// Request Method Generation
1127// ─────────────────────────────────────────────────────────────────────────────
1128
1129/// Generate a portable request method (no CallOptions, no ZMQ deps).
1130#[allow(clippy::too_many_arguments)]
1131pub fn generate_portable_request_method(
1132    capnp_mod: &TokenStream,
1133    req_type: &syn::Ident,
1134    response_type: &syn::Ident,
1135    variant: &UnionVariant,
1136    resolved: &ResolvedSchema,
1137    scope: Option<&ScopedMethodContext>,
1138    response_variants: Option<&[UnionVariant]>,
1139    is_scoped: bool,
1140    types_crate: Option<&syn::Path>,
1141) -> TokenStream {
1142    generate_request_method_inner(
1143        capnp_mod,
1144        req_type,
1145        response_type,
1146        variant,
1147        resolved,
1148        scope,
1149        response_variants,
1150        is_scoped,
1151        types_crate,
1152    )
1153}
1154
1155/// Inner request method generation (transport-agnostic).
1156#[allow(clippy::too_many_arguments)]
1157fn generate_request_method_inner(
1158    capnp_mod: &TokenStream,
1159    req_type: &syn::Ident,
1160    response_type: &syn::Ident,
1161    variant: &UnionVariant,
1162    resolved: &ResolvedSchema,
1163    scope: Option<&ScopedMethodContext>,
1164    response_variants: Option<&[UnionVariant]>,
1165    is_scoped: bool,
1166    types_crate: Option<&syn::Path>,
1167) -> TokenStream {
1168    let method_name = format_ident!("{}", to_snake_case(&variant.name));
1169    let method_discriminator = scope
1170        .map(|context| context.root_method_discriminator)
1171        .unwrap_or_else(|| {
1172            resolved
1173                .raw
1174                .request_struct
1175                .as_ref()
1176                .and_then(|request| {
1177                    request
1178                        .union_fields()
1179                        .find(|field| field.name == variant.name)
1180                })
1181                .map(|field| field.discriminant_value)
1182                .unwrap_or_else(|| {
1183                    resolved
1184                        .raw
1185                        .request_variants
1186                        .iter()
1187                        .position(|candidate| candidate.name == variant.name)
1188                        .and_then(|index| u16::try_from(index).ok())
1189                        .unwrap_or(0)
1190                })
1191        });
1192    let doc = if variant.description.is_empty() {
1193        format!(
1194            "{} ({} variant)",
1195            to_snake_case(&variant.name),
1196            variant.type_name
1197        )
1198    } else {
1199        let scope_info = if variant.scope.is_empty() {
1200            String::new()
1201        } else {
1202            format!("\n\nScope: {}", variant.scope)
1203        };
1204        format!("{}{}", variant.description, scope_info)
1205    };
1206
1207    // For scoped methods, walk the ScopedMethodContext chain and shadow `req`
1208    let (outer_req_setup, parse_call) = if let Some(sc) = scope {
1209        let mut chain = Vec::new();
1210        let mut cur = Some(sc);
1211        while let Some(c) = cur {
1212            chain.push(c);
1213            cur = c.parent.as_deref();
1214        }
1215        chain.reverse();
1216
1217        let mut setup = TokenStream::new();
1218        let mut prev_var = format_ident!("req");
1219
1220        for (i, level) in chain.iter().enumerate() {
1221            let init_fn = format_ident!("init_{}", to_snake_case(&level.factory_name));
1222            let tmp = format_ident!("__s{}", i);
1223
1224            setup.extend(quote! { let mut #tmp = #prev_var.#init_fn(); });
1225
1226            for f in &level.scope_fields {
1227                let setter = format_ident!("set_{}", to_snake_case(&f.name));
1228                let field = format_ident!("{}", to_snake_case(&f.name));
1229                setup.extend(match f.type_name.as_str() {
1230                    "Text" => quote! { #tmp.#setter(&self.#field); },
1231                    _ => quote! { #tmp.#setter(self.#field); },
1232                });
1233            }
1234            prev_var = tmp;
1235        }
1236
1237        setup.extend(quote! { let mut req = #prev_var; });
1238
1239        (setup, quote! { Self::parse_scoped_response(&response) })
1240    } else {
1241        (
1242            TokenStream::new(),
1243            quote! { Self::parse_response(&response) },
1244        )
1245    };
1246
1247    // Determine typed return info if response_variants are available
1248    let typed_info = response_variants.and_then(|resp_vars| {
1249        find_typed_return_info(
1250            &variant.name,
1251            resp_vars,
1252            resolved,
1253            is_scoped,
1254            response_type,
1255            &parse_call,
1256            types_crate,
1257        )
1258    });
1259
1260    // Detect if this method returns StreamInfo
1261    let is_streaming = response_variants
1262        .and_then(|resp_vars| {
1263            let expected_name = if is_scoped {
1264                variant.name.clone()
1265            } else {
1266                format!("{}Result", variant.name)
1267            };
1268            resp_vars.iter().find(|v| v.name == expected_name)
1269        })
1270        .map(|v| is_rpc_stream_info(&v.type_name, resolved))
1271        .unwrap_or(false);
1272
1273    // For streaming methods, use call_streaming with ephemeral pubkey
1274    let (return_type, response_handling, extra_param, call_expr) = if is_streaming {
1275        let (rt, rh) = if let Some(ref info) = typed_info {
1276            let ret = &info.return_type;
1277            let match_body = &info.match_body;
1278            (quote! { #ret }, quote! { #match_body })
1279        } else {
1280            (quote! { #response_type }, quote! { #parse_call })
1281        };
1282        (
1283            rt,
1284            rh,
1285            quote! { , ephemeral_pubkey: [u8; 32] },
1286            quote! {
1287                let response = self.call_streaming_with_method(#method_discriminator,payload, ephemeral_pubkey).await?;
1288            },
1289        )
1290    } else {
1291        let (rt, rh) = if let Some(ref info) = typed_info {
1292            let ret = &info.return_type;
1293            let match_body = &info.match_body;
1294            (quote! { #ret }, quote! { #match_body })
1295        } else {
1296            (quote! { #response_type }, quote! { #parse_call })
1297        };
1298        (
1299            rt,
1300            rh,
1301            TokenStream::new(),
1302            quote! { let response = self.call_with_method(#method_discriminator,payload).await?; },
1303        )
1304    };
1305
1306    match variant.type_name.as_str() {
1307        "Void" => {
1308            let set_method = format_ident!("set_{}", to_snake_case(&variant.name));
1309            let setter = quote! { req.#set_method(()); };
1310            quote! {
1311                #[doc = #doc]
1312                pub async fn #method_name(&self #extra_param) -> anyhow::Result<#return_type> {
1313                    let __request_id = self.next_id();
1314                    let payload = hyprstream_rpc::serialize_message(|msg| {
1315                        let mut req = msg.init_root::<#capnp_mod::#req_type::Builder>();
1316                        req.set_id(__request_id);
1317                        #outer_req_setup
1318                        #setter
1319                    })?;
1320                    #call_expr
1321                    #response_handling
1322                }
1323            }
1324        }
1325        "Text" => {
1326            let set_method = format_ident!("set_{}", to_snake_case(&variant.name));
1327            let setter = quote! { req.#set_method(value); };
1328            quote! {
1329                #[doc = #doc]
1330                pub async fn #method_name(&self, value: &str #extra_param) -> anyhow::Result<#return_type> {
1331                    let __request_id = self.next_id();
1332                    let payload = hyprstream_rpc::serialize_message(|msg| {
1333                        let mut req = msg.init_root::<#capnp_mod::#req_type::Builder>();
1334                        req.set_id(__request_id);
1335                        #outer_req_setup
1336                        #setter
1337                    })?;
1338                    #call_expr
1339                    #response_handling
1340                }
1341            }
1342        }
1343        "Data" => {
1344            let set_method = format_ident!("set_{}", to_snake_case(&variant.name));
1345            let setter = quote! { req.#set_method(value); };
1346            quote! {
1347                #[doc = #doc]
1348                pub async fn #method_name(&self, value: &[u8] #extra_param) -> anyhow::Result<#return_type> {
1349                    let __request_id = self.next_id();
1350                    let payload = hyprstream_rpc::serialize_message(|msg| {
1351                        let mut req = msg.init_root::<#capnp_mod::#req_type::Builder>();
1352                        req.set_id(__request_id);
1353                        #outer_req_setup
1354                        #setter
1355                    })?;
1356                    #call_expr
1357                    #response_handling
1358                }
1359            }
1360        }
1361        "Bool" => {
1362            let set_method = format_ident!("set_{}", to_snake_case(&variant.name));
1363            let setter = quote! { req.#set_method(value); };
1364            quote! {
1365                #[doc = #doc]
1366                pub async fn #method_name(&self, value: bool #extra_param) -> anyhow::Result<#return_type> {
1367                    let __request_id = self.next_id();
1368                    let payload = hyprstream_rpc::serialize_message(|msg| {
1369                        let mut req = msg.init_root::<#capnp_mod::#req_type::Builder>();
1370                        req.set_id(__request_id);
1371                        #outer_req_setup
1372                        #setter
1373                    })?;
1374                    #call_expr
1375                    #response_handling
1376                }
1377            }
1378        }
1379        t if CapnpType::classify_primitive(t).is_numeric() => {
1380            let set_method = format_ident!("set_{}", to_snake_case(&variant.name));
1381            let setter = quote! { req.#set_method(value); };
1382            let ty = rust_type_tokens(&CapnpType::classify_primitive(t).rust_owned_type());
1383            quote! {
1384                #[doc = #doc]
1385                pub async fn #method_name(&self, value: #ty #extra_param) -> anyhow::Result<#return_type> {
1386                    let __request_id = self.next_id();
1387                    let payload = hyprstream_rpc::serialize_message(|msg| {
1388                        let mut req = msg.init_root::<#capnp_mod::#req_type::Builder>();
1389                        req.set_id(__request_id);
1390                        #outer_req_setup
1391                        #setter
1392                    })?;
1393                    #call_expr
1394                    #response_handling
1395                }
1396            }
1397        }
1398        struct_name => {
1399            if let Some(s) = resolved.find_struct(struct_name) {
1400                let nuf: Vec<_> = s.non_union_fields().collect();
1401                let is_void_wrapper =
1402                    nuf.is_empty() || (nuf.len() == 1 && nuf[0].type_name == "Void");
1403
1404                if is_void_wrapper {
1405                    let init_method = format_ident!("init_{}", to_snake_case(&variant.name));
1406                    let setter = quote! { req.#init_method(); };
1407                    quote! {
1408                        #[doc = #doc]
1409                        pub async fn #method_name(&self #extra_param) -> anyhow::Result<#return_type> {
1410                            let __request_id = self.next_id();
1411                            let payload = hyprstream_rpc::serialize_message(|msg| {
1412                                let mut req = msg.init_root::<#capnp_mod::#req_type::Builder>();
1413                                req.set_id(__request_id);
1414                                #outer_req_setup
1415                                #setter
1416                            })?;
1417                            #call_expr
1418                            #response_handling
1419                        }
1420                    }
1421                } else {
1422                    let data_name = format_ident!("{}", struct_name);
1423                    let init_method = format_ident!("init_{}", to_snake_case(&variant.name));
1424
1425                    quote! {
1426                        #[doc = #doc]
1427                        pub async fn #method_name(&self, __request: &#data_name #extra_param) -> anyhow::Result<#return_type> {
1428                            let __request_id = self.next_id();
1429                            let payload = hyprstream_rpc::serialize_message(|msg| {
1430                                let mut req = msg.init_root::<#capnp_mod::#req_type::Builder>();
1431                                req.set_id(__request_id);
1432                                #outer_req_setup
1433                                let mut __inner = req.#init_method();
1434                                hyprstream_rpc::capnp::ToCapnp::write_to(__request, &mut __inner);
1435                            })?;
1436                            #call_expr
1437                            #response_handling
1438                        }
1439                    }
1440                }
1441            } else {
1442                let _comment = format!(
1443                    "TODO: {} — struct {} not found in schema",
1444                    to_snake_case(&variant.name),
1445                    struct_name
1446                );
1447                quote! {
1448                    // #comment
1449                }
1450            }
1451        }
1452    }
1453}
1454
1455// ─────────────────────────────────────────────────────────────────────────────
1456// Typed Return Info
1457// ─────────────────────────────────────────────────────────────────────────────
1458
1459struct TypedReturnInfo {
1460    return_type: TokenStream,
1461    match_body: TokenStream,
1462}
1463
1464fn find_typed_return_info(
1465    request_name: &str,
1466    response_variants: &[UnionVariant],
1467    resolved: &ResolvedSchema,
1468    is_scoped: bool,
1469    response_type: &syn::Ident,
1470    parse_call: &TokenStream,
1471    types_crate: Option<&syn::Path>,
1472) -> Option<TypedReturnInfo> {
1473    let expected_name = if is_scoped {
1474        request_name.to_owned()
1475    } else {
1476        format!("{}Result", request_name)
1477    };
1478
1479    let resp_variant = response_variants.iter().find(|v| v.name == expected_name)?;
1480    let variant_pascal = resolved.name(&resp_variant.name).pascal_ident.clone();
1481    let ct = resolved
1482        .resolve_type(&resp_variant.type_name)
1483        .capnp_type
1484        .clone();
1485
1486    let has_error = response_variants.iter().any(|v| v.name == "error");
1487
1488    let error_arm = if has_error {
1489        quote! {
1490            #response_type::Error(ref e) => Err(anyhow::anyhow!("{}", e.message)),
1491        }
1492    } else {
1493        TokenStream::new()
1494    };
1495
1496    let wildcard_arm = quote! {
1497        _ => Err(anyhow::anyhow!("Unexpected response variant")),
1498    };
1499
1500    match ct {
1501        CapnpType::Void => Some(TypedReturnInfo {
1502            return_type: quote! { () },
1503            match_body: quote! {
1504                match #parse_call? {
1505                    #response_type::#variant_pascal => Ok(()),
1506                    #error_arm
1507                    #wildcard_arm
1508                }
1509            },
1510        }),
1511        CapnpType::Bool => Some(TypedReturnInfo {
1512            return_type: quote! { bool },
1513            match_body: quote! {
1514                match #parse_call? {
1515                    #response_type::#variant_pascal(v) => Ok(v),
1516                    #error_arm
1517                    #wildcard_arm
1518                }
1519            },
1520        }),
1521        CapnpType::Text => Some(TypedReturnInfo {
1522            return_type: quote! { String },
1523            match_body: quote! {
1524                match #parse_call? {
1525                    #response_type::#variant_pascal(v) => Ok(v),
1526                    #error_arm
1527                    #wildcard_arm
1528                }
1529            },
1530        }),
1531        CapnpType::Data => Some(TypedReturnInfo {
1532            return_type: quote! { Vec<u8> },
1533            match_body: quote! {
1534                match #parse_call? {
1535                    #response_type::#variant_pascal(v) => Ok(v),
1536                    #error_arm
1537                    #wildcard_arm
1538                }
1539            },
1540        }),
1541        CapnpType::UInt8
1542        | CapnpType::UInt16
1543        | CapnpType::UInt32
1544        | CapnpType::UInt64
1545        | CapnpType::Int8
1546        | CapnpType::Int16
1547        | CapnpType::Int32
1548        | CapnpType::Int64
1549        | CapnpType::Float32
1550        | CapnpType::Float64 => {
1551            let rust_type = rust_type_tokens(&ct.rust_owned_type());
1552            Some(TypedReturnInfo {
1553                return_type: quote! { #rust_type },
1554                match_body: quote! {
1555                    match #parse_call? {
1556                        #response_type::#variant_pascal(v) => Ok(v),
1557                        #error_arm
1558                        #wildcard_arm
1559                    }
1560                },
1561            })
1562        }
1563        CapnpType::ListText => Some(TypedReturnInfo {
1564            return_type: quote! { Vec<String> },
1565            match_body: quote! {
1566                match #parse_call? {
1567                    #response_type::#variant_pascal(v) => Ok(v),
1568                    #error_arm
1569                    #wildcard_arm
1570                }
1571            },
1572        }),
1573        CapnpType::ListData => Some(TypedReturnInfo {
1574            return_type: quote! { Vec<Vec<u8>> },
1575            match_body: quote! {
1576                match #parse_call? {
1577                    #response_type::#variant_pascal(v) => Ok(v),
1578                    #error_arm
1579                    #wildcard_arm
1580                }
1581            },
1582        }),
1583        CapnpType::ListPrimitive(ref inner) => {
1584            let rust_inner = rust_type_tokens(&inner.rust_owned_type());
1585            Some(TypedReturnInfo {
1586                return_type: quote! { Vec<#rust_inner> },
1587                match_body: quote! {
1588                    match #parse_call? {
1589                        #response_type::#variant_pascal(v) => Ok(v),
1590                        #error_arm
1591                        #wildcard_arm
1592                    }
1593                },
1594            })
1595        }
1596        CapnpType::ListStruct(ref inner) => {
1597            let data_name = format_ident!("{}", inner);
1598            Some(TypedReturnInfo {
1599                return_type: quote! { Vec<#data_name> },
1600                match_body: quote! {
1601                    match #parse_call? {
1602                        #response_type::#variant_pascal(v) => Ok(v),
1603                        #error_arm
1604                        #wildcard_arm
1605                    }
1606                },
1607            })
1608        }
1609        CapnpType::Struct(ref name) => {
1610            if let Some(s) = resolved.find_struct(name) {
1611                let return_type = if let Some(ref dt) = s.domain_type {
1612                    resolve_domain_type(dt, types_crate)
1613                } else {
1614                    let data_name = format_ident!("{}", name);
1615                    quote! { #data_name }
1616                };
1617                Some(TypedReturnInfo {
1618                    return_type: return_type.clone(),
1619                    match_body: quote! {
1620                        match #parse_call? {
1621                            #response_type::#variant_pascal(v) => Ok(v),
1622                            #error_arm
1623                            #wildcard_arm
1624                        }
1625                    },
1626                })
1627            } else {
1628                None
1629            }
1630        }
1631        _ => None,
1632    }
1633}
1634
1635/// Context for scoped method generation.
1636pub struct ScopedMethodContext {
1637    pub factory_name: String,
1638    pub scope_fields: Vec<FieldDef>,
1639    pub parent: Option<Box<ScopedMethodContext>>,
1640    /// Canonical discriminator of the outermost service union arm.
1641    pub root_method_discriminator: u16,
1642}
1643
1644// ─────────────────────────────────────────────────────────────────────────────
1645// parse_response
1646// ─────────────────────────────────────────────────────────────────────────────
1647
1648pub fn generate_parse_response_fn(
1649    response_type: &syn::Ident,
1650    capnp_mod: &TokenStream,
1651    resp_type: &syn::Ident,
1652    variants: &[UnionVariant],
1653    resolved: &ResolvedSchema,
1654    types_crate: Option<&syn::Path>,
1655) -> TokenStream {
1656    let which_ident = format_ident!("Which");
1657    let match_arms: Vec<TokenStream> = variants
1658        .iter()
1659        .map(|v| {
1660            generate_parse_match_arm(
1661                response_type,
1662                capnp_mod,
1663                v,
1664                resolved,
1665                &which_ident,
1666                types_crate,
1667            )
1668        })
1669        .collect();
1670
1671    quote! {
1672        /// Parse a response from raw bytes.
1673        pub fn parse_response(bytes: &[u8]) -> anyhow::Result<#response_type> {
1674            let reader = capnp::serialize::read_message(
1675                &mut std::io::Cursor::new(bytes),
1676                capnp::message::ReaderOptions::new(),
1677            )?;
1678            let resp = reader.get_root::<#capnp_mod::#resp_type::Reader>()?;
1679            use #capnp_mod::#resp_type::Which;
1680            match resp.which()? {
1681                #(#match_arms)*
1682            }
1683        }
1684    }
1685}
1686
1687pub fn generate_parse_match_arm(
1688    response_type: &syn::Ident,
1689    capnp_mod: &TokenStream,
1690    v: &UnionVariant,
1691    resolved: &ResolvedSchema,
1692    which_ident: &syn::Ident,
1693    types_crate: Option<&syn::Path>,
1694) -> TokenStream {
1695    let variant_pascal = resolved.name(&v.name).pascal_ident.clone();
1696    let ct = resolved.resolve_type(&v.type_name).capnp_type.clone();
1697
1698    match ct {
1699        CapnpType::Void => quote! {
1700            #which_ident::#variant_pascal(()) => Ok(#response_type::#variant_pascal),
1701        },
1702        CapnpType::Bool
1703        | CapnpType::UInt8
1704        | CapnpType::UInt16
1705        | CapnpType::UInt32
1706        | CapnpType::UInt64
1707        | CapnpType::Int8
1708        | CapnpType::Int16
1709        | CapnpType::Int32
1710        | CapnpType::Int64
1711        | CapnpType::Float32
1712        | CapnpType::Float64 => quote! {
1713            #which_ident::#variant_pascal(v) => Ok(#response_type::#variant_pascal(v)),
1714        },
1715        CapnpType::Text => quote! {
1716            #which_ident::#variant_pascal(v) => Ok(#response_type::#variant_pascal(v?.to_str()?.to_string())),
1717        },
1718        CapnpType::Data => quote! {
1719            #which_ident::#variant_pascal(v) => Ok(#response_type::#variant_pascal(v?.to_vec())),
1720        },
1721        CapnpType::ListText
1722        | CapnpType::ListData
1723        | CapnpType::ListPrimitive(_)
1724        | CapnpType::ListStruct(_) => generate_list_parse_arm(
1725            &variant_pascal,
1726            response_type,
1727            &v.type_name,
1728            resolved,
1729            capnp_mod,
1730            which_ident,
1731        ),
1732        CapnpType::Struct(ref name) => {
1733            if let Some(s) = resolved.find_struct(name) {
1734                let data_type = if let Some(ref dt) = s.domain_type {
1735                    resolve_domain_type(dt, types_crate)
1736                } else {
1737                    let ident = format_ident!("{}", name);
1738                    quote! { #ident }
1739                };
1740                quote! {
1741                    #which_ident::#variant_pascal(v) => {
1742                        let v = v?;
1743                        Ok(#response_type::#variant_pascal(
1744                            <#data_type as hyprstream_rpc::FromCapnp>::read_from(v)?
1745                        ))
1746                    }
1747                }
1748            } else {
1749                quote! {
1750                    #which_ident::#variant_pascal(_v) => {
1751                        Ok(#response_type::#variant_pascal(Vec::new()))
1752                    }
1753                }
1754            }
1755        }
1756        _ => quote! {
1757            #which_ident::#variant_pascal(_v) => {
1758                Ok(#response_type::#variant_pascal(Vec::new()))
1759            }
1760        },
1761    }
1762}
1763
1764fn generate_list_parse_arm(
1765    variant_pascal: &syn::Ident,
1766    response_type: &syn::Ident,
1767    type_name: &str,
1768    resolved: &ResolvedSchema,
1769    _capnp_mod: &TokenStream,
1770    which_ident: &syn::Ident,
1771) -> TokenStream {
1772    let ct = resolved.resolve_type(type_name).capnp_type.clone();
1773    match ct {
1774        CapnpType::ListText => quote! {
1775            #which_ident::#variant_pascal(v) => {
1776                let list = v?;
1777                let mut result = Vec::with_capacity(list.len() as usize);
1778                for i in 0..list.len() {
1779                    result.push(list.get(i)?.to_str()?.to_string());
1780                }
1781                Ok(#response_type::#variant_pascal(result))
1782            }
1783        },
1784        CapnpType::ListPrimitive(_) => quote! {
1785            #which_ident::#variant_pascal(v) => {
1786                let list = v?;
1787                let result: Vec<_> = list.iter().collect();
1788                Ok(#response_type::#variant_pascal(result))
1789            }
1790        },
1791        CapnpType::ListStruct(ref inner) => {
1792            if resolved.is_struct(inner) {
1793                quote! {
1794                    #which_ident::#variant_pascal(v) => {
1795                        let list = v?;
1796                        let mut result = Vec::with_capacity(list.len() as usize);
1797                        for i in 0..list.len() {
1798                            result.push(hyprstream_rpc::capnp::FromCapnp::read_from(list.get(i))?);
1799                        }
1800                        Ok(#response_type::#variant_pascal(result))
1801                    }
1802                }
1803            } else {
1804                quote! {
1805                    #which_ident::#variant_pascal(_v) => {
1806                        Ok(#response_type::#variant_pascal(Vec::new()))
1807                    }
1808                }
1809            }
1810        }
1811        _ => quote! {
1812            #which_ident::#variant_pascal(_v) => {
1813                Ok(#response_type::#variant_pascal(Vec::new()))
1814            }
1815        },
1816    }
1817}
1818
1819// ─────────────────────────────────────────────────────────────────────────────
1820// Scoped Factory Method
1821// ─────────────────────────────────────────────────────────────────────────────
1822
1823/// Generate a scoped factory method for portable clients (no jwt_token field).
1824fn generate_portable_scoped_factory_method(sc: &ScopedClient) -> TokenStream {
1825    let method_name = format_ident!("{}", to_snake_case(&sc.factory_name));
1826    let client_name_ident = format_ident!("{}", sc.client_name);
1827    let doc = format!("Create a scoped {} client.", sc.factory_name);
1828
1829    let params: Vec<TokenStream> = sc
1830        .scope_fields
1831        .iter()
1832        .map(|f| {
1833            let name = format_ident!("{}", to_snake_case(&f.name));
1834            let ty =
1835                rust_type_tokens(&CapnpType::classify_primitive(&f.type_name).rust_param_type());
1836            quote! { #name: #ty }
1837        })
1838        .collect();
1839
1840    let field_inits: Vec<TokenStream> = sc
1841        .scope_fields
1842        .iter()
1843        .map(|f| {
1844            let name = format_ident!("{}", to_snake_case(&f.name));
1845            match f.type_name.as_str() {
1846                "Text" => quote! { #name: #name.to_owned() },
1847                _ => quote! { #name },
1848            }
1849        })
1850        .collect();
1851
1852    quote! {
1853        #[doc = #doc]
1854        pub fn #method_name(&self #(, #params)*) -> #client_name_ident {
1855            #client_name_ident {
1856                client: std::sync::Arc::clone(&self.client),
1857                call_options: self.call_options.clone(),
1858                #(#field_inits,)*
1859            }
1860        }
1861    }
1862}
1863
1864#[cfg(test)]
1865#[allow(clippy::expect_used)]
1866mod resolved_service_codegen_tests {
1867    use super::generate_constructors;
1868
1869    #[test]
1870    fn generated_clients_require_explicit_provider_for_production() {
1871        let generated = generate_constructors("model").to_string();
1872        assert!(!generated.contains("production_rpc_client"));
1873        assert!(!generated.contains("SelectedService"));
1874        assert!(!generated.contains("ServiceResolver"));
1875        assert!(!generated.contains("try_global_service"));
1876        assert!(!generated.contains("from_service_resolver"));
1877        assert!(!generated.contains("ResolvedRpcClient"));
1878        assert!(!generated.contains("from_installed_resolver"));
1879        assert!(!generated.contains("from_resolver"));
1880        assert_eq!(
1881            generated
1882                .matches("local bootstrap refuses network transport")
1883                .count(),
1884            2,
1885        );
1886        assert!(!generated.contains("pub fn for_service"));
1887        assert!(!generated.contains("pub async fn from_provider"));
1888        assert!(generated.contains("for_local_bootstrap"));
1889        assert!(generated.contains("from_local_bootstrap_provider"));
1890    }
1891
1892    #[test]
1893    fn generated_request_builder_preserves_both_client_auth_options() {
1894        let source = include_str!("client.rs");
1895        let request_start = source
1896            .find("pub fn request(&self) -> hyprstream_rpc::RequestBuilder")
1897            .expect("generated client template must define request()");
1898        let request_end = source[request_start..]
1899            .find("/// Send a raw request")
1900            .expect("request() must end before raw call generation");
1901        let generated = &source[request_start..request_start + request_end];
1902        assert!(
1903            generated.contains("match &self.call_options.jwt"),
1904            "a generated client with_bearer token must reach request()"
1905        );
1906        assert!(
1907            generated.contains("builder.jwt(token.clone())"),
1908            "request() must carry the direct bearer into its per-call builder"
1909        );
1910        assert!(
1911            generated.contains("match &self.call_options.delegated_bearer"),
1912            "request() must retain delegated-bearer propagation"
1913        );
1914    }
1915
1916    #[test]
1917    fn application_call_graph_limits_local_bootstrap_to_explicit_bootstrap_paths() {
1918        let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
1919            .parent()
1920            .and_then(std::path::Path::parent)
1921            .expect("workspace root");
1922        let source_root = root.join("crates/hyprstream/src");
1923        let mut explicit = 0usize;
1924        let mut stack = vec![source_root];
1925        while let Some(path) = stack.pop() {
1926            for entry in std::fs::read_dir(path).expect("read application source") {
1927                let entry = entry.expect("source entry");
1928                let path = entry.path();
1929                if path.is_dir() {
1930                    stack.push(path);
1931                } else if path.extension().and_then(|v| v.to_str()) == Some("rs") {
1932                    let source = std::fs::read_to_string(&path).expect("read Rust source");
1933                    explicit += source.matches("::from_provider(").count();
1934                    assert!(
1935                        !source.contains("::from_resolver("),
1936                        "compatibility resolver constructor remains in {}",
1937                        path.display(),
1938                    );
1939                    if !path.ends_with("services/policy.rs") {
1940                        assert!(
1941                            !source.contains(".resolve_service_key("),
1942                            "ordinary consumer performs an independent response-key lookup in {}",
1943                            path.display(),
1944                        );
1945                    }
1946                    let registry_cli_bootstrap = path.ends_with("bin/main.rs")
1947                        && source.contains("Pre-Discovery CLI bootstrap")
1948                        && source
1949                            .matches("RegistryClient::for_local_bootstrap(")
1950                            .count()
1951                            == 1;
1952                    for line in source
1953                        .lines()
1954                        .filter(|line| line.contains("::for_local_bootstrap("))
1955                    {
1956                        let command_local_worker = path.ends_with("bin/main.rs")
1957                            && line.contains("WorkerClient::for_local_bootstrap");
1958                        let command_local_inference = path.ends_with("cli/training_handlers.rs")
1959                            && line.contains("InferenceClient::for_local_bootstrap");
1960                        assert!(
1961                            line.contains("PolicyClient")
1962                                || line.contains("DiscoveryClient")
1963                                || (registry_cli_bootstrap && line.contains("RegistryClient"))
1964                                || command_local_worker
1965                                || command_local_inference,
1966                            "non-bootstrap application client bypasses installed resolver in {}: {line}",
1967                            path.display(),
1968                        );
1969                    }
1970                }
1971            }
1972        }
1973        assert!(explicit >= 50, "explicit provider migration regressed");
1974    }
1975}