gorpc

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 5, 2026 License: MIT Imports: 16 Imported by: 0

README

GoRPC

Go Reference Go Report Card CI

Small Go-to-Go RPC for internal service calls.

This is meant to keep the useful shape of net/rpc without inheriting gob as the default wire choice or dragging in protobuf, schema files, generated stubs, duplicate DTO models, service discovery, load balancing, or cross-language ceremony.

Current Scope

  • TCP listener/client
  • Long-lived full-duplex peer connection after the client dials and the server accepts
  • Automatic client reconnect with exponential backoff
  • Ping/pong connection monitoring
  • Length-prefixed MessagePack frames
  • Shared Go request/response structs
  • Synchronous and asynchronous unary request/response calls from either side
  • Request IDs in every request/response frame
  • Context deadline propagation and best-effort cancel frames
  • Client-side correlation IDs for asynchronous callbacks
  • Request-scoped *gorpc.Context with client name, request ID, function, and connection addresses
  • Structured remote errors
  • Max frame size enforcement
  • Basic protocol/version/codec handshake with optional client name metadata
  • Optional HMAC-SHA256 shared-secret handshake auth
  • Optional slog debug hooks
  • Graceful server shutdown

Server.ServeTCP, Server.ServeUnix, and Server.ServeUnixPacket cover the common listener cases. Server.ServeListener accepts any existing net.Listener.

The words server and client only describe who accepts the connection and who initiates it. Once connected, both sides can register functions, send requests, receive responses, and handle incoming requests over the same full-duplex connection.

TCPDial, UnixDial, and UnixPacketDial establish the first connection, then the returned client keeps monitoring and reconnecting until Close is called. Reconnect attempts are intentionally aggressive: quick retry, exponential backoff capped at seconds, jitter, explicit dial timeouts, write deadlines, and ping/pong stale-connection detection. The lower-level Dial accepts a context, network, address, and full ClientOptions when you need explicit startup control. Use NewTCPClient, NewUnixClient, or NewUnixPacketClient when the dialing side needs to register functions before connecting. Client.Call, Client.CallWithTimeout, and Client.CallContext cover synchronous calls. Client.AsyncCall sends the request and invokes a typed callback when the response arrives. Calls made while disconnected wait for the next connection; timeout/context variants bound that wait. Calls already in flight when a connection drops fail with ErrUnavailable; GoRPC does not silently replay them because the remote side may already have processed the request.

Streaming, service discovery, pub/sub, load balancing, and generated code are intentionally out of v1.

Shared-secret auth is optional. The secret is not sent over the wire; GoRPC uses a handshake challenge and HMAC-SHA256 proof.

auth := gorpc.SharedSecret("change-me")

server := gorpc.NewServer(gorpc.ServerOptions{
	Auth: auth,
})

client, err := gorpc.TCPDial("127.0.0.1:9070", "inventory-example-client", gorpc.ClientOptions{
	Auth: auth,
})

Install

go get github.com/dan-sherwin/gorpc

Example

The types are shown inline here to keep the example self-contained. In a real app, put them in a shared Go package imported by both sides. The function string is just the wire dispatch name; it does not have to match the local Go function name.

Server app:

package main

import (
	"log"
	"time"

	"github.com/dan-sherwin/gorpc"
)

type GetItemRequest struct {
	ID string
}

type GetItemResponse struct {
	ID   string
	Name string
}

type ClientNoteRequest struct {
	ItemID string
}

type ClientNoteResponse struct {
	Note string
}

func getItem(ctx *gorpc.Context, req GetItemRequest) (GetItemResponse, error) {
	log.Printf("handling %s request_id=%d client=%q remote=%s",
		ctx.Function(),
		ctx.RequestID(),
		ctx.ClientName(),
		ctx.RemoteAddr(),
	)

	var note ClientNoteResponse
	if err := ctx.CallWithTimeout("client_note", ClientNoteRequest{ItemID: req.ID}, &note, time.Second); err == nil {
		log.Printf("client note: %s", note.Note)
	}

	return GetItemResponse{
		ID:   req.ID,
		Name: "Widget Pack",
	}, nil
}

