Documentation
¶
Overview ¶
Package rpcclient builds gRPC client connections from a Config: it wires transport credentials, per-RPC bearer/DPoP tokens (loaded from the environment or from a retriable.Storage folder), keepalive parameters, message size limits and an optional blocking dial with timeout.
The Client owns a single *grpc.ClientConn that callers pass to the generated service constructors, together with Client.Opts() which holds the default call options (WaitForReady, MaxCallSendMsgSize, MaxCallRecvMsgSize):
cfg := &rpcclient.Config{
Endpoint: "https://api.example.com:443",
TLS: tlsCfg, // *tls.Config; nil dials without TLS
DialTimeout: 5 * time.Second,
}
if err := cfg.LoadAuthTokenOrFromEnv("MY_AUTH_TOKEN"); err != nil {
return err
}
client, err := rpcclient.New(cfg)
if err != nil {
return err
}
defer client.Close()
svc := pb.NewMyServiceClient(client.Conn())
res, err := svc.Call(ctx, req, client.Opts()...)
Endpoint accepts https://, http://, unixs:///path and unix:///path, or a bare host[:port]. Host schemes are stripped and ":443" is appended when no port is given; Unix targets use gRPC's unix resolver. TLS and the Authorization token apply when TLS is configured and the endpoint uses the https:// or unixs:// scheme. New rejects TLS with any other endpoint; nil TLS dials without security.
Config has no yaml/json tags and is populated programmatically. All constructors return errors rather than panic.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client owns a gRPC connection created from a Config, together with the default call options to use on it. Obtain one with New or NewFromURL and release it with Close.
func New ¶
New creates a client from cfg (see Config for the fields). It returns an error when Endpoint is empty, TLS is set for a non-secure endpoint, the DPoP key cannot be loaded, the AuthToken has expired, or (when DialTimeout > 0) the connection is not ready in time.
func NewFromURL ¶
NewFromURL creates a client for the endpoint with default settings: no TLS, no authentication, lazy (non-blocking) connect.
func (*Client) Conn ¶
func (c *Client) Conn() *grpc.ClientConn
Conn returns the gRPC connection, to be passed to generated service client constructors.
func (*Client) Opts ¶
func (c *Client) Opts() []grpc.CallOption
Opts returns the call options to pass on each RPC: WaitForReady(true) and the send/receive message size limits, or Config.CallOptions when set.
type Config ¶
type Config struct {
// Endpoint of the server: https://host[:port], http://, unixs:///path,
// unix:///path, or a bare host[:port]. ":443" is appended to host targets
// when no port is given.
Endpoint string
// DialTimeout, when > 0, makes New block until the connection is Ready
// or fail after this duration. Zero connects lazily in the background.
DialTimeout time.Duration
// DialKeepAliveTime is the time after which client pings the server to see if
// transport is alive.
DialKeepAliveTime time.Duration
// DialKeepAliveTimeout is the time that the client waits for a response for the
// keep-alive probe. If the response is not received in this time, the connection is closed.
DialKeepAliveTimeout time.Duration
// TLS holds the client TLS configuration. When set, Endpoint must start
// with https:// or unixs://; otherwise New returns an error. CallerIdentity
// and AuthToken are applied with TLS. A nil TLS dials without security.
TLS *tls.Config
// DialOptions is a list of extra dial options for the grpc client
// (e.g., for interceptors), appended after the options derived from
// this Config.
DialOptions []grpc.DialOption
// CallOptions, when set, replaces the default call options returned by
// Client.Opts (WaitForReady and the message size limits).
CallOptions []grpc.CallOption
// Context is the default client context; it can be used to cancel grpc dial out and
// other operations that do not have an explicit context.
Context context.Context
// MaxRecvMsgSize sets the maximum message size the client accepts from
// the server (grpc.MaxCallRecvMsgSize); 0 means math.MaxInt32.
MaxRecvMsgSize int
// MaxSendMsgSize sets the maximum message size the client sends to the
// server (grpc.MaxCallSendMsgSize); 0 means 10 MiB.
MaxSendMsgSize int
// StorageFolder is the retriable.Storage folder holding the
// .auth_token file and DPoP keys; see Storage.
StorageFolder string
// UserAgent, when set, is sent as the gRPC user agent.
UserAgent string
// CallerIdentity, when set, supplies (and refreshes) the per-RPC
// authorization token; it takes precedence over AuthToken.
CallerIdentity credentials.CallerIdentity
// AuthToken is a static token attached to every RPC, typically set by
// LoadAuthToken or CheckAuthTokenFromEnv. DPoP tokens are signed with
// the key named by DpopJkt from Storage.
AuthToken *retriable.AuthToken
// TokenLocation describes where AuthToken came from, for logging.
TokenLocation string
// contains filtered or unexported fields
}
Config describes how to build a Client. It is populated programmatically (no yaml/json tags); only Endpoint is required.
func (*Config) CheckAuthTokenFromEnv ¶ added in v0.35.346
CheckAuthTokenFromEnv loads AuthToken from the named environment variable (see retriable.ParseAuthToken for the accepted formats). It returns false when the variable is unset or empty, and an error when the value is malformed or the token has expired.
func (*Config) LoadAuthToken ¶
LoadAuthToken sets AuthToken and TokenLocation from the .auth_token file in Storage. It does not check expiry; New does.
func (*Config) LoadAuthTokenOrFromEnv ¶ added in v0.35.346
LoadAuthTokenOrFromEnv sets AuthToken from the named environment variable when it is set, otherwise from the .auth_token file in Storage.
func (*Config) SetStorage ¶ added in v0.35.348
SetStorage replaces the storage returned by Storage.
Source Files