Add GenServer v2 with Message trait for typed actors

Introduce a new GenServer v2 implementation with:
- `&mut self` style handlers (struct IS the process state)
- Typed message handlers via `Call<M>`, `Cast<M>`, `Info<M>` traits
- Clean result types: `Init`, `Reply`, `Status`
- `Message` trait with `encode_local`/`encode_remote` for typed serialization
- `#[derive(Message)]` macro for automatic message encoding/decoding

The Message trait provides self-describing messages with tag prefixes for
type discrimination when receiving raw bytes. Local encoding uses postcard
with a tag prefix, while remote encoding is prepared for ETF (BEAM interop).

Also includes:
- ETF helper module for Erlang Term Format integration
- Clippy warning fixes across the codebase

Author: scrogson

crates/ambitious-macros/src/lib.rs

@@ -48,7 +48,7 @@ extern crate proc_macro;
 
 use proc_macro::TokenStream;
 use quote::quote;
-use syn::{DeriveInput, ItemFn, parse_macro_input};
+use syn::{Data, DeriveInput, Fields, ItemFn, parse_macro_input};
 
 /// Derive macro for GenServer implementation helpers.
 ///
@@ -229,3 +229,172 @@ pub fn test(_attr: TokenStream, item: TokenStream) -> TokenStream {
 
     TokenStream::from(expanded)
 }
