Skip to main content

hyprstream_rpc_derive/codegen/
metadata.rs

1//! Schema metadata and JSON dispatcher 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/// Generate schema metadata + render_doc only for a server-side projection.
11/// Used by `generate_rpc_server!` (the contract crate owns the client).
12pub fn generate_metadata_client_only(
13    service_name: &str,
14    resolved: &ResolvedSchema,
15    types_crate: Option<&syn::Path>,
16) -> TokenStream {
17    generate_metadata_client_projection(service_name, resolved, types_crate, false)
18}
19
20/// Generate the public client metadata, including the transport-agnostic JSON
21/// dispatcher used by schema-driven SDK tooling.
22pub fn generate_metadata_client_with_dispatch(
23    service_name: &str,
24    resolved: &ResolvedSchema,
25    types_crate: Option<&syn::Path>,
26) -> TokenStream {
27    generate_metadata_client_projection(service_name, resolved, types_crate, true)
28}
29
30fn generate_metadata_client_projection(
31    service_name: &str,
32    resolved: &ResolvedSchema,
33    types_crate: Option<&syn::Path>,
34    include_json_dispatcher: bool,
35) -> TokenStream {
36    let metadata_structs = generate_metadata_structs();
37    let pascal = to_pascal_case(service_name);
38    let schema_metadata = generate_schema_metadata_fn(
39        service_name,
40        &pascal,
41        &resolved.raw.request_variants,
42        &resolved.raw.response_variants,
43        resolved,
44        &resolved.raw.scoped_clients,
45    );
46    // This dispatcher only invokes methods on the generated transport-agnostic
47    // client. Keeping it here makes schema-driven tooling available from the
48    // Apache SDK without pulling in an implementation/service crate.
49    let json_dispatcher = if include_json_dispatcher {
50        generate_json_dispatcher(
51            &pascal,
52            &resolved.raw.request_variants,
53            &resolved.raw.response_variants,
54            resolved,
55            &resolved.raw.scoped_clients,
56        )
57    } else {
58        TokenStream::new()
59    };
60    let scoped_client_tree = generate_scoped_client_tree(&resolved.raw.scoped_clients, types_crate);
61    let render_doc = generate_render_doc(
62        service_name,
63        &resolved.raw.request_variants,
64        &resolved.raw.response_variants,
65        resolved,
66        &resolved.raw.scoped_clients,
67    );
68    quote! {
69        #metadata_structs
70        #schema_metadata
71        #json_dispatcher
72        #scoped_client_tree
73        #render_doc
74    }
75}
76
77/// Generate schema metadata functions + JSON dispatchers.
78pub fn generate_metadata(
79    service_name: &str,
80    resolved: &ResolvedSchema,
81    types_crate: Option<&syn::Path>,
82) -> TokenStream {
83    let pascal = to_pascal_case(service_name);
84
85    let metadata_structs = generate_metadata_structs();
86    let schema_metadata = generate_schema_metadata_fn(
87        service_name,
88        &pascal,
89        &resolved.raw.request_variants,
90        &resolved.raw.response_variants,
91        resolved,
92        &resolved.raw.scoped_clients,
93    );
94    let json_dispatcher = generate_json_dispatcher(
95        &pascal,
96        &resolved.raw.request_variants,
97        &resolved.raw.response_variants,
98        resolved,
99        &resolved.raw.scoped_clients,
100    );
101    let scoped_client_tree = generate_scoped_client_tree(&resolved.raw.scoped_clients, types_crate);
102    let render_doc = generate_render_doc(
103        service_name,
104        &resolved.raw.request_variants,
105        &resolved.raw.response_variants,
106        resolved,
107        &resolved.raw.scoped_clients,
108    );
109
110    quote! {
111        #metadata_structs
112        #schema_metadata
113        #json_dispatcher
114        #scoped_client_tree
115        #render_doc
116    }
117}
118
119fn generate_metadata_structs() -> TokenStream {
120    quote! {
121        pub use hyprstream_rpc::metadata::{ParamMeta as ParamSchema, MethodMeta as MethodSchema};
122    }
123}
124
125fn generate_schema_metadata_fn(
126    service_name: &str,
127    pascal: &str,
128    request_variants: &[UnionVariant],
129    response_variants: &[UnionVariant],
130    resolved: &ResolvedSchema,
131    scoped_clients: &[ScopedClient],
132) -> TokenStream {
133    let scoped_names: Vec<&str> = scoped_clients
134        .iter()
135        .map(|sc| sc.factory_name.as_str())
136        .collect();
137    let doc = format!("Schema metadata for the {pascal} service.");
138
139    let method_entries: Vec<TokenStream> = request_variants
140        .iter()
141        .filter(|v| !scoped_names.contains(&v.name.as_str()))
142        .map(|v| generate_method_schema_entry(v, resolved, false, "", response_variants, false))
143        .collect();
144
145    let mut scoped_fns = Vec::new();
146    collect_scoped_metadata_recursive(service_name, scoped_clients, resolved, &mut scoped_fns);
147
148    quote! {
149        #[doc = #doc]
150        pub fn schema_metadata() -> (&'static str, &'static [MethodSchema]) {
151            static METHODS: &[MethodSchema] = &[
152                #(#method_entries,)*
153            ];
154            (#service_name, METHODS)
155        }
156
157        #(#scoped_fns)*
158    }
159}
160
161fn generate_method_schema_entry(
162    v: &UnionVariant,
163    resolved: &ResolvedSchema,
164    is_scoped: bool,
165    scope_field: &str,
166    response_variants: &[UnionVariant],
167    is_scoped_streaming_check: bool,
168) -> TokenStream {
169    let method_name = to_snake_case(&v.name);
170    let method_desc = &v.description;
171    let scope_str = v.scope.as_str();
172    let doc_example = &v.doc_example;
173    let is_streaming = is_streaming_variant(&v.name, response_variants, is_scoped_streaming_check);
174    let cli_hidden = v.cli_hidden;
175    let ct = CapnpType::classify_primitive(&v.type_name);
176
177    let params = match ct {
178        CapnpType::Void => vec![],
179        CapnpType::Struct(_) | CapnpType::Unknown(_) => {
180            if let Some(sdef) = resolved.find_struct(&v.type_name) {
181                sdef.non_union_fields()
182                    .map(|f| {
183                        let fname = to_snake_case(&f.name);
184                        let ftype = &f.type_name;
185                        let fdesc = &f.description;
186                        let is_optional = f.optional || ftype == "Bool";
187                        let required = !is_optional;
188                        let default_val = if ftype == "Bool" { "false" } else { "" };
189                        quote! {
190                            ParamSchema { name: #fname, type_name: #ftype, required: #required, description: #fdesc, default_value: #default_val }
191                        }
192                    })
193                    .collect()
194            } else {
195                vec![]
196            }
197        }
198        _ => {
199            let type_str = &v.type_name;
200            vec![quote! {
201                ParamSchema { name: "value", type_name: #type_str, required: true, description: "", default_value: "" }
202            }]
203        }
204    };
205
206    quote! {
207        MethodSchema {
208            name: #method_name,
209            params: &[#(#params),*],
210            is_scoped: #is_scoped,
211            scope_field: #scope_field,
212            description: #method_desc,
213            scope: #scope_str,
214            is_streaming: #is_streaming,
215            hidden: #cli_hidden,
216            doc_example: #doc_example,
217        }
218    }
219}
220
221fn generate_scoped_schema_metadata_fn(
222    service_name: &str,
223    sc: &ScopedClient,
224    resolved: &ResolvedSchema,
225) -> TokenStream {
226    let scope_snake = to_snake_case(&sc.factory_name);
227    let fn_name = format_ident!("{}_schema_metadata", scope_snake);
228    let scope_pascal = to_pascal_case(&sc.factory_name);
229    let doc = format!("Schema metadata for scoped {scope_pascal} methods.");
230    let scope_field_name = sc
231        .scope_fields
232        .first()
233        .map(|f| to_snake_case(&f.name))
234        .unwrap_or_default();
235
236    let method_entries: Vec<TokenStream> = sc
237        .inner_request_variants
238        .iter()
239        .map(|v| {
240            generate_method_schema_entry(
241                v,
242                resolved,
243                true,
244                &scope_field_name,
245                &sc.inner_response_variants,
246                true,
247            )
248        })
249        .collect();
250
251    quote! {
252        #[doc = #doc]
253        pub fn #fn_name() -> (&'static str, &'static str, &'static [MethodSchema]) {
254            static METHODS: &[MethodSchema] = &[
255                #(#method_entries,)*
256            ];
257            (#service_name, #scope_snake, METHODS)
258        }
259    }
260}
261
262// ─────────────────────────────────────────────────────────────────────────────
263// JSON Dispatcher
264// ─────────────────────────────────────────────────────────────────────────────
265
266/// Check if a request variant's corresponding response is StreamInfo.
267fn is_streaming_variant(
268    variant_name: &str,
269    response_variants: &[UnionVariant],
270    is_scoped: bool,
271) -> bool {
272    let expected_name = if is_scoped {
273        variant_name.to_owned()
274    } else {
275        format!("{}Result", variant_name)
276    };
277    response_variants
278        .iter()
279        .find(|v| v.name == expected_name)
280        .map(|v| v.type_name == "StreamInfo")
281        .unwrap_or(false)
282}
283
284fn generate_json_dispatcher(
285    pascal: &str,
286    request_variants: &[UnionVariant],
287    response_variants: &[UnionVariant],
288    resolved: &ResolvedSchema,
289    scoped_clients: &[ScopedClient],
290) -> TokenStream {
291    let client_name = format_ident!("{}Client", pascal);
292    let scoped_names: Vec<&str> = scoped_clients
293        .iter()
294        .map(|sc| sc.factory_name.as_str())
295        .collect();
296
297    // Non-streaming dispatch arms for call_method
298    let main_match_arms: Vec<TokenStream> = request_variants
299        .iter()
300        .filter(|v| !scoped_names.contains(&v.name.as_str()))
301        .filter(|v| !is_streaming_variant(&v.name, response_variants, false))
302        .map(|v| generate_json_method_dispatch_arm(v, response_variants, false, resolved))
303        .collect();
304
305    // Streaming dispatch arms for call_streaming_method
306    let main_streaming_arms: Vec<TokenStream> = request_variants
307        .iter()
308        .filter(|v| !scoped_names.contains(&v.name.as_str()))
309        .filter(|v| is_streaming_variant(&v.name, response_variants, false))
310        .map(|v| generate_json_streaming_dispatch_arm(v, resolved))
311        .collect();
312
313    let streaming_method = quote! {
314        /// Dispatch a streaming method call by name with JSON arguments and an ephemeral public key.
315        /// Returns the verified-capnp `StreamInfo` library type (decoded + COSE-verified
316        /// inside `call_streaming`) — NOT a re-serialized `serde_json::Value` (#468).
317        #[allow(unused_variables)]
318        pub async fn call_streaming_method(
319            &self,
320            method: &str,
321            args: &serde_json::Value,
322            ephemeral_pubkey: [u8; 32],
323        ) -> anyhow::Result<hyprstream_rpc::stream_info::StreamInfo> {
324            match method {
325                #(#main_streaming_arms)*
326                _ => anyhow::bail!("Unknown streaming method: {}", method),
327            }
328        }
329    };
330
331    let mut scoped_dispatchers = Vec::new();
332    collect_scoped_dispatchers_recursive(scoped_clients, resolved, &mut scoped_dispatchers);
333
334    // Generate call_scoped_method on the top-level client
335    let top_scoped_dispatch = generate_call_scoped_method_for_client(scoped_clients);
336
337    // Generate call_scoped_method on scoped clients that have children
338    let mut nested_scoped_dispatch = Vec::new();
339    collect_call_scoped_method_recursive(scoped_clients, &mut nested_scoped_dispatch);
340
341    // Generate call_scoped_streaming_method on the top-level client
342    let top_scoped_streaming = generate_call_scoped_streaming_method_for_client(scoped_clients);
343
344    // Generate call_scoped_streaming_method on scoped clients that have children
345    let mut nested_scoped_streaming = Vec::new();
346    collect_call_scoped_streaming_method_recursive(scoped_clients, &mut nested_scoped_streaming);
347
348    quote! {
349        impl #client_name {
350            /// Dispatch a method call by name with JSON arguments.
351            /// Returns the response as a proper JSON value.
352            pub async fn call_method(&self, method: &str, args: &serde_json::Value) -> anyhow::Result<serde_json::Value> {
353                match method {
354                    #(#main_match_arms)*
355                    _ => anyhow::bail!("Unknown method: {}", method),
356                }
357            }
358
359            #streaming_method
360
361            #top_scoped_dispatch
362
363            #top_scoped_streaming
364        }
365
366        #(#scoped_dispatchers)*
367
368        #(#nested_scoped_dispatch)*
369
370        #(#nested_scoped_streaming)*
371    }
372}
373
374fn generate_json_method_dispatch_arm(
375    v: &UnionVariant,
376    response_variants: &[UnionVariant],
377    is_scoped: bool,
378    resolved: &ResolvedSchema,
379) -> TokenStream {
380    let method_name_str = to_snake_case(&v.name);
381    let method_name = format_ident!("{}", method_name_str);
382    let ct = resolved.resolve_type(&v.type_name).capnp_type.clone();
383
384    match ct {
385        CapnpType::Void => {
386            let result_name = if is_scoped {
387                v.name.clone()
388            } else {
389                format!("{}Result", v.name)
390            };
391            let resp = response_variants.iter().find(|r| r.name == result_name);
392            let resp_is_void = resp.is_none_or(|r| r.type_name == "Void");
393
394            if resp_is_void {
395                quote! {
396                    #method_name_str => {
397                        self.#method_name().await?;
398                        Ok(serde_json::Value::Null)
399                    }
400                }
401            } else {
402                quote! {
403                    #method_name_str => {
404                        let result = self.#method_name().await?;
405                        Ok(serde_json::to_value(&result)?)
406                    }
407                }
408            }
409        }
410        CapnpType::Text => quote! {
411            #method_name_str => {
412                let value = args[#method_name_str].as_str().or_else(|| args["value"].as_str()).unwrap_or_default();
413                let result = self.#method_name(value).await?;
414                Ok(serde_json::to_value(&result)?)
415            }
416        },
417        _ if ct == CapnpType::Bool || ct.is_numeric() => {
418            let rust_ty = rust_type_tokens(&ct.rust_owned_type());
419            quote! {
420                #method_name_str => {
421                    let __value = args
422                        .get(#method_name_str)
423                        .or_else(|| args.get("value"))
424                        .cloned()
425                        .ok_or_else(|| anyhow::anyhow!("missing argument for {}", #method_name_str))?;
426                    let value: #rust_ty = serde_json::from_value(__value)?;
427                    let result = self.#method_name(value).await?;
428                    Ok(serde_json::to_value(&result)?)
429                }
430            }
431        }
432        _ => {
433            if let Some(sdef) = resolved.find_struct(&v.type_name) {
434                let nuf: Vec<_> = sdef.non_union_fields().collect();
435                let is_void_wrapper =
436                    nuf.is_empty() || (nuf.len() == 1 && nuf[0].type_name == "Void");
437
438                if is_void_wrapper {
439                    // Void wrapper struct: call with no args
440                    quote! {
441                        #method_name_str => {
442                            let result = self.#method_name().await?;
443                            Ok(serde_json::to_value(&result)?)
444                        }
445                    }
446                } else {
447                    let data_name = format_ident!("{}", v.type_name);
448
449                    quote! {
450                        #method_name_str => {
451                            let __req: #data_name = serde_json::from_value(args.clone())?;
452                            let result = self.#method_name(&__req).await?;
453                            Ok(serde_json::to_value(&result)?)
454                        }
455                    }
456                }
457            } else {
458                let err_msg = format!("Method {}: struct type not found", method_name_str);
459                quote! {
460                    #method_name_str => anyhow::bail!(#err_msg),
461                }
462            }
463        }
464    }
465}
466
467/// Generate a streaming dispatch arm for call_streaming_method.
468fn generate_json_streaming_dispatch_arm(
469    v: &UnionVariant,
470    resolved: &ResolvedSchema,
471) -> TokenStream {
472    let method_name_str = to_snake_case(&v.name);
473    let method_name = format_ident!("{}", method_name_str);
474    let ct = resolved.resolve_type(&v.type_name).capnp_type.clone();
475
476    // #468: streaming methods ALWAYS resolve to the verified-capnp `StreamInfo`
477    // library type (decoded + COSE-verified inside `call_streaming`). The JSON
478    // dispatch wrappers return that native type directly — NO `serde_json::to_value`
479    // round-trip — so the signed artifact flows through typed to MCP/VFS consumers.
480    match ct {
481        CapnpType::Void => quote! {
482            #method_name_str => {
483                let result = self.#method_name(ephemeral_pubkey).await?;
484                Ok(result)
485            }
486        },
487        CapnpType::Text => quote! {
488            #method_name_str => {
489                let value = args[#method_name_str].as_str().or_else(|| args["value"].as_str()).unwrap_or_default();
490                let result = self.#method_name(value, ephemeral_pubkey).await?;
491                Ok(result)
492            }
493        },
494        _ => {
495            if let Some(sdef) = resolved.find_struct(&v.type_name) {
496                let nuf: Vec<_> = sdef.non_union_fields().collect();
497                let is_void_wrapper =
498                    nuf.is_empty() || (nuf.len() == 1 && nuf[0].type_name == "Void");
499
500                if is_void_wrapper {
501                    quote! {
502                        #method_name_str => {
503                            let result = self.#method_name(ephemeral_pubkey).await?;
504                            Ok(result)
505                        }
506                    }
507                } else {
508                    let data_name = format_ident!("{}", v.type_name);
509
510                    quote! {
511                        #method_name_str => {
512                            let __req: #data_name = serde_json::from_value(args.clone())?;
513                            let result = self.#method_name(&__req, ephemeral_pubkey).await?;
514                            Ok(result)
515                        }
516                    }
517                }
518            } else {
519                let err_msg = format!(
520                    "Streaming method {}: struct type not found",
521                    method_name_str
522                );
523                quote! {
524                    #method_name_str => anyhow::bail!(#err_msg),
525                }
526            }
527        }
528    }
529}
530
531// ─────────────────────────────────────────────────────────────────────────────
532// Recursive helpers for scoped metadata and dispatch
533// ─────────────────────────────────────────────────────────────────────────────
534
535fn collect_scoped_metadata_recursive(
536    service_name: &str,
537    clients: &[ScopedClient],
538    resolved: &ResolvedSchema,
539    out: &mut Vec<TokenStream>,
540) {
541    for sc in clients {
542        out.push(generate_scoped_schema_metadata_fn(
543            service_name,
544            sc,
545            resolved,
546        ));
547        collect_scoped_metadata_recursive(service_name, &sc.nested_clients, resolved, out);
548    }
549}
550
551fn collect_scoped_dispatchers_recursive(
552    clients: &[ScopedClient],
553    resolved: &ResolvedSchema,
554    out: &mut Vec<TokenStream>,
555) {
556    for sc in clients {
557        out.push(generate_scoped_dispatcher_block(sc, resolved));
558        collect_scoped_dispatchers_recursive(&sc.nested_clients, resolved, out);
559    }
560}
561
562fn generate_scoped_dispatcher_block(sc: &ScopedClient, resolved: &ResolvedSchema) -> TokenStream {
563    let scoped_client_name = format_ident!("{}", sc.client_name);
564    let scoped_match_arms: Vec<TokenStream> = sc
565        .inner_request_variants
566        .iter()
567        .filter(|v| !is_streaming_variant(&v.name, &sc.inner_response_variants, true))
568        .map(|v| generate_json_method_dispatch_arm(v, &sc.inner_response_variants, true, resolved))
569        .collect();
570
571    // Streaming dispatch arms
572    let scoped_streaming_arms: Vec<TokenStream> = sc
573        .inner_request_variants
574        .iter()
575        .filter(|v| is_streaming_variant(&v.name, &sc.inner_response_variants, true))
576        .map(|v| generate_json_streaming_dispatch_arm(v, resolved))
577        .collect();
578
579    let scoped_streaming_method = quote! {
580        /// Dispatch a scoped streaming method call by name with JSON arguments and an ephemeral public key.
581        /// Returns the verified-capnp `StreamInfo` library type (#468).
582        #[allow(unused_variables)]
583        pub async fn call_streaming_method(
584            &self,
585            method: &str,
586            args: &serde_json::Value,
587            ephemeral_pubkey: [u8; 32],
588        ) -> anyhow::Result<hyprstream_rpc::stream_info::StreamInfo> {
589            match method {
590                #(#scoped_streaming_arms)*
591                _ => anyhow::bail!("Unknown scoped streaming method: {}", method),
592            }
593        }
594    };
595
596    quote! {
597        impl #scoped_client_name {
598            /// Dispatch a scoped method call by name with JSON arguments.
599            pub async fn call_method(&self, method: &str, args: &serde_json::Value) -> anyhow::Result<serde_json::Value> {
600                match method {
601                    #(#scoped_match_arms)*
602                    _ => anyhow::bail!("Unknown scoped method: {}", method),
603                }
604            }
605
606            #scoped_streaming_method
607        }
608    }
609}
610
611/// Generate a factory call expression for a scoped client.
612/// Handles type conversion for non-string scope fields (e.g., UInt32 → parse from &str).
613fn generate_scoped_factory_call(sc: &ScopedClient) -> TokenStream {
614    let factory_snake = format_ident!("{}", to_snake_case(&sc.factory_name));
615    if sc.scope_fields.is_empty() {
616        quote! { self.#factory_snake() }
617    } else if sc.scope_fields.len() == 1 {
618        // Check if scope field needs parsing from string
619        let field = &sc.scope_fields[0];
620        match field.type_name.as_str() {
621            "UInt8" | "UInt16" | "UInt32" | "UInt64" | "Int8" | "Int16" | "Int32" | "Int64"
622            | "Float32" | "Float64" => {
623                quote! { self.#factory_snake(scope_id.parse()?) }
624            }
625            _ => {
626                quote! { self.#factory_snake(scope_id) }
627            }
628        }
629    } else {
630        // Multiple scope fields — not supported in call_scoped_method yet
631        quote! { self.#factory_snake(scope_id) }
632    }
633}
634
635/// Generate `call_scoped_method` on the top-level client.
636fn generate_call_scoped_method_for_client(scoped_clients: &[ScopedClient]) -> TokenStream {
637    if scoped_clients.is_empty() {
638        return TokenStream::new();
639    }
640
641    let match_arms: Vec<TokenStream> = scoped_clients
642        .iter()
643        .map(|sc| {
644            let scope_name_str = to_snake_case(&sc.factory_name);
645            let factory_call = generate_scoped_factory_call(sc);
646
647            quote! {
648                #scope_name_str => #factory_call.call_scoped_method(remaining, method, args).await,
649            }
650        })
651        .collect();
652
653    quote! {
654        /// Dispatch a scoped method call through nested scope chain.
655        #[allow(unused_variables)]
656        pub async fn call_scoped_method(
657            &self,
658            scopes: &[(&str, &str)],
659            method: &str,
660            args: &serde_json::Value,
661        ) -> anyhow::Result<serde_json::Value> {
662            if scopes.is_empty() {
663                return self.call_method(method, args).await;
664            }
665            let (scope_name, scope_id) = scopes[0];
666            let remaining = &scopes[1..];
667            match scope_name {
668                #(#match_arms)*
669                _ => anyhow::bail!("Unknown scope: {}", scope_name),
670            }
671        }
672    }
673}
674
675/// Recursively generate `call_scoped_method` on all scoped clients.
676fn collect_call_scoped_method_recursive(clients: &[ScopedClient], out: &mut Vec<TokenStream>) {
677    for sc in clients {
678        let client_name = format_ident!("{}", sc.client_name);
679
680        if sc.nested_clients.is_empty() {
681            out.push(quote! {
682                impl #client_name {
683                    /// Dispatch a scoped method call through nested scope chain.
684                    pub async fn call_scoped_method(
685                        &self,
686                        scopes: &[(&str, &str)],
687                        method: &str,
688                        args: &serde_json::Value,
689                    ) -> anyhow::Result<serde_json::Value> {
690                        if scopes.is_empty() {
691                            return self.call_method(method, args).await;
692                        }
693                        anyhow::bail!("No nested scopes available for '{}'", scopes[0].0)
694                    }
695                }
696            });
697        } else {
698            let match_arms: Vec<TokenStream> = sc.nested_clients.iter().map(|nested| {
699                let scope_name_str = to_snake_case(&nested.factory_name);
700                let factory_call = generate_scoped_factory_call(nested);
701
702                quote! {
703                    #scope_name_str => #factory_call.call_scoped_method(remaining, method, args).await,
704                }
705            }).collect();
706
707            out.push(quote! {
708                impl #client_name {
709                    /// Dispatch a scoped method call through nested scope chain.
710                    #[allow(unused_variables)]
711                    pub async fn call_scoped_method(
712                        &self,
713                        scopes: &[(&str, &str)],
714                        method: &str,
715                        args: &serde_json::Value,
716                    ) -> anyhow::Result<serde_json::Value> {
717                        if scopes.is_empty() {
718                            return self.call_method(method, args).await;
719                        }
720                        let (scope_name, scope_id) = scopes[0];
721                        let remaining = &scopes[1..];
722                        match scope_name {
723                            #(#match_arms)*
724                            _ => anyhow::bail!("Unknown scope: {}", scope_name),
725                        }
726                    }
727                }
728            });
729        }
730        collect_call_scoped_method_recursive(&sc.nested_clients, out);
731    }
732}
733
734/// Generate `call_scoped_streaming_method` on the top-level client.
735fn generate_call_scoped_streaming_method_for_client(
736    scoped_clients: &[ScopedClient],
737) -> TokenStream {
738    if scoped_clients.is_empty() {
739        return TokenStream::new();
740    }
741
742    let match_arms: Vec<TokenStream> = scoped_clients.iter().map(|sc| {
743        let scope_name_str = to_snake_case(&sc.factory_name);
744        let factory_call = generate_scoped_factory_call(sc);
745
746        quote! {
747            #scope_name_str => #factory_call.call_scoped_streaming_method(remaining, method, args, ephemeral_pubkey).await,
748        }
749    }).collect();
750
751    quote! {
752        /// Dispatch a scoped streaming method call through nested scope chain.
753        #[allow(unused_variables)]
754        pub async fn call_scoped_streaming_method(
755            &self,
756            scopes: &[(&str, &str)],
757            method: &str,
758            args: &serde_json::Value,
759            ephemeral_pubkey: [u8; 32],
760        ) -> anyhow::Result<hyprstream_rpc::stream_info::StreamInfo> {
761            if scopes.is_empty() {
762                return self.call_streaming_method(method, args, ephemeral_pubkey).await;
763            }
764            let (scope_name, scope_id) = scopes[0];
765            let remaining = &scopes[1..];
766            match scope_name {
767                #(#match_arms)*
768                _ => anyhow::bail!("Unknown scope: {}", scope_name),
769            }
770        }
771    }
772}
773
774/// Recursively generate `call_scoped_streaming_method` on all scoped clients.
775fn collect_call_scoped_streaming_method_recursive(
776    clients: &[ScopedClient],
777    out: &mut Vec<TokenStream>,
778) {
779    for sc in clients {
780        let client_name = format_ident!("{}", sc.client_name);
781
782        if sc.nested_clients.is_empty() {
783            out.push(quote! {
784                impl #client_name {
785                    /// Dispatch a scoped streaming method call through nested scope chain.
786                    pub async fn call_scoped_streaming_method(
787                        &self,
788                        scopes: &[(&str, &str)],
789                        method: &str,
790                        args: &serde_json::Value,
791                        ephemeral_pubkey: [u8; 32],
792                    ) -> anyhow::Result<hyprstream_rpc::stream_info::StreamInfo> {
793                        if scopes.is_empty() {
794                            return self.call_streaming_method(method, args, ephemeral_pubkey).await;
795                        }
796                        anyhow::bail!("No nested scopes available for '{}'", scopes[0].0)
797                    }
798                }
799            });
800        } else {
801            let match_arms: Vec<TokenStream> = sc.nested_clients.iter().map(|nested| {
802                let scope_name_str = to_snake_case(&nested.factory_name);
803                let factory_call = generate_scoped_factory_call(nested);
804
805                quote! {
806                    #scope_name_str => #factory_call.call_scoped_streaming_method(remaining, method, args, ephemeral_pubkey).await,
807                }
808            }).collect();
809
810            out.push(quote! {
811                impl #client_name {
812                    /// Dispatch a scoped streaming method call through nested scope chain.
813                    #[allow(unused_variables)]
814                    pub async fn call_scoped_streaming_method(
815                        &self,
816                        scopes: &[(&str, &str)],
817                        method: &str,
818                        args: &serde_json::Value,
819                        ephemeral_pubkey: [u8; 32],
820                    ) -> anyhow::Result<hyprstream_rpc::stream_info::StreamInfo> {
821                        if scopes.is_empty() {
822                            return self.call_streaming_method(method, args, ephemeral_pubkey).await;
823                        }
824                        let (scope_name, scope_id) = scopes[0];
825                        let remaining = &scopes[1..];
826                        match scope_name {
827                            #(#match_arms)*
828                            _ => anyhow::bail!("Unknown scope: {}", scope_name),
829                        }
830                    }
831                }
832            });
833        }
834        collect_call_scoped_streaming_method_recursive(&sc.nested_clients, out);
835    }
836}
837
838/// Generate `scoped_client_tree()` metadata function.
839fn generate_scoped_client_tree(
840    scoped_clients: &[ScopedClient],
841    types_crate: Option<&syn::Path>,
842) -> TokenStream {
843    let mut consts = Vec::new();
844    let mut top_level_names = Vec::new();
845
846    for sc in scoped_clients {
847        generate_tree_consts(sc, &mut consts, &mut top_level_names, types_crate);
848    }
849
850    let top_refs: Vec<syn::Ident> = top_level_names;
851
852    quote! {
853        /// Returns the scoped client tree metadata for dynamic CLI/MCP dispatch.
854        pub fn scoped_client_tree() -> &'static [hyprstream_rpc::metadata::ScopedClientTreeNode] {
855            use hyprstream_rpc::metadata::ScopedClientTreeNode;
856            #(#consts)*
857            static TREE: &[ScopedClientTreeNode] = &[#(#top_refs),*];
858            TREE
859        }
860    }
861}
862
863/// Recursively generate const nodes for the scoped client tree (bottom-up).
864fn generate_tree_consts(
865    sc: &ScopedClient,
866    consts: &mut Vec<TokenStream>,
867    names_out: &mut Vec<syn::Ident>,
868    types_crate: Option<&syn::Path>,
869) {
870    let mut child_names = Vec::new();
871    for nested in &sc.nested_clients {
872        generate_tree_consts(nested, consts, &mut child_names, types_crate);
873    }
874
875    let scope_snake = to_snake_case(&sc.factory_name);
876    let const_name = format_ident!("__SCOPE_{}", scope_snake.to_uppercase());
877    let scope_field_name = sc
878        .scope_fields
879        .first()
880        .map(|f| to_snake_case(&f.name))
881        .unwrap_or_default();
882    let fn_name = format_ident!("{}_schema_metadata", scope_snake);
883
884    let metadata_fn_path = match types_crate {
885        Some(tc) => quote! { #tc::#fn_name },
886        None => quote! { #fn_name },
887    };
888
889    let nested_refs: Vec<&syn::Ident> = child_names.iter().collect();
890    let nested_array = if nested_refs.is_empty() {
891        quote! { &[] }
892    } else {
893        quote! { &[#(#nested_refs),*] }
894    };
895
896    consts.push(quote! {
897        const #const_name: ScopedClientTreeNode = ScopedClientTreeNode {
898            scope_name: #scope_snake,
899            scope_field: #scope_field_name,
900            metadata_fn: #metadata_fn_path,
901            nested: #nested_array,
902        };
903    });
904
905    names_out.push(const_name);
906}
907
908// ---------------------------------------------------------------------------
909// render_doc() generation — man page rendering from schema metadata
910// ---------------------------------------------------------------------------
911
912/// Generate `render_doc(path: &[&str]) -> Option<String>` for service documentation.
913fn generate_render_doc(
914    service_name: &str,
915    request_variants: &[UnionVariant],
916    _response_variants: &[UnionVariant],
917    resolved: &ResolvedSchema,
918    scoped_clients: &[ScopedClient],
919) -> TokenStream {
920    let scoped_names: Vec<&str> = scoped_clients
921        .iter()
922        .map(|sc| sc.factory_name.as_str())
923        .collect();
924
925    let overview = format_service_overview(
926        service_name,
927        request_variants,
928        &scoped_names,
929        scoped_clients,
930    );
931
932    let method_arms: Vec<TokenStream> = request_variants
933        .iter()
934        .filter(|v| !scoped_names.contains(&v.name.as_str()) && !v.cli_hidden)
935        .map(|v| {
936            let method_snake = to_snake_case(&v.name);
937            let page = format_man_page(
938                service_name,
939                &method_snake,
940                v,
941                resolved,
942                request_variants,
943                &scoped_names,
944            );
945            quote! { #method_snake => ::core::option::Option::Some(#page.to_owned()), }
946        })
947        .collect();
948
949    let mut scope_single_arms = Vec::new();
950    let mut scope_multi_arms = Vec::new();
951
952    for sc in scoped_clients {
953        let scope_snake = to_snake_case(&sc.factory_name);
954        let scope_overview = format_scope_overview(service_name, &scope_snake, sc);
955
956        let scope_method_arms: Vec<TokenStream> = sc
957            .inner_request_variants
958            .iter()
959            .filter(|v| !v.cli_hidden)
960            .map(|v| {
961                let m_name = to_snake_case(&v.name);
962                let page = format_scoped_man_page(
963                    service_name,
964                    &scope_snake,
965                    &m_name,
966                    v,
967                    resolved,
968                    &sc.inner_request_variants,
969                );
970                quote! { #m_name => ::core::option::Option::Some(#page.to_owned()), }
971            })
972            .collect();
973
974        let nested_single_arms: Vec<TokenStream> = sc
975            .nested_clients
976            .iter()
977            .map(|nsc| {
978                let nscope_snake = to_snake_case(&nsc.factory_name);
979                let nested_overview = format_scope_overview(service_name, &format!("{} {}", scope_snake, nscope_snake), nsc);
980                quote! { [#nscope_snake] => ::core::option::Option::Some(#nested_overview.to_owned()), }
981            })
982            .collect();
983
984        let nested_multi_arms: Vec<TokenStream> = sc
985            .nested_clients
986            .iter()
987            .map(|nsc| {
988                let nscope_snake = to_snake_case(&nsc.factory_name);
989                let nested_method_arms: Vec<TokenStream> = nsc
990                    .inner_request_variants
991                    .iter()
992                    .filter(|v| !v.cli_hidden)
993                    .map(|v| {
994                        let m_name = to_snake_case(&v.name);
995                        let page = format_scoped_man_page(
996                            service_name,
997                            &format!("{} {}", scope_snake, nscope_snake),
998                            &m_name, v, resolved, &nsc.inner_request_variants,
999                        );
1000                        quote! { [#nscope_snake, #m_name] => ::core::option::Option::Some(#page.to_owned()), }
1001                    })
1002                    .collect();
1003                quote! { #(#nested_method_arms)* }
1004            })
1005            .collect();
1006
1007        scope_single_arms.push(quote! {
1008            #scope_snake => ::core::option::Option::Some(#scope_overview.to_owned()),
1009        });
1010
1011        scope_multi_arms.push(quote! {
1012            [#scope_snake, method] => match *method {
1013                #(#scope_method_arms)*
1014                _ => ::core::option::Option::None,
1015            },
1016            [#scope_snake, rest @ ..] => match rest {
1017                #(#nested_single_arms)*
1018                #(#nested_multi_arms)*
1019                _ => ::core::option::Option::None,
1020            },
1021        });
1022    }
1023
1024    quote! {
1025        /// Render documentation for this service.
1026        pub fn render_doc(path: &[&str]) -> ::core::option::Option<String> {
1027            match path {
1028                [] | [""] => ::core::option::Option::Some(#overview.to_owned()),
1029                [single] => match *single {
1030                    #(#method_arms)*
1031                    #(#scope_single_arms)*
1032                    _ => ::core::option::Option::None,
1033                },
1034                multi => match multi {
1035                    #(#scope_multi_arms)*
1036                    _ => ::core::option::Option::None,
1037                },
1038            }
1039        }
1040    }
1041}
1042
1043fn format_service_overview(
1044    service_name: &str,
1045    request_variants: &[UnionVariant],
1046    scoped_names: &[&str],
1047    scoped_clients: &[ScopedClient],
1048) -> String {
1049    let mut out = format!("NAME\n    {} \u{2014} service\n\nMETHODS\n", service_name);
1050    for v in request_variants {
1051        if scoped_names.contains(&v.name.as_str()) || v.cli_hidden {
1052            continue;
1053        }
1054        let name = to_snake_case(&v.name);
1055        let desc = doc_first_sentence(&v.description);
1056        if desc.is_empty() {
1057            out.push_str(&format!("    {}\n", name));
1058        } else {
1059            out.push_str(&format!("    {:20} {}\n", name, desc));
1060        }
1061    }
1062    if !scoped_clients.is_empty() {
1063        out.push_str("\nSCOPED\n");
1064        for sc in scoped_clients {
1065            let scope_name = to_snake_case(&sc.factory_name);
1066            let n = sc
1067                .inner_request_variants
1068                .iter()
1069                .filter(|v| !v.cli_hidden)
1070                .count();
1071            out.push_str(&format!(
1072                "    {:20} ({} methods)\n",
1073                format!("{}/", scope_name),
1074                n
1075            ));
1076        }
1077    }
1078    out.push_str(&format!("\nUsage: man {} <method>\n", service_name));
1079    out
1080}
1081
1082fn format_scope_overview(service_name: &str, scope_path: &str, sc: &ScopedClient) -> String {
1083    let scope_field = sc
1084        .scope_fields
1085        .first()
1086        .map(|f| to_snake_case(&f.name))
1087        .unwrap_or_default();
1088    let mut out = format!(
1089        "NAME\n    {} {} \u{2014} scoped operations (by {})\n\nMETHODS\n",
1090        service_name, scope_path, scope_field
1091    );
1092    for v in &sc.inner_request_variants {
1093        if v.cli_hidden {
1094            continue;
1095        }
1096        let name = to_snake_case(&v.name);
1097        let desc = doc_first_sentence(&v.description);
1098        if desc.is_empty() {
1099            out.push_str(&format!("    {}\n", name));
1100        } else {
1101            out.push_str(&format!("    {:20} {}\n", name, desc));
1102        }
1103    }
1104    if !sc.nested_clients.is_empty() {
1105        out.push_str("\nNESTED\n");
1106        for nsc in &sc.nested_clients {
1107            let n = to_snake_case(&nsc.factory_name);
1108            let cnt = nsc
1109                .inner_request_variants
1110                .iter()
1111                .filter(|v| !v.cli_hidden)
1112                .count();
1113            out.push_str(&format!("    {:20} ({} methods)\n", format!("{}/", n), cnt));
1114        }
1115    }
1116    out.push_str(&format!(
1117        "\nUsage: man {} {} <method>\n",
1118        service_name, scope_path
1119    ));
1120    out
1121}
1122
1123fn format_man_page(
1124    service_name: &str,
1125    method_name: &str,
1126    v: &UnionVariant,
1127    resolved: &ResolvedSchema,
1128    all_variants: &[UnionVariant],
1129    scoped_names: &[&str],
1130) -> String {
1131    let mut out = String::new();
1132    let desc = doc_first_sentence(&v.description);
1133    if desc.is_empty() {
1134        out.push_str(&format!("NAME\n    {} {}\n", service_name, method_name));
1135    } else {
1136        out.push_str(&format!(
1137            "NAME\n    {} {} \u{2014} {}\n",
1138            service_name, method_name, desc
1139        ));
1140    }
1141    let synopsis = doc_format_synopsis(service_name, method_name, v, resolved);
1142    out.push_str(&format!("\nSYNOPSIS\n    {}\n", synopsis));
1143    // S3 (#547): scope is mandatory; empty only means a `$scopeExempt` method.
1144    let scope = if v.scope.is_empty() {
1145        "exempt"
1146    } else {
1147        &v.scope
1148    };
1149    out.push_str(&format!("\nSCOPE\n    {}\n", scope));
1150    if !v.description.is_empty() {
1151        out.push_str(&format!("\nDESCRIPTION\n    {}\n", v.description));
1152    }
1153    let params = doc_format_params(v, resolved);
1154    if !params.is_empty() {
1155        out.push_str(&format!("\nPARAMETERS\n{}", params));
1156    }
1157    if !v.doc_example.is_empty() {
1158        out.push_str(&format!("\nEXAMPLES\n    {}\n", v.doc_example));
1159    }
1160    let see_also = doc_format_see_also(service_name, method_name, all_variants, scoped_names);
1161    if !see_also.is_empty() {
1162        out.push_str(&format!("\nSEE ALSO\n    {}\n", see_also));
1163    }
1164    out
1165}
1166
1167fn format_scoped_man_page(
1168    service_name: &str,
1169    scope_path: &str,
1170    method_name: &str,
1171    v: &UnionVariant,
1172    resolved: &ResolvedSchema,
1173    sibling_variants: &[UnionVariant],
1174) -> String {
1175    let mut out = String::new();
1176    let desc = doc_first_sentence(&v.description);
1177    if desc.is_empty() {
1178        out.push_str(&format!(
1179            "NAME\n    {} {} {}\n",
1180            service_name, scope_path, method_name
1181        ));
1182    } else {
1183        out.push_str(&format!(
1184            "NAME\n    {} {} {} \u{2014} {}\n",
1185            service_name, scope_path, method_name, desc
1186        ));
1187    }
1188    // S3 (#547): scope is mandatory; empty only means a `$scopeExempt` method.
1189    let scope = if v.scope.is_empty() {
1190        "exempt"
1191    } else {
1192        &v.scope
1193    };
1194    out.push_str(&format!("\nSCOPE\n    {}\n", scope));
1195    if !v.description.is_empty() {
1196        out.push_str(&format!("\nDESCRIPTION\n    {}\n", v.description));
1197    }
1198    let params = doc_format_params(v, resolved);
1199    if !params.is_empty() {
1200        out.push_str(&format!("\nPARAMETERS\n{}", params));
1201    }
1202    if !v.doc_example.is_empty() {
1203        out.push_str(&format!("\nEXAMPLES\n    {}\n", v.doc_example));
1204    }
1205    let siblings: Vec<String> = sibling_variants
1206        .iter()
1207        .filter(|sv| !sv.cli_hidden && to_snake_case(&sv.name) != method_name)
1208        .map(|sv| {
1209            format!(
1210                "{} {} {}",
1211                service_name,
1212                scope_path,
1213                to_snake_case(&sv.name)
1214            )
1215        })
1216        .collect();
1217    if !siblings.is_empty() {
1218        out.push_str(&format!("\nSEE ALSO\n    {}\n", siblings.join(", ")));
1219    }
1220    out
1221}
1222
1223fn doc_format_synopsis(
1224    service_name: &str,
1225    method_name: &str,
1226    v: &UnionVariant,
1227    resolved: &ResolvedSchema,
1228) -> String {
1229    let ct = CapnpType::classify_primitive(&v.type_name);
1230    match ct {
1231        CapnpType::Void => format!("ctl /srv/{} {}", service_name, method_name),
1232        CapnpType::Struct(_) | CapnpType::Unknown(_) => {
1233            if let Some(sdef) = resolved.find_struct(&v.type_name) {
1234                let fields: Vec<String> = sdef
1235                    .non_union_fields()
1236                    .map(|f: &FieldDef| format!("\"{}\": ...", to_snake_case(&f.name)))
1237                    .collect();
1238                if fields.is_empty() {
1239                    format!("ctl /srv/{} {}", service_name, method_name)
1240                } else {
1241                    format!(
1242                        "ctl /srv/{} {} '{{{{ {} }}}}'",
1243                        service_name,
1244                        method_name,
1245                        fields.join(", ")
1246                    )
1247                }
1248            } else {
1249                format!(
1250                    "ctl /srv/{} {} <{}>",
1251                    service_name, method_name, v.type_name
1252                )
1253            }
1254        }
1255        _ => format!(
1256            "ctl /srv/{} {} <{}>",
1257            service_name, method_name, v.type_name
1258        ),
1259    }
1260}
1261
1262fn doc_format_params(v: &UnionVariant, resolved: &ResolvedSchema) -> String {
1263    let ct = CapnpType::classify_primitive(&v.type_name);
1264    match ct {
1265        CapnpType::Struct(_) | CapnpType::Unknown(_) => {
1266            if let Some(sdef) = resolved.find_struct(&v.type_name) {
1267                let mut out = String::new();
1268                for f in sdef.non_union_fields() {
1269                    let fname = to_snake_case(&f.name);
1270                    let req = if f.optional || f.type_name == "Bool" {
1271                        "optional"
1272                    } else {
1273                        "required"
1274                    };
1275                    if f.description.is_empty() {
1276                        out.push_str(&format!("    {:16} {:10} ({})\n", fname, f.type_name, req));
1277                    } else {
1278                        out.push_str(&format!(
1279                            "    {:16} {:10} ({}) \u{2014} {}\n",
1280                            fname, f.type_name, req, f.description
1281                        ));
1282                    }
1283                }
1284                out
1285            } else {
1286                String::new()
1287            }
1288        }
1289        _ => String::new(),
1290    }
1291}
1292
1293fn doc_format_see_also(
1294    service_name: &str,
1295    method_name: &str,
1296    all_variants: &[UnionVariant],
1297    scoped_names: &[&str],
1298) -> String {
1299    let siblings: Vec<String> = all_variants
1300        .iter()
1301        .filter(|v| {
1302            !v.cli_hidden
1303                && !scoped_names.contains(&v.name.as_str())
1304                && to_snake_case(&v.name) != method_name
1305        })
1306        .map(|v| format!("{} {}", service_name, to_snake_case(&v.name)))
1307        .collect();
1308    siblings.join(", ")
1309}
1310
1311fn doc_first_sentence(desc: &str) -> &str {
1312    if desc.is_empty() {
1313        return desc;
1314    }
1315    if let Some(pos) = desc.find(". ") {
1316        &desc[..pos + 1]
1317    } else {
1318        desc
1319    }
1320}
1321
1322#[cfg(test)]
1323#[allow(clippy::expect_used)]
1324mod primitive_json_dispatch_tests {
1325    use super::*;
1326
1327    #[test]
1328    fn bool_and_numeric_arguments_generate_typed_json_calls() {
1329        for (capnp_type, rust_type) in [
1330            ("Bool", "bool"),
1331            ("UInt8", "u8"),
1332            ("UInt16", "u16"),
1333            ("UInt32", "u32"),
1334            ("UInt64", "u64"),
1335            ("Int8", "i8"),
1336            ("Int16", "i16"),
1337            ("Int32", "i32"),
1338            ("Int64", "i64"),
1339            ("Float32", "f32"),
1340            ("Float64", "f64"),
1341        ] {
1342            let variant: UnionVariant = serde_json::from_value(serde_json::json!({
1343                "name": "setValue", "type_name": capnp_type, "description": "",
1344                "scope": "write", "cli_hidden": false, "doc_example": ""
1345            }))
1346            .expect("primitive request variant");
1347            let schema = ParsedSchema {
1348                request_variants: vec![variant],
1349                response_variants: vec![],
1350                structs: vec![],
1351                scoped_clients: vec![],
1352                enums: vec![],
1353                request_struct: None,
1354                response_struct: None,
1355            };
1356            let resolved = ResolvedSchema::from(&schema);
1357            for scoped in [false, true] {
1358                let arm = generate_json_method_dispatch_arm(
1359                    &schema.request_variants[0],
1360                    &[],
1361                    scoped,
1362                    &resolved,
1363                );
1364                let text = arm.to_string();
1365                assert!(text.contains(&format!("let value : {rust_type}")), "{text}");
1366                assert!(text.contains("serde_json :: from_value"), "{text}");
1367                assert!(text.contains("self . set_value (value) . await"), "{text}");
1368                assert!(!text.contains("struct type not found"), "{text}");
1369                syn::parse2::<syn::Expr>(quote! { match method { #arm _ => unreachable!() } })
1370                    .expect("primitive dispatch arm is valid Rust syntax");
1371            }
1372        }
1373    }
1374}