photoncloud-monorepo/specifications/flaredb/002-raft-features/contracts/raft-service.md

Raft Service Contract (gRPC)

Overview

Single RPC entrypoint for Raft message exchange; uses raft-rs Message protobuf encoding (prost).

Service

service RaftService {
  rpc Send(RaftMessage) returns (RaftResponse);
}

Messages

• RaftMessage

  • message: bytes (serialized raft::eraftpb::Message via prost)

• RaftResponse

  • Empty payload; errors conveyed via gRPC status

Expectations

• Client (peer) wraps raft-rs Message and posts to remote peer via Send.
• Receivers decode and feed into RawNode::step, then drive on_ready to persist/apply.
• Transport must retry/transient-handle UNAVAILABLE; fail fast on INVALID_ARGUMENT decode errors.

Test Hooks

• Integration harness should:
  • Start 3 peers with distinct addresses.
  • Wire RaftService between peers.
  • Propose on leader; verify followers receive and persist entries.
  • Simulate follower stop/restart and verify catch-up via Send.