cmdstream

README

cmd-stream-go

cmd-stream-go is a high-performance, modular client–server library for Go, based on the Command Pattern. It's designed for efficient, low-latency communication over TCP/TLS, with support for streaming and observability.

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

Contents

• cmd-stream-go
  • Contents
  • Why cmd-stream-go?
  • Overview
  • Tests
  • Benchmarks
  • How To
  • Network Protocols Support
  • Client & Server
  • High-performance Communication Channel
  • cmd-stream-go and RPC
  • Architecture

Why cmd-stream-go?

It delivers high-performance and resource efficiency, helping 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 the 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.

Tests

The main cmd-stream-go module contains basic integration tests, while each submodule (see Architecture) has approximately 90% code coverage.

Benchmarks

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

How To

Getting started is easy:

1. Implement the Command Pattern.
2. Generate the serialization code.

For more details, explore the following resources:

• Tutorial
• OpenTelemetry Instrumentation
• Examples

Network Protocols Support

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

Client & Server

The client operates asynchronously, sending Commands to the server. On the server side, the Invoker executes the Commands, while the Receiver provides the underlying server functionality.

High-performance Communication Channel

To maximize performance between services:

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

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

cmd-stream-go and RPC

Already using RPC? You can use cmd-stream-go as a faster transport layer. See the RPC example.

Architecture

cmd-stream-go is split into the following submodules:

• core-go: The core module that includes client and server definitions.
• delegate-go: The client delegates all communication-related tasks to its delegate, the server follows the same approach. The connection is also initialized at this level.
• handler-go: The server delegate uses a handler to receive and process Commands.
• transport-go: Responsible for Commands/Results delivery.

cmd-stream-go was designed in such a way that you can easily replace any part of it.

Documentation

Index

• func MakeClient[T any](codec cln.Codec[T], conn net.Conn, ops ...cln.SetOption) (client *ccln.Client[T], err error)
• func MakeClientGroup[T any](clientsCount int, codec cln.Codec[T], factory cln.ConnFactory, ...) (group grp.ClientGroup[T], err error)
• func MakeReconnectClient[T any](codec cln.Codec[T], factory cln.ConnFactory, ops ...cln.SetOption) (client *ccln.Client[T], err error)
• func MakeServer[T any](codec srv.Codec[T], invoker handler.Invoker[T], ops ...srv.SetOption) *csrv.Server
• func NewMakeClientsError(count int, cause error) error

Functions

func MakeClient

func MakeClient[T any](codec cln.Codec[T], conn net.Conn, ops ...cln.SetOption) (
	client *ccln.Client[T], err error)

MakeClient creates and initializes a new cmd-stream client.

It adapts the provided codec and applies optional configuration for transport, delegation, and keepalive behavior.

Parameters:

• codec: Codec used for encoding Commands / decoding Results.
• conn: The underlying network connection.
• ops: Optional configuration settings.

Returns an error if setup fails at any step (e.g., delegate creation).

func MakeClientGroup

func MakeClientGroup[T any](clientsCount int, codec cln.Codec[T],
	factory cln.ConnFactory,
	ops ...grp.SetOption[T],
) (group grp.ClientGroup[T], err error)

MakeClientGroup creates a new ClientGroup with the specified number of clients.

If the Reconnect option is enabled, reconnect-capable clients are created. The default dispatch strategy is round-robin.

Parameters:

• clientsCount: Number of clients to create.
• codec: Codec used for encoding Commands and decoding Results.
• factory: Connection factory for establishing client connections.
• ops: Optional group-level configuration (e.g., dispatch strategy, reconnect, client options).

If client creation fails, the function returns an error along with a group containing the successfully created clients.

func MakeReconnectClient

func MakeReconnectClient[T any](codec cln.Codec[T], factory cln.ConnFactory,
	ops ...cln.SetOption) (client *ccln.Client[T], err error)

MakeReconnectClient creates a new cmd-stream client with support for automatic reconnection (which occurs if the Codec.Decode method encounters a network error).

It sets up a reconnect-aware delegate using the provided codec, connection factory, and optional configuration settings.

Parameters:

• codec: Codec used for encoding Commands and decoding Results.
• factory: Connection factory used to establish new connections.
• ops: Optional client configuration settings.

Returns an error if setup fails at any step (e.g., during delegate creation).

func MakeServer

func MakeServer[T any](codec srv.Codec[T], invoker handler.Invoker[T],
	ops ...srv.SetOption) *csrv.Server

MakeServer creates a new cmd-stream server.

It applies optional configuration to initialize transport, handler, and delegate components before creating the server instance.

Parameters:

• codec: Codec used for decoding incoming Commands and encoding outgoing Results.
• invoker: Executes the Commands.
• ops: Optional server configuration (e.g., transport, handler, delegate, core settings).

Returns a fully initialized server.

func NewMakeClientsError

func NewMakeClientsError(count int, cause error) error

NewMakeClientsError creates an error indicating a failure to create the specified number of clients.