Skip to main content

hiway_macros/
lib.rs

1#![doc = "Attribute macros for hiway event specifications and injected ports."]
2#![forbid(unsafe_code)]
3
4use proc_macro::TokenStream;
5use proc_macro2::{Ident, Span, TokenStream as TokenStream2};
6use proc_macro_crate::{crate_name, FoundCrate};
7use quote::{format_ident, quote, ToTokens};
8use syn::{
9    parenthesized,
10    parse::{Parse, ParseStream},
11    parse_macro_input, Error, Fields, Ident as SynIdent, ItemEnum, ItemStruct, LitInt, Path,
12    Result, Token,
13};
14
15#[proc_macro_attribute]
16pub fn events(attributes: TokenStream, item: TokenStream) -> TokenStream {
17    let attributes = parse_macro_input!(attributes as EventsArgs);
18    let item = parse_macro_input!(item as ItemEnum);
19    match expand_events(&attributes, &item) {
20        Ok(tokens) => tokens.into(),
21        Err(error) => error.into_compile_error().into(),
22    }
23}
24
25#[proc_macro_attribute]
26pub fn port(attributes: TokenStream, item: TokenStream) -> TokenStream {
27    let attributes = parse_macro_input!(attributes as PortArgs);
28    let item = parse_macro_input!(item as ItemStruct);
29    match expand_port(&attributes, &item) {
30        Ok(tokens) => tokens.into(),
31        Err(error) => error.into_compile_error().into(),
32    }
33}
34
35#[proc_macro_attribute]
36pub fn graph(attributes: TokenStream, item: TokenStream) -> TokenStream {
37    let attributes = parse_macro_input!(attributes as GraphArgs);
38    let item = parse_macro_input!(item as ItemStruct);
39    match expand_graph(&attributes, &item) {
40        Ok(tokens) => tokens.into(),
41        Err(error) => error.into_compile_error().into(),
42    }
43}
44
45struct EventsArgs {
46    wire_major: Option<LitInt>,
47    schema_revision: Option<LitInt>,
48}
49
50impl Parse for EventsArgs {
51    fn parse(input: ParseStream<'_>) -> Result<Self> {
52        let mut wire_major = None;
53        let mut schema_revision = None;
54        while !input.is_empty() {
55            let key: SynIdent = input.parse()?;
56            input.parse::<Token![=]>()?;
57            match key.to_string().as_str() {
58                "wire_major" if wire_major.is_none() => wire_major = Some(input.parse()?),
59                "schema_revision" if schema_revision.is_none() => {
60                    schema_revision = Some(input.parse()?);
61                }
62                "wire_major" | "schema_revision" => {
63                    return Err(Error::new(key.span(), "event version field repeated"));
64                }
65                _ => return Err(Error::new(key.span(), "unknown event declaration field")),
66            }
67            if input.peek(Token![,]) {
68                input.parse::<Token![,]>()?;
69            }
70        }
71        Ok(Self {
72            wire_major,
73            schema_revision,
74        })
75    }
76}
77
78impl EventsArgs {
79    fn wire_constants(&self, hiway: &TokenStream2) -> TokenStream2 {
80        let wire_major = self.wire_major.as_ref().map(
81            |literal| quote!(const WIRE_MAJOR: #hiway::WireMajor = #hiway::WireMajor(#literal);),
82        );
83        let schema_revision = self.schema_revision.as_ref().map(|literal| {
84            quote!(const SCHEMA_REVISION: #hiway::SchemaRevision = #hiway::SchemaRevision(#literal);)
85        });
86        quote!(#wire_major #schema_revision)
87    }
88}
89
90fn conditional_attribute(meta: &syn::Meta) -> Result<Option<TokenStream2>> {
91    match meta {
92        syn::Meta::List(list) if list.path.is_ident("cfg") => Ok(Some(quote!(#meta))),
93        syn::Meta::List(list) if list.path.is_ident("cfg_attr") => {
94            let (predicate, attributes) = list.parse_args_with(|input: ParseStream<'_>| {
95                let predicate = if input.peek(syn::LitBool) {
96                    input.parse::<syn::LitBool>()?.to_token_stream()
97                } else {
98                    input.parse::<syn::Meta>()?.to_token_stream()
99                };
100                input.parse::<Token![,]>()?;
101                let attributes = input.parse_terminated(syn::Meta::parse, Token![,])?;
102                Ok((predicate, attributes))
103            })?;
104
105            let mut conditional_attributes = Vec::new();
106            for attribute in attributes {
107                if let Some(attribute) = conditional_attribute(&attribute)? {
108                    conditional_attributes.push(attribute);
109                }
110            }
111            if conditional_attributes.is_empty() {
112                Ok(None)
113            } else {
114                Ok(Some(
115                    quote!(cfg_attr(#predicate, #(#conditional_attributes),*)),
116                ))
117            }
118        }
119        _ => Ok(None),
120    }
121}
122
123fn event_options(attributes: &[syn::Attribute]) -> Result<(Option<syn::LitStr>, bool)> {
124    let mut id = None;
125    let mut latest = false;
126    for attribute in attributes
127        .iter()
128        .filter(|attribute| attribute.path().is_ident("event"))
129    {
130        let mut found_option = false;
131        attribute.parse_nested_meta(|meta| {
132            if meta.path.is_ident("latest") {
133                if latest {
134                    return Err(meta.error("duplicate latest-state declaration"));
135                }
136                latest = true;
137                found_option = true;
138                return Ok(());
139            }
140            if !meta.path.is_ident("id") {
141                return Err(meta.error("unknown event attribute field"));
142            }
143            if id.is_some() {
144                return Err(meta.error("duplicate event id"));
145            }
146            let value = meta.value()?.parse::<syn::LitStr>()?;
147            if value.value().is_empty() {
148                return Err(syn::Error::new_spanned(
149                    &value,
150                    "event id must not be empty",
151                ));
152            }
153            found_option = true;
154            id = Some(value);
155            Ok(())
156        })?;
157        if !found_option {
158            return Err(syn::Error::new_spanned(
159                attribute,
160                "event attribute requires `id = \"...\"`",
161            ));
162        }
163    }
164    Ok((id, latest))
165}
166
167// Keep variant validation and its generated items together.
168#[allow(clippy::too_many_lines)]
169fn expand_events(arguments: &EventsArgs, item: &ItemEnum) -> Result<TokenStream2> {
170    if !item.generics.params.is_empty() {
171        return Err(Error::new_spanned(
172            &item.generics,
173            "event declarations with generics are not supported",
174        ));
175    }
176
177    let mut item = (*item).clone();
178    let hiway = hiway_path()?;
179    let visibility = &item.vis;
180    let enum_name = &item.ident;
181    let module = format_ident!("{}", snake_case(&enum_name.to_string()));
182    let wire_constants = arguments.wire_constants(&hiway);
183    let marker_visibility = if matches!(visibility, syn::Visibility::Inherited) {
184        quote!(pub(crate))
185    } else {
186        quote!(pub)
187    };
188
189    let mut markers = Vec::with_capacity(item.variants.len());
190    let mut implementations = Vec::with_capacity(item.variants.len());
191    let mut enum_conversions = Vec::with_capacity(item.variants.len());
192    for variant in &mut item.variants {
193        let (explicit_id, latest) = event_options(&variant.attrs)?;
194        let delivery =
195            latest.then(|| quote!(const DELIVERY: #hiway::Delivery = #hiway::Delivery::Latest;));
196        variant
197            .attrs
198            .retain(|attribute| !attribute.path().is_ident("event"));
199        let mut conditional_attributes = Vec::new();
200        for attribute in &variant.attrs {
201            if let Some(attribute) = conditional_attribute(&attribute.meta)? {
202                conditional_attributes.push(attribute);
203            }
204        }
205        let name = &variant.ident;
206        let (payload, enum_value, conversion_arm, constructor) = match &variant.fields {
207            Fields::Unit => (
208                quote!(()),
209                quote!({ let () = value.into_inner(); Self::#name }),
210                quote!(#enum_name::#name => ::core::result::Result::Ok(#hiway::EventValue::new(()))),
211                quote! {
212                    #[allow(non_upper_case_globals)]
213                    #marker_visibility const #name: #hiway::EventValue<#name> =
214                        #hiway::EventValue::new(());
215                },
216            ),
217            Fields::Unnamed(fields) if fields.unnamed.len() == 1 => {
218                let payload = &fields.unnamed[0].ty;
219                (
220                    quote!(#payload),
221                    quote!(Self::#name(value.into_inner())),
222                    quote!(#enum_name::#name(payload) => ::core::result::Result::Ok(#hiway::EventValue::new(payload))),
223                    quote! {
224                        #[allow(non_snake_case)]
225                        #marker_visibility const fn #name(
226                            payload: <#name as #hiway::EventSpec>::Payload,
227                        ) -> #hiway::EventValue<#name> {
228                            #hiway::EventValue::new(payload)
229                        }
230                    },
231                )
232            }
233            Fields::Unnamed(_) | Fields::Named(_) => {
234                return Err(Error::new_spanned(
235                    &variant.fields,
236                    "event variants must be unit-like or carry one unnamed payload",
237                ));
238            }
239        };
240
241        markers.push(quote! {
242            #(#[#conditional_attributes])*
243            #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
244            #marker_visibility struct #name {
245                _private: (),
246            }
247
248            #(#[#conditional_attributes])*
249            #constructor
250        });
251        let event_id = match explicit_id {
252            Some(id) => quote!(#hiway::EventId::from_name(#id)),
253            None => event_identity(&hiway, enum_name, name),
254        };
255        implementations.push(quote! {
256            #(#[#conditional_attributes])*
257            impl #hiway::EventSpec for #module::#name {
258                type Payload = #payload;
259                const ID: #hiway::EventId = #event_id;
260                #wire_constants
261                #delivery
262            }
263        });
264        enum_conversions.push(quote! {
265            #(#[#conditional_attributes])*
266            impl ::core::convert::From<#hiway::EventValue<#module::#name>> for #enum_name {
267                fn from(value: #hiway::EventValue<#module::#name>) -> Self {
268                    #enum_value
269                }
270            }
271
272            #(#[#conditional_attributes])*
273            impl ::core::convert::TryFrom<#enum_name> for #hiway::EventValue<#module::#name> {
274                type Error = #enum_name;
275
276                fn try_from(value: #enum_name) -> ::core::result::Result<Self, Self::Error> {
277                    match value {
278                        #conversion_arm,
279                        other => ::core::result::Result::Err(other),
280                    }
281                }
282            }
283        });
284    }
285
286    Ok(quote! {
287        #[allow(dead_code)]
288        #item
289
290        #visibility mod #module {
291            #(#markers)*
292        }
293
294        #(#implementations)*
295        #(#enum_conversions)*
296    })
297}
298
299fn event_identity(hiway: &TokenStream2, enum_name: &Ident, variant: &Ident) -> TokenStream2 {
300    quote! {
301        #hiway::EventId::from_name(concat!(
302            module_path!(),
303            "::",
304            stringify!(#enum_name),
305            "::",
306            stringify!(#variant),
307        ))
308    }
309}
310
311struct PortArgs {
312    factory: Option<Path>,
313    send: Vec<Path>,
314    recv: Vec<Path>,
315    required: Vec<Path>,
316}
317
318impl Parse for PortArgs {
319    fn parse(input: ParseStream<'_>) -> Result<Self> {
320        let mut factory = None;
321        let mut send = None;
322        let mut recv = None;
323        let mut required = None;
324        while !input.is_empty() {
325            let key: SynIdent = input.parse()?;
326            match key.to_string().as_str() {
327                "factory" if factory.is_none() => {
328                    input.parse::<Token![=]>()?;
329                    factory = Some(input.parse()?);
330                }
331                "factory" => return Err(Error::new(key.span(), "port factory repeated")),
332                "send" | "recv" | "required" => {
333                    let content;
334                    parenthesized!(content in input);
335                    let paths = content
336                        .parse_terminated(Path::parse, Token![,])?
337                        .into_iter()
338                        .collect::<Vec<_>>();
339                    match key.to_string().as_str() {
340                        "send" if send.is_none() => send = Some(paths),
341                        "recv" if recv.is_none() => recv = Some(paths),
342                        "required" if required.is_none() => required = Some(paths),
343                        _ => {
344                            return Err(Error::new(key.span(), "port capability group repeated"));
345                        }
346                    }
347                }
348                "capacity" => {
349                    return Err(Error::new(key.span(), "stream capacity belongs to owner"));
350                }
351                _ => {
352                    return Err(Error::new(
353                        key.span(),
354                        "expected `factory = Type`, `send(...)`, `recv(...)`, or `required(...)`",
355                    ));
356                }
357            }
358            if input.peek(Token![,]) {
359                input.parse::<Token![,]>()?;
360            }
361        }
362        Ok(Self {
363            factory,
364            send: send.unwrap_or_default(),
365            recv: recv.unwrap_or_default(),
366            required: required.unwrap_or_default(),
367        })
368    }
369}
370
371struct GraphArgs {
372    entries: Vec<GraphEntry>,
373}
374
375struct GraphEntry {
376    field: SynIdent,
377    event: Path,
378    capacity: LitInt,
379    subscribers: LitInt,
380    waiters: LitInt,
381}
382
383impl Parse for GraphArgs {
384    fn parse(input: ParseStream<'_>) -> Result<Self> {
385        let mut entries = Vec::new();
386        while !input.is_empty() {
387            let field: SynIdent = input.parse()?;
388            input.parse::<Token![=]>()?;
389            let content;
390            parenthesized!(content in input);
391            let event: Path = content.parse()?;
392            content.parse::<Token![,]>()?;
393            let capacity: LitInt = content.parse()?;
394            let (subscribers, waiters) = if content.is_empty() {
395                (syn::parse_quote!(8), syn::parse_quote!(16))
396            } else {
397                if !content.peek(Token![,]) {
398                    return Err(content.error(
399                        "expected `(event, capacity)` or `(event, capacity, subscribers, waiters)`",
400                    ));
401                }
402                content.parse::<Token![,]>()?;
403                let subscribers: LitInt = content.parse()?;
404                content.parse::<Token![,]>()?;
405                let waiters: LitInt = content.parse()?;
406                if !content.is_empty() {
407                    return Err(content.error(
408                        "expected `(event, capacity)` or `(event, capacity, subscribers, waiters)`",
409                    ));
410                }
411                (subscribers, waiters)
412            };
413            entries.push(GraphEntry {
414                field,
415                event,
416                capacity,
417                subscribers,
418                waiters,
419            });
420            if input.peek(Token![,]) {
421                input.parse::<Token![,]>()?;
422            }
423        }
424        if entries.is_empty() {
425            return Err(input.error("graph must declare at least one event"));
426        }
427        Ok(Self { entries })
428    }
429}
430
431fn validate_graph(arguments: &GraphArgs, item: &ItemStruct) -> Result<()> {
432    if !item.generics.params.is_empty() {
433        return Err(Error::new_spanned(
434            &item.generics,
435            "graph declarations with generics are not supported",
436        ));
437    }
438    if !matches!(item.fields, Fields::Unit) {
439        return Err(Error::new_spanned(
440            &item.fields,
441            "graph declarations must be unit structs",
442        ));
443    }
444
445    let mut fields = std::collections::BTreeSet::new();
446    let mut events = std::collections::BTreeSet::new();
447    for entry in &arguments.entries {
448        if !fields.insert(entry.field.to_string()) {
449            return Err(Error::new_spanned(&entry.field, "graph field repeated"));
450        }
451        let event_name = entry.event.to_token_stream().to_string();
452        if !events.insert(event_name) {
453            return Err(Error::new_spanned(&entry.event, "graph event repeated"));
454        }
455    }
456    Ok(())
457}
458
459fn expand_graph(arguments: &GraphArgs, item: &ItemStruct) -> Result<TokenStream2> {
460    validate_graph(arguments, item)?;
461    let hiway = hiway_path()?;
462    let graph = &item.ident;
463    let visibility = &item.vis;
464    let attrs = &item.attrs;
465    let payload_bounds = arguments
466        .entries
467        .iter()
468        .map(|entry| {
469            let event = &entry.event;
470            quote!(<#event as #hiway::EventSpec>::Payload: ::core::marker::Copy)
471        })
472        .collect::<Vec<_>>();
473    let fields_definitions = arguments.entries.iter().map(|entry| {
474        let field = &entry.field;
475        let event = &entry.event;
476        let capacity = &entry.capacity;
477        let subscribers = &entry.subscribers;
478        let waiters = &entry.waiters;
479        quote! {
480            #field: #hiway::StaticFabric<'route, #event, #capacity, #subscribers, #waiters>
481        }
482    });
483    let constructor_parameters = arguments.entries.iter().map(|entry| {
484        let field = &entry.field;
485        let event = &entry.event;
486        let capacity = &entry.capacity;
487        let subscribers = &entry.subscribers;
488        let waiters = &entry.waiters;
489        quote! {
490            #field: &'route #hiway::StaticStream<#event, #capacity, #subscribers, #waiters>
491        }
492    });
493    let constructor_fields = arguments.entries.iter().map(|entry| {
494        let field = &entry.field;
495        quote! { #field: #hiway::StaticFabric::new(#field) }
496    });
497    let binding_impls = arguments
498        .entries
499        .iter()
500        .map(|entry| graph_binding(&hiway, graph, entry, &payload_bounds));
501
502    Ok(quote! {
503        #(#attrs)*
504        #visibility struct #graph<'route>
505        where
506            #(#payload_bounds,)*
507        {
508            #(#fields_definitions,)*
509        }
510
511        impl<'route> #graph<'route>
512        where
513            #(#payload_bounds,)*
514        {
515            #[must_use]
516            pub const fn new(
517                #(#constructor_parameters,)*
518            ) -> Self {
519                Self {
520                    #(#constructor_fields,)*
521                }
522            }
523
524            pub fn sender<S>(&self) -> ::core::result::Result<
525                <Self as #hiway::PortBinding<'route, S>>::Sender,
526                #hiway::TopicError,
527            >
528            where
529                S: #hiway::EventSpec,
530                Self: #hiway::PortBinding<'route, S>,
531            {
532                <Self as #hiway::PortBinding<'route, S>>::sender(self)
533            }
534
535            pub fn subscribe<S>(
536                &self,
537                role: #hiway::SubscriptionRole,
538            ) -> ::core::result::Result<
539                <Self as #hiway::PortBinding<'route, S>>::Receiver,
540                #hiway::TopicError,
541            >
542            where
543                S: #hiway::EventSpec,
544                Self: #hiway::PortBinding<'route, S>,
545            {
546                <Self as #hiway::PortBinding<'route, S>>::subscribe(self, role)
547            }
548        }
549
550        #(#binding_impls)*
551    })
552}
553
554fn graph_binding(
555    hiway: &TokenStream2,
556    graph: &Ident,
557    entry: &GraphEntry,
558    payload_bounds: &[TokenStream2],
559) -> TokenStream2 {
560    let field = &entry.field;
561    let event = &entry.event;
562    let capacity = &entry.capacity;
563    let subscribers = &entry.subscribers;
564    let waiters = &entry.waiters;
565    let binding = quote!(
566        <#hiway::StaticFabric<'route, #event, #capacity, #subscribers, #waiters>
567            as #hiway::PortBinding<'route, #event>>
568    );
569    quote! {
570        impl<'route> #hiway::PortBinding<'route, #event> for #graph<'route>
571        where
572            #(#payload_bounds,)*
573        {
574            type Sender = #binding::Sender;
575            type Receiver = #binding::Receiver;
576
577            fn sender(&self) -> ::core::result::Result<Self::Sender, #hiway::TopicError> {
578                #binding::sender(&self.#field)
579            }
580
581            fn subscribe(
582                &self,
583                role: #hiway::SubscriptionRole,
584            ) -> ::core::result::Result<Self::Receiver, #hiway::TopicError> {
585                #binding::subscribe(&self.#field, role)
586            }
587        }
588    }
589}
590
591// Keep endpoint selection and the corresponding binding expansion together.
592#[allow(clippy::too_many_lines)]
593fn expand_port(arguments: &PortArgs, item: &ItemStruct) -> Result<TokenStream2> {
594    if !item.generics.params.is_empty() || item.generics.where_clause.is_some() {
595        return Err(Error::new_spanned(
596            &item.generics,
597            "port declarations with generics or where clauses are not supported",
598        ));
599    }
600    if !matches!(item.fields, Fields::Unit) {
601        return Err(Error::new_spanned(
602            &item.fields,
603            "ports must be unit structs; application state belongs in the owning type",
604        ));
605    }
606
607    let factory = &arguments.factory;
608    let port = &item.ident;
609    let visibility = &item.vis;
610    let attrs = &item.attrs;
611    let send = capability_list(&arguments.send, "send")?;
612    let mut receive_paths = arguments.recv.clone();
613    receive_paths.extend(arguments.required.iter().cloned());
614    let recv = capability_list(&receive_paths, "receive")?;
615    let hiway = hiway_path()?;
616
617    let send_paths = &arguments.send;
618    let mut tokens: Vec<_> = quote!(#item #(#send_paths)* #(#receive_paths)* #hiway)
619        .into_iter()
620        .collect();
621    let mut names = std::collections::HashSet::new();
622    while let Some(token) = tokens.pop() {
623        match token {
624            proc_macro2::TokenTree::Group(group) => tokens.extend(group.stream()),
625            proc_macro2::TokenTree::Ident(ident) => {
626                names.insert(ident.to_string().trim_start_matches("r#").to_owned());
627            }
628            _ => {}
629        }
630    }
631    let fresh_ident = |mut name: String| {
632        while names.contains(&name) {
633            name.push('_');
634        }
635        format_ident!("{name}")
636    };
637    let inferred_factory = fresh_ident("__Factory".into());
638    let mut generics = syn::Generics::default();
639    let mut binding_bounds = Vec::new();
640    let mut sender_types = Vec::new();
641    let mut receiver_types = Vec::new();
642    for (capabilities, types, endpoint, bound) in [
643        (
644            &send,
645            &mut sender_types,
646            "Sender",
647            quote!(#hiway::EventSender),
648        ),
649        (
650            &recv,
651            &mut receiver_types,
652            "Receiver",
653            quote!(#hiway::EventReceiver),
654        ),
655    ] {
656        for (index, (event, _, _)) in capabilities.iter().enumerate() {
657            let associated = format_ident!("{endpoint}");
658            if let Some(factory) = factory {
659                types.push(quote!(<#factory as #hiway::OwnedPortBinding<#event>>::#associated));
660            } else {
661                let parameter = fresh_ident(format!("__{endpoint}{index}"));
662                generics
663                    .params
664                    .push(syn::parse_quote!(#parameter: #bound<#event>));
665                binding_bounds.push(quote!(
666                    #hiway::PortBinding<'__binding, #event, #associated = #parameter>
667                ));
668                types.push(quote!(#parameter));
669            }
670        }
671    }
672    let (impl_generics, type_generics, where_clause) = generics.split_for_impl();
673    let (bind_generics, factory_type, bind_where, sender_method, receiver_method) =
674        if let Some(factory) = factory {
675            (
676                quote!(),
677                quote!(#factory),
678                quote!(),
679                quote!(sender_owned),
680                quote!(subscribe_owned),
681            )
682        } else {
683            (
684                quote!(<'__binding, #inferred_factory: ?Sized>),
685                quote!(#inferred_factory),
686                quote!(where #inferred_factory: #(#binding_bounds +)*),
687                quote!(sender),
688                quote!(subscribe),
689            )
690        };
691    let binding = |event: &Path| {
692        if let Some(factory) = factory {
693            quote!(<#factory as #hiway::OwnedPortBinding<#event>>)
694        } else {
695            quote!(<#inferred_factory as #hiway::PortBinding<'__binding, #event>>)
696        }
697    };
698    let sender_fields = send.iter().zip(&sender_types).map(|((_, _, field), ty)| {
699        let field = format_ident!("__send_{field}");
700        quote!(#field: #ty)
701    });
702    let sender_initializers = send.iter().map(|(event, _, field)| {
703        let field = format_ident!("__send_{field}");
704        let binding = binding(event);
705        quote!(#field: #binding::#sender_method(factory)?)
706    });
707    let receiver_fields = recv.iter().zip(&receiver_types).map(|((_, _, field), ty)| {
708        let field = format_ident!("__recv_{field}");
709        quote!(#field: #ty)
710    });
711    let receiver_initializers = recv.iter().enumerate().map(|(index, (event, _, field))| {
712        let field = format_ident!("__recv_{field}");
713        let role = if index < arguments.recv.len() {
714            quote!(#hiway::SubscriptionRole::Observer)
715        } else {
716            quote!(#hiway::SubscriptionRole::Required)
717        };
718        let binding = binding(event);
719        quote!(#field: #binding::#receiver_method(factory, #role)?)
720    });
721
722    let event_impls = port_event_impls(
723        &hiway,
724        &generics,
725        port,
726        &send,
727        &recv,
728        &sender_types,
729        &receiver_types,
730    );
731    let named_methods = named_port_methods(&hiway, &send, &recv);
732    let generic_methods = generic_port_methods(&hiway);
733
734    Ok(quote! {
735        #(#attrs)*
736        #visibility struct #port #generics {
737            #(#sender_fields,)*
738            #(#receiver_fields,)*
739        }
740
741        impl #impl_generics #port #type_generics #where_clause {
742            pub fn bind #bind_generics(
743                factory: &#factory_type,
744            ) -> ::core::result::Result<Self, #hiway::PortError> #bind_where {
745                ::core::result::Result::Ok(Self {
746                    #(#sender_initializers,)*
747                    #(#receiver_initializers,)*
748                })
749            }
750
751            #generic_methods
752
753            #named_methods
754        }
755
756        #event_impls
757    })
758}
759
760fn port_event_impls(
761    hiway: &TokenStream2,
762    generics: &syn::Generics,
763    port: &Ident,
764    send: &[(Path, Ident, Ident)],
765    recv: &[(Path, Ident, Ident)],
766    sender_types: &[TokenStream2],
767    receiver_types: &[TokenStream2],
768) -> TokenStream2 {
769    let mut used_tokens = quote!(#generics #port #hiway #(#sender_types)* #(#receiver_types)*);
770    for (event, name, field) in send.iter().chain(recv) {
771        used_tokens.extend(quote!(#event #name #field));
772    }
773    let mut tokens: Vec<_> = used_tokens.into_iter().collect();
774    let mut names = std::collections::HashSet::new();
775    while let Some(token) = tokens.pop() {
776        match token {
777            proc_macro2::TokenTree::Group(group) => tokens.extend(group.stream()),
778            proc_macro2::TokenTree::Ident(ident) => {
779                names.insert(ident.to_string().trim_start_matches("r#").to_owned());
780            }
781            _ => {}
782        }
783    }
784    let fresh_ident = |mut name: String| {
785        while names.contains(&name) {
786            name.push('_');
787        }
788        format_ident!("{name}")
789    };
790    let (impl_generics, type_generics, where_clause) = generics.split_for_impl();
791    let port_impl =
792        quote!(impl #impl_generics #hiway::Port for #port #type_generics #where_clause {});
793    let publication_impls = send.iter().zip(sender_types).map(|((event, _, field), sender)| {
794        let sender_field = format_ident!("__send_{field}");
795        quote! {
796            impl #impl_generics #hiway::EventPort<#event> for #port #type_generics #where_clause {
797                type Sender = #sender;
798
799                fn event_sender(&self) -> &Self::Sender {
800                    &self.#sender_field
801                }
802            }
803        }
804    });
805    let receiver_impls = recv.iter().zip(receiver_types).map(|((event, _, field), receiver)| {
806        let receiver_field = format_ident!("__recv_{field}");
807        quote! {
808            impl #impl_generics #hiway::EventReceiver<#event> for #port #type_generics #where_clause {
809                type Value = <#receiver
810                    as #hiway::EventReceiver<#event>>::Value;
811
812                fn event_try_recv(&self) -> ::core::result::Result<
813                    ::core::option::Option<#hiway::StreamItem<Self::Value>>,
814                    #hiway::ReceiveError,
815                > {
816                    <#receiver
817                        as #hiway::EventReceiver<#event>>::event_try_recv(&self.#receiver_field)
818                }
819
820                fn event_recv_now(&self) -> ::core::result::Result<
821                    ::core::option::Option<#hiway::StreamItem<Self::Value>>,
822                    #hiway::ReceiveError,
823                > {
824                    <#receiver
825                        as #hiway::EventReceiver<#event>>::event_recv_now(&self.#receiver_field)
826                }
827
828                fn event_recv(
829                    &self,
830                ) -> impl ::core::future::Future<
831                    Output = ::core::result::Result<
832                        #hiway::StreamItem<Self::Value>,
833                        #hiway::ReceiveError,
834                    >,
835                > + '_ {
836                    <#receiver
837                        as #hiway::EventReceiver<#event>>::event_recv(&self.#receiver_field)
838                }
839            }
840        }
841    });
842    let send_receiver_impls =
843        recv.iter()
844            .zip(receiver_types)
845            .map(|((event, _, field), receiver)| {
846                send_receiver_impl(
847                    hiway,
848                    generics,
849                    port,
850                    event,
851                    field,
852                    receiver,
853                    &fresh_ident("__SendReceiver".to_owned()),
854                )
855            });
856
857    quote! {
858        #port_impl
859        #(#publication_impls)*
860        #(#receiver_impls)*
861        #(#send_receiver_impls)*
862    }
863}
864
865fn send_receiver_impl(
866    hiway: &TokenStream2,
867    generics: &syn::Generics,
868    port: &Ident,
869    event: &Path,
870    field: &Ident,
871    receiver: &TokenStream2,
872    parameter: &Ident,
873) -> TokenStream2 {
874    let receiver_field = format_ident!("__recv_{field}");
875    let receiver_parameter = syn::parse2::<proc_macro2::Ident>(receiver.clone())
876        .ok()
877        .filter(|ident| {
878            generics
879                .type_params()
880                .any(|parameter| parameter.ident == *ident)
881        });
882    let mut send_generics = generics.clone();
883    let send_receiver = if let Some(receiver_parameter) = receiver_parameter {
884        send_generics
885            .make_where_clause()
886            .predicates
887            .push(syn::parse_quote!(
888                #receiver_parameter: #hiway::SendEventReceiver<#event>
889            ));
890        quote!(#receiver_parameter)
891    } else {
892        send_generics.params.push(syn::parse_quote!(#parameter));
893        let receiver_path = match syn::parse2::<syn::TypePath>(receiver.clone()) {
894            Ok(receiver_path) => receiver_path,
895            Err(error) => return error.to_compile_error(),
896        };
897        let factory = match receiver_path.qself {
898            Some(qself) => qself.ty,
899            None => {
900                return syn::Error::new_spanned(receiver, "expected owned receiver projection")
901                    .to_compile_error()
902            }
903        };
904        let predicates = &mut send_generics.make_where_clause().predicates;
905        predicates.push(syn::parse_quote!(
906            #factory: #hiway::OwnedPortBinding<#event, Receiver = #parameter>
907        ));
908        predicates.push(syn::parse_quote!(
909            #parameter: #hiway::SendEventReceiver<#event> + 'static
910        ));
911        quote!(#parameter)
912    };
913    let (_, type_generics, _) = generics.split_for_impl();
914    let (send_impl_generics, _, send_where_clause) = send_generics.split_for_impl();
915    quote! {
916        impl #send_impl_generics #hiway::SendEventReceiver<#event>
917            for #port #type_generics #send_where_clause
918        {
919            fn event_recv_future(
920                &self,
921            ) -> impl ::core::future::Future<
922                Output = ::core::result::Result<
923                    #hiway::StreamItem<
924                        <Self as #hiway::EventReceiver<#event>>::Value,
925                    >,
926                    #hiway::ReceiveError,
927                >,
928            > + ::core::marker::Send {
929                <#send_receiver as #hiway::SendEventReceiver<#event>>::event_recv_future(
930                    &self.#receiver_field,
931                )
932            }
933        }
934    }
935}
936
937fn named_port_methods(
938    hiway: &TokenStream2,
939    send: &[(Path, Ident, Ident)],
940    recv: &[(Path, Ident, Ident)],
941) -> TokenStream2 {
942    let named_publish_methods = send.iter().map(|(event, _, field)| {
943        let publish = format_ident!("publish_{field}");
944        let publish_now = format_ident!("publish_now_{field}");
945        quote! {
946            pub async fn #publish(
947                &self,
948                payload: <#event as #hiway::EventSpec>::Payload,
949            ) -> ::core::result::Result<
950                (),
951                #hiway::SendError<<#event as #hiway::EventSpec>::Payload>,
952            > {
953                <Self as #hiway::PortExt>::publish::<#event>(
954                    self,
955                    #hiway::EventValue::new(payload),
956                ).await
957            }
958
959            pub fn #publish_now(
960                &self,
961                payload: <#event as #hiway::EventSpec>::Payload,
962            ) -> ::core::result::Result<
963                (),
964                #hiway::TrySendError<<#event as #hiway::EventSpec>::Payload>,
965            > {
966                <Self as #hiway::PortExt>::publish_now::<#event>(
967                    self,
968                    #hiway::EventValue::new(payload),
969                )
970            }
971        }
972    });
973    let named_receive_methods = recv.iter().map(|(event, _, field)| {
974        let recv = format_ident!("recv_{field}");
975        let recv_now = format_ident!("recv_now_{field}");
976        quote! {
977            pub fn #recv(
978                &self,
979            ) -> impl ::core::future::Future<
980                    Output = ::core::result::Result<
981                        #hiway::StreamItem<<Self as #hiway::EventReceiver<#event>>::Value>,
982                        #hiway::ReceiveError,
983                >,
984            > + '_ {
985                <Self as #hiway::EventReceiver<#event>>::event_recv(self)
986            }
987
988            pub fn #recv_now(
989                &self,
990            ) -> ::core::result::Result<
991                ::core::option::Option<
992                    #hiway::StreamItem<<Self as #hiway::EventReceiver<#event>>::Value>,
993                >,
994                #hiway::ReceiveError,
995            > {
996                <Self as #hiway::EventReceiver<#event>>::event_recv_now(self)
997            }
998        }
999    });
1000
1001    quote! {
1002        #(#named_publish_methods)*
1003        #(#named_receive_methods)*
1004    }
1005}
1006
1007fn generic_port_methods(hiway: &TokenStream2) -> TokenStream2 {
1008    quote! {
1009        pub fn prepare<E>(&self, value: #hiway::EventValue<E>)
1010            -> ::core::result::Result<
1011                #hiway::PortPreparation<'_, Self, E>,
1012                #hiway::TrySendError<E::Payload>,
1013            >
1014        where E: #hiway::EventSpec, Self: #hiway::EventPort<E> {
1015            <Self as #hiway::PortExt>::prepare(self, value)
1016        }
1017
1018        pub fn try_recv<E>(&self) -> ::core::result::Result<
1019            ::core::option::Option<#hiway::StreamItem<<Self as #hiway::EventReceiver<E>>::Value>>,
1020            #hiway::ReceiveError,
1021        >
1022        where E: #hiway::EventSpec, Self: #hiway::EventReceiver<E> {
1023            <Self as #hiway::PortExt>::try_recv::<E>(self)
1024        }
1025
1026        pub async fn publish<E>(
1027            &self,
1028            value: #hiway::EventValue<E>,
1029        ) -> ::core::result::Result<(), #hiway::SendError<E::Payload>>
1030        where
1031            E: #hiway::EventSpec,
1032            Self: #hiway::EventPort<E>,
1033        {
1034            <Self as #hiway::PortExt>::publish(self, value).await
1035        }
1036
1037        pub fn publish_now<E>(
1038            &self,
1039            value: #hiway::EventValue<E>,
1040        ) -> ::core::result::Result<(), #hiway::TrySendError<E::Payload>>
1041        where
1042            E: #hiway::EventSpec,
1043            Self: #hiway::EventPort<E>,
1044        {
1045            <Self as #hiway::PortExt>::publish_now(self, value)
1046        }
1047
1048        pub async fn recv<E>(
1049            &self,
1050        ) -> ::core::result::Result<
1051            #hiway::StreamItem<<Self as #hiway::EventReceiver<E>>::Value>,
1052            #hiway::ReceiveError,
1053        >
1054        where
1055            E: #hiway::EventSpec,
1056            Self: #hiway::EventReceiver<E>,
1057        {
1058            <Self as #hiway::PortExt>::recv::<E>(self).await
1059        }
1060
1061        pub fn recv_now<E>(
1062            &self,
1063        ) -> ::core::result::Result<
1064            ::core::option::Option<
1065                #hiway::StreamItem<<Self as #hiway::EventReceiver<E>>::Value>,
1066            >,
1067            #hiway::ReceiveError,
1068        >
1069        where
1070            E: #hiway::EventSpec,
1071            Self: #hiway::EventReceiver<E>,
1072        {
1073            <Self as #hiway::PortExt>::recv_now::<E>(self)
1074        }
1075    }
1076}
1077
1078fn capability_list(paths: &[Path], label: &str) -> Result<Vec<(Path, Ident, Ident)>> {
1079    let mut names = std::collections::BTreeSet::new();
1080    let mut capabilities = Vec::with_capacity(paths.len());
1081    for path in paths {
1082        let Some(segment) = path.segments.last() else {
1083            return Err(Error::new_spanned(
1084                path,
1085                "event specification path is empty",
1086            ));
1087        };
1088        let variant = segment.ident.clone();
1089        if !names.insert(variant.to_string()) {
1090            return Err(Error::new_spanned(
1091                path,
1092                format!("duplicate {label} event `{variant}`"),
1093            ));
1094        }
1095        let field = format_ident!("{}", snake_case(&variant.to_string()));
1096        capabilities.push((path.clone(), variant, field));
1097    }
1098    Ok(capabilities)
1099}
1100
1101fn snake_case(name: &str) -> String {
1102    let mut output = String::with_capacity(name.len() + 4);
1103    let characters = name.chars().collect::<Vec<_>>();
1104    for (index, character) in characters.iter().copied().enumerate() {
1105        let previous_is_lowercase = index
1106            .checked_sub(1)
1107            .and_then(|previous| characters.get(previous))
1108            .is_some_and(|previous| previous.is_lowercase() || previous.is_ascii_digit());
1109        let next_is_lowercase = characters
1110            .get(index + 1)
1111            .is_some_and(|next| next.is_lowercase());
1112        if character.is_uppercase() && index != 0 && (previous_is_lowercase || next_is_lowercase) {
1113            output.push('_');
1114        }
1115        output.extend(character.to_lowercase());
1116    }
1117    output
1118}
1119
1120fn hiway_path() -> Result<TokenStream2> {
1121    match crate_name("hiway") {
1122        Ok(FoundCrate::Itself) => Ok(quote!(::hiway)),
1123        Ok(FoundCrate::Name(name)) => {
1124            let ident = Ident::new(&name, Span::call_site());
1125            Ok(quote!(::#ident))
1126        }
1127        Err(error) => Err(Error::new(
1128            Span::call_site(),
1129            format!("hiway macro could not locate the hiway dependency: {error}"),
1130        )),
1131    }
1132}
1133
1134#[cfg(test)]
1135mod tests {
1136    use super::*;
1137
1138    #[test]
1139    fn event_and_port_arguments_reject_removed_contracts() {
1140        let namespace = syn::parse_str::<EventsArgs>(r#"namespace = "legacy""#)
1141            .err()
1142            .expect("namespace must be rejected");
1143        assert!(namespace.to_string().contains("unknown event declaration"));
1144
1145        let inferred = syn::parse_str::<PortArgs>("send(events::Started)").unwrap();
1146        assert!(inferred.factory.is_none());
1147
1148        let removed_flag = syn::parse_str::<PortArgs>("factory = Bus, no_std")
1149            .err()
1150            .expect("removed flag must be rejected");
1151        assert!(removed_flag.to_string().contains("expected"));
1152
1153        let capacity = syn::parse_str::<PortArgs>("factory = Bus, capacity = 8")
1154            .err()
1155            .expect("subscriber capacity must be rejected");
1156        assert_eq!(capacity.to_string(), "stream capacity belongs to owner");
1157    }
1158
1159    #[test]
1160    fn port_arguments_distinguish_observers_and_required_receivers() {
1161        let arguments = syn::parse_str::<PortArgs>(
1162            "factory = Bus, send(events::Started), recv(events::Changed), required(events::Stopped)",
1163        ).unwrap();
1164        assert_eq!(arguments.send.len(), 1);
1165        assert_eq!(arguments.send[0].segments.last().unwrap().ident, "Started");
1166        assert_eq!(arguments.recv.len(), 1);
1167        assert_eq!(arguments.recv[0].segments.last().unwrap().ident, "Changed");
1168        assert_eq!(arguments.required.len(), 1);
1169        assert_eq!(
1170            arguments.required[0].segments.last().unwrap().ident,
1171            "Stopped"
1172        );
1173
1174        let repeated = syn::parse_str::<PortArgs>("factory = Bus, required(A), required(B)")
1175            .err()
1176            .expect("required group cannot be repeated");
1177        assert_eq!(repeated.to_string(), "port capability group repeated");
1178    }
1179
1180    #[test]
1181    fn port_rejects_receiving_one_event_in_both_roles() {
1182        let arguments = syn::parse_str::<PortArgs>(
1183            "factory = Bus, recv(events::Changed), required(events::Changed)",
1184        )
1185        .unwrap();
1186        let item = syn::parse_str::<ItemStruct>("struct Receiver;").unwrap();
1187        assert_eq!(
1188            expand_port(&arguments, &item).unwrap_err().to_string(),
1189            "duplicate receive event `Changed`",
1190        );
1191    }
1192
1193    #[test]
1194    fn port_rejects_generic_and_stateful_declarations() {
1195        let arguments = syn::parse_str::<PortArgs>("factory = Bus").unwrap();
1196        let generic = syn::parse_str::<ItemStruct>("struct PlayerPort<T>;").unwrap();
1197        assert!(expand_port(&arguments, &generic)
1198            .unwrap_err()
1199            .to_string()
1200            .contains("generics"));
1201
1202        let stateful = syn::parse_str::<ItemStruct>("struct Player { health: u8 }").unwrap();
1203        assert!(expand_port(&arguments, &stateful)
1204            .unwrap_err()
1205            .to_string()
1206            .contains("application state"));
1207    }
1208
1209    #[test]
1210    fn marker_modules_use_rust_snake_case() {
1211        assert_eq!(snake_case("GameEvents"), "game_events");
1212        assert_eq!(snake_case("HTTPEvents"), "http_events");
1213    }
1214}