GRPC Actors

[acroca]

Description

Adds alpha support for hosting Dapr actors over the app-initiated SubscribeActorEventsAlpha1 gRPC stream (dapr/dapr#9812). The app dials daprd's gRPC port, registers its actor types and runtime config in the stream's first message, and receives all actor callbacks, method invocations, reminders, timers, deactivations, pushed over that single stream. No inbound HTTP or gRPC port is needed for actor callbacks; outbound actor operations (state, reminders, timers, invocations) also go over daprd's gRPC API, so actor apps are fully gRPC-native.

The same actor classes, ActorRuntime, and ActorRuntimeConfig work unchanged on both transports, only the hosting service differs. HTTP actor hosting (FastAPI/Flask extensions) is untouched.

What's included

New public API (alpha)

• dapr.actor.ActorGrpcHost (dapr/actor/runtime/grpc_host.py), stream lifecycle: registration handshake (with timeout), concurrent callback dispatch with serialized stream writes and request/response correlation by id, automatic reconnect + re-registration after transient drops (UNAVAILABLE/UNKNOWN/INTERNAL, gated on channel_ready()), graceful shutdown with in-flight task draining. A stale-session guard ensures replies from handlers that outlive a connection are never sent on its successor.
• DaprActorGrpcClient (dapr/clients/grpc/dapr_actor_grpc_client.py), implements DaprActorClientBase over the unary actor RPCs (InvokeActor, GetActorState, ExecuteActorStateTransaction, reminder/timer registration incl. TTL and failure policies), with Dapr-Reentrancy-Id propagation. Closes the long-standing # TODO: We will allow to use gRPC client later in runtime.py.

Protocol semantics

• Error mapping: unknown actor type/method → request_failed with NOT_FOUND (permanent, non-retryable in daprd); application handler exceptions → invoke_response{error=true} carrying the same JSON payload the HTTP extensions return, so callers observe identical errors on both transports.
• Reminder/timer payloads arrive as BytesValue-packed Any; fire bodies are synthesized to match daprd's HTTP delivery byte-for-byte so ActorRuntime needs no changes. Timers registered via the unary gRPC RPC are base64-wrapped by daprd (json.Marshal of raw bytes); the host transparently recovers the original payload (documented edge case in _grpc_callbacks.py).
• Dapr-Reentrancy-Id and content-type metadata are propagated in both directions.

Supporting changes

• ActorRuntime.register_actor gains an additive actor_client parameter (defaults to the existing HTTP client).
• ActorRuntimeConfig/ActorTypeConfig/ActorReentrancyConfig gain read-only properties; the registration message is built from typed config objects rather than as_dict().
• create_aio_channel() / resolve_grpc_endpoint() (dapr/clients/grpc/_channel.py), single home for grpc.aio channel setup, now also used by DaprGrpcClientAsync (its inline channel construction is replaced).
• DAPR_REENTRANCY_ID_HEADER consolidated into dapr/clients/base.py.

Example, examples/demo_actor/demo_actor/demo_actor_grpc_service.py hosts the existing DemoActor over the stream; README section added. Note: daprd currently requires a gRPC app channel (--app-protocol grpc --app-port with a listener), so the example runs an empty grpc.aio.server() on the app port, no actor traffic flows through it.

Issue reference

Close: #1078

[codecov]

Codecov Report

❌ Patch coverage is 91.66667% with 43 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.97%. Comparing base (bffb749) to head (5f74ed5).
⚠️ Report is 142 commits behind head on main.

Files with missing lines	Patch %	Lines
dapr/actor/runtime/grpc_host.py	84.68%	36 Missing ⚠️
dapr/clients/grpc/dapr_actor_grpc_client.py	94.68%	5 Missing ⚠️
dapr/clients/grpc/_channel.py	93.33%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1081      +/-   ##
==========================================
- Coverage   86.63%   82.97%   -3.67%     
==========================================
  Files          84      150      +66     
  Lines        4473    15326   +10853     
==========================================
+ Hits         3875    12716    +8841     
- Misses        598     2610    +2012     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR introduces alpha gRPC-native actor hosting for the Dapr Python SDK via an app-initiated SubscribeActorEventsAlpha1 stream, enabling actor callbacks (invoke/reminder/timer/deactivate) to be delivered over a single outbound gRPC connection without HTTP callback endpoints. It also adds a gRPC-based outbound actor client so actor apps can operate without requiring daprd’s HTTP port.

Changes:

• Added ActorGrpcHost to host actors over the SubscribeActorEventsAlpha1 bidirectional stream with reconnect/dispatch behavior.
• Added DaprActorGrpcClient to perform outbound actor operations over unary gRPC actor RPCs (invoke/state/reminders/timers) and wired runtime registration to accept a pluggable actor client.
• Added unit + integration + example coverage for gRPC actor hosting, plus shared gRPC channel creation utilities and documentation updates.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
dapr/actor/__init__.py	Exposes ActorGrpcHost as a public actor API entrypoint.
dapr/actor/runtime/_grpc_callbacks.py	Builds stream registration + callback payloads and handles metadata extraction/heuristics.
dapr/actor/runtime/config.py	Adds read-only/snapshot properties for actor runtime/type/reentrancy config objects.
dapr/actor/runtime/grpc_host.py	Implements the alpha actor hosting service over the gRPC actor stream.
dapr/actor/runtime/runtime.py	Adds optional actor_client parameter to registration to support non-HTTP outbound ops.
dapr/aio/clients/grpc/client.py	Refactors async gRPC client to use shared channel creation + endpoint resolution.
dapr/clients/base.py	Centralizes DAPR_REENTRANCY_ID_HEADER constant.
dapr/clients/grpc/_channel.py	Adds shared resolve_grpc_endpoint() and create_aio_channel() helpers.
dapr/clients/grpc/dapr_actor_grpc_client.py	Adds gRPC actor client implementing outbound actor operations over unary RPCs.
dapr/clients/http/dapr_actor_http_client.py	Switches to the centralized reentrancy header constant.
docs/actor/actor.runtime.rst	Documents the new actor.runtime.grpc_host module in API docs.
examples/demo_actor/README.md	Adds “Run with gRPC actor hosting (alpha)” instructions.
examples/demo_actor/demo_actor/demo_actor_grpc_service.py	Adds gRPC-stream-hosted demo actor service (alpha).
tests/actor/test_actor_runtime_config.py	Adds tests validating new read-only config properties/snapshot behavior.
tests/actor/test_grpc_callbacks.py	Adds tests for registration message building + callback payload synthesis + heuristics.
tests/actor/test_grpc_host.py	Adds scripted fake-sidecar tests for ActorGrpcHost behavior.
tests/actor_grpc_utils.py	Adds helper probe to detect sidecar support for SubscribeActorEventsAlpha1.
tests/clients/fake_dapr_server.py	Extends fake daprd to support actor stream + unary actor RPCs for tests.
tests/clients/test_dapr_actor_grpc_client.py	Adds unit tests for DaprActorGrpcClient request shaping and behavior.
tests/examples/test_demo_actor_grpc.py	Adds example test for the gRPC-stream demo actor scenario.
tests/integration/apps/actor_grpc_host.py	Adds integration-test actor host subprocess using ActorGrpcHost.
tests/integration/test_actor_grpc.py	Adds end-to-end integration tests for stream-hosted actor callbacks and state.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 2 comments.