dohertj2/scadalink-design
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
488a7b534be413e6e53bd01d95ab8f8a1036db74
scadalink-design/AkkaDotNet/AkkaComponents.md
Joseph Doherty de636b908b Add Akka.NET reference documentation 
Notes and documentation covering actors, remoting, clustering, persistence,
streams, serialization, hosting, testing, and best practices for the Akka.NET
framework used throughout the ScadaLink system.
2026-03-16 09:08:17 -04:00

219 lines
11 KiB
Markdown
Raw Blame History

# Akka.NET Components Reference
This document catalogs the major components (modules/libraries) of the Akka.NET framework, along with a brief description and a link to the official documentation for each.
---
## Core Components
### 1. Actors (Akka — The Core Library)
The foundational building block of Akka.NET. Actors encapsulate state and behavior, communicate exclusively through asynchronous message passing, and form supervision hierarchies for fault tolerance. The core library includes the `ActorSystem`, `Props`, `IActorRef`, mailboxes, dispatchers, routers, FSM (Finite State Machine), and the supervision/monitoring model.
- **NuGet Package:** `Akka`
- **Documentation:** <https://getakka.net/articles/intro/what-is-akka.html>
- **Concepts — Actor References:** <https://getakka.net/articles/concepts/actors.html>
- **Supervision & Monitoring:** <https://getakka.net/articles/concepts/supervision.html>
### 2. Remoting (Akka.Remote)
Enables transparent communication between actor systems running on different hosts or processes. Messages are serialized and sent over the network; remote and local message sends use the same API. Remoting is the transport layer upon which Clustering is built.
- **NuGet Package:** `Akka.Remote`
- **Documentation:** <https://getakka.net/articles/remoting/index.html>
- **Configuration Reference:** <https://getakka.net/articles/configuration/modules/akka.remote.html>
### 3. Cluster (Akka.Cluster)
Organizes multiple actor systems into a membership-based "meta-system" with failure detection, member lifecycle management, role assignment, and split-brain resolution. In most real-world applications, Cluster is used instead of raw Remoting.
- **NuGet Package:** `Akka.Cluster`
- **Documentation:** <https://getakka.net/articles/clustering/cluster-overview.html>
- **Configuration Reference:** <https://getakka.net/articles/configuration/modules/akka.cluster.html>
### 4. Cluster Sharding (Akka.Cluster.Sharding)
Distributes a large set of stateful entities (actors) across cluster members. Entities are addressed by an identifier and are automatically balanced, migrated on failure, and guaranteed to be unique across the cluster. Typically paired with Persistence.
- **NuGet Package:** `Akka.Cluster.Sharding`
- **Documentation:** <https://getakka.net/articles/clustering/cluster-sharding.html>
### 5. Cluster Singleton (Akka.Cluster.Tools)
Ensures that exactly one instance of a particular actor exists across the entire cluster at any given time. If the hosting node goes down, the singleton is automatically migrated to another node.
- **NuGet Package:** `Akka.Cluster.Tools`
- **Documentation:** <https://getakka.net/articles/clustering/cluster-singleton.html>
### 6. Cluster Publish-Subscribe (Akka.Cluster.Tools)
Provides a distributed publish-subscribe mechanism within a cluster. Messages can be broadcast to all subscribers of a topic or sent to a single interested party. Part of the `Akka.Cluster.Tools` package alongside Cluster Singleton.
- **NuGet Package:** `Akka.Cluster.Tools`
- **Documentation:** <https://getakka.net/articles/clustering/distributed-publish-subscribe.html>
### 7. Cluster Metrics (Akka.Cluster.Metrics)
Collects and publishes node-level resource metrics (CPU, memory) across the cluster. Useful for adaptive load balancing and monitoring.
- **NuGet Package:** `Akka.Cluster.Metrics`
- **Documentation:** <https://getakka.net/articles/clustering/cluster-metrics.html>
### 8. Persistence (Akka.Persistence)
Enables actors to persist their state as a sequence of events (event sourcing) or snapshots. On restart or migration, the actor replays its event journal to recover state. Supports pluggable journal and snapshot store backends (SQL Server, PostgreSQL, SQLite, MongoDB, etc.).
- **NuGet Package:** `Akka.Persistence`
- **Documentation:** <https://getakka.net/articles/persistence/architecture.html>
- **Configuration Reference:** <https://getakka.net/articles/configuration/modules/akka.persistence.html>
- **Persistence Query (CQRS Projections):** <https://getakka.net/articles/persistence/persistence-query.html>
### 9. Distributed Data (Akka.DistributedData)
Shares data across cluster nodes using Conflict-Free Replicated Data Types (CRDTs). Supports reads and writes even during network partitions, with eventual consistency guarantees and automatic conflict resolution.
- **NuGet Package:** `Akka.DistributedData`
- **Documentation:** <https://getakka.net/articles/clustering/distributed-data.html>
### 10. Streams (Akka.Streams)
A higher-level abstraction on top of actors for building reactive, back-pressured stream processing pipelines. Implements the Reactive Streams standard. Provides composable building blocks: `Source`, `Flow`, `Sink`, and `Graph` DSL.
- **NuGet Package:** `Akka.Streams`
- **Documentation:** <https://getakka.net/articles/streams/introduction.html>
- **Modularity & Composition:** <https://getakka.net/articles/streams/modularitycomposition.html>
---
## Hosting & Integration
### 11. Akka.Hosting
The recommended modern integration layer for Akka.NET with the `Microsoft.Extensions.*` ecosystem (Hosting, DependencyInjection, Configuration, Logging). Provides HOCON-less, code-first configuration and an `ActorRegistry` for injecting actor references into ASP.NET Core, SignalR, gRPC, and other DI-based services.
- **NuGet Package:** `Akka.Hosting`
- **GitHub / Documentation:** <https://github.com/akkadotnet/Akka.Hosting>
- **Sub-packages:**
- `Akka.Remote.Hosting` — Akka.Remote configuration via Hosting
- `Akka.Cluster.Hosting` — Akka.Cluster, Sharding, and Tools configuration via Hosting
- `Akka.Persistence.Hosting` — Persistence configuration via Hosting
### 12. Akka.DependencyInjection
Integrates `Microsoft.Extensions.DependencyInjection` (or other DI containers) directly into actor construction, allowing actors to receive injected services through their constructors.
- **NuGet Package:** `Akka.DependencyInjection`
- **Documentation:** <https://getakka.net/articles/actors/dependency-injection.html>
---
## Discovery & Management
### 13. Akka.Discovery
Provides a pluggable service discovery API for dynamically locating cluster nodes in cloud and containerized environments. Ships with a built-in config-based discovery method and supports plugins for AWS, Azure, Kubernetes, and more.
- **NuGet Package:** `Akka.Discovery` (core); provider-specific packages (e.g. `Akka.Discovery.Azure`, `Akka.Discovery.AwsApi`, `Akka.Discovery.KubernetesApi`)
- **Documentation:** <https://getakka.net/articles/discovery/index.html>
### 14. Akka.Management
A toolkit for managing and bootstrapping Akka.NET clusters in dynamic environments. Exposes HTTP endpoints for cluster coordination and works with Akka.Discovery to enable safe, automated cluster formation via Cluster Bootstrap (replacing static seed nodes).
- **NuGet Package:** `Akka.Management`
- **Documentation:** <https://getakka.net/articles/discovery/akka-management.html>
- **GitHub:** <https://github.com/akkadotnet/Akka.Management>
### 15. Akka.Coordination
Provides lease-based distributed locking primitives used by Split Brain Resolver, Cluster Sharding, and Cluster Singleton to prevent split-brain scenarios. Backend implementations include Azure Blob Storage (`Akka.Coordination.Azure`).
- **NuGet Package:** `Akka.Coordination.Azure`
- **Documentation (Azure Lease):** <https://github.com/akkadotnet/Akka.Management> (see Coordination section)
---
## Testing
### 16. Akka.TestKit
The base testing framework for Akka.NET actors. Provides `TestProbe`, `TestActorRef`, `EventFilter`, and other utilities for unit and integration testing of actor-based systems. Requires a test-framework-specific adapter package.
- **NuGet Package:** `Akka.TestKit` (base), `Akka.TestKit.Xunit2`, `Akka.TestKit.NUnit`, `Akka.TestKit.MSTest`
- **Documentation:** <https://getakka.net/articles/actors/testing-actor-systems.html>
### 17. Akka.Hosting.TestKit
An integration testing toolkit built on top of `Akka.Hosting` and xUnit. Provides a `TestKit` base class that spins up a full `Microsoft.Extensions.Hosting` environment with DI, logging, and Akka.NET — ideal for testing actors alongside other services.
- **NuGet Package:** `Akka.Hosting.TestKit`
- **NuGet Page:** <https://www.nuget.org/packages/Akka.Hosting.TestKit>
### 18. Akka.MultiNodeTestRunner
Infrastructure for running distributed, multi-node integration tests across multiple actor systems. Used to validate cluster behavior, split-brain scenarios, and network partition handling.
- **GitHub:** <https://github.com/akkadotnet/Akka.MultiNodeTestRunner>
---
## Networking
### 19. Akka.IO
Low-level, actor-based TCP and UDP networking built into the core Akka library. Provides non-blocking I/O through an actor API rather than traditional socket programming.
- **Part of the core `Akka` NuGet package**
- **Documentation (TCP):** <https://getakka.net/articles/networking/io.html>
---
## Serialization & Configuration
### 20. Serialization
Akka.NET includes a pluggable serialization system used for message passing (both local and remote). The default serializer is JSON-based; high-performance alternatives include Hyperion and custom `Serializer` implementations. Serialization is critical for Remoting, Persistence, and Cluster Sharding.
- **Part of the core `Akka` NuGet package**
- **Documentation:** <https://getakka.net/articles/networking/serialization.html>
### 21. HOCON Configuration
Akka.NET uses HOCON (Human-Optimized Config Object Notation) as its primary configuration format. HOCON supports includes, substitutions, and hierarchical keys. With `Akka.Hosting`, HOCON can be replaced entirely by code-first configuration.
- **Documentation:** <https://getakka.net/articles/configuration/hocon.html>
- **Module Configs:** <https://getakka.net/articles/configuration/modules/akka.html>
---
## Persistence Providers (Selected)
Akka.Persistence supports pluggable backends. Some notable provider packages:
| Provider | NuGet Package | Documentation / GitHub |
|---|---|---|
| SQL (Linq2Db — SQL Server, PostgreSQL, SQLite, MySQL, Oracle) | `Akka.Persistence.Sql` | <https://github.com/akkadotnet/Akka.Persistence.Sql> |
| MongoDB | `Akka.Persistence.MongoDb` | <https://github.com/akkadotnet/Akka.Persistence.MongoDB> |
| Azure (Table Storage / Blob Storage) | `Akka.Persistence.Azure` | <https://github.com/petabridge/Akka.Persistence.Azure> |
---
## Logging Integrations
| Logger | NuGet Package | GitHub |
|---|---|---|
| Serilog | `Akka.Logger.Serilog` | <https://github.com/akkadotnet/Akka.Logger.Serilog> |
| NLog | `Akka.Logger.NLog` | <https://github.com/akkadotnet/Akka.Logger.NLog> |
---
## Additional Resources
- **Official Documentation Home:** <https://getakka.net/>
- **GitHub Organization:** <https://github.com/akkadotnet>
- **Modules Overview:** <https://getakka.net/articles/intro/modules.html>
- **Bootcamp (Learn Akka.NET):** <https://learnakka.net/>
- **Example Projects:** <https://getakka.net/articles/examples.html>
- **Community Discord:** <https://discord.gg/GSCfPwhbWP>
- **Petabridge (Commercial Support):** <https://petabridge.com/>
Reference in New Issue View Git Blame Copy Permalink