func main() {
	server := gorpc.NewServer(gorpc.ServerOptions{})

	gorpc.MustRegister(server, "get_an_item", getItem)

	log.Println("listening on 127.0.0.1:9070")
	if err := server.ServeTCP("127.0.0.1:9070"); err != nil {
		log.Fatal(err)
	}
}

Client app:

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/dan-sherwin/gorpc"
)

type GetItemRequest struct {
	ID string
}

type GetItemResponse struct {
	ID   string
	Name string
}

type ClientNoteRequest struct {
	ItemID string
}

type ClientNoteResponse struct {
	Note string
}

func main() {
	client := gorpc.NewTCPClient("127.0.0.1:9070", "inventory-example-client")
	gorpc.MustRegister(client, "client_note", clientNote)

	if err := client.Connect(context.Background()); err != nil {
		log.Fatal(err)
	}
	defer func() {
		_ = client.Close()
	}()

	var item GetItemResponse
	if err := client.CallWithTimeout("get_an_item", GetItemRequest{ID: "widget-001"}, &item, 5*time.Second); err != nil {
		log.Fatal(err)
	}

	fmt.Printf("%s: %s\n", item.ID, item.Name)
}

func clientNote(_ *gorpc.Context, req ClientNoteRequest) (ClientNoteResponse, error) {
	return ClientNoteResponse{Note: "client saw request for " + req.ItemID}, nil
}

Async calls use the same request/response structs and add a callback plus a caller-owned correlation ID:

func handleGetItem(ctx gorpc.ClientContext, resp *GetItemResponse) {
	if ctx.Error() != nil {
		log.Fatal(ctx.Error())
	}

	fmt.Printf("async %s: %s: %s\n", ctx.CorrelationID(), resp.ID, resp.Name)
}

if err := client.AsyncCall("get_an_item", GetItemRequest{ID: "widget-async"}, handleGetItem, "example-async-1"); err != nil {
	log.Fatal(err)
}

For server-initiated calls outside an existing request handler, use ServerOptions.OnConnect or server.Connections() to get a *gorpc.Conn, then call conn.Call, conn.CallWithTimeout, or conn.AsyncCall.

Runnable Example

A working server/client example with sync calls, async callbacks, and structured remote errors lives under examples/inventory.

Build both commands:

go build ./examples/inventory/server
go build ./examples/inventory/client

Run the server:

go run ./examples/inventory/server

Run the client in another terminal:

go run ./examples/inventory/client

License

MIT. See LICENSE.

Versioning

Semantic Versioning. First public tag: v0.1.0.

CI expectations

  • go mod tidy check
  • go build ./...
  • go vet ./...
  • go test ./... -race
  • golangci-lint run
  • govulncheck ./...

Supported Go version: 1.26.3+.

Documentation

Overview

Package gorpc provides a small Go-to-Go RPC transport for internal services.

It is intentionally not a protobuf, gRPC, Connect, or IDL replacement. Both sides share normal Go request and response types, and the wire protocol uses length-prefixed MessagePack frames over a single full-duplex connection. Once connected, either side can send unary requests and receive responses.

Index

Constants

View Source 
const (
	DefaultDialTimeout       = 5 * time.Second
	DefaultWriteTimeout      = 10 * time.Second
	DefaultReconnectMinDelay = 100 * time.Millisecond
	DefaultReconnectMaxDelay = 5 * time.Second
	DefaultReconnectJitter   = 0.2
	DefaultPingInterval      = 10 * time.Second
	DefaultPingTimeout       = 3 * time.Second
)

Reconnect defaults used by Client when options are unset.

