Dapr Actors (Next) SDK

[WhitWaldo]

Description

This PR introduces a re-imagined implementation of the Dapr Actors SDK. In the longer term, it is intended to replace the current Dapr.Actors project, but that won't happen for quite some time. This is not a mere rewrite of the original SDK but rather an overhaul of the Dapr Actor SDK to support functionality that I've wanted to see in an actor framework in my years developing against actors. With the introduction of bidirectional gRPC stream support in v1.18 of the runtime, I thought now would be a good time to introduce this new project so I might take advantage of the opportunity to modernize the SDK and add this new functionality.

At a high level, the actor model itself is unchanged. Actors are still virtual, addressed by type and id, and support reentrancy, timers, reminders, and proxying. Dapr.Actors.Next is a separate package and is not API-compatible with Dapr.Actors, but it is fully wire-compatible with the Dapr runtime, so adopting it requires no runtime changes (except that prerequisite of v1.18). Adopting this package will require a rewrite of your actor implementation rather than being an in-place upgrade.

Two things drive the change. The first is the transport itself. Actor callbacks (invoke, reminder, timer, and deactivate) now arrive over a persistent, app-initiated bidirectional gRPC stream rather than per-call requests into hosted actor-handler endpoints. This is the same streaming pattern Dapr already uses for streaming pub/sub and workflow dispatch. It lowers per-call overhead and it means there are no actor handler endpoints to map. The second is the amount of work the SDK now does locally, on your side of the connection, to make actor code easier and safer to write, which is where most of the new functionality lives.

On the modernization front, the SDK is build for current .NET (supporting .NET 8, 9 and 10 and then 10 and 11 after the EOL of 8 and 9 later this year). Source generators replace the reflection-based proxy and dispatch machinery, which removes reflection from the hot path and makes the runtime packages trim- and Native-AOT-friendly. Nullable reference types are enabled across the public surface, registration and configuration follow the dependency injection and options patterns used elsewhere in the modern SDK, and serialization moves to the same pluggable IDaprSerializer abstraction that State Management and Workflows already use (System.Text.Json by default with no more DataContract or remoting/non-remoting proxy split). A set of Roslyn analyzers, several with code fixes, catch actor-specific mistakes at build time, from a state change that would break deserialization of existing data to blocking calls or wall-clock time reads inside a turn.

Beyond modernization, a package adds capabilities the original never had. State migration is handled through a versioned state envelope and typed upcaster chains, so older persisted state stays loadable under new code. A first-class state machine programming model lets actors that are genuinely state machines be authored as explicit transition tables, with a runtime-defined (interpreted) variant that can run a machine supplied as data and verify it before it goes live. Pub/sub-driven actors let an actor react to topic events through a single subscription attribute. A dynamic invocation surface allows calling actors by type, id, and method with no compile-time contract, which is also the natural path for cross-language callers.

The capability I'm most enthusiastic about, and the one that most justifies the effort, is testing. The hard parts of actors (reentrancy, a timer coming due mid-turn, duplicate or out-of-order delivery, a failure in the middle of a state write, etc.) are normally only reachable with a running sidecar and wall-clock timing, which makes them effectively untestable. This SDK ships an in-memory deterministic test runtime that isolates the sources of nondeterminism (transport, scheduling and time) behind abstractions, so the same actor code runs against either the real runtime or the test runtime. Concurrency races become plain, repeatable unit tests seeded for reproducibility, virtual time drives timers and reminders without real waits, faults can be injected deliberately, and state machines can be structurally verified, all with no sidecar, state store, or Docker. For deeper exploration, the runtime can optionally bridge to Microsoft Coyote which was the inspiration for this functionality. To be clear, this does not replace the end-to-end coverage afforded by Dapr.Testcontainers, which still proves the real protocol against a live sidecar; rather it supplements that with fast, deterministic testing of your actual application logic, letting you keep the bulk of your coverage in millisecond unit tests and reserve integration tests for what only a real runtime can prove.

A few design decisions are worth calling out explicitly because they shape how the SDK behaves. The host is build as a stream manager that opens one stream per hosted actor type, which gives per-type fault isolation, configuration and lifecycle. Consumption of the callback stream is non-blocking with the SDK owning backpressure. Delivery is treated as a first-class concept rather than as an afterthought: invokes are at-least-once, so turns must be safe to re-run, and reminders re-fire until acknowledged, so handlers must be idempotent. Reentrancy call-chain metadata is propagated automatically when reentrancy is enabled, so authors never have to manage headers by hand. A single [GenerateActorClient] interface can back multiple actor types.

In the dapr/docs repository, I'll be opening a separate documentation PR in the near future covering the concepts, a how-to guide, the state machine and dynamic invocation surfaces, testing and a full example suite with an accompanying tutorial, along with guidance for developers migrating from Dapr.Actors. My hope is that the tests, examples and inline structure make the intent legible in the meantime, and I welcome feedback on both the surface and the underlying design decisions.

Issue reference

We strive to have all PR being opened based on an issue, where the problem or feature have been discussed prior to implementation.

Please reference the issue this PR will close: #[issue number]

Checklist

Please make sure you've completed the relevant tasks for this PR, out of the following list:

• Code compiles correctly
• Created/updated tests
• Extended the documentation