v0.19.2

Added

• Add support for channels-console (#261) </>

Fixed

• Metrics counter names (#260) </>

Misc

• Bump kameo to version 0.19.2 </>

---

See the full CHANGELOG.md

v0.19.0

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

Highlighted Changes

Add metrics feature flag (#250)

Actor mailbox metrics are now supported with the metrics feature flag, which track the following per actor:

• Messages sent/received
• Lifecycle events sent/received
• Link died events sent/received

This is implemented with the metrics crate, and allows better insight into the performance of actors in apps.

Add scheduler actor (#251)

The kameo_actors crate now supports a new [Scheduler] actor, which lets you schedule messages to be sent to actors at intervals or after a timeout.

use kameo::prelude::*;
use kameo_actors::scheduler::{Scheduler, SetInterval, SetTimeout};

let scheduler_ref = Scheduler::spawn_default();

let set_interval = SetInterval::new(actor_ref.downgrade(), Duration::from_secs(1), Msg);
scheduler_ref.tell(set_interval);

let set_timeout = SetTimeout::new(actor_ref.downgrade(), Duration::from_secs(1), Msg);
scheduler_ref.tell(set_timeout);

Add ctx attribute to #[messages] macro (#240)

The #[messages] macro now supports receiving the ctx: &mut Context<Self, Self::Reply> parameter usually accessible in the Message trait.

Use #[message(ctx)] to include a ctx parameter:

#[message(ctx)]
async fn inc(&mut self, amount: u32, ctx: &mut Context<Self, i64>) -> i64 {
    // ctx is available but not part of Inc struct
}

Or specify a custom parameter name with #[message(ctx = name)]:

#[message(ctx = my_ctx)]
async fn reset(&mut self, my_ctx: &mut Context<Self, ()>) {
    self.count = 0;
}

BREAKING: Move spawn methods to new Spawn trait (#253)

The spawn* methods previously available on the Actor trait have now been moved to a sealed Spawn trait provided by kameo

---

Added

• BREAKING: Add metrics feature flag for mailbox sent/received metrics (#250)
• Add ctx attribute (#240)
• Add scheduler actor (#251)

Changed

• BREAKING: Hide MailboxSender internal variants (#248)
• BREAKING: Move spawn methods to new Spawn trait (#253)

Fixed

• BREAKING: Actors not being unregistered on stop (#254)

Documentation

• Fix bootstrapping actor swarm complete code example </>

Misc

• Update const-str requirement from 0.6.4 to 0.7.0 (#236)
• Update const-str requirement from 0.6.4 to 0.7.0 (#237)
• Update const-str requirement from 0.6.4 to 0.7.0 (#241)
• Update const-str requirement from 0.6.4 to 0.7.0 (#243)
• Upgrade const-str to 0.7.0 </>
• Fix ci </>
• Bump kameo_macros to version 0.19.0 </>

---

See the full CHANGELOG.md

v0.18.0

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.

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:

// 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

v0.17.2

Added

• Implement PartialEq, Eq, and Hash for actor ref types (#189)

Fixed

• Actor::on_message not being called (#186)

Documentation

• Fix version 0.17.0 and 0.17.1 links in CHANGELOG.md </>

Misc

• Bump kameo to version 0.17.2 </>

---

See the full CHANGELOG.md

v0.17.1

⚠️ 0.17.1 has been yanked due to a bug where Actor::on_message is not called. See #186. Please upgrade to 0.17.2 which fixes this issue.

Added

• Add ReplyRecipient and WeakReplyRecipient to prelude (#184)

Fixed

• Wait_for_stop calls for wait_for_shutdown instead of wait_for_startup (#183)

Misc

• Bump kameo to version 0.17.1 </>

---

See the full CHANGELOG.md

v0.17.0

⚠️ 0.17.0 has been yanked due to a bug where .wait_for_stop() incorrectly called wait_for_startup(). See #183. Please upgrade to 0.17.2 which fixes this issue.

Kameo 0.17.0 has been released, with some flexibility improvements to the API.

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

And thanks to our new contributors:

• @Malefaro made their first contribution in #179

• @hanekoo made their first contribution in #163

• @Avi-D-coder made their first contribution in #170

• @artemijan made their first contribution in #177

Highlighted Changes

Add Actor::Args associated type and actor spawn methods (#168)

New Actor::Args associated type

A new Args type is added to the Actor trait, allowing the actors state to be initialized in the on_start method.

Unfortunately this makes the on_start method required, since it cannot have a default implementation. But the #[derive(Actor)] macro just sets the Args = Self, and returns the state in the implementation.

Actor spawn methods

The spawn functions have been moved to be part of the Actor trait directly.

This means instead of kameo::spawn(MyActor), you now use MyActor::spawn(MyActor). This looks a little redundant, however the args passed to MyActor::spawn(args) can now be a different type to the actor itself, allowing some powerful patterns.

The spawn methods available are now:

• Actor::spawn
• Actor::spawn_with_mailbox
• Actor::spawn_link
• Actor::spawn_link_with_mailbox
• Actor::spawn_in_thread
• Actor::spawn_in_thread_with_mailbox
• Actor::prepare
• Actor::prepare_with_mailbox

For the methods not suffixed with _with_mailbox, the default mailbox is a bounded with a capacity of 64.

Add Recipient and ReplyRecipient types for type erased actor refs (#160, #179)

ActorRefs can be "downgraded" into new type erased types Recipient<M> and ReplyRecipient<M, R, E> using the new .recipient() and .reply_recipient() methods.

This allows you to erase the actors type itself, and in exchange have a recipient which can only handle messages of a single type.

New Broker and MessageBus actors

The kameo_actors crate now has two new actors: Broker, and MessageBus.

Add actor shutdown result handling and error hook (#166)

Adds a new wait_for_shutdown_result method to ActorRef, for handling errors during shutdown. Additionally, exposes a kameo::error::set_actor_error_hook function for setting a global function to be called when an actor's on_start or on_stop methods return an error.

---

Added

• BREAKING: Add Recipient type for type erased actor refs (#160)
• BREAKING: Add Actor::Args associated type and actor spawn methods (#168)
• Add Recipient and WeakRecipient to prelude </>
• Add broker actor (#161)
• Add message bus actor (#162)
• Add track_caller to Recipient::tell </>
• Add actor shutdown result handling and error hook (#166)
• Implement downgrade for Recipient </>
• Add msg and err methods to SendError (#169)
• Add message_queue actor (#163)
• Add reply recipient that can do ask requests (#179)

Changed

• Wrap large enum variant in Box to fix clippy lint </>
• Format toml files </>

Fixed

• Process buffered messages before stopping gracefully </>
• Actors not stopping due to leaked ActorRef

Misc

• Update criterion requirement from 0.5 to 0.6 (#173)
• Update release script shabangs </>
• Bump kameo_macros to version 0.17.0 </>

---

See the full CHANGELOG.md

v0.16.0

Kameo 0.16 has been released, and brings some much needed simplicity to to library.

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

And thanks to our new contributors:

• @attila-lin made their first contribution in #149

Breaking Changes

Removed Mailbox Generics and Request Traits

The actor trait no longer has a type Mailbox associated type.
Instead, the mailbox is specified when spawning the actor using the spawn_with_mailbox functions.

By default, actors are spawned using bounded mailboxes with a capactiy of 64.

This change also removes the BoundedMailbox and UnboundedMailbox types, and the Mailbox trait,
and replaces it all with an enum over tokio's mpsc bounded & unbounded types.
The new types are MailboxSender, MailboxReceiver, WeakMailboxReceiver.

Removes the request traits (MessageSend, TryMessageSend, etc)

There's no longer the request traits, and instead .send(), .try_send(), .blocking_send() are called directly on the request types rather than as trait implementations.

This is a huge improvement from a simplicity perspective, as many complicated trait bounds were the cause of the mailbox flexibility.

How do we call .send_sync() and .try_send_sync()?

These methods were only available on unbounded mailboxes.
This can still be achieved by using .now_or_never() on the request,
however bounded mailboxes may return None here.

One major downside of course is that custom mailbox types can no longer be used,
since they're hard coded enum variants within kameo instead of a trait implementation.
However, the existing Mailbox trait is already very specific, and other mailbox types couldn't
even be implemented due to some features missing in other asynchronous channel types.

Added

• Add prelude module (#145)
• Add Actor::next method (#147)
• Add on_message function to Actor trait (#155)

Changed

• BREAKING: Use ForwardMessageSend trait for Context::forward methods (#146)
• BREAKING: Move pool and pubsub actors into new kameo_actors crate (#154)

Removed

• BREAKING: Remove mailbox generics and request traits (#153)
• Remove unnecessary trait bound in Context::forward method </>

Fixed

• Spawn with tokio unstable cfg flags </>

Documentation

• Bump version in getting started page </>
• Remove unnecessary tokio time sleep import in code docs </>
• Add vanhouc sponsor to README.md </>
• Fix sponsor badge link </>
• Impove registerering and looking up actors example </>

Misc

• Fix clippy lints (#149)
• Ci updates </>
• Improve ci and run in parallel (#156)
• Add release scripts </>
• Bump kameo_macros to version 0.16.0 </>

---

See the full CHANGELOG.md

v0.15.0

Kameo 0.15 has been released with some major improvements to error handling, the actor trait, and more.

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

And thanks to our new contributors:

• @Tristaan made their first contribution in #142
• @Plebshot made their first contribution in #128
• @agoldhammer made their first contribution in #126
• @hirschenberger made their first contribution in #121

Breaking Changes

Added Error type to Actor trait (#138)

The Actor trait now has an Error associated type, which is used within the actors lifecycle methods for improved
error handling.

This new associated type must be fmt::Debug + Send + 'static.

impl Actor for MyActor {
    type Mailbox = UnboundedMailbox<Self>;
    type Error = MyActorError; // New associated type!

    async fn on_start(&mut self, actor_ref: ActorRef<Self>) -> Result<(), Self::Error> { // Methods now return the associated error
        Ok(())
    }

    async fn on_panic(&mut self, actor_ref: WeakActorRef<Self>, err: PanicError) -> Result<ControlFlow<ActorStopReason>, Self::Error> {
        if let Some(err) = err.downcast::<MyActorError>() {
            // We can downcast panic errors if they match our error type!
            println!("Actor error: {err}");
        }
    }
}

The #[derive(Actor)] macro uses the kameo::error::Infallible type for the error type.

Use ControlFlow enum Actor methods (#140)

Methods on the Actor trait which previously returned Option<ActorStopReason> have been replaced with
ControlFlow<ActorStopReason>.

Previously, if an actor method returned Some(ActorStopReason), the actor would stop running. With this release,
these methods now return either ControlFlow::Continue(()) for the actor to continue running, or
ControlFlow::Break(ActorStopReason) to stop the actor. This has some nice benefits, including being able to use the
? operator to short circuit and return early, just like the Result and Option types in Rust.

Added ActorRef::wait_startup_result method (#139)

The new wait_startup_result method can be called on actor refs to receive a clone of any errors that might've occured
during the actor's on_start method.

use kameo::actor::{Actor, ActorRef};
use kameo::mailbox::unbounded::UnboundedMailbox;

struct MyActor;

impl Actor for MyActor {
    type Mailbox = UnboundedMailbox<Self>;
    type Error = std::num::ParseIntError;

    async fn on_start(&mut self, actor_ref: ActorRef<Self>) -> Result<(), Self::Error> {
        "invalid int".parse().map(|_: i32| ()) // Will always error
    }
}

let actor_ref = kameo::spawn(MyActor);
let startup_result = actor_ref.wait_startup_result().await;
assert!(startup_result.is_err());

Least loaded scheduling for actor pool

The actor pool now uses least loaded scheduling rather than round-robin.

This improves situations where one actor might be slower to process messages, allowing available actors to handle
requests instead.

---

Added

• BREAKING: Add unregister method to ActorSwarm (#133)
• BREAKING: Add ReplyError trait for better PanicError downcasting (#137)
• BREAKING: Add Error type to Actor trait (#138)
• Add PubSub SubscribeFilter functionality (#120)
• Implement infallible replies for missing std::collections types (#127)
• Move PartialEq and Hash manual implementations from PeerId to PeerIdKind </>
• Impl Error for PanicError </>
• Add ActorRef::wait_startup_result method (#139)
• Add PanicError::downcast method </>
• Implement least loaded scheduling for actor pool </>
• Use target_has_atomic cfg to detect Atomic type support for 32-bit embedded systems, wasm, etc (#142)

Changed

• BREAKING: Use ControlFlow enum instead of Option for Actor methods (#140)
• Use Box<dyn FnMut> for PubSub filter functions to allow dynamic filtering behavior (#124)
• Update overhead benchmark and delete fibonacci benchmark </>
• Use downcast-rs instead of mopa for ReplyError trait </>
• Use ReplyError to simplify trait bounds </>

Removed

• BREAKING: Remove internment dependency and simplify peer ID handling (#123)
• BREAKING: Remove lifetime from Context and borrow mutably instead (#144)
• Remove reply implementations for unstable integer atomics </>

Fixed

• BREAKING: Actor pool worker scheduling </>
• ActorID PartialEq and Hash implementations </>
• Missing Hasher import in id tests </>
• wait_startup deadlock on actor start error </>
• Pubsub tests </>

Documentation

• Bump kameo version in getting started page </>
• Document remote links </>
• Add bootstrapping with custom behaviour docs </>
• Add sponsor logos to README.md </>
• Fix typos (#128)
• Remove blank line in reply_sender code docs </>
• Fix sponsor badge link in README.md </>
• Add comparing rust actor libraries blog post to resources in README.md </>
• Improve actor code docs </>
• Replace round-robin with least-connections ActorPool scheduling </>

Misc

• Add remote as required feature for examples (#121)
• Improve release script </>
• Update libp2p dependency from version 0.54.1 to 0.55.0 (#122)

---

See the full CHANGELOG.md

v0.14.0

Kameo 0.14 is here, bringing some nice new features, two new contributors, and two new generous sponsors.

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

And thanks to @meowjesty and @Kamil729 for their contributions!

New Features

Deadlock Warnings

Any ask or tell requests which could result in a deadlock will now emit tracing warnings.

An example includes sending a tell request with .send instead of .try_send, which may result in a deadlock if the mailbox is full.
Doing so will print a warning:

At src/lib.rs:277, An actor is sending a blocking tell request to itself using a bounded mailbox, which may lead to a deadlock.

A nice feature of these warnings is that they show exactly which line of code the issue comes from, making it easily resolvable.

Note that these warnings are only present in debug builds.

Remote Actor Links

Actors can now be linked together remotely! This means if one actor dies, the other will be notified.

This can be achieved with the new methods:

• ActorRef::link_remote
• ActorRef::unlink_remote
• RemoteActorRef::link_remote
• RemoteActorRef::unlink_remote

Additionally, if a peer gets disconnected, any actors with links to that peer will be notified with ActorStopReason::PeerDisconnected,
making the system robust even if a peer crashes or is disconnected.

ActorRef's blocking_link and blocking_unlink

ActorRef now supports linking and unlinking actors with the new blocking_link and blocking_unlink methods for syncrhonous contexts.

Local Actor Registry

Previously actors could be registered and looked up with kameo's remote feature. But now, this feature is supported for non-remote kameo environments,
providing an easy way to register and lookup actors.

let actor_ref = kameo::spawn(MyActor); 
actor_ref.register("my awesome actor")?; 

let other_actor_ref = ActorRef::<MyActor>::lookup("my awesome actor")?.unwrap(); 
assert_eq!(actor_ref.id(), other_actor_ref.id()); 

Full Control Over Actor Swarm

Configuring or having any sort of control over the underlying libp2p swarm was impossible with kameo.
But now, its very easy and flexible, allowing any kind of custom behaviour to be implemented.

Some new methods when bootstrapping include:

• ActorSwarm::bootstrap_with_behaviour for providing a custom behaviour.
• ActorSwarm::bootstrap_with_swarm for providing a custom swarm.
• ActorSwarm::bootstrap_manual for extremely manual processing of the actor swarm. (see examples/manual_swarm.rs)

Added

• BREAKING: Add support for manual swarm operations (#111)
• BREAKING: Add local actor registry for non-remote environments (#114)
• BREAKING: Add support for remote actor links (#116)
• Add warnings for potential deadlocks (#87)
• Implement infallible reply for std::path types (#96)
• Add blocking_link and blocking_unlink methods to ActorRef (#115)

Changed

• BREAKING: Use kameo::error::Infallible in Reply derive macro instead of ()
• BREAKING: Modularize features and improve conditional compilation (#112)

Removed

• BREAKING: Remove actor state from PreparedActor (#99)
• BREAKING: Remove deprecated link_child, unlink_child, link_together, and unlink_together methods </>
• Remove mailbox capacity warning on unbounded mailbox tell requests </>
• Remove itertools dependency and replace repeat_n with std::iter::repeat </>

Fixed

• Fix clippy lints and add to CI

Documentation

• Add Caido Community sponsor to README.md </>
• Remote stars badge from README.md </>
• Add huly labs sponsor to README.md </>

Misc

• Fix release script with current release notes </>
• Add changelog links for new versions </>
• Remove flake.nix and flake.lock </>

---

See the full CHANGELOG.md

v0.13.0

• @13r0ck made their first contribution in #79

Added

• Impl IntoFuture for requests (#72)
• Add public BoxReplySender type alias (#70)
• Add support for preparing an actor and running it outside a spawned task (#69)
• Add Context::reply shorthand method </>

Changed

• BREAKING: Relax request impls to be generic to any mailbox (#71)
• BREAKING: Use owned actor ref in spawn_with function (#68)

Fixed

• BREAKING: Startup deadlock on small bounded mailboxes (#84)
• Tokio_unstable compile error in spawn </>
• Request downcasting and added tests (#85)

Documentation

• Remove reverences to deprecated linking methods (#79)

Misc

• Add empty message to git tag release script </>
• Remove msrv from Cargo.toml (#82)

---

See the full CHANGELOG.md