Skip to content

feat: let Core append to and close a Stream for Workflow code - #1801

Draft
moetemp wants to merge 2 commits into
moe/streams-crate-typesfrom
moe/streams-direct
Draft

moetemp wants to merge 2 commits into
moe/streams-crate-typesfrom
moe/streams-direct

Conversation

@moetemp

@moetemp moetemp commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

What was changed

This PR lets Core append to and close a Stream itself, for Workflow code.

It's a prototype, created for the purpose of getting your feedback on the design. Its base is #1817, and the Python SDK's side is temporalio/sdk-python#2132. The read of a Stream from Workflow code is a separate PR on top of this one, #1819.

  • Where the code is. The state of a run's Stream calls and the calls to the Store are in temporalio-streams, in its workflow module behind a cargo feature. Core has the commands, the marker machine and the handling of the Workflow Task.
  • Commands and jobs. AppendToStream and CloseStream are commands for Core, not for the server. ResolveStreamAppend and ResolveStreamClose give the results. The Worker gets its Stream runtimes in WorkerConfig::stream_runtimes, by Store name. The field numbers have gaps, which the commands and the job of the read take in feat: let Core read a Stream for Workflow code #1819.
  • An append keeps its Workflow Task open, as a Local Activity does, with the same heartbeat.
  • One core_stream marker for a Workflow Task. An append has its offsets or its failure. A close has its intent and its result. The marker is bounded at 256 KiB, and Core then rolls the task over.
  • Replay. Workflow code gets each result in the same activation as in the first run. An append calls no Store.
  • An append writes as the Workflow Producer, with the Workflow Task as its epoch.
  • A close takes effect after its Workflow Task is in History. The task records the intent, Core closes the Stream after the server took the task, and the next task gives the result. A failed task closes nothing.
  • A Store outage. Core tries an append or a close again for as long as the Store is unavailable. If one is still in the outage at the heartbeat of its Workflow Task, the task fails, and Core forces no task for it.
  • A graceful shutdown waits for a close in flight, for at most 10 s.
  • Metrics for appends and closes, with their failures and latencies.

Why?

Workflow code that appends token by token would need a Local Activity for each append, and each one writes a marker. With this PR, the appends of a Workflow Task share one marker. A close also needs an order that a Local Activity can't give. It takes effect only after the server has the task that asked for it, so a failed task closes nothing.

These points are open.

  • temporalio-sdk-core takes temporalio-streams as a plain dependency. Should it be a feature?
  • An append is at-least-once. A rerun of a failed task writes a second copy with a higher epoch.
  • The time in which an append holds its Workflow Task open counts toward the task duration warning. feat: let Core read a Stream for Workflow code #1819 leaves that time out.

Checklist

  1. How was this tested: the tests in crates/sdk-core/src/core_tests/streams.rs drive Core with a mock history and a test Store, TestStreamStore in core_tests/stream_store.rs. It has a rule of the Stream service only where a test of Core needs it. A cached run that gets another Worker's Stream events is evicted, and the tests of that are in feat: let Core read a Stream for Workflow code #1819, since they use a read. The integration tests that need a Temporal server have no Stream case yet.
  2. Any docs updates needed? No.

@moetemp moetemp changed the title feat: let Core read and append a Stream inside the Workflow Task feat: let Core read, append and close a Stream for Workflow code Nov 15, 2026
@moetemp
moetemp force-pushed the moe/streams-direct branch 2 times, most recently from 00ab95b to e8637fe Compare November 16, 2026 19:36
@moetemp
moetemp force-pushed the moe/streams-direct branch 2 times, most recently from 5170611 to 16fb9e1 Compare November 17, 2026 06:06
@moetemp
moetemp added this pull request to stack #1812 November 17, 2026 20:51
@moetemp
moetemp removed this pull request from stack #1812 November 17, 2026 22:01
@moetemp
moetemp force-pushed the moe/streams-direct branch 2 times, most recently from b4676e7 to 0bfdf6d Compare November 18, 2026 15:08
@moetemp
moetemp added this pull request to stack #1818 November 18, 2026 18:05
@moetemp
moetemp force-pushed the moe/streams-direct branch 2 times, most recently from 13d0f1c to c393914 Compare November 18, 2026 20:17
@moetemp
moetemp removed this pull request from stack #1818 November 18, 2026 20:21
Workflow code can append to and close a Stream through Core. The marker of a Workflow Task records
each result, so a replay calls no Store. The protos, the call code and Core's side are one commit,
since none compiles alone.
The tests drive a Worker on a mock history and a test Store. They cover the order of calls, replay,
a Store outage, the shutdown wait and the metrics.
@moetemp moetemp changed the title feat: let Core read, append and close a Stream for Workflow code feat: let Core append to and close a Stream for Workflow code Nov 19, 2026
@moetemp
moetemp changed the base branch from moe/streams-crate to moe/streams-crate-types November 19, 2026 05:44
@moetemp
moetemp added this pull request to stack #1820 November 19, 2026 05:46
@moetemp
moetemp removed this pull request from stack #1820 November 19, 2026 07:29

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant