Expand user guide documentation and storage example with REPL

[meling]

Documentation and Expanded Storage Example

Significantly expands the user guide and developer guide documentation, and upgrades the examples/storage example to cover all call types — including unicast, multicast, correctable reads, and nested (symmetric) quorum calls using ServerCtx.Config(). Adds NewLocalSystems to the core library for pre-allocating local test clusters, and removes the legacy gorumsexample directory in favor of the richer storage example.

Changes

Documentation (doc/)

• user-guide.md:
  • Expand the call types table to include synchronous quorum calls and correctable streaming calls.
  • Add a Mermaid sequence diagram illustrating multicast, quorum call, and correctable call flows.
  • Separate node-context vs. config-context generated functions into distinct code blocks with explanatory prose.
  • Clarify that unicast and multicast are one-way — no server-side result is returned.
  • Clarify that the handler context is derived from the gRPC stream context and extended with per-request metadata.
  • Add a Server-Side Interceptors section with code examples for logging, delay, metadata injection, and request filtering interceptors.
  • Add an Interactive REPL section documenting all REPL commands, flags, and an example session.
  • Add a Nested Quorum Calls with ServerCtx.Config section, covering peer tracking setup, ctx.Release() usage, handler code, and a sequence diagram.
  • Add a Reverse Direction Calls with ServerCtx.ClientConfig section, covering firewall use cases, client setup, handler code, and a sequence diagram.
  • Update proto package references from gorumsexample to storage/proto.
• dev-guide.md:
  • Clarify what counts as "static code" in dev/ (non-zorums_ .go files excluding test files).
  • Expand the Makefile targets table with all current targets.

Storage example (examples/storage/)

• proto/storage.proto — Add call types:
  • WriteUnicast (unicast)
  • WriteMulticast (multicast)
  • ReadNestedQC (quorum call with server-side fan-out via ServerCtx.Config())
  • WriteNestedMulticast (quorum call wrapping a nested multicast)
  • ReadCorrectable (streaming quorum call)
• server.go:
  • Implement WriteUnicast, ReadCorrectable, ReadNestedQC, and WriteNestedMulticast handlers.
  • Add rawWriter helper that translates \n to \r\n for correct output in raw terminal mode.
  • Replace startServer helper with gorums.NewSystem-based setup.
  • Remove hard-coded interceptors from the server; interceptors are now configured via CLI flag.
  • Update newStorageServer to accept io.Writer and a label for logging.
• main.go:
  • Replace manual server loop with gorums.NewLocalSystems for local cluster setup.
  • Add --interceptors flag supporting logging, nofoo, metadata, delayed.
  • Call sys.NewOutboundConfig (no explicit node list needed — stored by NewLocalSystems).
• repl.go:
  • Add ucast / unicast command for one-way unicast writes.
  • Add cread sub-command for correctable reads (streams progressive updates).
  • Add nread and nwrite sub-commands for nested quorum call / nested multicast.
  • Replace github.com/google/shlex with a self-contained splitQuoted implementation (removes external dependency).
  • Refactor parseConfiguration into parseConfiguration + parseIndices (error-returning, no implicit fmt.Println).
  • Fix cfg range syntax to allow stop == numNodes (exclusive end).
  • Add delayOutput constant for short post-call delay so server log lines appear before the prompt.
  • Remove stale FIXME comment about arrow keys on Windows.

Core library

• system.go:
  • Add NewLocalSystems(n int, opts ...ServerOption) ([]*System, func(), error) — pre-allocates all listeners before creating any system (solves the chicken-and-egg address problem), configures each system with WithConfig (node IDs 1..n), and returns a stop closure.
  • Add nodeList field to System to store the node list set by NewLocalSystems.
  • Update NewOutboundConfig to use the stored node list automatically, simplifying call sites.

Testing

All existing tests continue to pass. The storage example builds and runs end-to-end with the new REPL commands and local cluster setup. Storage example has been tested manually.

Related

Closes #285

[deepsource-io]

DeepSource Code Review

