Distribution 1.1.0-prerelease

This is a prerelease version of Distribution.
There is a newer version of this package available.
See the version list below for details.
dotnet add package Distribution --version 1.1.0-prerelease
NuGet\Install-Package Distribution -Version 1.1.0-prerelease
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Distribution" Version="1.1.0-prerelease" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Distribution --version 1.1.0-prerelease
#r "nuget: Distribution, 1.1.0-prerelease"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Distribution as a Cake Addin
#addin nuget:?package=Distribution&version=1.1.0-prerelease&prerelease

// Install Distribution as a Cake Tool
#tool nuget:?package=Distribution&version=1.1.0-prerelease&prerelease

Distribution - Virtual Actor Framework

There is decent amount of actor-like frameworks, including those that support an idea of Virtual Actors, e.g. Orleans and Proto.Actor

The two mentioned frameworks are the closest to what I would like to use, but they have some drawbacks, like extra build step or inability to use different transport protocol. Below is the list of features built in the current framework. Each of them can be considered as an advantage or a disadvantage depending on specific use-case.

Features

  • Single thread
  • Zero configuration
  • Cross platform .NET 7
  • UDP broadcasting for automatic service discovery without a single point of failure
  • Peer-To-Peer network of independent nodes without consensus leaders
  • Random placement of virtual actors within a cluster
  • Ability to create multiple instances of the same type of actor using unique ID
  • Ability to override any layer, including protocol, actor placement strategy, service discovery, etc
  • No dangerous binary serialization or 3rd party serializtion libraries
  • Simple C# POCO classes for messages, no attributes or other decorators
  • Process messages using the same or multiple actor classes with [Subscription] attribute
  • Kestrel server middleware to process message queries
  • Usage of Task methods instead of FIFO loops for asynchronous communication
  • Automatic loading and mapping for actors and messages using reflection, borrowed from Mediatr framework
  • No use of locks

Nuget

Install-Package Distribution

Sample

This is an example of using actors locally within the same app.

// Define message and response format 

public class DemoMessage { public string Name { get; set; }}
public class DemoResponse { public string Data { get; set; }}

// Define actor processing this particular message   

public class DemoActor
{
  [Processor]
  public virtual Task<DemoResponse> SomeAction(DemoMessage message)
  {
    return Task.FromResult(new DemoResponse { Data = "Response from actor" });
  }
}

// Processing

public class Client
{
  async Task SendMessageToActor()
  {
    var scene = new Scene();
    var message = new DemoMessage { Name = "Message to actor" };
    var response = await scene.Send<DemoResponse>("Custom Actor ID", message);

    Console.WriteLine("Response : " + response.Data);
  }
}

An example with a distributed network of actors in the cluster is a bit more complex and can be found in the Samples directory.

Disclaimer

In order to keep things simple and flexible, the main focus was on simplicity and scalability rather than performance.

Notes

Practically all parts of this framework use the most basic implementation of each layer meaning that it's a general purpose implementation that may need to be extended to solve more specific problems.

  1. HTTP and JSON are somewhat slow, but were chosen for communication instead of sockets to make it easier to build a network of a million of nodes without a need to manage permanent connections between peers.
  2. UDP broadcasting can detect nodes within the same network segment. To make peer discovery global there will be a need for services like Consul or manual NAT traversing.
  3. There is a heavy use of reflection for mapping between actors and messages. No benchmarks, but switching to compiled delegates may improve latency.

Improvements

Even though existing modules are the most basic at the core, they can be easily extended or overridden to achieve more specific goals.

  1. When there is no requirement to have millions of nodes, it's possible to implement ICommunicator and use sockets with Message Pack or Flat Buffers for lower latency.
  2. Peer discovery is encapsulated inside of the Beacon class. When needed, it's easy to override any of its method or implement IBeacon to use it with Consul or some other service discovery tool.
Product Compatible and additional computed target framework versions.
.NET net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (4)

Showing the top 4 NuGet packages that depend on Distribution:

Package Downloads
Canvas.Core

Internal package used in Canvas.Views.Web

Distribution.Service

HTTP service with streaming and parallel execution.

Distribution.Cluster

General purpose virtual actor framework for peer-to-peer microservices or in-process communication within the same app with possible extension to blockchains.

Distribution.Stream

HTTP service with streaming and parallel execution.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
2.0.5 81 3/25/2024
2.0.4 157 3/18/2024
2.0.3 55 3/18/2024
2.0.2 59 3/18/2024
2.0.1 122 3/15/2024
2.0.0 59 3/15/2024
1.3.5 77 3/14/2024
1.3.3 55 3/14/2024
1.3.2 63 3/14/2024
1.3.1 79 3/14/2024
1.3.0 80 3/7/2024
1.2.6 55 3/7/2024
1.2.5 127 3/3/2024
1.2.4 91 3/3/2024
1.2.3 99 3/1/2024
1.2.2 58 2/26/2024
1.2.1 58 2/26/2024
1.2.0 85 2/26/2024
1.1.8-prerelease 109 2/24/2023
1.1.6-prerelease 84 2/19/2023
1.1.5-prerelease 103 2/14/2023
1.1.1-prerelease 79 2/13/2023
1.1.0-prerelease 205 11/6/2022
1.0.9-prerelease 93 11/6/2022
1.0.8-prerelease 115 6/9/2022
1.0.7-prerelease 115 6/7/2022
1.0.6-prerelease 118 6/3/2022
1.0.5-prerelease 115 5/31/2022
1.0.3-prerelease 120 4/4/2022
1.0.2-prerelease 186 4/3/2022