View Source 
const (
	ErrorCodeCanceled         = "canceled"
	ErrorCodeDeadlineExceeded = "deadline_exceeded"
	ErrorCodeInternal         = "internal"
	ErrorCodeInvalidRequest   = "invalid_request"
	ErrorCodeNotFound         = "not_found"
	ErrorCodeUnauthorized     = "unauthorized"
	ErrorCodeUnavailable      = "unavailable"
)

Remote error codes used by the built-in server and helpers.

View Source 
const CodecMessagePack = "msgpack"

CodecMessagePack is the v1 MessagePack codec name used during handshake.

View Source 
const DefaultHandshakeTimeout = 5 * time.Second

DefaultHandshakeTimeout is the default timeout for the initial protocol handshake.

View Source 
const DefaultMaxFrameSize int64 = 64 * 1024 * 1024

DefaultMaxFrameSize is the default maximum encoded frame size.

View Source 
const ProtocolVersion uint16 = 1

ProtocolVersion is the current GoRPC wire protocol version.

Variables

View Source 
var (
	ErrClosed            = errors.New("gorpc: closed")
	ErrAuthentication    = errors.New("gorpc: authentication failed")
	ErrDuplicateFunction = errors.New("gorpc: duplicate function")
	ErrInvalidFunction   = errors.New("gorpc: invalid function")
	ErrInvalidHandler    = errors.New("gorpc: invalid handler")
	ErrInvalidResponse   = errors.New("gorpc: invalid response")
	ErrUnavailable       = errors.New("gorpc: unavailable")
)

Common GoRPC errors.

View Source 
var (
	ErrFrameTooLarge = errors.New("gorpc: frame too large")
	ErrProtocol      = errors.New("gorpc: protocol error")
)

Frame read/write errors.

Functions

func Call 

func Call[Req, Resp any](ctx context.Context, client *Client, function string, req Req) (Resp, error)

Call performs a typed unary request/response call.

func MustRegister 

func MustRegister[Req, Resp any](target any, function string, fn HandlerFunc[Req, Resp])

MustRegister is Register that panics on error.

func Register 

func Register[Req, Resp any](target any, function string, fn HandlerFunc[Req, Resp]) error

Register binds a typed unary handler to a function name. The target can be a *Server, for functions the accepted side handles, or a *Client, for functions the dialing side handles after the connection is established.

Types

type Auth added in v0.2.0 

type Auth struct {
	// contains filtered or unexported fields
}

Auth configures optional connection authentication.

func SharedSecret added in v0.2.0 

func SharedSecret(secret string) Auth

SharedSecret enables HMAC-SHA256 challenge/response authentication.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the dialing side of a long-lived full-duplex GoRPC connection. It can send requests, register functions for the accepted side to call, and reconnects automatically after connection loss until Close is called.

func Dial 

func Dial(ctx context.Context, network, address string, opts ClientOptions) (*Client, error)

Dial connects to a GoRPC server, completes the protocol handshake, and starts background reconnect monitoring.

func NewClient added in v0.3.0 

func NewClient(network, address string, opts ClientOptions) *Client

NewClient creates a client without connecting it. Use this when the dialing side needs to register functions before the accepted side can call them.

func NewTCPClient added in v0.3.0 

func NewTCPClient(address, clientName string, opts ...ClientOptions) *Client

NewTCPClient creates a TCP client without connecting it.

func NewUnixClient added in v0.3.0 

func NewUnixClient(path, clientName string, opts ...ClientOptions) *Client

NewUnixClient creates a Unix socket client without connecting it.

func NewUnixPacketClient added in v0.3.0 

func NewUnixPacketClient(path, clientName string, opts ...ClientOptions) *Client

NewUnixPacketClient creates a Unix packet socket client without connecting it.

func TCPDial added in v0.2.0 

func TCPDial(address, clientName string, opts ...ClientOptions) (*Client, error)

TCPDial connects to address using TCP and reconnects automatically until Close is called.

func UnixDial added in v0.2.0 

func UnixDial(path, clientName string, opts ...ClientOptions) (*Client, error)

UnixDial connects to path using a Unix socket and reconnects automatically until Close is called.

