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

v0.12.2

Added

• Add spawn_link and link/unlink functions (#67)

Documentation

• Update README with improved content </>

Misc

• Add release script </>

---

See the full CHANGELOG.md

v0.12.1

Added

• Add ForwardMessageSendSync request trait (#65)

Fixed

• Actor lifecycle error handling when on_start errors </>

Documentation

• Add FAQ to book about reasons for actors stopping </>

Misc

• Ignore alpha and beta tags in cliff.toml </>

---

See the full CHANGELOG.md

v0.12.0

• @shusvr made their first contribution in #60
• @marcaddeo made their first contribution in #47

Added

• Add ActorRef::wait_startup method (#63)

Changed

• BREAKING: Make Links private (#57)
• BREAKING: Move actor pool and pubsub to their own modules (#56)
• BREAKING: Move ActorIDFromBytesError to error module </>
• BREAKING: Move remote actor functionality behind remote feature (#60) </>
• ActorID and improve documentation (#48)

Documentation

• Remove benchmark from README.md </>
• Add contributors badge to README.md </>
• Add Discord badge to README.md </>
• Add book badge to README.md </>
• Add getting help section to README.md </>
• Improve README with use cases, additional resources, and clearer structure </>
• Add support section to README.md </>
• Add Distributed Actor Communication section to README.md </>
• Improve code docs for remote module </>
• Add in-depth distributed actors information to kameo book (#51)
• Update heading levels in book </>
• Improve code docs and examples with all tests passing (#54)
• Add FAQ to book (#59)

Misc

• Add links to README badges (#47)
• Add gtag to kameo book (#52)
• Add Github CI </>
• Remote beta and nightly toolchains from CI </>
• Create CODE_OF_CONDUCT.md </>
• Add CONTRIBUTING.md </>
• Add github issue templates </>
• Move banner.png into docs directory </>
• Add .envrc to .gitignore </>
• Add pr detection to git cliff contributors </>

---

See the full CHANGELOG.md

v0.12.0-alpha.1

[0.12.0-alpha.1] - 2024-10-09

• @shusvr made their first contribution in #60
• @marcaddeo made their first contribution in #47

Changed

• BREAKING: Make Links private (#57)
• BREAKING: Move actor pool and pubsub to their own modules (#56)
• BREAKING: Move ActorIDFromBytesError to error module </>
• BREAKING: Move remote actor functionality behind remote feature (#60) </>
• ActorID and improve documentation (#48)

Documentation

• Remove benchmark from README.md </>
• Add contributors badge to README.md </>
• Add Discord badge to README.md </>
• Add book badge to README.md </>
• Add getting help section to README.md </>
• Improve README with use cases, additional resources, and clearer structure </>
• Add support section to README.md </>
• Add Distributed Actor Communication section to README.md </>
• Improve code docs for remote module </>
• Add in-depth distributed actors information to kameo book (#51)
• Update heading levels in book </>
• Improve code docs and examples with all tests passing (#54)
• Add FAQ to book (#59)

Misc

• Add links to README badges (#47)
• Add gtag to kameo book (#52)
• Add Github CI </>
• Remote beta and nightly toolchains from CI </>
• Create CODE_OF_CONDUCT.md </>
• Add CONTRIBUTING.md </>
• Add github issue templates </>
• Move banner.png into docs directory </>
• Add .envrc to .gitignore </>
• Add pr detection to git cliff contributors </>

---

See the full CHANGELOG.md

v0.11.0

Added

• BREAKING: Add lifetime to requests to avoid mailbox cloning </>
• Use interned peer ids for improved performance (#43)
• Return stream from join handle in attach_stream </>

Changed

• BREAKING: Detach stream when actor stops </>
• BREAKING: Use multiaddr and add SwarmFuture (#44) </>

Fixed

• attach_stream panicking when actor is stopped </>

Documentation

• Add book explaining core concepts (#40)
• Add missing examples from actors page </>
• Fix indentation for request features </>
• Add note about Result::Err in the reply trait </>
• Add note about SendError::HandlerError in replies </>
• Add icons and links to core concepts overview page </>
• Fix formatting in book </>
• Add icons to introduction headings </>

Misc

• Fix path to README in Cargo.toml </>
• Add obsidian related items to .gitignore </>
• Remove unused mailbox modules </>
• Update git cliff configuration </>

---

See the full CHANGELOG.md

v0.10.0

Added

• BREAKING: Add request traits (#39)
• Add delayed_send for unbounded actors </>
• Add remote actor support (#35)
• Add actor attribute to Actor derive macro </>
• Make actor swarm listen address optional </>
• Use macro to clean request trait impls for MaybeRequestTimeout </>

Removed

• BREAKING: Remove queries (#36)

Fixed

• Call on_panic when actor panics during startup </>

Documentation

• Update README.md </>
• Improve documentation for async messages </>
• Add missing mut from reply_sender example </>
• Add MessageSend import in code examples </>

Misc

• Fix path to README in Cargo.toml files </>
• Move kameo crate to root directory </>
• Add banner image </>
• Create dependabot.yml </>
• Remote PR number suffix from changelog generation </>

---

See the full CHANGELOG.md

v0.9.0

Added

• BREAKING: Add support for bounded/unbounded mailboxes (#29) #29
• Add Send + 'static bounds to Reply trait </>
• Add pubsub actor (#31) </>
• Add support for async pool factory functions (#33) #33
• Add async spawn_with function (#34) #34

Changed

• BREAKING: Return SendError from send methods allowing replies to be received blocking (#27) #27

Fixed

• Buffered messages not being applied correctly (#32) #32

Misc

• Update CHANGELOG.md </>
• Move crates out of nested crates dir </>

---

See the full CHANGELOG.md