Deprecate cloudevents messages

[acroca]

Description

dapr.ext.grpc topic handlers have always received a cloudevents.sdk.event.v1.Event. This PR deprecates that in favor of the SDK-owned SubscriptionMessage, the same type the streaming subscription API (DaprClient.subscribe()) already delivers, as the first step toward removing the cloudevents dependency from the grpc extra entirely.

Why

• The SDK uses the cloudevents library purely as a data container: daprd does all CloudEvents enveloping/parsing and delivers pre-parsed fields over gRPC. No marshalling code is ever used.
• The type leaks into users' handler signatures, so cloudevents' internal layout is effectively our public API. cloudevents 2.0 moved cloudevents.sdk.* to cloudevents.v1.sdk.*, which breaks both the extension and every user import (see the dependabot bump chore(deps): Bump cloudevents from 1.12.1 to 2.2.0 #1113). Upstream has moved 1.x to security-fixes-only support.
• The borrowed type also doesn't fit Dapr's delivery model: the topic name was stuffed into Subject, and gRPC metadata was crammed into extensions as _metadata_* keys. SubscriptionMessage has first-class topic() / pubsub_name(), and gains a metadata() accessor here.

How it works

The delivered type is inferred from the handler's event-parameter annotation, no new parameters on App() or subscribe():

from dapr.ext.grpc import App, SubscriptionMessage

app = App()

@app.subscribe(pubsub_name='pubsub', topic='orders')
def new_style(event: SubscriptionMessage):   # annotated → SubscriptionMessage, no warning
    data = event.data()                       # parsed by content type

@app.subscribe(pubsub_name='pubsub', topic='orders2')
def old_style(event):                         # unannotated (or v1.Event) → legacy Event
    ...                                       # + DeprecationWarning at registration

Backward compatibility

• Existing handlers (unannotated or annotated with v1.Event) receive the exact same v1.Event as before, byte-for-byte, plus one DeprecationWarning per subscription at registration time (not per event).
• SubscriptionMessage.__init__ gains an optional metadata parameter, additive; streaming API callers are unaffected (metadata() is empty there).

Note for maintainers: deprecation timeline

The legacy cloudevents handler type is removed by 1.22:

[codecov]

Codecov Report

❌ Patch coverage is 92.59259% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.22%. Comparing base (bffb749) to head (5611baa).
⚠️ Report is 168 commits behind head on main.

Files with missing lines	Patch %	Lines
dapr/ext/grpc/_servicer.py	91.37%	5 Missing ⚠️
dapr/ext/grpc/app.py	94.11%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1118      +/-   ##
==========================================
- Coverage   86.63%   82.22%   -4.42%     
==========================================
  Files          84      116      +32     
  Lines        4473     9618    +5145     
==========================================
+ Hits         3875     7908    +4033     
- Misses        598     1710    +1112     

☔ 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 updates the dapr.ext.grpc pub/sub callback surface to support delivering the SDK-owned SubscriptionMessage to topic handlers (instead of leaking cloudevents.sdk.event.v1.Event), while preserving the legacy CloudEvents delivery path and emitting a deprecation warning for legacy handler signatures.

Changes:

• Added handler event-type inference based on the first parameter’s type annotation to choose between legacy v1.Event delivery and new SubscriptionMessage delivery.
• Plumbed a legacy_cloudevent flag through _CallbackServicer and added support for populating SubscriptionMessage.metadata() from gRPC invocation metadata (and bulk entry metadata).
• Updated examples and tests to use/validate SubscriptionMessage delivery and the deprecation behavior.

Reviewed changes

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

Show a summary per file

File	Description
tests/integration/apps/pubsub_subscriber.py	Migrates integration subscriber to SubscriptionMessage and persists raw_data()
tests/ext/grpc/test_servicier.py	Adds coverage for legacy vs SubscriptionMessage delivery (single + bulk) including metadata
tests/ext/grpc/test_app.py	Adds tests for annotation-based inference and deprecation warnings
examples/pubsub-simple/subscriber.py	Updates example handlers to SubscriptionMessage APIs (data(), topic(), metadata())
dapr/ext/grpc/app.py	Implements annotation inference + deprecation warning; wires legacy_cloudevent through registration
dapr/ext/grpc/AGENTS.md	Updates extension guidance/docs to prefer SubscriptionMessage and documents deprecation timeline
dapr/ext/grpc/_servicer.py	Adds dual delivery path (v1.Event vs SubscriptionMessage) and metadata plumbing (single + bulk)
dapr/ext/grpc/init.py	Re-exports SubscriptionMessage from the SDK common module
dapr/common/pubsub/subscription.py	Extends SubscriptionMessage with optional metadata and accessor

---

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