grpcclient

README

grpcclient

A light, framework-free gRPC client dial factory for Go — a decoupled Target, go/tls credentials, and the go/transit client interceptors

Part of the phpboyscout Go toolkit — small, framework-free Go modules extracted from go-tool-base. Docs: grpcclient.go.phpboyscout.uk

---

gitlab.com/phpboyscout/go/grpcclient builds a *grpc.ClientConn from a plain Target: transport credentials are selected from the target's go/tls pair (insecure loopback when disabled, a hardened TLS credential when enabled), the endpoint is assembled from host and port, and the caller's dial options — into which the go/transit client interceptors are passed — are applied.

It is the gRPC client half of the transport stack extracted from go-tool-base: a service or library that only dials gRPC gets the factory and transit's interceptors without ever linking the server stack (controls, authn, gateway).

Install

go get gitlab.com/phpboyscout/go/grpcclient

Quick start

package main

import (
	"gitlab.com/phpboyscout/go/grpcclient"
	gtls "gitlab.com/phpboyscout/go/tls"
	transitgrpc "gitlab.com/phpboyscout/go/transit/grpc"
	"google.golang.org/grpc"
)

func main() {
	conn, err := grpcclient.Dial(
		grpcclient.Target{
			Host: "svc.internal",
			Port: 443,
			TLS:  gtls.Pair{Enabled: true, Cert: "/etc/pki/internal-ca.pem"},
		},
		// transit client interceptors, passed as ordinary dial options
		grpc.WithChainUnaryInterceptor(
			transitgrpc.CircuitBreakerInterceptor(log, transitgrpc.DefaultCircuitBreakerConfig()),
		),
		transitgrpc.OTelClientHandler(),
	)
	if err != nil {
		panic(err)
	}
	defer conn.Close()

	// client := pb.NewYourServiceClient(conn)
}

Design

• Framework-free. Depends only on the gRPC SDK, go/tls, go/transit and cockroachdb/errors (plus transit's OTel/redact transitive deps). A depfootprint_test.go guard forbids go-tool-base, the server stack (controls/authn/gateway), Viper/Cobra/Charm and the cloud SDKs.
• Decoupled Target. Target{Host, Port, TLS} — not a server-settings type — so a client never imports server configuration.
• Credentials from the Target. Dial derives transport credentials from Target.TLS and places them ahead of the caller's options, so an option can never silently downgrade transport security.
• Interceptors are transit's. Circuit breaking and OpenTelemetry are the go/transit gRPC client interceptors; you pass them to Dial as dial options.

Compatibility

go/transit and go/tls versions are pinned and kept in lockstep with go-tool-base. Grouped Renovate updates keep them aligned.

Documentation

Guides and the factory model: grpcclient.go.phpboyscout.uk. API reference: pkg.go.dev.

License

See LICENSE.

Documentation

Overview

Package grpcclient is a light, framework-free gRPC client dial factory.

It builds a *grpc.ClientConn from a plain Target (host, port and go/tls material), selecting transport credentials from the target's TLS pair and applying the caller's dial options — into which gitlab.com/phpboyscout/go/transit's client interceptors (OTelClientHandler, CircuitBreakerInterceptor, …) are passed. It depends only on the gRPC SDK, go/tls and go/transit; it never pulls in the server stack (controls, authn, gateway) or the CLI/config/TUI stack, so a client-only consumer stays light. A depfootprint test enforces that boundary.

Index

• func Dial(t Target, opts ...grpc.DialOption) (*grpc.ClientConn, error)
• type Target

Functions

func Dial

func Dial(t Target, opts ...grpc.DialOption) (*grpc.ClientConn, error)

Dial creates a gRPC client connection to the target. It builds transport credentials from t.TLS (insecure when disabled), assembles the endpoint from Host/Port (empty Host means loopback), and applies the caller's dial options. Pass go/transit client interceptors — OTelClientHandler, the circuit-breaker client interceptors — as dial options here.

It uses grpc.NewClient, so the returned connection is lazy: no network I/O happens until the first RPC.

Types

type Target

type Target struct {
	// Host is the dial host. Empty means loopback (localhost), the common case
	// for dialing a co-located local server.
	Host string
	// Port is the dial port.
	Port int
	// TLS is the go/tls transport pair. When disabled, insecure loopback
	// credentials are used; when enabled, transport credentials are built via
	// go/tls, trusting the CA in TLS.Cert (or the system roots when Cert is empty).
	TLS gtls.Pair
}

Target identifies a gRPC server to dial. It is deliberately decoupled from any server-side settings type: a caller supplies just the host, port and TLS material, so a client-only consumer never imports a server configuration type.