restatedev / restatedev/sdk-shared-core

Support service protocol V7 with streaming eager state entries

Open
#64 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
7
Forks
14
PR merge metrics
No merged PRs in 30d

Description

Problem

The StartMessage in the service protocol (V1-V6) requires all state entries to be embedded in the message itself. This means the server must materialize all state entries into memory before sending the message, and the total state size is bounded by the max message size limit (~32MB).

The server-side implementation in restatedev/restate#4344 / restatedev/restate#4413 introduces protocol V7, which streams state entries in batches after the StartMessage using two new control messages.

Protocol V7 Changes

Two new control message types (server → SDK only):

  • EagerStateEntryMessage (0x0006): Carries a batch of StateEntry key-value pairs. Sent zero or more times.
  • EagerStateCompleteMessage (0x0007): Terminates the eager state stream. Sent exactly once. Contains partial_state: bool indicating whether the combined state is a complete or partial view.
V7 message sequence:
StartMessage (state_map: [], partial_state: ignored)
EagerStateEntryMessage { state_map: [...] }    ← 0 or more
EagerStateCompleteMessage { partial_state }     ← exactly 1
CommandMessage / NotificationMessage ...        ← journal replay

V1-V6 behavior is completely unchanged.

Required Changes in sdk-shared-core

1. Protocol Version
  • Add V7 = 7 to the Version enum in src/service_protocol/version.rs
  • Update maximum_supported_version() to return V7
  • Add content-type string application/vnd.restate.invocation.v7
2. Protobuf / Generated Code
  • Update the service-protocol submodule to include the new proto definitions
  • Regenerate src/service_protocol/generated/dev.restate.service.protocol.rs
  • New message types: EagerStateEntryMessage and EagerStateCompleteMessage
3. Message Types and Codec
  • Add EagerStateEntry = 0x0006 and EagerStateComplete = 0x0007 to the MessageType enum in src/service_protocol/header.rs
  • Add encode/decode support in src/service_protocol/encoding.rs and messages.rs
4. VM State Machine
  • Add a new intermediate state WaitingEagerState between WaitingStart and WaitingReplayEntries
  • In V7: StartMessage transitions to WaitingEagerState (with empty EagerState)
  • EagerStateEntryMessage accumulates entries into EagerState
  • EagerStateCompleteMessage sets partial_state and transitions to WaitingReplayEntries
  • In V5/V6: behavior unchanged — state comes from StartMessage.state_map, transitions directly to WaitingReplayEntries
5. Error Handling
  • In WaitingEagerState: reject any message that isn't EagerStateEntryMessage or EagerStateCompleteMessage
  • In other states: reject EagerStateEntryMessage / EagerStateCompleteMessage as protocol errors
  • In V5/V6: reject the new message types entirely
6. Tests
  • V7 with no state entries (immediate EagerStateCompleteMessage)
  • V7 with a single batch of entries
  • V7 with multiple batches
  • V7 with partial_state: true and partial_state: false
  • Verify V5/V6 behavior is unchanged
  • Verify error on receiving new messages in wrong states

Related

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with src/service_protocol/version.rs, header.rs, encoding.rs, messages.rs, and the VM state-machine implementation; also inspect the service-protocol submodule before regenerating generated/dev.restate.service.protocol.rs. Exercise the listed V7 state-stream cases and V5/V6 compatibility and error cases; done means protocol messages, transitions, and rejection behavior match the issue.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
api, backend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.