We reviewed changes in 08d70f0...9ec7ddd on this pull request. Below is the summary for the review, and you can see the individual issues we found as inline review comments.

See full review on DeepSource ↗

PR Report Card

Overall Grade

Security   Reliability   Complexity   Hygiene

Code Review Summary

Analyzer	Status	Updated (UTC)	Details
Go		Mar 14, 2026 3:54p.m.	Review ↗
Shell		Mar 14, 2026 3:54p.m.	Review ↗

[Copilot]

Pull request overview

This PR updates Gorums documentation and examples to better cover all call types (unicast, multicast, quorum calls, correctable streaming) and symmetric/nested call patterns, while adding a core helper (NewLocalSystems) to simplify local multi-node setups and outbound configuration.

Changes:

• Expand doc/user-guide.md and doc/dev-guide.md with updated guidance, diagrams, interceptor docs, and REPL usage.
• Upgrade examples/storage to cover additional call types (including correctable + nested calls) and extend the REPL accordingly; remove the legacy examples/gorumsexample proto.
• Add gorums.NewLocalSystems and update System.NewOutboundConfig to reuse a stored node list when available.

Reviewed changes

Copilot reviewed 16 out of 19 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
system.go	Adds NewLocalSystems, stores a node list on System, and changes NewOutboundConfig defaults.
go.work	Bumps workspace Go version to 1.26.0.
go.sum	Updates dependency checksums after module/version bumps.
go.mod	Bumps module Go version to 1.26.0 and updates dependencies.
examples/storage/server.go	Refactors server startup via gorums.NewSystem and adds new handlers (unicast, multicast, correctable, nested calls).
examples/storage/repl.go	Adds new REPL commands and replaces shlex with a local quoted-splitting implementation.
examples/storage/proto/storage_gorums.pb.go	Regenerated Gorums bindings for new call types.
examples/storage/proto/storage.proto	Extends the Storage service with unicast, multicast, nested quorum calls, and correctable streaming quorum call.
examples/storage/proto/storage.pb.go	Regenerated protobuf bindings for updated storage proto.
examples/storage/main.go	Uses gorums.NewLocalSystems, adds interceptor flag parsing, and sets up local systems.
examples/storage/client.go	Minor cleanup while keeping configuration creation for the REPL client.
examples/gorumsexample/storage.proto	Removes legacy tutorial proto (directory deprecation).
examples/go.sum	Updates example-module checksums (including removal of google/shlex).
examples/go.mod	Bumps example module Go version to 1.26.0 and updates deps.
doc/user-guide.md	Major expansion: call types, diagrams, interceptors, REPL docs, nested call patterns.
doc/dev-guide.md	Clarifies “static code” definition in dev/ and expands Makefile targets table.
AGENTS.md	Adds conventional-commit requirements; removes a design-doc reference.
.vscode/gorums.txt	Adds new words/commands to workspace dictionary.
.gitignore	Removes ignores for legacy tutorial generated files (since tutorial example is removed).

Comments suppressed due to low confidence (1)

doc/user-guide.md:123

• This section says the runnable example is examples/storage, but the sequence diagram and proto snippet still use method names like ReadOrdered/ReadQCStream that don’t exist in examples/storage/proto/storage.proto (which uses ReadRPC/WriteRPC/ReadCorrectable, etc.). Please update the diagram/snippet to match the actual storage example API, or clarify that it’s a separate tutorial proto.

    Note over Client,Node B: Correctable (Streaming)
    Client->>Node A: ReadQCStream(Req)
    Client->>Node B: ReadQCStream(Req)
    Node A-->>Client: ReadResponse(v1, t1)
    Node B-->>Client: ReadResponse(v1, t1)
    Note over Client: Client reads first quorum result
    Node A-->>Client: ReadResponse(v2, t2)
    Node B-->>Client: ReadResponse(v2, t2)
    Note over Client: Client reads updated quorum result

Configuring Call Types in Protobuf

The file storage.proto should have the following content, illustrating the different call types:

