docs: add API redesign plan for v0.5 by ElFantasma · Pull Request #147 · lambdaclass/spawned

ElFantasma · 2026-02-04T15:29:11Z

Summary

Add docs/API_REDESIGN.md documenting the planned API changes for v0.5
Addresses issues Improve type safety for request/reply message handling #144 (type safety) and Circular dependency problem with bidirectional actor communication #145 (circular deps)
Introduces Handler pattern and Recipient for type-safe actor communication

Key Decisions

Per-message types with Handler<M> trait (Actix-style)
Recipient<M> for type-erased message sending
Internal actor identity (no public Pid)
Trait-based supervision (Supervisable, Linkable, Monitorable)

Object-safe Receiver trait (Actix pattern)

The original Receiver<M> trait used RPITIT (-> impl Future) for request(), which is incompatible with dyn Receiver<M> — making Recipient<M> = Arc<dyn Receiver<M>> uncompilable.

Switched to the Actix pattern: Receiver::request() synchronously enqueues the message and returns a oneshot::Receiver for the reply. Async waiting happens outside the trait boundary. send_request() is an ergonomic async wrapper on the concrete Recipient and ActorRef types.

Also replaced Box<dyn Any + Send> mailbox channel with typed Envelope<A> trait objects for better type safety on the actor side.

Related: #144, #145, #138

github-actions · 2026-02-04T15:29:32Z

🤖 Kimi Code Review

⚠️ Review failed: Kimi API request failed with status 429

Automated review by Kimi (Moonshot AI)

github-actions · 2026-02-04T15:30:02Z

🤖 Codex Code Review

I only see documentation changes in this PR (docs/API_REDESIGN.md) and no code diffs. That means there’s nothing to review yet for correctness, concurrency, performance, or lifecycle behavior.

If the intent is to review the planned API changes, I can do a design review of the doc. Otherwise, please provide the code diff for PR #147 so I can assess the actual implementation.

If you want doc-only feedback, I can note: no executable changes, so no functional risk, but the doc doesn’t specify error semantics for request() cancellation, backpressure, or shutdown ordering—those will be important when the code lands.

Automated review by OpenAI Codex · custom prompt

greptile-apps · 2026-02-04T15:32:50Z

Greptile Overview

Greptile Summary

This PR adds comprehensive documentation for a v0.5 API redesign that introduces the Handler<M> pattern (inspired by Actix) and Recipient<M> type for type-safe, type-erased actor communication.

Key Changes

Documents solution to Circular dependency problem with bidirectional actor communication #145 (circular dependencies) using Recipient<M> pattern for bidirectional actor communication without circular type dependencies
Documents solution to Improve type safety for request/reply message handling #144 (type safety) using per-message Handler<M> trait for compile-time type checking of request/reply pairs
Introduces trait-based supervision system (Supervisable, Linkable, Monitorable) replacing public Pid exposure
Provides detailed implementation plan with phased rollout strategy and clear migration path
Includes concrete examples showing Bank actor and circular dependency resolution patterns

Documentation Quality

The design document is well-structured with:

Clear problem statements and rationale for each decision
Comprehensive code examples demonstrating both problems and solutions
Detailed phase-by-phase implementation plan
Migration strategy to minimize breaking changes
Verification steps and future considerations for v0.6+

Technical Considerations

Uses RPITIT (impl Trait in traits) requiring Rust 1.75+
Type-erased Recipient<M> maintains type safety per message type while breaking actor type dependencies
Sequential message processing per actor (mutable self) is intentional design choice

Confidence Score: 4/5

This documentation-only PR is safe to merge with high confidence
Score reflects that this is a design document with no code changes, well-thought-out technical approach solving real issues, and comprehensive implementation plan. Minor deduction for lack of proof-of-concept implementation and potential Rust version compatibility concerns that should be verified during implementation.
No files require special attention - this is documentation only

Important Files Changed

Filename	Overview
docs/API_REDESIGN.md	Comprehensive API redesign plan introducing `Handler<M>` pattern and `Recipient<M>` for type-safe actor communication, solving circular dependencies and type safety issues

Sequence Diagram

sequenceDiagram
    participant Client
    participant OrderService
    participant OrderRecipient as Recipient InventoryReserve
    participant InventoryService
    participant UpdateRecipient as Recipient OrderUpdate
    
    Note over Client,InventoryService: Solving Circular Dependencies with Recipient
    
    Client->>OrderService: PlaceOrder message
    activate OrderService
    
    OrderService->>OrderService: ctx.recipient()
    Note right of OrderService: Get typed Recipient for callbacks
    
    OrderService->>OrderRecipient: request InventoryReserve
    Note right of OrderRecipient: Type-erased message sending
    
    OrderRecipient->>InventoryService: InventoryReserve with reply_to
    activate InventoryService
    
    InventoryService->>InventoryService: Reserve inventory
    
    InventoryService->>UpdateRecipient: send OrderUpdate
    Note right of UpdateRecipient: Callback via Recipient not ActorRef
    
    UpdateRecipient->>OrderService: OrderUpdate message
    deactivate InventoryService
    
    OrderService->>Client: Result
    deactivate OrderService
    
    Note over Client,InventoryService: No circular dependency between actor types

greptile-apps

_{1 file reviewed, 4 comments}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps · 2026-02-04T15:32:54Z

docs/API_REDESIGN.md

+    fn request(&self, msg: M) -> impl Future<Output = Result<M::Result, ActorError>> + Send;
+}


RPITIT (return position impl Trait in traits) requires Rust 1.75+. Check MSRV compatibility or consider async_trait for older versions.

Prompt To Fix With AI

This is a comment left during a code review. Path: docs/API_REDESIGN.md Line: 99:100 Comment: RPITIT (return position `impl Trait` in traits) requires Rust 1.75+. Check MSRV compatibility or consider `async_trait` for older versions. How can I resolve this? If you propose a fix, please make it concise.

Removed RPITIT from the Receiver trait (now uses oneshot::Receiver return). Handler and Actor still use RPITIT but those traits are never used as dyn so object safety isn't a concern. Added a note about Rust 1.75+ requirement.

greptile-apps · 2026-02-04T15:32:55Z

docs/API_REDESIGN.md

+/// Typed handle to an actor
+pub struct ActorRef<A: Actor> {
+    id: ActorId,  // Internal identity (not public)
+    sender: mpsc::Sender<Box<dyn Any + Send>>,


Using Box<dyn Any + Send> for the message channel will require runtime type checking and downcasting. Document the expected error handling when type casting fails, or consider using an enum wrapper for better compile-time guarantees.

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

Prompt To Fix With AI

This is a comment left during a code review. Path: docs/API_REDESIGN.md Line: 231:231 Comment: Using `Box<dyn Any + Send>` for the message channel will require runtime type checking and downcasting. Document the expected error handling when type casting fails, or consider using an enum wrapper for better compile-time guarantees. Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time! How can I resolve this? If you propose a fix, please make it concise.

Replaced Box<dyn Any + Send> with typed Box<dyn Envelope<A> + Send>. Each envelope captures the concrete message type and dispatches via Envelope::handle(), so there's no runtime downcasting — the type is preserved inside the envelope closure.

greptile-apps · 2026-02-04T15:32:56Z

docs/API_REDESIGN.md

+    fn link(&self, other: &dyn Linkable);
+    fn unlink(&self, other: &dyn Linkable);


The link and unlink methods take &dyn Linkable, which requires identity comparison to track links. Consider documenting how actor identity/equality works with trait objects, or including an actor_id() method in the trait for proper tracking.

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

Prompt To Fix With AI

This is a comment left during a code review. Path: docs/API_REDESIGN.md Line: 159:160 Comment: The `link` and `unlink` methods take `&dyn Linkable`, which requires identity comparison to track links. Consider documenting how actor identity/equality works with trait objects, or including an `actor_id()` method in the trait for proper tracking. Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time! How can I resolve this? If you propose a fix, please make it concise.

Added actor_id() to Supervisable trait. Linkable::link/unlink use this for identity tracking internally.

greptile-apps · 2026-02-04T15:32:57Z

docs/API_REDESIGN.md

+
+/// Handler for a specific message type
+pub trait Handler<M: Message>: Actor {
+    fn handle(&mut self, msg: M, ctx: &Context<Self>) -> impl Future<Output = M::Result> + Send;


The Handler::handle signature uses RPITIT. Also note that using &mut self in async contexts may cause issues with concurrent message handling. Consider documenting that messages are processed sequentially per actor to clarify this design choice.

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

Prompt To Fix With AI

This is a comment left during a code review. Path: docs/API_REDESIGN.md Line: 205:205 Comment: The `Handler::handle` signature uses RPITIT. Also note that using `&mut self` in async contexts may cause issues with concurrent message handling. Consider documenting that messages are processed sequentially per actor to clarify this design choice. Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time! How can I resolve this? If you propose a fix, please make it concise.

Added a doc comment clarifying: RPITIT is fine here since Handler is never used as dyn, and &mut self is safe because actors process messages sequentially (one at a time, no concurrent access).

MegaRedHand · 2026-02-04T21:36:24Z

docs/API_REDESIGN.md

+trait MessageSender<M: Send>: Send + Sync {
+    fn send(&self, msg: M) -> Result<(), ActorError>;
+}
+
+// ActorRef<A> implements MessageSender<A::Message>
+// Type-erased handle for specific message type
+type Recipient<M> = Arc<dyn MessageSender<M>>;


The names of these two are confusing. One is just a reference to the other, but one is a "sender" and the other a "recipient"

You are right: renamed the trait to Receiver<M> and left the alias as Recipient<M>

docs: add API redesign plan for v0.5

41e4b62

greptile-apps bot reviewed Feb 4, 2026

View reviewed changes

MegaRedHand reviewed Feb 4, 2026

View reviewed changes

fix: use Receiver trait with Recipient alias for consistent naming

a39ce76

ElFantasma mentioned this pull request Feb 5, 2026

Circular dependency problem with bidirectional actor communication #145

Open

ElFantasma added 2 commits February 5, 2026 18:19

docs: use Actix-style object-safe Receiver trait in API plan

fa724c8

docs: address PR review comments on Supervisable and Handler traits

1ef33bf

		fn request(&self, msg: M) -> impl Future<Output = Result<M::Result, ActorError>> + Send;
		}

		fn link(&self, other: &dyn Linkable);
		fn unlink(&self, other: &dyn Linkable);

Conversation

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

Uh oh!

Summary

Key Decisions

Object-safe Receiver trait (Actix pattern)

Uh oh!

github-actions bot commented Feb 4, 2026

🤖 Kimi Code Review

Uh oh!

github-actions bot commented Feb 4, 2026

🤖 Codex Code Review

Uh oh!

greptile-apps bot commented Feb 4, 2026

Greptile Overview

Greptile Summary

Key Changes

Documentation Quality

Technical Considerations

Confidence Score: 4/5

Important Files Changed

Sequence Diagram

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

ElFantasma Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

ElFantasma Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

ElFantasma Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

ElFantasma Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

MegaRedHand Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

ElFantasma Feb 5, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ElFantasma commented Feb 4, 2026 •

edited

Loading