Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Allow a timer summary on Workflow.sleep and Workflow.await with timeout

Open
  • Is something wrong?
#3,108 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 2 days

@sangkyoonnam is already working on this.

Since Oct 1, 2026.

  • #3109 by @sangkyoonnam — open

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
55/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
java
Domain
api, backend, distributed-systems

Research direction

Start with SyncWorkflowContext.java:1368-1401 and trace the Workflow sleep/await APIs into WorkflowOutboundCallsInterceptor, its Base, and TracingWorkerInterceptor. Add the proposed TimerOptions overloads while preserving both CANCEL_AWAIT_TIMER_ON_CONDITION branches, then verify replay compatibility with an old history that has no timer summary.

Written by the indexing model from the issue text.

Description

enhancement

Is your feature request related to a problem? Please describe.

Workflow.newTimer(Duration, TimerOptions) can set a summary, but Workflow.sleep(Duration) and Workflow.await(Duration, Supplier) create their timers with default options (SyncWorkflowContext.java:1368-1401). I'd like sleep and timed await to accept TimerOptions, so a workflow waiting on a human approval with a timeout can label that timer. Today the workaround for sleep is Workflow.newTimer(d, options).get(). For a timed await you have to race the condition against your own timer and cancel it yourself, which is what await already does internally. temporalio/features#669 tracks this across SDKs.

Describe the solution you'd like

// Workflow
public static void sleep(Duration duration, TimerOptions options);
public static boolean await(Duration timeout, TimerOptions options, Supplier<Boolean> unblockCondition);

// WorkflowOutboundCallsInterceptor (+ Base)
void sleep(Duration duration, TimerOptions options);
boolean await(Duration timeout, TimerOptions options, String reason, Supplier<Boolean> unblockCondition);

This follows #2218, which added newTimer(Duration, TimerOptions) to the interceptor, its Base, and TracingWorkerInterceptor. The interface is @Experimental, but direct implementers still get a source change. Replay checks the timer command type and ID, not its user metadata, so I don't expect this to need a new SDK flag. I haven't verified that against a replay yet. Both await branches under CANCEL_AWAIT_TIMER_ON_CONDITION (enabled in #3099) would keep their behavior.

Other SDKs: Python has workflow.sleep(..., summary=) and workflow.wait_condition(..., timeout_summary=). Go has workflow.AwaitWithOptions with AwaitOptions{Timeout, TimerOptions}. PHP added AwaitOptions to Workflow::awaitWithTimeout() in temporalio/sdk-php#805.

Describe alternatives you've considered

An AwaitOptions class like Go and PHP. It leaves room for more await settings but adds a type for one field today.

Additional context

This doesn't cover sleep(long, ...) or timed Promise.get, which also goes through await. I'd like to implement it, with a replay test against an old history that has no summary. I'll go with the TimerOptions overloads unless you'd rather have AwaitOptions.

Dominant language
Java
Stars
433
Forks
257
Avg merge
2d 22h
Merged PRs (30d)
22

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from temporalio/sdk-java

All issues in temporalio/sdk-java

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.