docs: API alternatives design documents by ElFantasma · Pull Request #154 · lambdaclass/spawned

ElFantasma · 2026-02-20T01:11:20Z

Summary

Design decision records documenting the API redesign process that led to Approach B (#[protocol] + #[actor] macros).

docs/design/API_REDESIGN.md — initial v0.5 redesign plan: Handler, Recipient, object-safe Receiver pattern, supervision trait sketches (from docs: add API redesign plan for v0.5 #147)
docs/design/API_ALTERNATIVES_SUMMARY.md — comprehensive comparison of 6 API approaches (A–F) with full chat room example code, analysis tables, and comparison matrix
docs/design/API_ALTERNATIVES_QUICK_REFERENCE.md — condensed version with the same structure, plus old API baseline example
Outcome: Approach B was chosen and implemented in PR feat: #[protocol] + #[actor] macros, Handler<M>, registry (0.5.0) #153

These docs are kept as architectural decision records for future reference (blog post, onboarding contributors).

Supersedes #147 and #150.

Test plan

Document renders correctly in GitHub markdown
Internal cross-references between docs work
Branch links point to correct branches

github-actions · 2026-02-20T01:11:38Z

🤖 Kimi Code Review

This is a documentation-only PR that summarizes API design alternatives. As such, there's no code to review for correctness, safety, or performance issues.

The document is well-structured and provides a comprehensive comparison of the different approaches. The examples are clear and the trade-offs are well-explained.

One minor suggestion: The "Status" column in the comparison matrix shows Approach B as "WIP" but the document states it's "Fully implemented" - this should be updated for consistency.

Automated review by Kimi (Moonshot AI) · custom prompt

github-actions · 2026-02-20T01:12:13Z

🤖 Codex Code Review

I checked the diff: it only adds docs/API_ALTERNATIVES_SUMMARY.md and makes no code changes. There are no correctness, concurrency, lifecycle, or performance implications to review in this PR.

If you want doc feedback, I can do a content/clarity pass with line references, but there’s no code-level review to perform here.

Automated review by OpenAI Codex · custom prompt

greptile-apps · 2026-02-20T01:13:25Z

Greptile Summary

Adds comprehensive API alternatives comparison document for the actor framework redesign. The document compares 6 different approaches (A-F) with the same chat room example, including full code samples, analysis tables, and trade-off discussions. All branch references have been verified and point to the correct branches (feat/approach-a, feat/approach-b, etc.). The document is well-structured with 1201 lines covering functional, code quality, and strategic dimensions of each approach.

Key sections:

Detailed explanations of the two core problems (Improve type safety for request/reply message handling #144: type safety, Circular dependency problem with bidirectional actor communication #145: circular dependencies)
Side-by-side code examples for each approach using the chat room scenario
Analysis tables comparing readability, expressivity, and API design
Comprehensive comparison matrix across functional, code quality, and strategic dimensions
Recommendation section favoring Approach A with Approach B as a strong alternative
Branch reference table mapping all feature branches

Confidence Score: 5/5

This PR is safe to merge with minimal risk - it only adds documentation
Documentation-only change with no code modifications. All branch references verified to exist. Single minor style issue (missing TOC entry) that doesn't affect functionality. The document is comprehensive, well-structured, and provides valuable technical comparison for API design decisions.
No files require special attention

Important Files Changed

Filename	Overview
docs/API_ALTERNATIVES_SUMMARY.md	New comprehensive API comparison document with 6 approaches, code examples, and analysis tables - well-structured and informative

_{Last reviewed commit: 7a92097}

greptile-apps

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps · 2026-02-20T01:13:30Z

docs/design/API_ALTERNATIVES_SUMMARY.md

+## Table of Contents
+
+- [The Two Problems](#the-two-problems)
+- [The Chat Room Example](#the-chat-room-example)
+- [Baseline: The Old API](#baseline-the-old-api-whats-on-main-today)
+- [Approach A: Handler\<M\> + Recipient\<M\>](#approach-a-handlerm--recipientm-actix-style)
+- [Approach B: Protocol Traits](#approach-b-protocol-traits-user-defined-contracts)
+- [Approach C: Typed Wrappers](#approach-c-typed-wrappers-non-breaking)
+- [Approach D: Derive Macro](#approach-d-derive-macro)
+- [Approach E: AnyActorRef](#approach-e-anyactorref-fully-type-erased)
+- [Approach F: PID Addressing](#approach-f-pid-addressing-erlang-style)
+- [Registry & Service Discovery](#registry--service-discovery)
+- [Macro Improvement Potential](#macro-improvement-potential)
+- [Comparison Matrix](#comparison-matrix)
+- [Recommendation](#recommendation)
+- [Branch Reference](#branch-reference)


Table of Contents is missing Detailed Design Documents section that exists at line 1198

Suggested change

## Table of Contents

- [The Two Problems](#the-two-problems)

- [The Chat Room Example](#the-chat-room-example)

- [Baseline: The Old API](#baseline-the-old-api-whats-on-main-today)

- [Approach A: Handler\<M\> + Recipient\<M\>](#approach-a-handlerm--recipientm-actix-style)

- [Approach B: Protocol Traits](#approach-b-protocol-traits-user-defined-contracts)

- [Approach C: Typed Wrappers](#approach-c-typed-wrappers-non-breaking)

- [Approach D: Derive Macro](#approach-d-derive-macro)

- [Approach E: AnyActorRef](#approach-e-anyactorref-fully-type-erased)

- [Approach F: PID Addressing](#approach-f-pid-addressing-erlang-style)

- [Registry & Service Discovery](#registry--service-discovery)

- [Macro Improvement Potential](#macro-improvement-potential)

- [Comparison Matrix](#comparison-matrix)

- [Recommendation](#recommendation)

- [Branch Reference](#branch-reference)

- [The Two Problems](#the-two-problems)

- [The Chat Room Example](#the-chat-room-example)

- [Baseline: The Old API](#baseline-the-old-api-whats-on-main-today)

- [Approach A: Handler\<M\> + Recipient\<M\>](#approach-a-handlerm--recipientm-actix-style)

- [Approach B: Protocol Traits](#approach-b-protocol-traits-user-defined-contracts)

- [Approach C: Typed Wrappers](#approach-c-typed-wrappers-non-breaking)

- [Approach D: Derive Macro](#approach-d-derive-macro)

- [Approach E: AnyActorRef](#approach-e-anyactorref-fully-type-erased)

- [Approach F: PID Addressing](#approach-f-pid-addressing-erlang-style)

- [Registry & Service Discovery](#registry--service-discovery)

- [Macro Improvement Potential](#macro-improvement-potential)

- [Comparison Matrix](#comparison-matrix)

- [Recommendation](#recommendation)

- [Branch Reference](#branch-reference)

- [Detailed Design Documents](#detailed-design-documents)

Prompt To Fix With AI

This is a comment left during a code review. Path: docs/API_ALTERNATIVES_SUMMARY.md Line: 5-20 Comment: Table of Contents is missing `Detailed Design Documents` section that exists at line 1198 ```suggestion - [The Two Problems](#the-two-problems) - [The Chat Room Example](#the-chat-room-example) - [Baseline: The Old API](#baseline-the-old-api-whats-on-main-today) - [Approach A: Handler\<M\> + Recipient\<M\>](#approach-a-handlerm--recipientm-actix-style) - [Approach B: Protocol Traits](#approach-b-protocol-traits-user-defined-contracts) - [Approach C: Typed Wrappers](#approach-c-typed-wrappers-non-breaking) - [Approach D: Derive Macro](#approach-d-derive-macro) - [Approach E: AnyActorRef](#approach-e-anyactorref-fully-type-erased) - [Approach F: PID Addressing](#approach-f-pid-addressing-erlang-style) - [Registry & Service Discovery](#registry--service-discovery) - [Macro Improvement Potential](#macro-improvement-potential) - [Comparison Matrix](#comparison-matrix) - [Recommendation](#recommendation) - [Branch Reference](#branch-reference) - [Detailed Design Documents](#detailed-design-documents) ``` How can I resolve this? If you propose a fix, please make it concise.

…ller API

…code

…separation)

… Approach B

…ter() in main.rs

docs: add API alternatives comparison doc with updated branch references

7a92097

greptile-apps bot reviewed Feb 20, 2026

View reviewed changes

ElFantasma added 16 commits February 20, 2026 12:45

docs: update Approach B examples to match protocol_impl! + aligned ca…

02c5c0d

…ller API

docs: move Deliver to user.rs in Approach A examples to match actual …

3ef90e4

…code

docs: add cross-crate scaling insight (A's circular dep vs B's clean …

e5bc50d

…separation)

docs: add cross-crate limitation note to Approach A section

56351e9

docs: move non-macro Approach A messages into their handler modules

550b6be

docs: update Approach A analysis table to reflect no shared messages.rs

b1db611

docs: add registry as third problem in API comparison

25709f0

docs: replace protocol_impl! with #[protocol] and #[bridge] macros in…

a1ddbc4

… Approach B

docs: simplify UserActions with #[bridge] short form, use as_broadcas…

e999e2e

…ter() in main.rs

docs: fix stale "identical" wording in macro improvement takeaway

87b1398

docs: redesign Approach B as one-protocol-per-actor (gen_server model)

f8d4a78

docs: clean up coding examples in Approaches A and B

f30dd0d

docs: update Approach B to match latest feat/approach-b implementation

ab2ccbe

docs: add condensed quick reference for API alternatives comparison

8fcecd8

docs: add old API chat room example to quick reference

d55e20f

docs: move design docs to docs/design/

65ab654

ElFantasma changed the title ~~Add API alternatives comparison document~~ docs: API alternatives design documents Mar 5, 2026

docs: add API redesign plan to docs/design/ (from #147)

e6b1475

This was referenced Mar 5, 2026

docs: add API redesign plan for v0.5 #147

Closed

docs: API alternatives summary with registry and macro analysis #150

Closed

feat: implement Handler<M> API with envelope-based mailbox #148

Closed

Approach A: Recipient<M> + actor_api! pattern #152

Closed

ElFantasma added 2 commits March 5, 2026 13:41

docs: add README to docs/design/

1e6fe74

docs: add framework comparison compiled from research (12+ frameworks)

32e054e

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: API alternatives design documents#154

docs: API alternatives design documents#154
ElFantasma wants to merge 20 commits intomainfrom
docs/api-comparison

ElFantasma commented Feb 20, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Feb 20, 2026

Uh oh!

github-actions bot commented Feb 20, 2026

Uh oh!

greptile-apps bot commented Feb 20, 2026

Important Files Changed

Uh oh!

greptile-apps bot left a comment

Uh oh!

greptile-apps bot Feb 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

ElFantasma commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

github-actions bot commented Feb 20, 2026

🤖 Kimi Code Review

Uh oh!

github-actions bot commented Feb 20, 2026

🤖 Codex Code Review

Uh oh!

greptile-apps bot commented Feb 20, 2026

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

ElFantasma commented Feb 20, 2026 •

edited

Loading