Skip to content

[Brook S5] Added the client Stream, its typed creates and Stream reads. - #375

Closed
moetemp wants to merge 1 commit into
moe/brook/review/s4-backendsfrom
moe/brook/review/s5-client-reads
Closed

moetemp wants to merge 1 commit into
moe/brook/review/s4-backendsfrom
moe/brook/review/s5-client-reads

Conversation

@moetemp

@moetemp moetemp commented Oct 25, 2026 •

Copy link
Copy Markdown
Owner

This PR adds temporalio.client.Stream, which makes the Stream calls outside Workflow code, with Client.create_stream, Client.create_or_get_stream, Client.get_stream, Client.to_stream and Stream reads (streams.Subscription).

  • A call takes the payload type as a type argument, as in client.get_stream[Turn]("chat-42"), and the id is positional. Python has no type arguments on a call, so the three calls are properties whose objects take the type as a subscript and keep it for type checkers. With no subscript, the type is Any and a read gives JSON values.
  • create_stream fails with StreamAlreadyExistsError if the id exists. create_or_get_stream sends USE_EXISTING and gets it, and ignores its options there. Both fail on a closed or expired Stream, and each create sends a new request id.
  • get_stream and to_stream(ref, *, payload_type=None) make no call. stream.ref is the data to pass on, and stream.proto_ref is the StreamRef wire message for a field of a proto message.
  • publish starts the write at the call and returns a future. The writes of one Stream keep the order of the calls. A write error that no caller got raises at the next call of the Stream, and close closes first, then raises it.
  • A close carries no value, and async with closes at the block end on any exception, as the generated resources do. A close that the Store refuses counts as not done, so the block end tries it again. A close of a Stream bound to a Workflow raises StreamNotOwnerError with no call, and so does async with at __aenter__.
  • rpc_timeout is the deadline of each call on every backend. The Redis and memory backends make no RPC, so they ignore rpc_metadata.
  • A read yields Records and Superseded items. It long-polls and starts at an offset, at END or at the newest last Records, 1 to 1000. It ends when the Stream is closed and the read gave its last item. A read with create_wait pauses between the reads that find no Stream.
  • A client Producer has a client epoch and a key for its process. A forked child makes its own key, so two children of one parent never write as one Producer.
  • A read keeps the offsets that it gave of each Producer that a later Superseded item can withdraw, as runs of consecutive offsets. A client's Records are never withdrawn, so a read keeps nothing for them.
  • An in-Python fake of the crate's runtime lets the facade tests run with no Store.

Why?

This is the client half of the API, which the next PR runs on Redis and in memory.

Part of the Streams review series.

Checklist

  1. How was this tested:
    • poe lint, poe gen-docs and pytest tests/contrib/streams.

@moetemp moetemp added the skip-changelog Changelog entry rides another PR label Oct 25, 2026
@moetemp
moetemp force-pushed the moe/brook/review/s4-backends branch from b146c64 to ce8bd6d Compare October 26, 2026 00:14
@moetemp
moetemp force-pushed the moe/brook/review/s5-client-reads branch from 252b606 to b70af4e Compare October 26, 2026 00:14
@moetemp
moetemp force-pushed the moe/brook/review/s4-backends branch from ce8bd6d to e453c8e Compare October 26, 2026 02:08
@moetemp
moetemp force-pushed the moe/brook/review/s5-client-reads branch 2 times, most recently from 50134b6 to 6636d64 Compare October 26, 2026 08:44
@moetemp
moetemp force-pushed the moe/brook/review/s4-backends branch 2 times, most recently from 0d0ab14 to 9f62387 Compare October 27, 2026 09:07
@moetemp
moetemp force-pushed the moe/brook/review/s5-client-reads branch 2 times, most recently from 86ae5d2 to c774176 Compare October 27, 2026 09:17
@moetemp
moetemp force-pushed the moe/brook/review/s4-backends branch from 9f62387 to 9afffa1 Compare October 27, 2026 09:17
@moetemp
moetemp force-pushed the moe/brook/review/s5-client-reads branch 2 times, most recently from fe0790c to 62769cb Compare October 28, 2026 07:54
@moetemp
moetemp force-pushed the moe/brook/review/s4-backends branch from 36ed7f5 to c0c0a86 Compare October 28, 2026 07:54
@moetemp
moetemp force-pushed the moe/brook/review/s5-client-reads branch from 62769cb to 7265a04 Compare October 28, 2026 08:05
@moetemp moetemp changed the title [Brook S5] Added client Stream handles and Stream reads. [Brook S5] Added the client Stream and Stream reads. Nov 3, 2026
@moetemp
moetemp force-pushed the moe/brook/review/s4-backends branch from e8cc77e to 9cfb80a Compare November 5, 2026 17:19
@moetemp
moetemp force-pushed the moe/brook/review/s5-client-reads branch from 96dfdd2 to 7104162 Compare November 5, 2026 17:19
@moetemp moetemp changed the title [Brook S5] Added the client Stream and Stream reads. [Brook S5] Added the client Stream, its typed creates and Stream reads. Nov 5, 2026
@moetemp
moetemp force-pushed the moe/brook/review/s4-backends branch from 9cfb80a to 98724fe Compare November 5, 2026 23:10
@moetemp
moetemp force-pushed the moe/brook/review/s5-client-reads branch from 7104162 to 4b9c1eb Compare November 5, 2026 23:10
@moetemp
moetemp force-pushed the moe/brook/review/s4-backends branch from 98724fe to b7b7ff1 Compare November 6, 2026 09:06
@moetemp
moetemp force-pushed the moe/brook/review/s5-client-reads branch from 4b9c1eb to 1d4d038 Compare November 6, 2026 09:06
@moetemp
moetemp force-pushed the moe/brook/review/s4-backends branch from b7b7ff1 to 6668d55 Compare November 6, 2026 09:22
@moetemp
moetemp force-pushed the moe/brook/review/s5-client-reads branch from 1d4d038 to 26c6741 Compare November 6, 2026 09:22
@moetemp

moetemp commented Nov 10, 2026

Copy link
Copy Markdown
Owner Author

Closed in favor of #381, the combined branch, which has this change.

@moetemp moetemp closed this Nov 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

skip-changelog Changelog entry rides another PR

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant