cmd-stream: High-Performance Distributed Command Pattern (DCP) for Go

cmd-stream is a networking framework that implements the Distributed Command Pattern (DCP) for Go. Designed for low-latency communication over TCP/TLS, it provides a flexible, decoupled alternative to traditional RPC by treating requests as first-class Command objects.

The architecture is straightforward: a client sends Commands to the server, where an Invoker executes them, and a Receiver provides the actual server-side functionality.

*Want to learn more about how the Command Pattern applies to network communication? Check out this series of posts*.

Why cmd-stream?

It delivers high-performance and resource efficiency by multiplexing asynchronous requests over long-lived connections, minimizing network overhead. This helps reduce infrastructure costs and scale more effectively.

Overview

Works over TCP, TLS or mutual TLS.
Has an asynchronous client that uses only one connection for both sending

Commands and receiving Results.

Supports server streaming, i.e. a Command can send back multiple Results.
Provides reconnect and keepalive features.
Supports the Circuit Breaker pattern.
Has OpenTelemetry integration.
Can work with various serialization formats.
Follows a modular design.

Benchmarks

QPS Benchmark

See go-client-server-benchmarks for detailed performance comparisons.

Stress Testing

The framework has successfully passed a 12-hour continuous stress test, ensuring stability under extreme conditions.

For more details on the testing methodology and results, see stress-test-go.

Installation

To obtain the framework, use:

go get github.com/cmd-stream/cmd-stream-go

How To

Getting started is easy:

Implement the Command Pattern.
Use one of the codecs:

- codec-json-go - simple and easy-to-use JSON codec (ideal for prototyping). - codec-protobuf-go - Protobuf-based codec (requires code generation). - codec-mus-stream-go - high-performance MUS codec (requires code generation).

Tip: Start with JSON for simplicity, and switch to MUS later for maximum performance.

Quick Look

Here's a minimal end-to-end example showing how Commands can be defined, sent, and executed over the network:

// Calc handles arithmetic logic.
type Calc struct{}
func (c Calc) Add(a, b int) int { return a + b } func (c Calc) Sub(a, b int) int { return a - b }
// AddCmd executes addition via Calc. type AddCmd struct{ A, B int }
func (c AddCmd) Exec(ctx context.Context, calc Calc, proxy core.Proxy) error {   _, err := proxy.Send(CalcResult(calc.Add(c.A, c.B)))   return err }
// SubCmd executes subtraction via Calc. type SubCmd struct{ A, B int }
func (c SubCmd) Exec(ctx context.Context, calc Calc, proxy core.Proxy) error {   _, err := proxy.Send(CalcResult(calc.Sub(c.A, c.B)))   return err }
// CalcResult represents the Command output. type CalcResult int
// LastOne indicates if this is the final result for the Command. func (r CalcResult) LastOne() bool { return true }
func main() {   // Imports and error handling omitted for brevity.
const addr = "127.0.0.1:9000"
// 1. Setup codecs with all supported Command and Result types.   reg := cdcjson.NewRegistry(     cdcjson.WithCmd[Calc, AddCmd](),     cdcjson.WithCmd[Calc, SubCmd](),     cdcjson.WithResult[Calc, CalcResult](),   )   serverCodec := cdcjson.NewServerCodecWith(reg)   clientCodec := cdcjson.NewClientCodecWith(reg)
// 2. Start server.   server, _ := cmdstream.NewServer(Calc{}, serverCodec)   go server.ListenAndServe(addr)   time.Sleep(100 * time.Millisecond)
// 3. Create sender.   sender, _ := cmdstream.NewSender(addr, clientCodec)
// 4. Send commands.   sum, _ := sender.Send(context.Background(), AddCmd{A: 2, B: 3})   fmt.Println(sum) // Output: 5
diff, _ := sender.Send(context.Background(), SubCmd{A: 8, B: 4})   fmt.Println(diff) // Output: 4 }

See the calc_json example for the full implementation.

Additional Resources

Network Protocols Support

Built on Go’s standard net package, cmd-stream supports connection-oriented protocols, such as TCP, TLS, and mutual TLS (for client authentication).

High-performance Communication Channel

To maximize performance between services:

Use N parallel clients. More connections typically improve throughput, until a saturation point.
Pre-establish all connections instead of opening them on-demand.
Keep connections alive to avoid the overhead from reconnections.

These practices, implemented via the Group, can significantly enhance throughput and reduce latency between your services.