+
+/// Derive macro for implementing the Message trait.
+///
+/// This generates implementations for `encode_local`, `decode_local`,
+/// `encode_remote`, and `decode_remote` with automatic type tagging.
+///
+/// # Supported Types
+///
+/// - Unit structs: `struct Ping;`
+/// - Newtype structs: `struct Add(i64);`
+/// - Structs with named fields: `struct Login { user: String, pass: String }`
+///
+/// # Attributes
+///
+/// - `#[message(tag = "custom")]` - Override the default tag (type name)
+///
+/// # Example
+///
+/// ```ignore
+/// use ambitious::Message;
+///
+/// #[derive(Message)]
+/// struct Get;
+///
+/// #[derive(Message)]
+/// #[message(tag = "increment")]
+/// struct Inc;
+///
+/// #[derive(Message)]
+/// struct Add(i64);
+///
+/// #[derive(Message)]
+/// struct SetUser {
+///     name: String,
+///     age: u32,
+/// }
+/// ```
+#[proc_macro_derive(Message, attributes(message))]
+pub fn derive_message(input: TokenStream) -> TokenStream {
+    let input = parse_macro_input!(input as DeriveInput);
+    let name = &input.ident;
+
+    // Check for custom tag attribute
+    let tag = get_message_tag(&input).unwrap_or_else(|| name.to_string());
+
+    // Generate different code based on struct variant
+    let (encode_body, decode_body) = match &input.data {
+        Data::Struct(data) => match &data.fields {
+            Fields::Unit => {
+                // Unit struct: struct Ping;
+                (
+                    quote! {
+                        ::ambitious::message::encode_with_tag(Self::tag(), &[])
+                    },
+                    quote! {
+                        let _ = bytes;
+                        Ok(Self)
+                    },
+                )
+            }
+            Fields::Unnamed(fields) if fields.unnamed.len() == 1 => {
+                // Newtype struct: struct Add(i64);
+                (
+                    quote! {
+                        let payload = ::ambitious::message::encode_payload(&self.0);
+                        ::ambitious::message::encode_with_tag(Self::tag(), &payload)
+                    },
+                    quote! {
+                        let inner = ::ambitious::message::decode_payload(bytes)?;
+                        Ok(Self(inner))
+                    },
+                )
+            }
+            Fields::Unnamed(_) => {
+                // Multi-field tuple struct not supported yet
+                return syn::Error::new_spanned(
+                    input,
+                    "Message derive only supports unit structs, newtype structs (single field), and named structs",
+                )
+                .to_compile_error()
+                .into();
+            }
+            Fields::Named(fields) => {
+                // Named struct: struct Login { user: String }
+                let field_names: Vec<_> = fields.named.iter().map(|f| &f.ident).collect();
+
+                (
+                    quote! {
+                        let payload = ::ambitious::message::encode_payload(&(#(&self.#field_names),*));
+                        ::ambitious::message::encode_with_tag(Self::tag(), &payload)
+                    },
+                    quote! {
+                        let (#(#field_names),*) = ::ambitious::message::decode_payload(bytes)?;
+                        Ok(Self { #(#field_names),* })
+                    },
+                )
+            }
+        },
+        Data::Enum(_) => {
+            return syn::Error::new_spanned(
+                input,
+                "Message derive does not support enums yet. Use separate structs for each message type.",
+            )
+            .to_compile_error()
+            .into();
+        }
+        Data::Union(_) => {
+            return syn::Error::new_spanned(input, "Message derive does not support unions")
+                .to_compile_error()
+                .into();
+        }
+    };
+
+    let expanded = quote! {
+        impl ::ambitious::message::Message for #name {
+            fn tag() -> &'static str {
+                #tag
+            }
+
+            fn encode_local(&self) -> Vec<u8> {
+                #encode_body
+            }
+
+            fn decode_local(bytes: &[u8]) -> Result<Self, ::ambitious::core::DecodeError> {
+                #decode_body
+            }
+
+            fn encode_remote(&self) -> Vec<u8> {
+                // For now, use same encoding as local
+                // TODO: Implement ETF encoding
+                self.encode_local()
+            }
+
+            fn decode_remote(bytes: &[u8]) -> Result<Self, ::ambitious::core::DecodeError> {
+                // For now, use same decoding as local
+                // TODO: Implement ETF decoding
+                Self::decode_local(bytes)
+            }
+        }
+    };
+
+    TokenStream::from(expanded)
+}
+
+/// Extract custom tag from #[message(tag = "...")] attribute
+fn get_message_tag(input: &DeriveInput) -> Option<String> {
+    for attr in &input.attrs {
+        if attr.path().is_ident("message")
+            && let Ok(meta) = attr.meta.require_list()
+        {
+            let tokens = meta.tokens.to_string();
+            // Simple parsing: look for tag = "value"
+            if let Some(start) = tokens.find("tag") {
+                let rest = &tokens[start..];
+                if let Some(eq_pos) = rest.find('=') {
+                    let after_eq = &rest[eq_pos + 1..].trim();
+                    // Extract string value between quotes
+                    if let Some(quote_start) = after_eq.find('"') {
+                        let after_quote = &after_eq[quote_start + 1..];
+                        if let Some(quote_end) = after_quote.find('"') {
+                            return Some(after_quote[..quote_end].to_string());
+                        }
+                    }
+                }
+            }
+        }
+    }
+    None
+}

crates/ambitious-macros/tests/derive_test.rs

@@ -1,6 +1,7 @@
 //! Integration tests for ambitious-macros.
 
-use ambitious_macros::{GenServerImpl, ambitious_process};
+use ambitious::message::{Message, decode_tag};
+use ambitious_macros::{GenServerImpl, Message as DeriveMessage, ambitious_process};
 
 #[derive(GenServerImpl)]
 struct TestServer {
@@ -24,3 +25,76 @@ fn test_ambitious_process_attribute() {
     // The attribute should not change the function signature
     // This test passes if it compiles
 }
+
+// =========================================================================
+// Message derive macro tests
+// =========================================================================
+
+// Unit struct with derive
+#[derive(DeriveMessage)]
+struct Ping;
+
+#[test]
+fn test_derive_unit_struct() {
+    let msg = Ping;
+    let bytes = msg.encode_local();
+
+    let (tag, payload) = decode_tag(&bytes).unwrap();
+    assert_eq!(tag, "Ping");
+    assert!(payload.is_empty());
+
+    let _decoded = Ping::decode_local(payload).unwrap();
+}
+
+// Newtype struct with derive
+#[derive(DeriveMessage)]
+struct Add(i64);
+
+#[test]
+fn test_derive_newtype_struct() {
+    let msg = Add(42);
+    let bytes = msg.encode_local();
+
+    let (tag, payload) = decode_tag(&bytes).unwrap();
+    assert_eq!(tag, "Add");
+
+    let decoded = Add::decode_local(payload).unwrap();
+    assert_eq!(decoded.0, 42);
+}
+
+// Named struct with derive
+#[derive(DeriveMessage, Debug, PartialEq)]
+struct Login {
+    username: String,
+    password: String,
+}
+
+#[test]
+fn test_derive_named_struct() {
+    let msg = Login {
+        username: "alice".to_string(),
+        password: "secret".to_string(),
+    };
+    let bytes = msg.encode_local();
+
+    let (tag, payload) = decode_tag(&bytes).unwrap();
+    assert_eq!(tag, "Login");
+
+    let decoded = Login::decode_local(payload).unwrap();
+    assert_eq!(decoded.username, "alice");
+    assert_eq!(decoded.password, "secret");
+}
+
+// Custom tag
+#[derive(DeriveMessage)]
+#[message(tag = "increment")]
+struct Inc;
+
+#[test]
+fn test_derive_custom_tag() {
+    let msg = Inc;
+    let bytes = msg.encode_local();
+
+    let (tag, _) = decode_tag(&bytes).unwrap();
+    assert_eq!(tag, "increment");
+}

crates/ambitious/Cargo.toml

@@ -36,6 +36,8 @@ hostname = "0.4"
 tokio-tungstenite = { version = "0.28", optional = true }
 serde_json = { version = "1", optional = true }
 futures = { version = "0.3", optional = true }
+erltf = "0.14.0"
+erltf_serde = "0.14.0"
 
 [features]
 default = []