Skip to content

[Brook K10] Added the Stream service WIT. - #220

Closed
moetemp wants to merge 12 commits into
moe/brook/review/streams-k9-writersfrom
moe/brook/review/streams-k10-wit
Closed

moetemp wants to merge 12 commits into
moe/brook/review/streams-k9-writersfrom
moe/brook/review/streams-k10-wit

Conversation

@moetemp

@moetemp moetemp commented Oct 27, 2026 •

Copy link
Copy Markdown
Owner

What changed?

This PR adds the Stream service WIT, the input of each SDK's nexgen client.

  • stream-service.wit is a System Nexus service. There's no writer WIT. SDKs call the writer methods with runtime.proto messages, so no SDK generates writer bindings with nexgen.
  • Each type binds to its split A1 proto. stream-ref.owner is an execution record.
  • The read item stream-item is a variant bound to A1's StreamRecord.item oneof, with the cases data, superseded and close. stream-error-reason binds A1's error enum.
  • A read record's item is optional, so an item kind that only a newer server knows decodes as no item.
  • Each request's %stream is required, and so are the lists. Each record lists its required fields first, so the generated Python models stay positional, with no kw_only.
  • The resource methods are publish, read, close and describe, the names users call. @nexus.operation keeps the wire names.
  • close-with-run, and the close's failed-tasks and previous-completed-task, are @nexus.omit, like the other native-only fields.
  • Unlike moetemp/sdk-streams#52, it follows the reworked nexgen. ReadRecords uses @nexus.poll, and create-stream returns the stream resource with created on it.
  • A create of a closed, expired or other-owned Stream fails, so the resource takes no create status. read takes max-bytes, which the request has. Only the client's read-records takes last, since Workflow replay needs a fixed range.
  • The WIT takes the nexgen directives of moetemp/nexgen#78 to #97, so the generated Stream API is the user API. Stream is generic in its value type body-t, and a create takes a StreamDefinition. The fields that the runtime sets have a @nexus.source per target, or @nexus.api-omit. The create and the handle factory take id and backend, not the ref.
  • publish(*values) returns the last offset. The read poll yields each Record and resumes after the last one, async with closes the Stream, and each error reason with a class raises that class.
  • The close has no status in the API. K6 gives CANCELED for a failure with CanceledFailureInfo.

Depends on #219 (K9), but needs only #212 (K1). Review lane is the proto and WIT reviewers.
Part of the Brook review series.

Why?

The WIT is only a nexgen input, so it's last and alone. After review the crate ships with the sdk-rust crates. sdk-python moves its pin to this PR's head in its coming repin.

How did you test it?

cargo fmt, cargo clippy -- -D warnings (with and without features), cargo test -p temporalio-streams --all-features and cargo doc pass at this commit.
nexgen at moetemp/nexgen#97 (c88f90ef) generates the WIT for Python, TypeScript and .NET.

@moetemp
moetemp force-pushed the moe/brook/review/streams-k10-wit branch from 6c8e944 to 4fea886 Compare October 27, 2026 07:35
@moetemp
moetemp force-pushed the moe/brook/review/streams-k9-writers branch from 26765fa to d18c6dc Compare October 27, 2026 08:17
@moetemp
moetemp force-pushed the moe/brook/review/streams-k10-wit branch from 4fea886 to 3f46160 Compare October 27, 2026 08:17
@moetemp moetemp added the skip-changelog Changelog entry rides another PR label Oct 27, 2026
@moetemp
moetemp force-pushed the moe/brook/review/streams-k9-writers branch from d18c6dc to 018e21d Compare October 27, 2026 16:55
@moetemp
moetemp force-pushed the moe/brook/review/streams-k10-wit branch from f89e58b to 03e0fad Compare October 27, 2026 16:55
@moetemp
moetemp force-pushed the moe/brook/review/streams-k9-writers branch from 018e21d to be4d7ae Compare October 27, 2026 23:46
@moetemp
moetemp force-pushed the moe/brook/review/streams-k10-wit branch from 03e0fad to 7bb4e72 Compare October 27, 2026 23:46
@moetemp
moetemp force-pushed the moe/brook/review/streams-k9-writers branch from be4d7ae to 95ed97c Compare October 28, 2026 08:55
@moetemp
moetemp force-pushed the moe/brook/review/streams-k10-wit branch from 7bb4e72 to 53631bb Compare October 28, 2026 08:55
@moetemp
moetemp force-pushed the moe/brook/review/streams-k10-wit branch from 53631bb to b5e1532 Compare October 29, 2026 04:06
@moetemp moetemp changed the title [Brook K10] Added the Stream service and writer WIT. [Brook K10] Added the Stream service WIT. Oct 29, 2026
@moetemp
moetemp force-pushed the moe/brook/review/streams-k9-writers branch from 0922872 to b163ba2 Compare October 29, 2026 08:37
@moetemp
moetemp force-pushed the moe/brook/review/streams-k10-wit branch 2 times, most recently from 23f4638 to d27b78f Compare October 29, 2026 09:17
Each SDK copies it and generates its client with nexgen's client target. SDKs call the
writer methods with `runtime.proto` messages, so there's no writer WIT.
The close request has a status of its own, an enum apart from the stream's status. As a
param, the caller sets it, and nothing fills it from the stream.
The read item binds the API's `StreamRecord.item` oneof as a variant, and the error reason
binds the new enum. The resource methods take the names users call, and each request lists
its required fields first, so the generated models stay positional.
A create of a closed, expired or other-owned Stream fails, so the handle no longer takes a
create status. The read method takes `last` and `max-bytes`, which the request has.
The generated Stream API is the user API. The directives hide the fields that the runtime sets,
make the Stream generic in its value type, and shape publish, read and close. A read item is
optional, so a reader can skip an item kind that it doesn't know.
Replay needs a fixed range, so the Workflow API omits `last`, and the resource `read` no longer
takes it. nexgen renamed the error enum's `base` keys to `name` and `extends`. The `max-records`
doc says that a Superseded item stays with its Record, as the proto does.
@moetemp
moetemp force-pushed the moe/brook/review/streams-k10-wit branch from d27b78f to 88adfdf Compare October 29, 2026 10:03
@moetemp
moetemp force-pushed the moe/brook/review/streams-k9-writers branch from 83b33d1 to 56fd065 Compare October 29, 2026 10:03
The SDK Stores ignore failed-tasks and previous-completed-task on a close, as they do withdraw-run.
nexgen's TypeScript and .NET client targets build the read iterator from these support helpers.
The close drops status, which the failure gives. An append with no sequence gets the next one from
the Store, so publish works.
@moetemp

moetemp commented Oct 31, 2026

Copy link
Copy Markdown
Owner Author

Closing. The Stream service WIT moved to temporalio/api#895.

@moetemp moetemp closed this Oct 31, 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