Kameo Files

A huge thank you to Huly Labs, Caido Community, vanhouc, cawfeecoder, and JaniM for supporting Kameo's development! 💖

And thanks to our new contributors:

• @LVivona made their first contribution in [#204]

Highlighted Changes

Add lookup_all method for actors registered on multiple peers (#190)

Previously in kameo, registering actors under the same name on different peers caused inconsistent behaviour within the kademlia DHT. Now when actors are registered on multiple nodes, lookup_all can be used to get a reference to them all.

It is still discouraged to register actors under the same name across peers however.

Add Context::stop method (#231)

Previously, the only way to gracefully stop an actor is with ActorRef::stop_gracefully, which stops the actor after all queued messages are processed.

This change allows message handlers to stop the actor immediately after processing the current message via the new Context::stop method.

:::rust
impl Message<ImmediatelyStop> for MyActor {
    type Reply = ();

    async fn handle(&mut self, _msg: ImmediatelyStop, ctx: Context<'_, Self, Self::Reply>) {
        ctx.stop(); // The actor will stop normally after this message is handled.
    }
}

Refactor remote system to use composable NetworkBehaviour pattern (#198)

This change completely redesigns Kameo's remote actor system to follow libp2p's idiomatic NetworkBehaviour pattern, replacing the previous monolithic wrapper approach with composable behaviors that integrate seamlessly into user-controlled swarms.

What Changed

Before: Kameo provided an ActorSwarm wrapper that internally managed its own libp2p swarm, limiting user customization and making integration with other libp2p protocols difficult.

After: Kameo now provides kameo::remote::Behaviour - a standard libp2p NetworkBehaviour that users can compose with other behaviors (mDNS, Gossipsub, etc.) in their own swarm configurations.

Key Improvements

• Full Swarm Control: Users now have complete control over transport configuration, connection management, and behavior composition
• Composable Design: Seamlessly integrate with mDNS discovery, custom transports, authentication, and other libp2p protocols
• Modular Architecture: Clean separation between messaging (kameo::remote::messaging) and registry (kameo::remote::registry) concerns
• Idiomatic libp2p: Follows established libp2p patterns and conventions, making it familiar to libp2p users

Architecture

The new system provides:

• kameo::remote::Behaviour - Main NetworkBehaviour combining messaging and registry
• kameo::remote::messaging::Behaviour - Handles remote message passing via request-response
• kameo::remote::registry::Behaviour - Manages actor discovery via Kademlia DHT
• Rich event system for monitoring network operations

Migration

This is a breaking change that requires updating swarm initialization code:

:::rust
// Before
let swarm = ActorSwarm::bootstrap()?;

// After
#[derive(NetworkBehaviour)]
struct MyBehaviour {
    kameo: kameo::remote::Behaviour,
    mdns: mdns::tokio::Behaviour,
}

let swarm = SwarmBuilder::with_new_identity()
    .with_behaviour(|key| {
        let kameo = kameo::remote::Behaviour::new(
            key.public().to_peer_id(),
            kameo::remote::messaging::Config::default()
        );
        kameo.init_global()?;
        Ok(MyBehaviour { kameo, mdns })
    })?
    .build();

---

Added

• BREAKING: Add a lookup_all method to the actor registry using providers (#190)
• BREAKING: Add fire-and-forget option for remote tell requests (#205)
• BREAKING: Add Context::stop method for stopping the actor within a message handler (#231)
• BREAKING: Add wait_for_startup/shudown_with_result methods for non Clone errors (#235)
• Implement Reply for most of kameo's types (#200)
• Add ActorRef::into_remote_ref method and impl Seralize/Deserialize for RemoteActorRef (#211)
• Use debug printing for panic error logs (#214)
• Improve RemoteActorRef Deserialize impl (#215)
• Remove Debug constraint on A for Context (#216)
• Add RemoteAskRequest::enqueue and try_enquque methods (#217)
• Implement Serialize and Deserialize for SendError </>
• Add Context::spawn method (#218)
• Add ForwardedReply Direct results (#223)
• Hash remote_message impls to auto generate ids (#228)

Changed

• BREAKING: Refactor remote system to use composable NetworkBehaviour pattern (#198)
• BREAKING: Use DeliveryMethod for PubSub actor (#206)
• BREAKING: Implement PartialOrd and Ord for actor id and ref types (#219)
• BREAKING: Return reference in Context::actor_ref (#222)
• Improve test and lint coverage for all workspace crates (#191)
• Rename ActorID to ActorId (#202)
• Consolidate remote feature conditional compilation blocks (#204)

Removed

• BREAKING: Remove dependency on once_cell (#209)
• BREAKING: Remove PendingReply lifetime (#212)

Fixed

• Resolve test and lint issues uncovered by improved CI (#192)
• Stop_gracefully panicking when actor is already stopped (#201)
• Prevent deadlock in ActorRef link/unlink methods (#221)
• Drop mailbox immediately when actor is stopped (#233)

Documentation

• Fix version 0.17.2 link in CHANGELOG.md </>
• Update outdated Actor example and FAQ </>
• Remove prerequisites from README.md </>

Misc

• Add msrv rust-version to and include fields to Cargo.toml files </>
• Fix clippy lints regarding msrv on remote feature flag </>
• Update criterion requirement from 0.6 to 0.7 (#225)
• Add JaniM to README.md sponsors <3 </>
• Update const-str requirement from 0.6.4 to 0.7.0 (#234)
• Bump kameo_macros to version 0.18.0 </>

---

See the full [CHANGELOG.md](https://github.com/tqwewe/kameo/blob/main/CHANGELOG.md#0180

See the full [CHANGELOG.md](https://github.com/tqwewe/kameo/blob/main/CHANGELOG.md#0180