edition = "2024";

package proto;
option go_package = "github.com/relab/gorums/examples/storage/proto";
option features.field_presence = IMPLICIT;

import "google/protobuf/empty.proto";
import "gorums.proto";

// Storage service defines the RPCs for a simple key-value storage system.
service Storage {
  // ReadOrdered is a FIFO-ordered RPC to a single node.
  rpc ReadOrdered(google.protobuf.Empty) returns (State) {}

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 27 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (1)

doc/user-guide.md:123

• The guide states that the runnable example and proto definition live in examples/storage/proto/storage.proto, but the proto snippet and diagrams below still use the older API shape (e.g., ReadOrdered/ReadQCStream/State) which does not match examples/storage/proto/storage.proto in this PR (ReadRPC/WriteRPC/ReadCorrectable/etc.). Please either update the snippet/diagrams to match the actual storage example, or clarify that this section uses a simplified, separate proto that is not the same as the runnable example.

The runnable version of this example lives in `examples/storage`.
The protobuf definition for that example lives in `examples/storage/proto/storage.proto`.
If you are starting from scratch, you can still create your own module and use the same proto structure.

```shell
mkdir $HOME/storageexample
cd $HOME/storageexample
go mod init storageexample
go get github.com/relab/gorums

Call Types

Gorums offers several call types including quorum calls, and one-way unicast and multicast communication.
To select a call type for a Protobuf service method, specify one of the following options (they cannot be combined):

Call type	Gorums option	Description
Ordered RPC	no option	FIFO-ordered synchronous RPC to a single node.
Unicast	gorums.unicast	FIFO-ordered one-way asynchronous unicast.
Multicast	gorums.multicast	FIFO-ordered one-way asynchronous multicast.
Quorum Call	gorums.quorumcall	FIFO-ordered asynchronous quorum call on a configuration of nodes.
Synchronous Quorum Call	gorums.quorumcall	Synchronous variant; chain a terminal method (.First(), .Majority(), .All(), .Threshold(n)) to block until the quorum threshold is met.
Correctable	gorums.quorumcall + stream	Streaming quorum call; use .Correctable(n) to observe progressive updates as nodes respond.

The generated API is similar to unary gRPC, unless the stream keyword is used in the proto definition.
Server streaming is only supported for quorum calls.
Client streaming is not supported.

sequenceDiagram
    participant Client
    participant Node A
    participant Node B

    Note over Client,Node B: Multicast (One-way)
    Client->>Node A: WriteMulticast(Req)
    Client->>Node B: WriteMulticast(Req)
    Note over Client: Client continues immediately

    Note over Client,Node B: Quorum Call (Synchronous)
    Client->>Node A: ReadQC(Req)
    Client->>Node B: ReadQC(Req)
    Node A-->>Client: ReadResponse(Value, Time)
    Node B-->>Client: ReadResponse(Value, Time)
    Note over Client: Client aggregates responses

    Note over Client,Node B: Correctable (Streaming)
    Client->>Node A: ReadQCStream(Req)
    Client->>Node B: ReadQCStream(Req)
    Node A-->>Client: ReadResponse(v1, t1)
    Node B-->>Client: ReadResponse(v1, t1)
    Note over Client: Client reads first quorum result
    Node A-->>Client: ReadResponse(v2, t2)
    Node B-->>Client: ReadResponse(v2, t2)
    Note over Client: Client reads updated quorum result

Loading

Configuring Call Types in Protobuf

The file storage.proto should have the following content, illustrating the different call types:

edition = "2024";

package proto;
option go_package = "github.com/relab/gorums/examples/storage/proto";
option features.field_presence = IMPLICIT;

import "google/protobuf/empty.proto";
import "gorums.proto";

// Storage service defines the RPCs for a simple key-value storage system.
service Storage {
  // ReadOrdered is a FIFO-ordered RPC to a single node.
  rpc ReadOrdered(google.protobuf.Empty) returns (State) {}

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 25 out of 28 changed files in this pull request and generated 6 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.