clientgrpc

README

client-grpc

Outbound gRPC client for omcrgnt apps: ecfg catalog resource, plaintext dial to host:port, OpenTelemetry traces via otelgrpc, Prometheus client metrics via go-grpc-middleware/providers/prometheus.

Pair with srv-grpc on the server side.

Catalog

import clientgrpc "github.com/omcrgnt/client-grpc"

type catalog struct {
	AssetGRPC *clientgrpc.Client `ecfg:"ASSET_GRPC"`
}

Client depends on the shared *GRPCMetrics singleton (registered in unique.Global on import, like srv-grpc). Ops metrics actuator calls RegisterMetrics before Start.

Typed stubs are created by the app from Conn():

mapv1.NewMapServiceClient(c.AssetGRPC.Conn())

Environment

Prefix comes from the app (EnvPrefix); fields below are relative to the slot (e.g. ASSET_GRPC).

Variable	Description
ASSET_GRPC_LABEL	Resource label (otel attribute client)
ASSET_GRPC_HOST	Target host / IP (common.v1.Host)
ASSET_GRPC_PORT	Target port 1–65535 (common.v1.Port)

Example:

BEMVPGAME_ASSET_GRPC_LABEL=asset
BEMVPGAME_ASSET_GRPC_HOST=127.0.0.1
BEMVPGAME_ASSET_GRPC_PORT=9084

Lifecycle

Hook	Role
Build / BuildConfig	Materialize from ecfg (Label, Host, Port)
Deps / Inject	Wire *GRPCMetrics
Start	grpc.NewClient with otel stats handler + prometheus interceptors
Close	Close ClientConn
Ready / ProbeReady	Wait until connectivity Ready

v1 transport is insecure/plaintext (internal mesh). TLS can be added later.

Telemetry

On Start:

• otelgrpc.NewClientHandler — client spans/metrics to process TracerProvider
• prometheus ClientMetrics (with handling-time histogram) — grpc_client_* series

Import the package (or srv-grpc) so metrics singletons exist; scrape via ops /metrics.

Example

See example/app.

Documentation

Index

• type Client
  • func (*Client) BuildConfig() (app.Materializer, error)
  • func (c *Client) Close(_ context.Context) error
  • func (c *Client) Conn() *grpc.ClientConn
  • func (*Client) Deps() []any
  • func (c *Client) Inject(args []any)
  • func (c *Client) Label() string
  • func (c *Client) ProbeReady(ctx context.Context) error
  • func (c *Client) Ready(ctx context.Context) error
  • func (c *Client) Start(ctx context.Context) error
  • func (c *Client) Target() string
• type Config
  • func (cfg *Config) Build() (any, error)
• type GRPCMetrics
  • func (m *GRPCMetrics) RegisterMetrics(reg *prom.Registry) error
  • func (m *GRPCMetrics) StreamClientInterceptor() grpc.StreamClientInterceptor
  • func (m *GRPCMetrics) UnaryClientInterceptor() grpc.UnaryClientInterceptor

Types

type Client

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

Client is an outbound gRPC connection resource. Catalog field: *Client (Configurable); dial happens in Start after Inject resolves GRPCMetrics.

func (*Client) BuildConfig

func (*Client) BuildConfig() (app.Materializer, error)

BuildConfig returns the config spec for materialize.

func (*Client) Close

func (c *Client) Close(_ context.Context) error

Close closes the gRPC connection.

func (*Client) Conn

func (c *Client) Conn() *grpc.ClientConn

Conn returns the underlying gRPC connection (nil before Start).

func (*Client) Deps

func (*Client) Deps() []any

Deps declares the shared GRPCMetrics singleton.

func (*Client) Inject

func (c *Client) Inject(args []any)

Inject receives GRPCMetrics from SDI.

func (*Client) Label

func (c *Client) Label() string

Label returns the configured resource label.

func (*Client) ProbeReady

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

ProbeReady reports outbound gRPC readiness (ops duck typing; no ops import).

func (*Client) Ready

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

Ready waits until the connection is Ready (or ctx ends).

func (*Client) Start

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

Start dials the target with otel + prometheus client instrumentation.

func (*Client) Target

func (c *Client) Target() string

Target returns host:port.

type Config

type Config struct {
	Label common.Label
	Host  common.Host
	Port  common.Port
}

Config is the gRPC client spec (Label, Host, Port); ecfg fills before Build. Target address is host:port (plaintext; TLS is out of scope for v1).

func (*Config) Build

func (cfg *Config) Build() (any, error)

type GRPCMetrics

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

GRPCMetrics is a singleton pool resource: contributor + shared prometheus interceptors for all client-grpc clients. RegisterMetrics matches ops metrics duck-typing (no ops import).

func (*GRPCMetrics) RegisterMetrics

func (m *GRPCMetrics) RegisterMetrics(reg *prom.Registry) error

func (*GRPCMetrics) StreamClientInterceptor

func (m *GRPCMetrics) StreamClientInterceptor() grpc.StreamClientInterceptor

func (*GRPCMetrics) UnaryClientInterceptor

func (m *GRPCMetrics) UnaryClientInterceptor() grpc.UnaryClientInterceptor