Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
40 commits
Select commit Hold shift + click to select a range
68e449a
Moved Core to the Direct Stream reads and appends.
moetemp Nov 15, 2026
4df40d8
Moved Core to the Stream WIT with the Workflow `iter` read.
moetemp Nov 15, 2026
ce6a47f
Pinned the Stream generator to nexgen with sync helpers and regenerated.
moetemp Nov 15, 2026
c9b497e
Gave Core the Stream runtime of each Store on the bridge.
moetemp Nov 15, 2026
01f1aae
Added the Workflow `iter` read, which Core runs in the Workflow Task.
moetemp Nov 15, 2026
59df07f
Made Core append a Workflow's Records inside the Workflow Task.
moetemp Nov 15, 2026
2162bfa
Let a replay with no Stream config start a read that History holds.
moetemp Nov 15, 2026
4593c90
Tested the Direct reads and appends of a Stream in Workflow code.
moetemp Nov 15, 2026
c222f69
Documented the Direct reads and appends and their costs.
moetemp Nov 15, 2026
0a75d18
Moved Core to the fixes of the Direct Stream calls.
moetemp Nov 15, 2026
cdc3245
Documented that a cap on the last Record of a closed Stream gives Done.
moetemp Nov 15, 2026
2e8517c
Tested failed replays, the capped Done and a run's end with a read open.
moetemp Nov 15, 2026
8b1472f
Replayed Direct calls whose ref names no Store with no Stream config.
moetemp Nov 15, 2026
d09e60f
Tested the fixes of the review, and wrapped three long lines.
moetemp Nov 15, 2026
0d1b363
Woke every task that waits on a read, and kept a bad body readable.
moetemp Nov 15, 2026
48eb52e
Ran the codec on the Stream bodies of Direct calls with no context.
moetemp Nov 15, 2026
d07acc6
Gave Core the Store runtimes only from a Worker with Workflows.
moetemp Nov 15, 2026
6158817
Moved Core to its fix of the transition coverage report.
moetemp Nov 15, 2026
089a551
Fitted the Redis tests to the Direct append and tested iter on Redis.
moetemp Nov 15, 2026
7c19be1
Raised a failed read's error at every step of its loop.
moetemp Nov 15, 2026
76eda4d
Said that a Store isn't meant to be written in Python.
moetemp Nov 15, 2026
4b66753
Moved Core to the Direct close of a Stream.
moetemp Nov 15, 2026
27c4833
Made Core close a Workflow's Stream after the task that asked for it.
moetemp Nov 15, 2026
50a0d4b
Polled for Activity Tasks only when a Worker runs regular Activities.
moetemp Nov 15, 2026
3c96bdc
Documented the Direct close in two Workflow Tasks.
moetemp Nov 15, 2026
237953e
Tested the Direct close of a Stream in Workflow code.
moetemp Nov 15, 2026
180b8a7
Wrapped two lines of the Streams README.
moetemp Nov 15, 2026
f7eb673
Moved Core to its Stream tests that wait for events.
moetemp Nov 15, 2026
3770e14
Gave a read of Workflow code no idle bound when `idle_timeout` is None.
moetemp Nov 16, 2026
83bfff2
Documented that a read of Workflow code waits for the Stream's close.
moetemp Nov 16, 2026
4d3c7be
Tested a read with no idle bound, and a zero idle timeout.
moetemp Nov 16, 2026
dced32a
Moved Core to a read that looks at the Store before its timeout.
moetemp Nov 16, 2026
0a65041
Moved Core to its Stream metrics and the shutdown wait for a close.
moetemp Nov 16, 2026
ee134d8
Documented the Stream metrics and the shutdown wait for a close.
moetemp Nov 16, 2026
f52df40
Tested the Stream metrics and a shutdown with a close in flight.
moetemp Nov 16, 2026
1fe8433
Pinned the nexgen fork commit that has the helper method in one PR.
moetemp Nov 16, 2026
306d331
Moved Core to the read-ahead option and the smaller Stream marker.
moetemp Nov 16, 2026
737fa09
Added `StreamConfig.workflow_read_ahead_bytes` for Workflow reads.
moetemp Nov 16, 2026
0523af2
Showed a decision in Workflow code as the example of `iter`.
moetemp Nov 16, 2026
fc1fcce
Tested the tool-call example of `iter` and the read-ahead bound.
moetemp Nov 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -228,8 +228,8 @@ jobs:
- run: uv tool install poethepoet
- run: uv sync --all-extras
- run: cargo install --locked nexgen --version 0.2.8 --features advanced --force
# The Stream package needs the `main` of nexgen, which no release has yet.
- run: cargo install --locked --git https://github.com/temporalio/nexgen --rev 9653a0f5a845df0c5059554f1b5813db6a74cd1a --features advanced --root "$RUNNER_TEMP/nexgen-stream" nexgen
# The Stream package needs `@nexus.helper` with `sync=true`, which only a nexgen fork has.
- run: cargo install --locked --git https://github.com/moetemp/nexgen --rev e4b1f297e7a3fa8bc20fbf176fa2727c9e83a20f --features advanced --root "$RUNNER_TEMP/nexgen-stream" nexgen
- run: echo "NEX_GEN_STREAM_BIN=$RUNNER_TEMP/nexgen-stream/bin/nexgen" >> "$GITHUB_ENV"
- run: poe build-develop
- run: poe gen-protos
Expand Down
5 changes: 5 additions & 0 deletions changelog/added/patient-river-heron.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
Add `iter` to the Workflow `Stream`, so Workflow code reads each Record of a Stream as it arrives. By default a read has no bound and reads until the Stream is closed. A read that waits on a quiet Stream holds its Workflow Task open, with one Workflow Task about every 8 s, and an `idle_timeout` ends it with `Idle`. Core reads the Store inside the Workflow Task, and a read costs one marker in History for each Workflow Task that it spans. `StreamConfig.workflow_read_replay_from` decides whether the marker holds the Records (`StreamReplaySource.HISTORY`) or only their offsets and a digest, which a replay reads from the Store again (`StreamReplaySource.STORE`, the default).
A Workflow's append on the Redis Store or `MemoryStreamStore` now runs in Core inside the Workflow Task, with no Local Activity. It writes as the Workflow, with its Workflow Task as the epoch.
A Workflow's close on the Redis Store or `MemoryStreamStore` now runs in Core, with no Activity, and spans two Workflow Tasks. The task that calls `close` records the intent, Core closes the Stream after the server took that task, and the next task gives the result, so a failed task closes nothing. Await the close: a graceful shutdown of the Worker waits at most 10 s for a close that the code doesn't await, and a Worker that dies when the Workflow ends loses it. An append and a close of Workflow code always carry the Workflow Task as their epoch.
Core records metrics for the Direct calls of a Stream, such as `temporal_stream_read_total`, `temporal_stream_read_records` and `temporal_stream_close_latency`, each with the attribute `stream_store`.
Add `StreamConfig.workflow_read_ahead_bytes`, the most bytes of one read's Records that wait in the Worker for Workflow code, 4 MiB by default.
8 changes: 5 additions & 3 deletions scripts/gen_nexus_system_api.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,9 @@
workflow_init_path = base_dir / "temporalio" / "workflow" / "__init__.py"
NEX_GEN_VERSION = "0.2.8"
# The Stream package needs a newer nexgen, which rejects the other WITs. One pin is enough
# again once the api WITs and a nexgen release agree. No release has nexgen commit 9653a0f5,
# the `main` of nexgen, yet, so NEX_GEN_STREAM_BIN points at a build of it.
# again once the api WITs and a nexgen release agree. The Stream WIT uses `@nexus.helper` with
# `sync=true` and `@nexus.support-type`, which only the fork https://github.com/moetemp/nexgen
# has, at commit e4b1f297. So NEX_GEN_STREAM_BIN points at a build of that commit.
NEX_GEN_STREAM_VERSION = "0.2.12"
proto_files = [
gen_protos.api_proto_dir
Expand Down Expand Up @@ -87,7 +88,8 @@ def nex_gen_stream_command() -> list[str]:
bin_path = os.environ.get("NEX_GEN_STREAM_BIN")
if not bin_path:
raise RuntimeError(
"NEX_GEN_STREAM_BIN must point at a nexgen build of commit 9653a0f5"
"NEX_GEN_STREAM_BIN must point at a nexgen build of commit e4b1f297 "
"of https://github.com/moetemp/nexgen"
)
version = subprocess.check_output([bin_path, "--version"], text=True).strip()
if version != f"nexgen {NEX_GEN_STREAM_VERSION}":
Expand Down
1 change: 1 addition & 0 deletions temporalio/bridge/Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

59 changes: 53 additions & 6 deletions temporalio/bridge/_visitor.py
Original file line number Diff line number Diff line change
Expand Up @@ -308,6 +308,38 @@ async def _visit_coresdk_workflow_activation_ResolveNexusOperation(
if o.HasField("result"):
await self._visit_coresdk_nexus_NexusOperationResult(fs, o.result)

async def _visit_temporal_api_stream_v1_StreamRecord(
self, fs: VisitorFunctions, o: Any
):
if o.HasField("body"):
await self._visit_temporal_api_common_v1_Payload(fs, o.body)

async def _visit_coresdk_workflow_activation_StreamReadEnd(
self, fs: VisitorFunctions, o: Any
):
if o.HasField("failure"):
await self._visit_temporal_api_failure_v1_Failure(fs, o.failure)

async def _visit_coresdk_workflow_activation_ResolveStreamRead(
self, fs: VisitorFunctions, o: Any
):
for v in o.records:
await self._visit_temporal_api_stream_v1_StreamRecord(fs, v)
if o.HasField("end"):
await self._visit_coresdk_workflow_activation_StreamReadEnd(fs, o.end)

async def _visit_coresdk_workflow_activation_ResolveStreamAppend(
self, fs: VisitorFunctions, o: Any
):
if o.HasField("failed"):
await self._visit_temporal_api_failure_v1_Failure(fs, o.failed)

async def _visit_coresdk_workflow_activation_ResolveStreamClose(
self, fs: VisitorFunctions, o: Any
):
if o.HasField("failed"):
await self._visit_temporal_api_failure_v1_Failure(fs, o.failed)

async def _visit_coresdk_workflow_activation_WorkflowActivationJob(
self, fs: VisitorFunctions, o: Any
):
Expand Down Expand Up @@ -353,6 +385,18 @@ async def _visit_coresdk_workflow_activation_WorkflowActivationJob(
await self._visit_coresdk_workflow_activation_ResolveNexusOperation(
fs, o.resolve_nexus_operation
)
elif o.HasField("resolve_stream_read"):
await self._visit_coresdk_workflow_activation_ResolveStreamRead(
fs, o.resolve_stream_read
)
elif o.HasField("resolve_stream_append"):
await self._visit_coresdk_workflow_activation_ResolveStreamAppend(
fs, o.resolve_stream_append
)
elif o.HasField("resolve_stream_close"):
await self._visit_coresdk_workflow_activation_ResolveStreamClose(
fs, o.resolve_stream_close
)

async def _visit_coresdk_workflow_activation_WorkflowActivation(
self, fs: VisitorFunctions, o: Any
Expand Down Expand Up @@ -492,6 +536,11 @@ async def _visit_coresdk_workflow_commands_ScheduleNexusOperation(
if o.HasField("input"):
await self._visit_nexus_operation_input_payload(fs, o.input)

async def _visit_coresdk_workflow_commands_AppendToStream(
self, fs: VisitorFunctions, o: Any
):
await self._visit_payload_container(fs, o.bodies)

async def _visit_coresdk_workflow_commands_WorkflowCommand(
self, fs: VisitorFunctions, o: Any
):
Expand Down Expand Up @@ -551,6 +600,10 @@ async def _visit_coresdk_workflow_commands_WorkflowCommand(
await self._visit_coresdk_workflow_commands_ScheduleNexusOperation(
fs, o.schedule_nexus_operation
)
elif o.HasField("append_to_stream"):
await self._visit_coresdk_workflow_commands_AppendToStream(
fs, o.append_to_stream
)

async def _visit_coresdk_workflow_completion_Success(
self, fs: VisitorFunctions, o: Any
Expand Down Expand Up @@ -681,12 +734,6 @@ async def _visit_temporal_api_streamservice_v1_ReadRecordsRequest(
) -> None:
pass

async def _visit_temporal_api_stream_v1_StreamRecord(
self, fs: VisitorFunctions, o: Any
):
if o.HasField("body"):
await self._visit_temporal_api_common_v1_Payload(fs, o.body)

async def _visit_temporal_api_streamservice_v1_ReadRecordsResponse(
self, fs: VisitorFunctions, o: Any
):
Expand Down
2 changes: 2 additions & 0 deletions temporalio/bridge/proto/common/__init__.py
Original file line number Diff line number Diff line change
@@ -1,13 +1,15 @@
from .common_pb2 import (
ExternalStorageMetrics,
NamespacedWorkflowExecution,
StreamReadStop,
VersioningIntent,
WorkerDeploymentVersion,
)

__all__ = [
"ExternalStorageMetrics",
"NamespacedWorkflowExecution",
"StreamReadStop",
"VersioningIntent",
"WorkerDeploymentVersion",
]
8 changes: 5 additions & 3 deletions temporalio/bridge/proto/common/common_pb2.py

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

39 changes: 39 additions & 0 deletions temporalio/bridge/proto/common/common_pb2.pyi
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,45 @@ else:

DESCRIPTOR: google.protobuf.descriptor.FileDescriptor

class _StreamReadStop:
ValueType = typing.NewType("ValueType", builtins.int)
V: typing_extensions.TypeAlias = ValueType

class _StreamReadStopEnumTypeWrapper(
google.protobuf.internal.enum_type_wrapper._EnumTypeWrapper[
_StreamReadStop.ValueType
],
builtins.type,
):
DESCRIPTOR: google.protobuf.descriptor.EnumDescriptor
STREAM_READ_STOP_UNSPECIFIED: _StreamReadStop.ValueType # 0
STREAM_READ_STOP_DONE: _StreamReadStop.ValueType # 1
"""The Stream is closed, and the read gave its last Record."""
STREAM_READ_STOP_MAX_RECORDS: _StreamReadStop.ValueType # 2
"""The read gave `max_records` Records."""
STREAM_READ_STOP_MAX_BYTES: _StreamReadStop.ValueType # 3
"""The next Record would pass `max_bytes`."""
STREAM_READ_STOP_IDLE: _StreamReadStop.ValueType # 4
"""No Record came for `idle_timeout`."""
STREAM_READ_STOP_TIMEOUT: _StreamReadStop.ValueType # 5
"""`timeout` passed since the read started."""

class StreamReadStop(_StreamReadStop, metaclass=_StreamReadStopEnumTypeWrapper):
"""Why a read of a Stream ended. A read that failed has no stop."""

STREAM_READ_STOP_UNSPECIFIED: StreamReadStop.ValueType # 0
STREAM_READ_STOP_DONE: StreamReadStop.ValueType # 1
"""The Stream is closed, and the read gave its last Record."""
STREAM_READ_STOP_MAX_RECORDS: StreamReadStop.ValueType # 2
"""The read gave `max_records` Records."""
STREAM_READ_STOP_MAX_BYTES: StreamReadStop.ValueType # 3
"""The next Record would pass `max_bytes`."""
STREAM_READ_STOP_IDLE: StreamReadStop.ValueType # 4
"""No Record came for `idle_timeout`."""
STREAM_READ_STOP_TIMEOUT: StreamReadStop.ValueType # 5
"""`timeout` passed since the read started."""
global___StreamReadStop = StreamReadStop

class _VersioningIntent:
ValueType = typing.NewType("ValueType", builtins.int)
V: typing_extensions.TypeAlias = ValueType
Expand Down
15 changes: 14 additions & 1 deletion temporalio/bridge/proto/external_data/__init__.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,19 @@
from .external_data_pb2 import LocalActivityMarkerData, PatchedMarkerData
from .external_data_pb2 import (
LocalActivityMarkerData,
PatchedMarkerData,
StreamAppendEntry,
StreamCloseEntry,
StreamMarkerData,
StreamReadEnded,
StreamReadEntry,
)

__all__ = [
"LocalActivityMarkerData",
"PatchedMarkerData",
"StreamAppendEntry",
"StreamCloseEntry",
"StreamMarkerData",
"StreamReadEnded",
"StreamReadEntry",
]
30 changes: 25 additions & 5 deletions temporalio/bridge/proto/external_data/external_data_pb2.py

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading
Loading