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#[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#[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}