[m3nax]

Description

Add support for actor list/get timers runtime methods dapr/dapr#10461

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: #1948

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

[Copilot]

🟡 Changes recommended

TTL timestamp parsing breaks sidecar queries, and completed local one-shot timers remain queryable.

2 open issues

• Parse absolute timer expiration timestamps in get and list responses · New
• Remove completed no-TTL one-shot timers from scheduler lookups · New

What changed in this PR

Adds actor timer get/list support across Actors.Next schedulers for the Dapr 1.19 runtime APIs, addressing #1948.

Changes:

• Adds timer query contracts, sidecar mappings, and local scheduler implementations.
• Adds unit and real-sidecar coverage.
• Introduces an HTTP timer example with Aspire hosting.

File	Description
test/​Dapr.IntegrationTest.Actors.Next/​RealSidecarActorTests.cs	Tests real-sidecar timer queries.
test/​Dapr.Actors.Next.Testing.Test/​ActorTestRuntimeTests.cs	Tests virtual timer queries and expiry.
test/​Dapr.Actors.Next.StateMachine.Test/​StateMachineEdgeTests.cs	Updates the scheduler stub.
test/​Dapr.Actors.Next.Core.Test/​TimerConcurrencyTests.cs	Tests local timer queries.
test/​Dapr.Actors.Next.Core.Test/​SidecarAdapterTests.cs	Tests request mapping and authentication.
src/​Dapr.Actors.Next.Testing/​VirtualActorTimeProvider.cs	Implements virtual timer queries.
src/​Dapr.Actors.Next.Core/​Timers/​IActorTimerScheduler.cs	Defines get/list methods.
src/​Dapr.Actors.Next.Core/​Timers/​DaprSidecarActorTimerScheduler.cs	Implements sidecar timer queries.
src/​Dapr.Actors.Next.Core/​Timers/​DaprSidecarActorReminderScheduler.cs	Reuses shared payload decoding.
src/​Dapr.Actors.Next.Core/​Timers/​CoreActorTimerScheduler.cs	Stores queryable timer metadata.
src/​Dapr.Actors.Next.Core/​Timers/​ActorTimerInfo.cs	Adds timer result records.
src/​Dapr.Actors.Next.Core/​Timers/​ActorSchedulePayloadDecoder.cs	Extracts shared payload decoding.
examples/​Actor.Next/​README.md	Links the timer example.
examples/​Actor.Next/​08-Timers/​Timers.Next.Example08.Tests/​Timers.Next.Example08.Tests.csproj	Defines the example test project.
examples/​Actor.Next/​08-Timers/​Timers.Next.Example08.Tests/​TimerDemoActorTests.cs	Tests the example with virtual time.
examples/​Actor.Next/​08-Timers/​Timers.Next.Example08.http	Provides sample HTTP requests.
examples/​Actor.Next/​08-Timers/​Timers.Next.Example08.csproj	Defines the example application.
examples/​Actor.Next/​08-Timers/​Timers.Next.Example08.AppHost/​Timers.Next.Example08.AppHost.csproj	Defines Aspire hosting dependencies.
examples/​Actor.Next/​08-Timers/​Timers.Next.Example08.AppHost/​Properties/​launchSettings.json	Configures dashboard launch settings.
examples/​Actor.Next/​08-Timers/​Timers.Next.Example08.AppHost/​Directory.Build.props	Imports target framework settings.
examples/​Actor.Next/​08-Timers/​Timers.Next.Example08.AppHost/​AppHost.cs	Configures application and sidecar hosting.
examples/​Actor.Next/​08-Timers/​TimerDemoActor.cs	Demonstrates timer management.
examples/​Actor.Next/​08-Timers/​README.md	Documents setup and usage.
examples/​Actor.Next/​08-Timers/​Properties/​launchSettings.json	Configures application launch settings.
examples/​Actor.Next/​08-Timers/​Program.cs	Exposes HTTP endpoints and demo UI.
examples/​Actor.Next/​08-Timers/​appsettings.json	Configures HTTP and gRPC endpoints.
all.sln	Includes the example projects.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Payload decoding can corrupt timer data, microsecond periods can break inspection, and one-shot metadata differs across schedulers.

1 open issue

• Preserve HTTP timer arguments without incorrect base64 decoding · New

3 previously missed issues

In code that hasn't changed since last review

Normalize infinite timer periods to null in stored timer info

src/​Dapr.Actors.Next.Core/​Timers/​CoreActorTimerScheduler.cs:188

Scheduling with period: Timeout.InfiniteTimeSpan creates a one-shot timer, but Get/List expose its period as -1 ms here. The sidecar scheduler omits negative periods and returns null instead, so consumers see different metadata for the same registration in memory and in production. Normalize negative periods to null in the stored timer info.

Support Go microsecond suffix in timer duration parsing

src/​Dapr.Actors.Next.Core/​Timers/​DaprSidecarActorTimerScheduler.cs:300

The runtime returns a 250-microsecond timer period as @every 250µs, but ActorScheduleDurationParser recognizes only ASCII us. As a result, GetAsync throws for that timer, and one such timer makes the entire ListAsync call throw. Accept Go's µs suffix in both the parser's regular expression and unit conversion, and cover it in get/list response tests.

Normalize virtual scheduler infinite periods to null

src/​Dapr.Actors.Next.Testing/​VirtualActorTimeProvider.cs:839

