feat(xmtp_macro): #[derive(Retryable)] proc macro for RetryableError

[insipx]

Summary

Adds a #[derive(Retryable)] proc macro that generates impl xmtp_common::RetryableError, replacing the hand-written per-enum boilerplate (satisfies the long-standing TODO in retry.rs). Mirrors the existing #[derive(ErrorCode)] macro: same crate (xmtp_macro), same re-export path (xmtp_common::Retryable), same spanned-error discipline.

Variant rules (first match wins)

Attribute	Generated arm
#[retry(when = EXPR)]	run EXPR with referenced fields bound (this / names / this0..)
#[retry(false)] / #[retry(true)] / bare #[retry]	constant
#[retry(inherit)]	forward to single inner field's is_retryable()
anything else	container `#[retry(default = true

#[from] carries no retry semantics — forwarding is always explicit via #[retry(inherit)]. A workspace census found 98 #[from] variants whose hand-written behavior was a hardcoded true/false (foreign inner types like prost/http/derive_builder) vs only 33 that forward; auto-forwarding (tried first) forced a noisy #[retry(false)] on the 3×-more-common case and made unannotated variants non-local to read. With explicit inherit, an unannotated variant is always the baseline.

Other properties:

• when binds only the fields the expression references (token scan) — no unused_variables under -D warnings.
• Generic types supported (split_for_impl); empty enums emit match *self {}; structs supported (when over self).
• Container misuse (e.g. #[retry(true)] on an enum) is a spanned compile error, not a silent no-op.

Testing

• 18 behavior tests in xmtp_common::retry::derive_tests covering every rule incl. generics, subset-when, empty enum, bare-#[from]-takes-baseline, default = true over #[from].
• 8 trybuild UI fixtures pinning each spanned compile_error path (crates/xmtp_macro/tests/ui/retryable/).
• cargo clippy --locked --all-features --all-targets -Dwarnings clean on touched crates; fmt clean; hakari no-op.

Migration of existing hand-written impls is stacked on top: #3754.

🤖 Generated with Claude Code

Note

Add #[derive(Retryable)] proc macro for RetryableError in xmtp_macro

• Adds a new Retryable derive macro in xmtp_macro/src/retryable.rs that generates xmtp_common::RetryableError implementations via is_retryable(&self).
• Supports per-variant and container-level #[retry] attributes: #[retry(true|false)], #[retry(inherit)] (forwards to a single field), #[retry(when = expr)], and #[retry(default = ...)] on enum containers.
• Re-exports Retryable from xmtp_common so consumers can import it as xmtp_common::Retryable.
• Adds compile-fail UI tests via trybuild covering invalid attribute combinations (conflicting keys, wrong placement, unknown keys, arity errors, union types).
• Updates nix/lib/filesets.nix to include tests/ui so trybuild .stderr snapshots are available in hermetic Nix builds.

^{Macroscope summarized 8a5996e.}

[claude]

Claude finished @insipx's task —— View job

---

Code Review - June 10, 2026 17:13 UTC

Todo List:

• Read test files and analyze coverage
• Review macro implementation for issues not already addressed
• Provide concise feedback

---

Review Summary

The #[derive(Retryable)] proc macro implementation is well-designed and production-ready. All previously identified issues (duplicate attributes, empty parens, container misuse, #[from] semantics) have been addressed with proper spanned compile errors.

Strengths:

• Comprehensive test coverage: 18 behavior tests + 8 trybuild UI fixtures covering all decision paths, edge cases (empty enum, generics, subset-field binding), and error conditions
• Robust error handling: All invalid attribute combinations produce clear, spanned diagnostics
• Clean implementation: Proper separation of parsing (RetryAttr::parse) and code generation (variant_arm, when_arm, forward_arm)
• No unsafe patterns: All unwrap() calls are justified by prior guards (e.g., f.named.len() == 1 at line 307)

Code quality notes:

• The token scanning in collect_idents (line 324) intentionally over-approximates references (e.g., identifiers in nested macros) — acceptable tradeoff since it only costs extra bindings, never misses
• The when expression binding strategy (lines 345-374) correctly avoids -D warnings by binding only referenced fields

No actionable issues found beyond what was already addressed in previous review rounds.

---

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces a substantial new proc macro (~375 lines) with multiple parsing paths and code generation logic. While well-tested and compile-time only, new feature components of this scope warrant human review to verify the macro's design and generated code correctness.

^{You can customize Macroscope's approvability policy. Learn more.}

[insipx]

CI analysis of the test-workspace failure (both PRs):

1. retryable_compile_fail (trybuild) — the hermetic nix build filters crate sources through commonCargoSources (.rs + Cargo.toml only), so the committed .stderr snapshots never reached CI; trybuild regenerated all 10 and failed by design. Fixed in 4701e13 by adding crates/xmtp_macro/tests/ui to the fileset one-offs (same pattern as xmtp_db/migrations).
2. client::tests::should_reconnect — pre-existing flake, not from this stack: the identical test fails on a recent main run (evidence), the failing path (ApiClientError::ClientWithEndpoint → tonic Cancelled during toxiproxy churn) was never migrated (ApiClientError is in the keep-hand-written list), and the unwrap is in test code racing a 500ms sleep.

Dismissing prior approval to re-evaluate 4701e13

[codecov]

Codecov Report

❌ Patch coverage is 95.49839% with 14 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.48%. Comparing base (b5cdc06) to head (4701e13).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
crates/xmtp_macro/src/retryable.rs	94.27%	13 Missing ⚠️
crates/xmtp_macro/src/lib.rs	75.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3753      +/-   ##
==========================================
+ Coverage   84.44%   84.48%   +0.03%     
==========================================
  Files         409      409              
  Lines       59606    60082     +476     
==========================================
+ Hits        50335    50761     +426     
- Misses       9271     9321      +50     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.