func UnixPacketDial added in v0.2.0 

func UnixPacketDial(path, clientName string, opts ...ClientOptions) (*Client, error)

UnixPacketDial connects to path using a Unix packet socket and reconnects automatically until Close is called.

func (*Client) AsyncCall added in v0.2.0 

func (c *Client) AsyncCall(function string, req any, handler any, correlationID string) error

AsyncCall sends a unary request and invokes handler when the response arrives.

func (*Client) AsyncCallContext added in v0.2.0 

func (c *Client) AsyncCallContext(ctx context.Context, function string, req any, handler any, correlationID string) error

AsyncCallContext sends a unary request and invokes handler when the response arrives. The context only controls waiting for a connection and writing the request frame.

func (*Client) AsyncCallWithTimeout added in v0.2.0 

func (c *Client) AsyncCallWithTimeout(function string, req any, handler any, correlationID string, timeout time.Duration) error

AsyncCallWithTimeout sends a unary request using a timeout while waiting for a connection and writing the request frame. The response handler runs later.

func (*Client) Call added in v0.2.0 

func (c *Client) Call(function string, req any, resp any) error

Call performs a unary request/response call using context.Background.

func (*Client) CallContext added in v0.2.0 

func (c *Client) CallContext(ctx context.Context, function string, req any, resp any) error

CallContext performs a unary request/response call. If the client is reconnecting, CallContext waits for the next connection until ctx is canceled.

func (*Client) CallWithTimeout added in v0.2.0 

func (c *Client) CallWithTimeout(function string, req any, resp any, timeout time.Duration) error

CallWithTimeout performs a unary request/response call with a timeout.

func (*Client) Close 

func (c *Client) Close() error

Close closes the client and stops reconnect attempts.

func (*Client) Connect added in v0.3.0 

func (c *Client) Connect(ctx context.Context) error

Connect establishes the first connection and starts background reconnect monitoring. It is called automatically by Dial and the TCPDial helpers.

func (*Client) WaitReady added in v0.2.0 

func (c *Client) WaitReady(ctx context.Context) error

WaitReady blocks until the client has an active connection or ctx is canceled.

type ClientContext added in v0.2.0 

type ClientContext interface {
	CorrelationID() string
	RequestID() uint64
	Function() string
	Error() error
}

ClientContext is passed to asynchronous response handlers for requests made by either a Client or an accepted Conn.

type ClientFunc added in v0.2.0 

type ClientFunc[Req, Resp any] func(context.Context, Req) (Resp, error)

ClientFunc is the typed function shape returned by Function.

func Function added in v0.2.0 

func Function[Req, Resp any](client *Client, function string) ClientFunc[Req, Resp]

Function returns a typed client function bound to a remote function name.

type ClientOptions 

type ClientOptions struct {
	ClientName       string
	Codec            Codec
	MaxFrameSize     int64
	HandshakeTimeout time.Duration
	Auth             Auth
	DialTimeout      time.Duration
	WriteTimeout     time.Duration
	Logger           *slog.Logger
	Dialer           *net.Dialer

	ReconnectMinDelay time.Duration
	ReconnectMaxDelay time.Duration
	ReconnectJitter   float64
	PingInterval      time.Duration
	PingTimeout       time.Duration
}

ClientOptions configures Dial and the network-specific dial helpers.

type Codec 

type Codec interface {
	Name() string
	Marshal(v any) ([]byte, error)
	Unmarshal(data []byte, v any) error
}

Codec marshals frame envelopes and function payloads.

type Conn added in v0.3.0 

type Conn struct {
	// contains filtered or unexported fields
}

Conn is one accepted GoRPC connection. A Conn can receive requests through server-registered functions and can also initiate requests back to the client over the same full-duplex connection.

func (*Conn) AsyncCall added in v0.3.0 

func (c *Conn) AsyncCall(function string, req any, handler any, correlationID string) error

