Cloud Native Actors

<p align="center"> <image src="https://raw.githubusercontent.com/devlooped/CloudActors/main/assets/img/banner.png" alt="Orleans logo" width="320px"> </p>

An opinionated, simplified and uniform Cloud Native actors' library that integrates with Microsoft Orleans.

Motivation

Watch the Orleans Virtual Meetup 7 where Yevhen (of Streamstone fame) makes the case for using message passing style with actors instead of the more common RPC style offered by Orleans.

<!-- include https://github.com/devlooped/.github/raw/main/osmf.md -->

Open Source Maintenance Fee

To ensure the long-term sustainability of this project, users of this package who generate revenue must pay an Open Source Maintenance Fee. While the source code is freely available under the terms of the License, this package and other aspects of the project require adherence to the Maintenance Fee.

To pay the Maintenance Fee, become a Sponsor at the proper OSMF tier. A single fee covers all of Devlooped packages.

<!-- https://github.com/devlooped/.github/raw/main/osmf.md --> <!-- #content -->

Overview

Rather than the RPC-style programming offered (and encouraged) out of the box by Orleans, Cloud Actors offers a message-passing style of programming with a uniform API to access actors: Execute and Query.

These uniform operations receive a message (a.k.a. command or query) and optionally return a result. Consumers always use the same API to invoke operations on actors, and the combination of the actor id and the message consitute enough information to route the message to the right actor.

Actors can be implemented as plain CLR objects, with no need to inherit from any base class or implement any interface. The Orleans plumbing of grains and their activation is completely hidden from the developer.

Features

Rather than relying on dynamic dispatch, this implementation relies heavily on source generators to provide strong-typed routing of messages, while preserving a flexible mechanism for implementors.

In addition, this library makes the grains completely transparent to the developer. They don't even need to take a dependency on Orleans. In other words: the developer writes his business logic as a plain CLR object (POCO).

The central abstraction of the library is the actor bus:

public interface IActorBus
{
    Task ExecuteAsync(string id, IActorCommand command);
    Task<TResult> ExecuteAsync<TResult>(string id, IActorCommand<TResult> command);
    Task<TResult> QueryAsync<TResult>(string id, IActorQuery<TResult> query);
}

Actors receive messages to process, which are typically plain records such as:

public partial record Deposit(decimal Amount) : IActorCommand;  // 👈 marker interface for void commands

public partial record Withdraw(decimal Amount) : IActorCommand;

public partial record Close(CloseReason Reason = CloseReason.Customer) : IActorCommand<decimal>; // 👈 marker interface for value-returning commands

public enum CloseReason
{
    Customer,
    Fraud,
    Other
}

public partial record GetBalance() : IActorQuery<decimal>; // 👈 marker interface for queries (a.k.a. readonly methods)

We can see that the only thing that distinguishes a regular Orleans parameter from an actor message, is that it implements the IActorCommand or IActorQuery interface. You can see the three types of messages supported by the library:

• IActorCommand - a message that is sent to an actor to be processed, but does not return a result.
• IActorCommand<TResult> - a message that is sent to an actor to be processed, and returns a result.
• IActorQuery<TResult> - a message that is sent to an actor to be processed, and returns a result. It differs from the previous type in that it is a read-only operation, meaning it does not mutate the state of the actor. This causes a Readonly method invocation on the grain.

The actor, for its part, only needs the [Actor] attribute to be recognized as such:

[Actor]
public class Account    // 👈 no need to inherit or implement anything by default
{
    public Account(string id) => Id = id;       // 👈 no need for parameterless constructor

    public string Id { get; }
    public decimal Balance { get; private set; }
    public bool IsClosed { get; private set; }
    public CloseReason Reason { get; private set; }

    //public void Execute(Deposit command)      // 👈 methods can be overloads of message types
    //{
    //    // validate command
    //    // decrease balance
    //}

    // Showcases that operations can have a name that's not Execute
    public Task DepositAsync(Deposit command)   // 👈 but can also use any name you like
    {
        // validate command
        Balance +-= command.Amount;
        return Task.CompletedTask;
    }

    // Showcases that operations don't have to be async
    public void Execute(Withdraw command)       // 👈 methods can be sync too
    {
        // validate command
        Balance -= command.Amount;
    }

    // Showcases value-returning operation with custom name.
    // In this case, closing the account returns the final balance.
    // As above, this can be async or not.
    public decimal Close(Close command)
    {
        var balance = Balance;
        Balance = 0;
        IsClosed = true;
        Reason = command.Reason;
        return balance;
    }

    // Showcases a query that doesn't change state
    public decimal Query(GetBalance _) => Balance;  // 👈 becomes [ReadOnly] grain operation
}

NOTE: properties with private setters do not need any additional attributes in order to be properly deserialized when reading the latest state from storage. A source generator encapsulates all state for use in (de)serialization operations.

On the hosting side, an AddCloudActors extension method is provided to register the automatically generated grains to route invocations to the actors:

var builder = WebApplication.CreateSlimBuilder(args);

builder.Host.UseOrleans(silo =>
{
    silo.UseLocalhostClustering();
    // 👇 registers generated grains, actor bus and activation features
    silo.AddCloudActors(); 
});

State Deserialization

The above Account class only provides a single constructor receiving the account identifier. After various operations are performed on it, however, the state will be changed via private property setters (or direct field mutation). When you annotate a class with the [Actor] attribute, a source generator will create an inner class to hold all state properties (and fields), and implement (explicitly) an IActor<TState> interface to allow getting/setting the instance state.

This provides seamless integration with Orleans' recommended IPersistentState<T> injection mechanism, as shown in the generated grain above.

The generated state class for the above Account actor looks like this:

partial class Account : IActor<Account.ActorState>
{
    ActorState? state;

    ActorState IActor<ActorState>.GetState()
    {
        state ??= new ActorState();
        state.Balance = Balance;
        state.IsClosed = IsClosed;
        state.Reason = Reason;
        return state;
    }

    ActorState IActor<ActorState>.SetState(ActorState state)
    {
        this.state = state;
        Balance = state.Balance;
        IsClosed = state.IsClosed;
        Reason = state.Reason;
        return state;
    }

    [GeneratedCode("Devlooped.CloudActors")]
    [GenerateSerializer]
    public partial class ActorState : IActorState<Account>
    {
        [Id(0)]
        public decimal Balance;
        [Id(1)]
        public bool IsClosed;
        [Id(2)]
        public CloseReason Reason;
    }
}

This is a sort of typed Memento pattern which allows the Orleans state persistence mechanisms to read and write the actor state without requiring any additional code from the developer.

[!NOTE] This code is automatically guaranteed to be in sync with the actor's properties and fields, since it's generated at compile time.

The explicit implementation of IActor<TState> also ensures that the actor's public API is not polluted with these methods.

Event Sourcing

Quite a natural extension of the message-passing style of programming for these actors, is to go full event sourcing. The library provides an interface IEventSourced for that:

public interface IEventSourced
{
    IReadOnlyList<object> Events { get; }
    void AcceptEvents();
    void LoadEvents(IEnumerable<object> history);
}

The sample Streamstone-based grain storage will invoke LoadEvents with the events from the stream (if found), and AcceptEvents will be invoked after the grain is saved, so it can clear the events list.

Optimistic concurrency is implemented by exposing the stream version as the IGranState.ETag and parsing it when persisting to ensure consistency.

Users are free to implement this interface in any way they deem fit, but the library provides a default implementation if the interface is inherited but n