grpc-client

grpc-client provides lightweight gRPC connection management, metadata helpers, and connectivity utilities for Go services. It is designed to complement google.golang.org/grpc with higher-level abstractions for connection lifecycle and retry configuration.

Features:

• ConnConfig — typed configuration struct (address, TLS, timeout, max retries, metadata)
• Connection — managed connection with Close, Metadata, and Ping helpers
• Works alongside any gRPC stub generated by protoc-gen-go-grpc
• No generated protobuf dependency — pure connection-layer utilities

Installation

go get github.com/BufferZoneCorp/grpc-client

Import path

import grpcclient "github.com/BufferZoneCorp/grpc-client"

Usage

package main

import (
    "fmt"
    "log"
    "time"

    grpcclient "github.com/BufferZoneCorp/grpc-client"
)

func main() {
    cfg := grpcclient.ConnConfig{
        Address:    "grpc.example.com:443",
        TLSEnabled: true,
        Timeout:    5 * time.Second,
        MaxRetries: 3,
        Metadata: map[string]string{
            "x-api-key":   "my-api-key",
            "x-client-id": "payments-service",
        },
    }

    conn, err := grpcclient.New(cfg)
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()

    // Check endpoint reachability before sending RPCs
    if !conn.Ping() {
        log.Fatal("gRPC endpoint is not reachable")
    }

    // Inspect connection metadata (useful for interceptors)
    for k, v := range conn.Metadata() {
        fmt.Printf("  %s: %s\n", k, v)
    }

    fmt.Println("connection ready")
}

With retries and custom timeout

cfg := grpcclient.ConnConfig{
    Address:    "internal-svc:9090",
    TLSEnabled: false,
    Timeout:    3 * time.Second,
    MaxRetries: 5,
}

conn, err := grpcclient.New(cfg)
if err != nil {
    log.Fatal(err)
}
defer conn.Close()

API reference

ConnConfig

Field	Type	Description
Address	string	host:port of the gRPC server
TLSEnabled	bool	Enable TLS transport
Timeout	time.Duration	Dial and per-call timeout
MaxRetries	int	Maximum number of retry attempts
Metadata	map[string]string	Key-value pairs sent as gRPC metadata headers

Connection methods

Method	Signature	Description
New	(cfg ConnConfig) (*Connection, error)	Create a new managed connection
Close	()	Release the connection and cancel its context
Metadata	() map[string]string	Return the configured metadata map
Ping	() bool	TCP-level reachability probe

Requirements

• Go 1.21 or later
• No external dependencies

License

MIT — see LICENSE.