AsyncCall sends a unary request to the connected client and invokes handler when the response arrives.

func (*Conn) AsyncCallContext added in v0.3.0 

func (c *Conn) AsyncCallContext(ctx context.Context, function string, req any, handler any, correlationID string) error

AsyncCallContext sends a unary request to the connected client and invokes handler when the response arrives.

func (*Conn) AsyncCallWithTimeout added in v0.3.0 

func (c *Conn) AsyncCallWithTimeout(function string, req any, handler any, correlationID string, timeout time.Duration) error

AsyncCallWithTimeout sends a unary request to the connected client using a timeout while writing the request frame. The response handler runs later.

func (*Conn) Call added in v0.3.0 

func (c *Conn) Call(function string, req any, resp any) error

Call performs a unary request/response call to the connected client.

func (*Conn) CallContext added in v0.3.0 

func (c *Conn) CallContext(ctx context.Context, function string, req any, resp any) error

CallContext performs a unary request/response call to the connected client.

func (*Conn) CallWithTimeout added in v0.3.0 

func (c *Conn) CallWithTimeout(function string, req any, resp any, timeout time.Duration) error

CallWithTimeout performs a unary request/response call to the connected client with a timeout.

func (*Conn) ClientName added in v0.3.0 

func (c *Conn) ClientName() string

ClientName returns the self-reported client name from the connection handshake. It is useful for logs and metrics, but is not authenticated.

func (*Conn) Close added in v0.3.0 

func (c *Conn) Close() error

Close closes the accepted connection, cancels active inbound handlers, and fails pending outbound calls.

func (*Conn) LocalAddr added in v0.3.0 

func (c *Conn) LocalAddr() net.Addr

LocalAddr returns the local address for the connection.

func (*Conn) RemoteAddr added in v0.3.0 

func (c *Conn) RemoteAddr() net.Addr

RemoteAddr returns the peer address for the connection.

type Context added in v0.2.0 

type Context struct {
	context.Context
	// contains filtered or unexported fields
}

Context is the request-scoped context passed to server handlers.

func (*Context) Call added in v0.3.0 

func (c *Context) Call(function string, req any, resp any) error

Call performs a unary request/response call back over the same accepted connection that delivered this request.

func (*Context) CallContext added in v0.3.0 

func (c *Context) CallContext(ctx context.Context, function string, req any, resp any) error

CallContext performs a unary request/response call back over the same accepted connection.

func (*Context) CallWithTimeout added in v0.3.0 

func (c *Context) CallWithTimeout(function string, req any, resp any, timeout time.Duration) error

CallWithTimeout performs a unary request/response call back over the same accepted connection with a timeout.

func (*Context) ClientName added in v0.2.0 

func (c *Context) ClientName() string

ClientName returns the self-reported client name from the connection handshake. It is useful for logs and metrics, but is not authenticated.

func (*Context) Conn added in v0.3.0 

func (c *Context) Conn() *Conn

Conn returns the accepted connection that delivered this request when the handler is running on a Server. Client-side handlers return nil here because they can already call back through their Client.

func (*Context) Function added in v0.2.0 

func (c *Context) Function() string

Function returns the remote function name for the request.

func (*Context) LocalAddr added in v0.2.0 

func (c *Context) LocalAddr() net.Addr

LocalAddr returns the local address for the connection.

func (*Context) RemoteAddr added in v0.2.0 

func (c *Context) RemoteAddr() net.Addr

RemoteAddr returns the peer address for the connection.

func (*Context) RequestID added in v0.2.0 

func (c *Context) RequestID() uint64

RequestID returns the request ID from the GoRPC frame.

type Frame 

type Frame struct {
	Version          uint16    `msgpack:"version"`
	Type             FrameType `msgpack:"type"`
	RequestID        uint64    `msgpack:"request_id,omitempty"`
	Function         string    `msgpack:"function,omitempty"`
	DeadlineUnixNano int64     `msgpack:"deadline_unix_nano,omitempty"`
	Payload          []byte    `msgpack:"payload,omitempty"`
}