The virtual scheduler also exposes Timeout.InfiniteTimeSpan as a -1 ms Period for one-shot timers. The sidecar returns null for this registration, so tests using virtual time observe different Get/List metadata from production. Normalize negative original periods to null when creating timer info, without changing reminder metadata.

2 resolved since last review

• Parse absolute timer expiration timestamps in get and list responses
• Remove completed no-TTL one-shot timers from scheduler lookups

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Valid sidecar timing formats can cause timer lookup and listing to fail during parsing.

No open issues 🎉

2 previously missed issues

In code that hasn't changed since last review

Support RFC 3339 absolute due times in timer mappings

src/​Dapr.Actors.Next.Core/​Timers/​DaprSidecarActorTimerScheduler.cs:289

Dapr accepts an absolute RFC 3339 dueTime and preserves that input in get/list responses. A timer registered with a timestamp, for example through HTTP, therefore reaches this duration-only parser and throws FormatException. The same mapping at line 299 makes one such timer prevent listing all timers for the actor. Define how absolute due times are represented in ActorTimerInfo, handle them in both mappings, and add get/list tests for timestamp-based registrations.

Handle Go microsecond units in timer duration parsing

src/​Dapr.Actors.Next.Core/​Timers/​DaprSidecarActorTimerScheduler.cs:300

A timer scheduled with a 0.5 ms period is returned by Dapr as @every 500µs. ActorScheduleDurationParser accepts ASCII us, but not Go's µs, so GetAsync throws FormatException; one such timer also makes the entire ListAsync call fail. Normalize the unit in both mappings, or support it in the shared parser, and add get/list regression coverage.

1 resolved since last review

• Preserve HTTP timer arguments without incorrect base64 decoding

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Valid timer durations can break queries, and one-shot period metadata does not consistently honor the public contract.

No open issues 🎉

4 previously missed issues

In code that hasn't changed since last review

Support Go-style duration formats in HTTP timer parsing

src/​Dapr.Actors.Next.Core/​Timers/​ActorScheduleDurationParser.cs:58

HTTP timers can use Go due times such as +1h, .5s, 1.s, and 1h.5m, which the runtime echoes unchanged. Parse cannot fully consume these forms and falls back to TimeSpan.Parse, which rejects their unit suffixes. As a result, GetAsync throws and one such registration makes ListAsync fail for the entire actor. Support the leading sign and leading/trailing decimal-point forms in the shared parser, with regression tests for these inputs.

Normalize nonpositive timer periods to null metadata

src/​Dapr.Actors.Next.Core/​Timers/​CoreActorTimerScheduler.cs:188

Passing TimeSpan.Zero or Timeout.InfiniteTimeSpan as the period creates a one-shot timer, but this stores a non-null Period in its get/list metadata. That contradicts ActorTimerInfo.Period's null-for-one-shot contract and misclassifies the timer for callers using Period.HasValue. Normalize nonpositive periods to null when constructing the metadata, and cover both values in the core scheduler tests.

Map sidecar zero-period timers to null periods

src/​Dapr.Actors.Next.Core/​Timers/​DaprSidecarActorTimerScheduler.cs:316

An explicitly registered zero period is returned by the sidecar as @every 0s for a one-shot timer. This mapping exposes TimeSpan.Zero instead of the null promised by ActorTimerInfo.Period, so callers using Period.HasValue misclassify it as periodic. Normalize nonpositive parsed periods to null and add a sidecar mapping test for @every 0s.

Normalize virtual scheduler one-shot periods to null

src/​Dapr.Actors.Next.Testing/​VirtualActorTimeProvider.cs:839

The virtual scheduler treats zero and Timeout.InfiniteTimeSpan periods as one-shot, but this mapping returns those values as a non-null Period. This violates ActorTimerInfo.Period's null-for-one-shot contract and misclassifies timers for callers using Period.HasValue in ActorTestRuntime. Normalize nonpositive periods to null here and cover both inputs in the virtual scheduler tests.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Timer visibility differs between in-memory and sidecar execution, and the integration test's version gate permits an unsupported default runtime.

1 open issue

• Align test runtime gate with the fixture's resolved version · New

1 previously missed issue

In code that hasn't changed since last review

Keep one-shot timers queryable until callback dispatch completes

src/​Dapr.Actors.Next.Core/​Timers/​ScheduledActorCallback.cs:195

One-shot timers become unqueryable before their callbacks finish. Here, onCompleted removes the registration before runtime.DispatchAsync; the direct VirtualActorTimeProvider scheduler similarly sets Canceled = true before dispatch, so its new get/list methods exclude the timer. In the runtime implementation linked by this PR, removal happens after CallReminder returns. Consequently, a callback inspecting its own timer can find it through the sidecar but not through either in-memory scheduler. Keep an admitted one-shot queryable until dispatch finishes, including failure, without admitting it twice. Preserve cancellation and replacement identity checks, and add callback-level get/list tests for both implementations.

_{Review effort: Balanced}

[WhitWaldo]

@m3nax If you can confirm this is safe to take out of draft, I'd be happy to merge it into the 1.19 release (but note that you have about 6 hours until it'll have to wait for an SDK patch release).

[m3nax]

@WhitWaldo Some checks seem to be failing, but I don’t think they’re related to my changes. Could you re-run them manually? If they pass, I think everything’s ready.

[WhitWaldo]

Looks good to me - thank you for putting together this contribution!