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

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