Repository navigation
Conversation
iter to the Workflow Stream, with Direct reads and appends in Coreiter to the Workflow Stream, with Direct reads, appends and closes in Core
moetemp
force-pushed
the
moe/streams-api
branch
from
November 15, 2026 18:51
4c5003d to
09d01f5
Compare
moetemp
force-pushed
the
moe/streams-direct
branch
from
November 15, 2026 18:51
a5fa03c to
7dabd9f
Compare
moetemp
force-pushed
the
moe/streams-api
branch
from
November 15, 2026 20:23
09d01f5 to
acf7b46
Compare
moetemp
force-pushed
the
moe/streams-direct
branch
from
November 15, 2026 20:23
7dabd9f to
f7eb673
Compare
This was referenced Nov 16, 2026
moetemp
force-pushed
the
moe/streams-api
branch
from
November 16, 2026 17:14
acf7b46 to
5c6e8a8
Compare
moetemp
force-pushed
the
moe/streams-direct
branch
from
November 16, 2026 17:14
4e0334b to
b556665
Compare
moetemp
force-pushed
the
moe/streams-api
branch
from
November 16, 2026 17:33
5c6e8a8 to
d6d4073
Compare
moetemp
force-pushed
the
moe/streams-direct
branch
from
November 16, 2026 17:33
b556665 to
dd3836f
Compare
moetemp
force-pushed
the
moe/streams-api
branch
from
November 16, 2026 19:42
d6d4073 to
d6dda76
Compare
moetemp
force-pushed
the
moe/streams-direct
branch
2 times, most recently
from
November 16, 2026 20:45
65fd4dd to
88cddf9
Compare
Core now reads and appends a Stream inside the Workflow Task. The bridge protos and the payload visitor follow its new commands and jobs, so a payload codec covers their bodies.
The WIT declares `iter` as a helper method of the Workflow Stream. Only that file differs from the pin before, so the bridge needs no rebuild.
The Stream WIT marks `iter` with `@nexus.helper sync=true` and returns a support class. Only a fork of nexgen knows these tags until its `main` has them.
Core reads and appends a Stream of Workflow code through the runtime of its Store. The Worker and the Replayer pass one for each Store of the client's Stream config that has one.
Core reads the Store and gives each page to the read in an activation, so a read costs one marker for each Workflow Task. `StreamConfig.workflow_read_replay_from` decides whether History holds the Records.
An append of a Workflow Producer on a Store with a Rust runtime goes to Core, which writes it as the Workflow with the task as its epoch. Its tests now expect that Producer and that marker.
A marker with the Records needs no Store, so a Replayer with no Stream config can replay it. The read takes its Store from the ref, as the first run had it.
The tests cover each stop, the marker, replays, a Worker with no cache, a failed task, a Signal, a Store written in Python and a payload codec, and measure a read of 200 Records.
A read keeps its Workflow Task open, and a replay of a `STORE` read needs the Records in the Store. The README, the changelog and the docs of the Store and the Replayer now say so.
Core now orders a Workflow's close after its own appends and evicts a replay whose marker Records can't be read. Its protos didn't change, so the bridge protos and the visitor stay.
Core ends such a read with Done, and counts the idle time only while a read waits for the Store. The stops, `iter_stream` and the README now say so.
A failed replay now reaches the caller with no cut-off, raised or in the result. New tests cover a second read after a `break`, a completion, a cancel and a continue-as-new.
Core now gives a replayed call with no Store name the Store of its entry in History. So a Replayer with no Stream config replays a Direct append and a `HISTORY` read of such a ref.
A second task that waited on one read replaced the future of the first, which then never woke. A Record that failed to decode moved `last_offset` past it, so a new read lost it.
The Local Activity path, a client and an Activity run it with no serialization context. A codec with a context then wrote bodies that no other reader of the Stream could decode.
Three Workflows dropped the outer loop that only the 1 s default needed. A plain `iter` now reads across a quiet gap, and a zero ends with `Idle` on an empty Stream.
A read with a short timeout gave no Record when its Workflow Task started late, which failed a test on the cloud run. The stubs of the Core protos have the new comments of the read bounds.
Core now records metrics for the Direct calls, and a graceful shutdown waits for a close in flight. Its protos changed only in a comment that the generated files already had.
A close that the code doesn't await is lost only when the Worker dies or the Store doesn't answer in 10 s. The README lists the metrics that Core records for the Direct calls.
One Workflow reads, appends and closes, and the buffer of its Runtime has each metric with its count and Store. A shutdown returns after a close that the code didn't await.
The fork has `@nexus.helper`, its `sync` form and `@nexus.support-type` in one pull request. The generated Stream package is the same with it.
The marker now holds each Stream ref once, so the generated stubs of `external_data` change. No Python code reads a marker entry's Stream ref.
A read stops asking the Store while that many bytes of its Records wait for Workflow code. The Worker and the Replayer give the bound to Core through the bridge.
A copy of each Record to another Stream is work that an Activity could do itself. The example now starts each tool as its call arrives, and the docs tell of the read-ahead bound.
The first tool starts before the model Activity completes. A bound below 1 raises, and a bound of 1 byte still gives every Record in order.
The stub of the Stream messages has the new comment, which says who sets the epoch.
Core adds a batch window and an idle default of 1 minute to a read, and can fail the Workflow when a replay lost its Records. Only comments of the generated stubs change.
`StreamConfig.workflow_read_batch_window` bounds how often a read activates a Workflow. `StreamReplayError` in the failure types fails the Workflow when a replay lost its Records.
A read with no `idle_timeout` now ends after 1 minute, so code on a quiet Stream checks `done`. The docs also say that an append is at-least-once, and give the 1 MiB marker rule.
A window of 1 s joins the four later Records of a read in one batch, and a zero window gives more batches. Lost Records fail the task by default, or the Workflow with the setting.
Core vendors the WIT that has no separate Workflow read, and its Store option is called `producer_idle_ttl`, as on the base branch.
The base branch runs a Workflow's close on a Store written in Python in a Local Activity, so the docs of this branch follow it.
A close on a Python Store runs in a Local Activity. The Direct close test of a failed task needs a Workflow that fails in the task of the intent.
The Workflow `Stream` reads with the same `read`, `iter_read` and `iter_read_items` as a client, so the generated Workflow target has no `iter`.
Workflow code reads with the same `read`, `iter_read` and `iter_read_items` as a client, so the separate `iter` and `StreamReading` go. A Core read that no call waits on closes before the activation completes, so it never holds a Workflow Task open for nobody.
The stops, `last_offset` of a read and the idle default of one minute are gone. A loop on a quiet Stream ends with `iter_read` after an empty page, and the costs that still hold stay.
mypy wants a type for the handle of a Nexus read and a mapping for the read cases, and basedpyright can't see that the instance uses `_DirectRead`.
moetemp
force-pushed
the
moe/streams-direct
branch
from
November 17, 2026 06:51
88cddf9 to
5fe21e2
Compare
iter to the Workflow Stream, with Direct reads, appends and closes in CoreA Workflow counts how often it wakes while it reads, and starts an Activity at a count. A replay starts it at the same Record, since the marker has the activation of each page. With other activations in the marker, the replay is a non-determinism error.
The earlier test counted the wakes with one condition. This one has the shape of the example, where each Record starts a task that counts and the loop starts an Activity when the count is 2.
An Activity between Records of one page is a later Workflow Task. The marker stays on the task that received the page.
Core tries a Direct read, append or close again while its Store is unavailable. A replay whose Store stays down fails only its Workflow Task.
A proxy in front of Redis drops each connection while it is down. The tests check that an append and a read give each Record once, and that a replay fails only its task.
Core tries a Direct call again while its Store is unavailable. A replay whose Store stays down fails only its Workflow Task, so `StreamReplayError` says it is not that error.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed?
This PR lets Workflow code read a Stream, with the same
read,iter_readanditer_read_itemsas a client. It also makes the WorkflowappendandcloseDirect calls. Core calls the Store itself, and Workflow code gets each Record as it arrives.It's a prototype, created for the purpose of getting your feedback on the API. Its base is #2129, and Core's side is temporalio/sdk-rust#1801.
readgives one page, anditer_readanditer_read_itemsgive every page and every Record, as on a client. Withwait, a call waits that long for a new Record and then gives an empty page. With nowait, it gives what is in the Stream. The iterators end when the Stream is closed and read to its end, and with nowaitalso when they catch up.append. It keeps its signature. Core writes the Records with the Workflow as the Producer and the Workflow Task as the epoch, and no Local Activity runs.close. It keeps its signature. The Workflow Task that asks for the close records only the intent. Core closes the Stream after the server took that task, and the next task gives the result. So an awaited close spans two Workflow Tasks, and no Activity runs. A Workflow Task that fails closes nothing, so its retry can still append.core_streammarker for each Workflow Task that it spans, whatever the number of Records. By default the marker has a range, a count and a digest. Withworkflow_read_replay_from=StreamReplaySource.HISTORYon theStreamConfig, it has the Records.StreamReplayErrormessage.StreamConfig.workflow_read_ahead_byteschanges that bound.StreamConfig.workflow_read_batch_windowchanges it, and zero turns it off.StreamReplayErrorinworkflow_failure_exception_types, the Workflow fails instead, as forNondeterminismError.temporal_stream_read_recordsandtemporal_stream_append_latency, each with astream_storeattribute. The README of the Streams helpers has the list.ReadRecords, so a Workflow outbound interceptor sees each page read, as it sees an append.MemoryStreamStoredo. For a Store written in Python,appendandclosekeep their Local Activity, and a read fails the Workflow.It depends on two things that have no release yet.
Streamgets its poll iterators from feat: generate the@nexus.polliterators for the Workflow target moetemp/nexgen#123, which is on a fork. So thecheck-protosjob builds the Stream package with a commit of that fork.readon both targets.Why?
A library that iterates a Stream in Workflow code needs each Record while its Producer still runs. ADK is an example, since its own loop reads the model through an async generator. On #2129, Workflow code can't read a Stream at all.
It has these costs.
wait, a quiet Stream gives empty pages, so code on a Stream that can be quiet for long usesiter_readand leaves the loop after an empty page.HISTORY.This point is open.
waitmakes one more read at its end, which gives the empty page that ends it.How did you test it?
The tests are in
tests/nexus/test_stream_direct.py. They run on the local dev server with the memory Store. They cover a generator overiter_read_itemsthat reads the Stream of a running Activity, a read with and with nowait, pages ofmax_recordsandmax_bytes, a loop that keeps one Core read, a loop that awaits an append for each Record, a read across a quiet gap, the marker with and without Records, a replay with and without a Stream config, a Worker with no cache, a Workflow Task that fails in the middle of a read, a cancel and acontinue_as_newwith a read open, two loops from one offset, an interceptor that sees each page read, a payload codec, the metrics, the read-ahead bound, the batch window, a Workflow failure for lost Records, a tool Activity that starts from inside the loop, and a close in two Workflow Tasks (in afinally, after a failed task, and with a cancel). A Redis test reads withiter_read_itemswhile an Activity appends, and replays its History from Redis.Link to a test plan if any -