Kameo Files

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.

:::rust
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.

:::rust
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](https://github.com/tqwewe/kameo/blob/main/CHANGELOG.md#0150