Frame is the v1 wire envelope. It is MessagePack-encoded and written with a 4-byte big-endian length prefix.

type FrameType 

type FrameType uint8

FrameType identifies the kind of message carried by a frame. 

const (
	FrameHello FrameType = iota + 1
	FrameHelloAck
	FrameRequest
	FrameResponse
	FrameError
	FrameCancel
	FramePing
	FramePong
	FrameStreamItem
	FrameStreamEnd
	FrameAuth
	FrameAuthAck
)

Frame types used by the v1 protocol.

func (FrameType) String 

func (t FrameType) String() string

type HandlerFunc 

type HandlerFunc[Req, Resp any] func(*Context, Req) (Resp, error)

HandlerFunc is the typed function shape used by registered unary functions.

type MessagePackCodec 

type MessagePackCodec struct{}

MessagePackCodec is the default v1 codec.

func (MessagePackCodec) Marshal 

func (MessagePackCodec) Marshal(v any) ([]byte, error)

Marshal encodes v as MessagePack.

func (MessagePackCodec) Name 

func (MessagePackCodec) Name() string

Name returns the handshake name for MessagePackCodec.

func (MessagePackCodec) Unmarshal 

func (MessagePackCodec) Unmarshal(data []byte, v any) error

Unmarshal decodes MessagePack data into v.

type RemoteError 

type RemoteError struct {
	Code    string         `msgpack:"code" json:"code"`
	Message string         `msgpack:"message" json:"message"`
	Details map[string]any `msgpack:"details,omitempty" json:"details,omitempty"`
}

RemoteError is sent in FrameError payloads and returned by callers when the server handled the request but rejected or failed it.

func NewRemoteError 

func NewRemoteError(code, message string, details map[string]any) *RemoteError

NewRemoteError creates a structured error suitable for returning from a handler.

func (*RemoteError) Error 

func (e *RemoteError) Error() string

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server accepts GoRPC connections, dispatches registered functions, and exposes accepted connections that can initiate requests back to the dialing side.

func NewServer 

func NewServer(opts ServerOptions) *Server

NewServer creates a Server with default codec and limits where options are unset.

func (*Server) Connections added in v0.3.0 

func (s *Server) Connections() []*Conn

Connections returns a snapshot of currently accepted connections.

func (*Server) ServeListener added in v0.2.0 

func (s *Server) ServeListener(ln net.Listener) error

ServeListener accepts GoRPC connections from ln until Shutdown is called or the listener returns an unrecoverable error.

func (*Server) ServeTCP added in v0.2.0 

func (s *Server) ServeTCP(address string) error

ServeTCP listens on address with the "tcp" network and serves GoRPC connections.

func (*Server) ServeUnix added in v0.2.0 

func (s *Server) ServeUnix(path string) error

ServeUnix listens on path with the "unix" network and serves GoRPC connections.

func (*Server) ServeUnixPacket added in v0.2.0 

func (s *Server) ServeUnixPacket(path string) error

ServeUnixPacket listens on path with the "unixpacket" network and serves GoRPC connections.

func (*Server) Shutdown 

func (s *Server) Shutdown(ctx context.Context) error

Shutdown closes the listener, closes active connections, and waits for handlers to exit.

type ServerOptions 

type ServerOptions struct {
	Codec            Codec
	MaxFrameSize     int64
	HandshakeTimeout time.Duration
	Auth             Auth
	WriteTimeout     time.Duration
	Logger           *slog.Logger
	OnConnect        func(*Conn)
	OnDisconnect     func(*Conn)
}

ServerOptions configures a GoRPC server.

Source Files

View all Source files

Directories

Path Synopsis
examples
inventory/client command
Package main runs the GoRPC Inventory example client.
 Package main runs the GoRPC Inventory example client.
inventory/server command
Package main runs the GoRPC Inventory example server.
 Package main runs the GoRPC Inventory example server.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.