blvm_sdk_macros/
lib.rs

1//! Procedural macros for BLVM SDK CLI module system.
2
3mod cli_spec;
4mod event_payload_map;
5mod module_impl;
6mod rpc_methods;
7
8use proc_macro::TokenStream;
9use quote::{quote, ToTokens};
10use std::collections::HashMap;
11use syn::{
12    parse_macro_input, punctuated::Punctuated, token::Comma, DeriveInput, Field, ImplItem, Item,
13    ItemImpl, LitStr, Meta,
14};
15
16type EventToMethodsMap = HashMap<String, Vec<(syn::Ident, Vec<(String, bool)>, Vec<String>)>>;
17
18/// Attribute macro: `#[command(name = "...")]` or `#[module_cli(name = "...")]` - on struct: marks CLI entry point.
19/// On impl block: generates `cli_spec()`. Same attribute works for both.
20#[proc_macro_attribute]
21pub fn command(attr: TokenStream, item: TokenStream) -> TokenStream {
22    let item = parse_macro_input!(item as Item);
23    match &item {
24        Item::Struct(_) => expand_module_cli(attr, item),
25        Item::Impl(impl_item) => expand_cli_subcommand(attr, impl_item.clone()),
26        _ => TokenStream::from(quote! { #item }),
27    }
28}
29
30/// Attribute macro: `#[module_cli(name = "...")]` - marks a struct as the module CLI entry point.
31///
32/// The `name` is the CLI command name (e.g. "sync-policy"). Emits `CLI_NAME` const.
33#[proc_macro_attribute]
34pub fn module_cli(attr: TokenStream, item: TokenStream) -> TokenStream {
35    let item = parse_macro_input!(item as Item);
36    expand_module_cli(attr, item)
37}
38
39fn expand_module_cli(attr: TokenStream, item: Item) -> TokenStream {
40    let args = parse_macro_input!(attr with Punctuated::<Meta, Comma>::parse_terminated);
41    let name = extract_name_from_meta(&args).unwrap_or_else(|| "cli".to_string());
42
43    let (struct_name, item_tokens) = match &item {
44        Item::Struct(s) => (s.ident.clone(), quote! { #item }),
45        _ => return TokenStream::from(quote! { #item }),
46    };
47
48    let name_lit = LitStr::new(&name, proc_macro2::Span::call_site());
49    let impl_block = quote! {
50        impl #struct_name {
51            /// CLI command name (from #[command(name = "...")]).
52            pub const CLI_NAME: &str = #name_lit;
53        }
54    };
55
56    TokenStream::from(quote! {
57        #item_tokens
58        #impl_block
59    })
60}
61
62/// Attribute macro: `#[cli_subcommand]` or `#[cli_subcommand(name = "...")]` - on impl block.
63///
64/// Generates `cli_spec()` function returning `blvm_node::module::ipc::protocol::CliSpec`.
65#[proc_macro_attribute]
66pub fn cli_subcommand(attr: TokenStream, item: TokenStream) -> TokenStream {
67    let item = parse_macro_input!(item as ItemImpl);
68    expand_cli_subcommand(attr, item)
69}
70
71fn expand_cli_subcommand(attr: TokenStream, mut item: ItemImpl) -> TokenStream {
72    let args = parse_macro_input!(attr with Punctuated::<Meta, Comma>::parse_terminated);
73    let cli_name = extract_name_from_meta(&args);
74
75    let derived_name = match &item.self_ty.as_ref() {
76        syn::Type::Path(p) => {
77            let ty_name = p
78                .path
79                .segments
80                .last()
81                .map(|s| s.ident.to_string())
82                .unwrap_or_default();
83            if ty_name.ends_with("Cli") {
84                let base = &ty_name[..ty_name.len() - 3];
85                base.chars()
86                    .enumerate()
87                    .flat_map(|(i, c)| {
88                        if c == '_' {
89                            vec!['-']
90                        } else if c.is_uppercase() && i > 0 {
91                            vec!['-', c.to_lowercase().next().unwrap()]
92                        } else if c.is_uppercase() {
93                            vec![c.to_lowercase().next().unwrap()]
94                        } else {
95                            vec![c]
96                        }
97                    })
98                    .collect::<String>()
99            } else {
100                ty_name.to_lowercase().replace('_', "-")
101            }
102        }
103        _ => "cli".to_string(),
104    };
105
106    let cli_name = cli_name.unwrap_or(derived_name);
107
108    let spec_code = cli_spec::generate_spec_code(&item, &cli_name);
109
110    let fn_item: ImplItem = syn::parse2(quote! {
111        /// Generated CLI spec for module registration.
112        pub fn cli_spec() -> blvm_node::module::ipc::protocol::CliSpec {
113            #spec_code
114        }
115    })
116    .expect("generated fn should parse");
117
118    item.items.push(fn_item);
119
120    if let Some(dispatch_code) = cli_spec::generate_dispatch_cli(&item) {
121        let dispatch_item: ImplItem =
122            syn::parse2(dispatch_code).expect("dispatch_cli should parse");
123        item.items.push(dispatch_item);
124    }
125
126    TokenStream::from(quote! { #item })
127}
128
129pub(crate) fn extract_name_from_meta(args: &Punctuated<Meta, Comma>) -> Option<String> {
130    for meta in args {
131        if let Meta::NameValue(nv) = meta {
132            if nv.path.is_ident("name") {
133                if let syn::Expr::Lit(el) = &nv.value {
134                    if let syn::Lit::Str(s) = &el.lit {
135                        return Some(s.value());
136                    }
137                }
138            }
139        }
140    }
141    None
142}
143
144/// Extract config type from #[module(config = DemoConfig)].
145pub(crate) fn extract_config_type_from_meta(args: &Punctuated<Meta, Comma>) -> Option<syn::Type> {
146    for meta in args {
147        if let Meta::NameValue(nv) = meta {
148            if nv.path.is_ident("config") {
149                return syn::parse2(nv.value.to_token_stream()).ok();
150            }
151        }
152    }
153    None
154}
155
156/// Infer config type from struct field `config: T`.
157fn extract_config_type_from_struct(struct_item: &syn::ItemStruct) -> Option<syn::Type> {
158    if let syn::Fields::Named(ref fields) = struct_item.fields {
159        for f in &fields.named {
160            if f.ident.as_ref().map(|i| i == "config").unwrap_or(false) {
161                return Some(f.ty.clone());
162            }
163        }
164    }
165    None
166}
167
168/// Derive module name from struct/type name: DemoModule → "demo", SyncPolicy → "sync-policy".
169pub(crate) fn derive_module_name(ident: &syn::Ident) -> String {
170    let s = ident.to_string();
171    let s = s.strip_suffix("Module").unwrap_or(&s);
172    s.chars()
173        .enumerate()
174        .flat_map(|(i, c)| {
175            if c == '_' {
176                vec!['-']
177            } else if c.is_uppercase() && i > 0 {
178                vec!['-', c.to_lowercase().next().unwrap()]
179            } else if c.is_uppercase() {
180                vec![c.to_lowercase().next().unwrap()]
181            } else {
182                vec![c]
183            }
184        })
185        .collect::<String>()
186}
187
188/// Extract migrations from #[module(migrations = ((1, up_initial), (2, up_add_items_tree)))].
189/// Returns Vec of (version_lit, fn_ident) for generating the migrations slice.
190fn extract_migrations_from_meta(args: &Punctuated<Meta, Comma>) -> Option<Vec<(u32, syn::Ident)>> {
191    for meta in args {
192        if let Meta::NameValue(nv) = meta {
193            if !nv.path.is_ident("migrations") {
194                continue;
195            }
196            let expr = &nv.value;
197            let mut pairs = Vec::new();
198            if let syn::Expr::Tuple(outer) = expr {
199                for elem in &outer.elems {
200                    if let syn::Expr::Tuple(inner) = elem {
201                        let elems: Vec<_> = inner.elems.iter().collect();
202                        if elems.len() >= 2 {
203                            let version = match &elems[0] {
204                                syn::Expr::Lit(el) => {
205                                    if let syn::Lit::Int(li) = &el.lit {
206                                        li.base10_parse::<u32>().ok()
207                                    } else {
208                                        None
209                                    }
210                                }
211                                _ => None,
212                            };
213                            let ident = match &elems[1] {
214                                syn::Expr::Path(ep) => ep.path.get_ident().cloned(),
215                                _ => None,
216                            };
217                            if let (Some(v), Some(i)) = (version, ident) {
218                                pairs.push((v, i));
219                            }
220                        }
221                    }
222                }
223            }
224            if !pairs.is_empty() {
225                return Some(pairs);
226            }
227        }
228    }
229    None
230}
231
232/// Attribute macro: `#[rpc_methods]` - on impl block with #[rpc_method] methods.
233///
234/// Generates `rpc_method_names() -> Vec<&'static str>` and `dispatch_rpc(&self, method, params, db)`.
235/// Enables auto-discovery of RPC methods for run_module!.
236#[proc_macro_attribute]
237pub fn rpc_methods(_attr: TokenStream, item: TokenStream) -> TokenStream {
238    let item = parse_macro_input!(item as ItemImpl);
239    rpc_methods::expand_rpc_methods(item).into()
240}
241
242/// Attribute macro: `#[rpc_method]` or `#[rpc_method(name = "...")]`.
243///
244/// Marks a method as an RPC endpoint. Without `name`, the function name is used (e.g. `demo_set` → "demo_set").
245/// Use with #[rpc_methods] or #[module(name = "x")] on the impl block for auto-discovery.
246#[proc_macro_attribute]
247pub fn rpc_method(_attr: TokenStream, item: TokenStream) -> TokenStream {
248    let item = parse_macro_input!(item as ImplItem);
249    TokenStream::from(quote! { #item })
250}
251
252/// Attribute macro: `#[migration(version = N)]` or `#[migration(version = N, down)]`.
253///
254/// Marks a function as a migration step. For `up` migrations (default), the function
255/// must have signature `fn(&MigrationContext) -> Result<()>`. Use with `run_migrations`:
256///
257/// ```ignore
258/// run_migrations(&db, &[(1, up_initial), (2, up_add_cache)])?;
259/// ```
260///
261/// `down` migrations are for future rollback support; currently pass-through only.
262#[proc_macro_attribute]
263pub fn migration(attr: TokenStream, item: TokenStream) -> TokenStream {
264    let args = parse_macro_input!(attr with Punctuated::<Meta, Comma>::parse_terminated);
265    let item = parse_macro_input!(item as syn::ItemFn);
266
267    let mut version = None;
268    let mut is_down = false;
269
270    for meta in args {
271        match meta {
272            Meta::NameValue(nv) if nv.path.is_ident("version") => {
273                if let syn::Expr::Lit(el) = &nv.value {
274                    if let syn::Lit::Int(li) = &el.lit {
275                        version = li.base10_parse::<u32>().ok();
276                    }
277                }
278            }
279            Meta::Path(p) if p.is_ident("down") => is_down = true,
280            _ => {}
281        }
282    }
283
284    if version.is_none() {
285        return syn::Error::new(
286            proc_macro2::Span::call_site(),
287            "#[migration] requires version = N (e.g. #[migration(version = 1)])",
288        )
289        .to_compile_error()
290        .into();
291    }
292
293    let _version = version.unwrap();
294    let _is_down = is_down;
295    // Pass through; module author collects migrations and passes to run_migrations
296    TokenStream::from(quote! { #item })
297}
298
299/// Extract env var name from `#[config_env]` or `#[config_env("ENV_NAME")]` on a field.
300/// Returns None if no config_env attr; Some(env_name) if present (None = use default).
301fn extract_config_env_from_field(field: &Field) -> Option<Option<String>> {
302    for attr in &field.attrs {
303        if attr.path().is_ident("config_env") {
304            // #[config_env] with no args is Meta::Path; parse_args fails on empty.
305            // #[config_env("X")] is Meta::List. Use meta structure directly.
306            return Some(match &attr.meta {
307                Meta::Path(_) => None, // #[config_env] - use default MODULE_CONFIG_<FIELD>
308                Meta::NameValue(nv) if nv.path.is_ident("env") => {
309                    if let syn::Expr::Lit(el) = &nv.value {
310                        if let syn::Lit::Str(s) = &el.lit {
311                            Some(s.value())
312                        } else {
313                            None
314                        }
315                    } else {
316                        None
317                    }
318                }
319                Meta::List(list) => syn::parse2::<LitStr>(list.tokens.clone())
320                    .ok()
321                    .map(|s| s.value()),
322                _ => None,
323            });
324        }
325    }
326    None
327}
328
329/// Generate env override assignment for a field based on its type.
330fn env_override_stmt(
331    field_name: &syn::Ident,
332    env_lit: &LitStr,
333    ty: &syn::Type,
334) -> proc_macro2::TokenStream {
335    let ty_str = ty.to_token_stream().to_string();
336    let ty_compact = ty_str.replace(' ', "");
337    if ty_compact == "String" {
338        quote! {
339            if let Ok(__v) = std::env::var(#env_lit) {
340                self.#field_name = __v;
341            }
342        }
343    } else if ty_compact.starts_with("Option<") {
344        quote! {
345            if let Ok(__v) = std::env::var(#env_lit) {
346                self.#field_name = Some(__v);
347            }
348        }
349    } else if ty_compact.starts_with("Vec<") {
350        quote! {
351            if let Ok(__v) = std::env::var(#env_lit) {
352                self.#field_name = __v.split(',').map(|s| s.trim().to_string()).filter(|s| !s.is_empty()).collect();
353            }
354        }
355    } else if ty_compact == "bool" {
356        quote! {
357            if let Ok(__v) = std::env::var(#env_lit) {
358                self.#field_name = __v.eq_ignore_ascii_case("true") || __v == "1";
359            }
360        }
361    } else {
362        quote! {
363            if let Ok(__v) = std::env::var(#env_lit) {
364                if let Ok(__parsed) = __v.parse() {
365                    self.#field_name = __parsed;
366                }
367            }
368        }
369    }
370}
371
372/// Attribute macro: `#[config(name = "...")]` or `#[module_config(name = "...")]` - marks a config struct.
373///
374/// The `name` matches the node config section `[modules.<name>]` for override merging.
375/// Emits `CONFIG_SECTION_NAME` const. Config loading (from env vars or file) is module-specific.
376///
377/// Field-level `#[config_env]` or `#[config_env("ENV_NAME")]`: env override for that field.
378/// - `#[config_env]` → uses `MODULE_CONFIG_<FIELD_UPPERCASE>` (node passes these)
379/// - `#[config_env("CUSTOM_ENV")]` → uses `CUSTOM_ENV` for standalone/override
380///
381/// Generates `apply_env_overrides(&mut self)` to apply env vars over loaded config.
382#[proc_macro_attribute]
383pub fn config(attr: TokenStream, item: TokenStream) -> TokenStream {
384    module_config(attr, item)
385}
386
387/// Strip #[config_env] from struct fields so derive macros (Serialize, etc.) don't see it.
388fn strip_config_env_from_item(item: &Item) -> Item {
389    let Item::Struct(mut s) = item.clone() else {
390        return item.clone();
391    };
392    if let syn::Fields::Named(ref mut fields) = s.fields {
393        for field in &mut fields.named {
394            field.attrs.retain(|a| !a.path().is_ident("config_env"));
395        }
396    }
397    Item::Struct(s)
398}
399
400#[proc_macro_attribute]
401pub fn module_config(attr: TokenStream, item: TokenStream) -> TokenStream {
402    let args = parse_macro_input!(attr with Punctuated::<Meta, Comma>::parse_terminated);
403    let item = parse_macro_input!(item as Item);
404
405    let name = extract_name_from_meta(&args);
406
407    // Output struct without #[config_env] so derive macros don't error on it
408    let item_stripped = strip_config_env_from_item(&item);
409    let item_tokens = quote! { #item_stripped };
410
411    let extra = if let Some(config_name) = name {
412        let name_lit = LitStr::new(&config_name, proc_macro2::Span::call_site());
413        if let Item::Struct(s) = &item {
414            let struct_name = &s.ident;
415            let mut apply_stmts = Vec::new();
416            if let syn::Fields::Named(fields) = &s.fields {
417                for field in &fields.named {
418                    let field_name = field.ident.as_ref().expect("named field");
419                    let Some(env_opt) = extract_config_env_from_field(field) else {
420                        continue;
421                    };
422                    let env_var = env_opt.unwrap_or_else(|| {
423                        format!(
424                            "MODULE_CONFIG_{}",
425                            field_name.to_string().to_uppercase().replace('-', "_")
426                        )
427                    });
428                    let env_lit = LitStr::new(&env_var, proc_macro2::Span::call_site());
429                    let ty = &field.ty;
430                    let set_stmt = env_override_stmt(field_name, &env_lit, ty);
431                    apply_stmts.push(set_stmt);
432                }
433            }
434            let apply_block = if apply_stmts.is_empty() {
435                quote! {
436                    /// Apply env overrides to config. No #[config_env] fields; no-op.
437                    pub fn apply_env_overrides(&mut self) {}
438                }
439            } else {
440                quote! {
441                    /// Apply env overrides for fields marked with #[config_env].
442                    /// Call after loading from file; env vars override file values.
443                    pub fn apply_env_overrides(&mut self) {
444                        #(#apply_stmts)*
445                    }
446                }
447            };
448
449            let load_block = quote! {
450                /// Load config from path (e.g. config.toml), apply env overrides.
451                /// Requires `#[derive(Default, Serialize, Deserialize)]` on the struct.
452                pub fn load(path: impl std::convert::AsRef<std::path::Path>) -> std::result::Result<Self, anyhow::Error> {
453                    let mut config: Self = std::fs::read_to_string(path.as_ref())
454                        .ok()
455                        .and_then(|s| toml::from_str(&s).ok())
456                        .unwrap_or_else(|| Self::default());
457                    config.apply_env_overrides();
458                    Ok(config)
459                }
460            };
461
462            quote! {
463                impl #struct_name {
464                    /// Config section name (from #[module_config(name = "...")]).
465                    /// Matches [modules.<name>] in node config for override merging.
466                    pub const CONFIG_SECTION_NAME: &str = #name_lit;
467                    #apply_block
468                    #load_block
469                }
470            }
471        } else {
472            quote! {}
473        }
474    } else {
475        quote! {}
476    };
477
478    TokenStream::from(quote! {
479        #item_tokens
480        #extra
481    })
482}
483
484/// Attribute macro: `#[module]` or `#[blvm_module]` - marks the main module struct.
485/// With `#[module(name = "demo")]` on an impl block: generates CLI, RPC, and event
486/// dispatch from a single impl (replaces #[command], #[rpc_methods], #[event_handlers]).
487#[proc_macro_attribute]
488pub fn module(attr: TokenStream, item: TokenStream) -> TokenStream {
489    blvm_module(attr, item)
490}
491
492/// Attribute macro: `#[blvm_module]` - marks the main module struct.
493/// On struct: `#[module(name = "demo", config = DemoConfig)]` generates `__module_new(config)`.
494/// With `migrations = ((1, up_initial), (2, up_add_items_tree))` also generates `ModuleMeta` impl
495/// for `run_module_main!(DemoModule)`.
496/// On impl: `#[module(name = "demo")]` generates cli_spec, dispatch_cli, rpc_method_names, etc.
497#[proc_macro_attribute]
498pub fn blvm_module(attr: TokenStream, item: TokenStream) -> TokenStream {
499    let item = parse_macro_input!(item as Item);
500    let args = parse_macro_input!(attr with Punctuated::<Meta, Comma>::parse_terminated);
501    match &item {
502        Item::Struct(struct_item) => {
503            let struct_name = &struct_item.ident;
504            let config_ty = extract_config_type_from_meta(&args)
505                .or_else(|| extract_config_type_from_struct(struct_item));
506            let migrations = extract_migrations_from_meta(&args);
507            let module_name =
508                extract_name_from_meta(&args).unwrap_or_else(|| derive_module_name(struct_name));
509
510            let mut blocks = Vec::new();
511            let ct = config_ty.as_ref();
512
513            if let (Some(ct), Some(migs)) = (ct, migrations) {
514                let name_lit = LitStr::new(&module_name, proc_macro2::Span::call_site());
515                let migration_entries: Vec<_> = migs
516                    .iter()
517                    .map(|(v, ident)| quote! { (#v, #ident as blvm_sdk::module::MigrationUp) })
518                    .collect();
519                let meta_impl = quote! {
520                    impl blvm_sdk::module::ModuleMeta for #struct_name {
521                        const MODULE_NAME: &'static str = #name_lit;
522                        type Config = #ct;
523                        fn migrations() -> &'static [(u32, blvm_sdk::module::MigrationUp)] {
524                            static MIGRATIONS: &[(u32, blvm_sdk::module::MigrationUp)] = &[#(#migration_entries),*];
525                            MIGRATIONS
526                        }
527                        fn __module_new(config: Self::Config) -> Self {
528                            Self { config }
529                        }
530                    }
531                };
532                blocks.push(meta_impl);
533            } else if let Some(ct) = ct {
534                let impl_block = quote! {
535                    impl #struct_name {
536                        #[doc(hidden)]
537                        pub fn __module_new(config: #ct) -> Self {
538                            Self { config }
539                        }
540                    }
541                };
542                blocks.push(impl_block);
543            }
544
545            if blocks.is_empty() {
546                TokenStream::from(quote! { #item })
547            } else {
548                TokenStream::from(quote! {
549                    #item
550                    #(#blocks)*
551                })
552            }
553        }
554        Item::Impl(impl_item) => module_impl::expand_module_impl(&args, impl_item.clone()),
555        _ => TokenStream::from(quote! { #item }),
556    }
557}
558
559/// Attribute macro: `#[on_event(NewBlock, NewTransaction, ...)]` - marks a method as event handler.
560/// Use with `#[event_handlers]` on the impl block. Pass-through; event_handlers reads this.
561#[proc_macro_attribute]
562pub fn on_event(_attr: TokenStream, item: TokenStream) -> TokenStream {
563    item
564}
565
566/// Attribute macro: `#[event_handlers]` - on impl block with #[on_event] methods.
567///
568/// Generates:
569/// - `event_types() -> Vec<EventType>` — all event types from #[on_event] handlers (for subscribe_events)
570/// - `dispatch_event(&self, event: EventMessage) -> impl Future` — dispatches to the right handler
571///
572/// Auto-subscribe: call `integration.subscribe_events(MyModule::event_types()).await?` after connect.
573/// Auto-unsubscribe: happens when module unloads (IPC connection closes).
574#[proc_macro_attribute]
575pub fn event_handlers(_attr: TokenStream, item: TokenStream) -> TokenStream {
576    let mut impl_block = parse_macro_input!(item as ItemImpl);
577
578    // Collect (event_type_ident, (method_ident, params, event_types_for_method)) from each #[on_event] method
579    let mut event_to_methods: EventToMethodsMap = HashMap::new();
580    let mut all_event_idents = Vec::<syn::Ident>::new();
581
582    for impl_item in &impl_block.items {
583        if let ImplItem::Fn(method) = impl_item {
584            for attr in &method.attrs {
585                if attr.path().is_ident("on_event") {
586                    let event_idents = parse_on_event_args(attr);
587                    let method_ident = method.sig.ident.clone();
588                    let params = parse_handler_params(method);
589                    let event_keys: Vec<String> =
590                        event_idents.iter().map(|e| e.to_string()).collect();
591                    for ev in &event_idents {
592                        let key = ev.to_string();
593                        if !all_event_idents.iter().any(|e| e == ev) {
594                            all_event_idents.push(ev.clone());
595                        }
596                        event_to_methods.entry(key).or_default().push((
597                            method_ident.clone(),
598                            params.clone(),
599                            event_keys.clone(),
600                        ));
601                    }
602                    break;
603                }
604            }
605        }
606    }
607
608    if all_event_idents.is_empty() {
609        return TokenStream::from(quote! { #impl_block });
610    }
611
612    // Generate event_types()
613    let event_type_exprs: Vec<_> = all_event_idents
614        .iter()
615        .map(|i| quote! { blvm_node::module::traits::EventType::#i })
616        .collect();
617
618    let event_types_fn: ImplItem = syn::parse2(quote! {
619        /// Event types to subscribe to (from #[on_event] handlers).
620        pub fn event_types() -> Vec<blvm_node::module::traits::EventType> {
621            vec![#(#event_type_exprs),*]
622        }
623    })
624    .expect("event_types fn should parse");
625
626    // Generate dispatch_event - match on event_type and call handler(s) with DI
627    let mut match_arms = Vec::new();
628    for (ev_key, method_infos) in &event_to_methods {
629        let ev_ident: syn::Ident = syn::parse_str(ev_key).unwrap();
630        let payload_fields = event_payload_map::payload_fields_for_event(ev_key);
631
632        let method_calls: Vec<proc_macro2::TokenStream> = method_infos
633            .iter()
634            .map(|(method_ident, params, event_types_for_method)| {
635                build_handler_call(
636                    method_ident,
637                    params,
638                    event_types_for_method,
639                    ev_key,
640                    &payload_fields,
641                )
642            })
643            .collect();
644
645        match_arms.push(quote! {
646            blvm_node::module::traits::EventType::#ev_ident => {
647                #(#method_calls)*
648            }
649        });
650    }
651    match_arms.push(quote! { _ => {} });
652
653    let dispatch_fn: ImplItem = syn::parse2(quote! {
654        /// Dispatch event to #[on_event] handlers.
655        pub async fn dispatch_event(
656            &self,
657            event: blvm_node::module::ipc::protocol::EventMessage,
658        ) -> Result<(), blvm_node::module::traits::ModuleError> {
659            use blvm_node::module::traits::EventType;
660            match event.event_type {
661                #(#match_arms),*
662            }
663            Ok(())
664        }
665    })
666    .expect("dispatch_event fn should parse");
667
668    impl_block.items.push(event_types_fn);
669    impl_block.items.push(dispatch_fn);
670
671    TokenStream::from(quote! { #impl_block })
672}
673
674fn parse_handler_params(method: &syn::ImplItemFn) -> Vec<(String, bool)> {
675    let mut out = Vec::new();
676    for arg in method.sig.inputs.iter().skip(1) {
677        if let syn::FnArg::Typed(pat_type) = arg {
678            let name = match &*pat_type.pat {
679                syn::Pat::Ident(pi) => pi.ident.to_string(),
680                _ => continue,
681            };
682            let is_event = matches!(
683                &*pat_type.ty,
684                syn::Type::Reference(tr) if matches!(&*tr.elem, syn::Type::Path(tp) if tp.path.is_ident("EventMessage"))
685            );
686            out.push((name, is_event));
687        }
688    }
689    out
690}
691
692fn build_handler_call(
693    method_ident: &syn::Ident,
694    params: &[(String, bool)],
695    event_types_for_method: &[String],
696    ev_key: &str,
697    payload_fields: &Option<Vec<(&'static str, bool)>>,
698) -> proc_macro2::TokenStream {
699    let use_di = event_types_for_method.len() == 1
700        && payload_fields.is_some()
701        && params.iter().all(|(name, is_event)| {
702            if *is_event {
703                true
704            } else {
705                payload_fields
706                    .as_ref()
707                    .unwrap()
708                    .iter()
709                    .any(|(f, _)| f == name)
710            }
711        });
712
713    if !use_di {
714        return quote! { self.#method_ident(&event).await?; };
715    }
716
717    let fields = payload_fields.as_ref().unwrap();
718    let field_idents: Vec<syn::Ident> = fields
719        .iter()
720        .map(|(f, _)| syn::Ident::new(f, proc_macro2::Span::call_site()))
721        .collect();
722    let ev_ident = syn::Ident::new(ev_key, proc_macro2::Span::call_site());
723
724    let call_args: Vec<proc_macro2::TokenStream> = params
725        .iter()
726        .map(|(name, is_event)| {
727            if *is_event {
728                quote! { &event }
729            } else {
730                let ident = syn::Ident::new(name, proc_macro2::Span::call_site());
731                let (_, is_copy) = fields.iter().find(|(f, _)| *f == name).unwrap();
732                if *is_copy {
733                    quote! { *#ident }
734                } else {
735                    quote! { #ident }
736                }
737            }
738        })
739        .collect();
740
741    quote! {
742        if let blvm_node::module::ipc::protocol::EventPayload::#ev_ident { #(#field_idents),* } = &event.payload {
743            self.#method_ident(#(#call_args),*).await?;
744        }
745    }
746}
747
748fn parse_on_event_args(attr: &syn::Attribute) -> Vec<syn::Ident> {
749    let parser = Punctuated::<syn::Ident, Comma>::parse_terminated;
750    attr.parse_args_with(parser)
751        .map(|p| p.into_iter().collect())
752        .unwrap_or_default()
753}
754
755/// Parameter attribute: `#[arg(long)]`, `#[arg(short = 'o')]`, `#[arg(default = "x")]`.
756/// Use on CLI handler parameters for named-arg parsing and type coercion.
757#[proc_macro_attribute]
758pub fn arg(_attr: TokenStream, item: TokenStream) -> TokenStream {
759    item
760}
761
762/// Field attribute: `#[config_env]` or `#[config_env("ENV_NAME")]`.
763/// Use with `#[module_config(name = "...")]` on the struct. Pass-through; the real logic
764/// is in `module_config` which reads this attribute to generate `apply_env_overrides()`.
765#[proc_macro_attribute]
766pub fn config_env(_attr: TokenStream, item: TokenStream) -> TokenStream {
767    item
768}
769
770/// Placeholder derive macro for future use.
771#[proc_macro_derive(ModuleCliSpec)]
772pub fn derive_module_cli_spec(input: TokenStream) -> TokenStream {
773    let _input = parse_macro_input!(input as DeriveInput);
774    quote! {}.into()
775}
blvm_sdk_macros/lib.rs

blvm_sdk_macros/
lib.rs
