gax
packagemodule
This package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
- Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
- Tagged version
Modules with tagged versions give importers more predictable builds.
- Stable version
When a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Open Source Insights
Documentation¶
Overview¶
Package gax contains a set of modules which aid the development of APIsfor clients and servers based on gRPC and Google API conventions.
Application code will rarely need to use this library directly.However, code generated automatically from API definition files can use itto simplify code generation and to provide more convenient and idiomatic API surfaces.
Index¶
- Constants
- Variables
- func BuildHeaders(ctx context.Context, keyvals ...string) http.Header
- func DetermineContentType(media io.Reader) (io.Reader, string)
- func InsertMetadataIntoOutgoingContext(ctx context.Context, keyvals ...string) context.Context
- func Invoke(ctx context.Context, call APICall, opts ...CallOption) error
- func IsFeatureEnabled(name string) bool
- func Sleep(ctx context.Context, d time.Duration) error
- func TestOnlyResetIsFeatureEnabled()
- func XGoogHeader(keyval ...string) string
- type APICall
- type Backoff
- type CallOption
- type CallSettings
- type ProtoJSONStream
- type Retryer
Examples¶
Constants¶
const Version =internal.VersionVersion specifies the gax-go version being used.
Variables¶
var (// GoVersion is a header-safe representation of the current runtime// environment's Go version. This is for GAX consumers that need to// report the Go runtime version in API calls.GoVersionstring)
Functions¶
funcBuildHeaders¶added inv2.12.0
BuildHeaders is for use by the Google Cloud Libraries only. See packagegithub.com/googleapis/gax-go/v2/callctx for help setting/retrievingrequest/response headers.
BuildHeaders returns a new http.Header that merges the providedkeyvals header pairs with any existing metadata/headers in the providedcontext. keyvals should have a corresponding value for every key provided.If there is an odd number of keyvals this method will panic.Existing values for keys will not be overwritten, instead provided valueswill be appended to the list of existing values.
funcDetermineContentType¶added inv2.6.0
DetermineContentType determines the content type of the supplied reader.The content of media will be sniffed to determine the content type.After calling DetectContentType the caller must not perform further reads onmedia, but rather read from the Reader that is returned.
funcInsertMetadataIntoOutgoingContext¶added inv2.12.0
InsertMetadataIntoOutgoingContext is for use by the Google Cloud Librariesonly. See packagegithub.com/googleapis/gax-go/v2/callctx for helpsetting/retrieving request/response headers.
InsertMetadataIntoOutgoingContext returns a new context that merges theprovided keyvals metadata pairs with any existing metadata/headers in theprovided context. keyvals should have a corresponding value for every keyprovided. If there is an odd number of keyvals this method will panic.Existing values for keys will not be overwritten, instead provided valueswill be appended to the list of existing values.
funcInvoke¶
func Invoke(ctxcontext.Context, callAPICall, opts ...CallOption)error
Invoke calls the given APICall, performing retries as specified by opts, ifany.
Example (Grpc)¶
package mainimport ("context""time"gax "github.com/googleapis/gax-go/v2""google.golang.org/grpc/codes")// Some result that the client might return.type fakeResponse struct{}// Some client that can perform RPCs.type fakeClient struct{}// PerformSomeRPC is a fake RPC that a client might perform.func (c *fakeClient) PerformSomeRPC(ctx context.Context) (*fakeResponse, error) {return nil, nil}func main() {ctx := context.Background()c := &fakeClient{}opt := gax.WithRetry(func() gax.Retryer {return gax.OnCodes([]codes.Code{codes.Unknown, codes.Unavailable}, gax.Backoff{Initial: time.Second,Max: 32 * time.Second,Multiplier: 2,})})var resp *fakeResponseerr := gax.Invoke(ctx, func(ctx context.Context, settings gax.CallSettings) error {var err errorresp, err = c.PerformSomeRPC(ctx)return err}, opt)if err != nil {// TODO: handle err}_ = resp // TODO: use resp if err is nil}Example (Http)¶
package mainimport ("context""net/http""time"gax "github.com/googleapis/gax-go/v2")// Some result that the client might return.type fakeResponse struct{}// Some client that can perform RPCs.type fakeClient struct{}// PerformSomeRPC is a fake RPC that a client might perform.func (c *fakeClient) PerformSomeRPC(ctx context.Context) (*fakeResponse, error) {return nil, nil}func main() {ctx := context.Background()c := &fakeClient{}opt := gax.WithRetry(func() gax.Retryer {return gax.OnHTTPCodes(gax.Backoff{Initial: time.Second,Max: 32 * time.Second,Multiplier: 2,}, http.StatusBadGateway, http.StatusServiceUnavailable)})var resp *fakeResponseerr := gax.Invoke(ctx, func(ctx context.Context, settings gax.CallSettings) error {var err errorresp, err = c.PerformSomeRPC(ctx)return err}, opt)if err != nil {// TODO: handle err}_ = resp // TODO: use resp if err is nil}funcIsFeatureEnabled¶added inv2.16.0
IsFeatureEnabled checks if an experimental feature is enabled viaenvironment variable. The environment variable must be prefixed with"GOOGLE_SDK_GO_EXPERIMENTAL_". The feature name passed to thisfunction must be the suffix (e.g., "FOO" for "GOOGLE_SDK_GO_EXPERIMENTAL_FOO").To enable the feature, the environment variable's value must be "true",case-insensitive. The result for each name is cached on the first call.
funcSleep¶
Sleep is similar to time.Sleep, but it can be interrupted by ctx.Done() closing.If interrupted, Sleep returns ctx.Err().
funcTestOnlyResetIsFeatureEnabled¶added inv2.16.0
func TestOnlyResetIsFeatureEnabled()
TestOnlyResetIsFeatureEnabled is for testing purposes only. It resets the cachedfeature flags, allowing environment variables to be re-read on the next call to IsFeatureEnabled.This function is not thread-safe; if another goroutine reads a feature after thisfunction is called but before the `featureEnabledOnce` is re-initialized by IsFeatureEnabled,it may see an inconsistent state.
funcXGoogHeader¶
XGoogHeader is for use by the Google Cloud Libraries only. See packagegithub.com/googleapis/gax-go/v2/callctx for help setting/retrievingrequest/response headers.
XGoogHeader formats key-value pairs.The resulting string is suitable for x-goog-api-client header.
Types¶
typeAPICall¶
type APICall func(context.Context,CallSettings)error
APICall is a user defined call stub.
typeBackoff¶
type Backoff struct {// Initial is the initial value of the retry period, defaults to 1 second.Initialtime.Duration// Max is the maximum value of the retry period, defaults to 30 seconds.Maxtime.Duration// Multiplier is the factor by which the retry period increases.// It should be greater than 1 and defaults to 2.Multiplierfloat64// contains filtered or unexported fields}Backoff implements backoff logic for retries. The configuration for retriesis described inhttps://google.aip.dev/client-libraries/4221. The currentretry limit starts at Initial and increases by a factor of Multiplier everyretry, but is capped at Max. The actual wait time between retries is arandom value between 1ns and the current retry limit. The purpose of thisrandom jitter is explained inhttps://www.awsarchitectureblog.com/2015/03/backoff.html.
Note: MaxNumRetries / RPCDeadline is specifically not provided. These shouldbe built on top of Backoff.
Example¶
package mainimport ("context""net/http""time"gax "github.com/googleapis/gax-go/v2")func main() {ctx := context.Background()bo := gax.Backoff{Initial: time.Second,Max: time.Minute, // Maximum amount of time between retries.Multiplier: 2,}performHTTPCallWithRetry := func(ctx context.Context, doHTTPCall func(ctx context.Context) (*http.Response, error)) (*http.Response, error) {for {resp, err := doHTTPCall(ctx)if err != nil {// Retry 503 UNAVAILABLE.if resp.StatusCode == http.StatusServiceUnavailable {if err := gax.Sleep(ctx, bo.Pause()); err != nil {return nil, err}continue}return nil, err}return resp, err}}// It's recommended to set deadlines on HTTP calls and around retrying. This// is also usually preferred over setting some fixed number of retries: one// advantage this has is that backoff settings can be changed independently// of the deadline, whereas with a fixed number of retries the deadline// would be a constantly-shifting goalpost.ctxWithTimeout, cancel := context.WithDeadline(ctx, time.Now().Add(5*time.Minute))defer cancel()resp, err := performHTTPCallWithRetry(ctxWithTimeout, func(ctx context.Context) (*http.Response, error) {req, err := http.NewRequest("some-method", "example.com", nil)if err != nil {return nil, err}req = req.WithContext(ctx)return http.DefaultClient.Do(req)})if err != nil {// TODO: handle err}_ = resp // TODO: use resp if err is nil}typeCallOption¶
type CallOption interface {// Resolve applies the option by modifying cs.Resolve(cs *CallSettings)}CallOption is an option used by Invoke to control behaviors of RPC calls.CallOption works by modifying relevant fields of CallSettings.
funcWithGRPCOptions¶
func WithGRPCOptions(opt ...grpc.CallOption)CallOption
WithGRPCOptions allows passing gRPC call options during client creation.
funcWithPath¶added inv2.3.0
func WithPath(pstring)CallOption
WithPath applies a Path override to the HTTP-based APICall.
This is for internal use only.
funcWithTimeout¶added inv2.8.0
func WithTimeout(ttime.Duration)CallOption
WithTimeout is a convenience option for setting a context.WithTimeout on thesingular context.Context used for **all** APICall attempts. Calculated fromthe start of the first APICall attempt.If the context.Context provided to Invoke already has a Deadline set, thatwill always be respected over the deadline calculated using this option.
typeCallSettings¶
type CallSettings struct {// Retry returns a Retryer to be used to control retry logic of a method call.// If Retry is nil or the returned Retryer is nil, the call will not be retried.Retry func()Retryer// CallOptions to be forwarded to GRPC.GRPC []grpc.CallOption// Path is an HTTP override for an APICall.Pathstring// contains filtered or unexported fields}CallSettings allow fine-grained control over how calls are made.
typeProtoJSONStream¶added inv2.2.0
type ProtoJSONStream struct {// contains filtered or unexported fields}ProtoJSONStream represents a wrapper for consuming a stream of protobufmessages encoded using protobuf-JSON format. More information on this formatcan be found athttps://developers.google.com/protocol-buffers/docs/proto3#json.The stream must appear as a comma-delimited, JSON array of obbjects withopening and closing square braces.
This is for internal use only.
Example¶
package mainimport ("io""net/http"gax "github.com/googleapis/gax-go/v2""google.golang.org/protobuf/reflect/protoreflect""google.golang.org/protobuf/types/known/structpb")func main() {var someHTTPCall func() (http.Response, error)res, err := someHTTPCall()if err != nil {// TODO: handle err}// The type of message expected in the stream.var typ protoreflect.MessageType = (&structpb.Struct{}).ProtoReflect().Type()stream := gax.NewProtoJSONStreamReader(res.Body, typ)defer stream.Close()for {m, err := stream.Recv()if err != nil {break}// TODO: use resp_ = m.(*structpb.Struct)}if err != io.EOF {// TODO: handle err}}funcNewProtoJSONStreamReader¶added inv2.2.0
func NewProtoJSONStreamReader(rcio.ReadCloser, typprotoreflect.MessageType) *ProtoJSONStream
NewProtoJSONStreamReader accepts a stream of bytes via an io.ReadCloser that areprotobuf-JSON encoded protobuf messages of the given type. The ProtoJSONStreammust be closed when done.
This is for internal use only.
func (*ProtoJSONStream)Close¶added inv2.2.0
func (s *ProtoJSONStream) Close()error
Close closes the stream so that resources are cleaned up.
func (*ProtoJSONStream)Recv¶added inv2.2.0
func (s *ProtoJSONStream) Recv() (proto.Message,error)
Recv decodes the next protobuf message in the stream or returns io.EOF ifthe stream is done. It is not safe to call Recv on the same stream fromdifferent goroutines, just like it is not safe to do so with a single gRPCstream. Type-cast the protobuf message returned to the type provided atProtoJSONStream creation.Calls to Recv after calling Close will produce io.EOF.
typeRetryer¶
type Retryer interface {// Retry reports whether a request should be retried and how long to pause before retrying// if the previous attempt returned with err. Invoke never calls Retry with nil error.Retry(errerror) (pausetime.Duration, shouldRetrybool)}Retryer is used by Invoke to determine retry behavior.
funcOnCodes¶
OnCodes returns a Retryer that retries if and only ifthe previous attempt returns a GRPC error whose error code is stored in cc.Pause times between retries are specified by bo.
bo is only used for its parameters; each Retryer has its own copy.
Example¶
package mainimport ("context""time"gax "github.com/googleapis/gax-go/v2""google.golang.org/grpc/codes")// Some result that the client might return.type fakeResponse struct{}// Some client that can perform RPCs.type fakeClient struct{}// PerformSomeRPC is a fake RPC that a client might perform.func (c *fakeClient) PerformSomeRPC(ctx context.Context) (*fakeResponse, error) {return nil, nil}func main() {ctx := context.Background()c := &fakeClient{}// UNKNOWN and UNAVAILABLE are typically safe to retry for idempotent RPCs.retryer := gax.OnCodes([]codes.Code{codes.Unknown, codes.Unavailable}, gax.Backoff{Initial: time.Second,Max: 32 * time.Second,Multiplier: 2,})performSomeRPCWithRetry := func(ctx context.Context) (*fakeResponse, error) {for {resp, err := c.PerformSomeRPC(ctx)if err != nil {if delay, shouldRetry := retryer.Retry(err); shouldRetry {if err := gax.Sleep(ctx, delay); err != nil {return nil, err}continue}return nil, err}return resp, err}}// It's recommended to set deadlines on RPCs and around retrying. This is// also usually preferred over setting some fixed number of retries: one// advantage this has is that backoff settings can be changed independently// of the deadline, whereas with a fixed number of retries the deadline// would be a constantly-shifting goalpost.ctxWithTimeout, cancel := context.WithDeadline(ctx, time.Now().Add(5*time.Minute))defer cancel()resp, err := performSomeRPCWithRetry(ctxWithTimeout)if err != nil {// TODO: handle err}_ = resp // TODO: use resp if err is nil}funcOnErrorFunc¶added inv2.1.0
OnErrorFunc returns a Retryer that retries if and only if the previous attemptreturns an error that satisfies shouldRetry.
Pause times between retries are specified by bo. bo is only used for itsparameters; each Retryer has its own copy.
Example¶
package mainimport ("context""time"gax "github.com/googleapis/gax-go/v2""google.golang.org/grpc/codes""google.golang.org/grpc/status")// Some result that the client might return.type fakeResponse struct{}// Some client that can perform RPCs.type fakeClient struct{}// PerformSomeRPC is a fake RPC that a client might perform.func (c *fakeClient) PerformSomeRPC(ctx context.Context) (*fakeResponse, error) {return nil, nil}func main() {ctx := context.Background()c := &fakeClient{}shouldRetryUnavailableUnKnown := func(err error) bool {st, ok := status.FromError(err)if !ok {return false}return st.Code() == codes.Unavailable || st.Code() == codes.Unknown}retryer := gax.OnErrorFunc(gax.Backoff{Initial: time.Second,Max: 32 * time.Second,Multiplier: 2,}, shouldRetryUnavailableUnKnown)performSomeRPCWithRetry := func(ctx context.Context) (*fakeResponse, error) {for {resp, err := c.PerformSomeRPC(ctx)if err != nil {if delay, shouldRetry := retryer.Retry(err); shouldRetry {if err := gax.Sleep(ctx, delay); err != nil {return nil, err}continue}return nil, err}return resp, err}}// It's recommended to set deadlines on RPCs and around retrying. This is// also usually preferred over setting some fixed number of retries: one// advantage this has is that backoff settings can be changed independently// of the deadline, whereas with a fixed number of retries the deadline// would be a constantly-shifting goalpost.ctxWithTimeout, cancel := context.WithDeadline(ctx, time.Now().Add(5*time.Minute))defer cancel()resp, err := performSomeRPCWithRetry(ctxWithTimeout)if err != nil {// TODO: handle err}_ = resp // TODO: use resp if err is nil}funcOnHTTPCodes¶added inv2.4.0
OnHTTPCodes returns a Retryer that retries if and only ifthe previous attempt returns a googleapi.Error whose status code is stored incc. Pause times between retries are specified by bo.
bo is only used for its parameters; each Retryer has its own copy.
Example¶
package mainimport ("context""net/http""time"gax "github.com/googleapis/gax-go/v2")// Some result that the client might return.type fakeResponse struct{}// Some client that can perform RPCs.type fakeClient struct{}// PerformSomeRPC is a fake RPC that a client might perform.func (c *fakeClient) PerformSomeRPC(ctx context.Context) (*fakeResponse, error) {return nil, nil}func main() {ctx := context.Background()c := &fakeClient{}retryer := gax.OnHTTPCodes(gax.Backoff{Initial: time.Second,Max: 32 * time.Second,Multiplier: 2,}, http.StatusBadGateway, http.StatusServiceUnavailable)performSomeRPCWithRetry := func(ctx context.Context) (*fakeResponse, error) {for {resp, err := c.PerformSomeRPC(ctx)if err != nil {if delay, shouldRetry := retryer.Retry(err); shouldRetry {if err := gax.Sleep(ctx, delay); err != nil {return nil, err}continue}return nil, err}return resp, err}}// It's recommended to set deadlines on RPCs and around retrying. This is// also usually preferred over setting some fixed number of retries: one// advantage this has is that backoff settings can be changed independently// of the deadline, whereas with a fixed number of retries the deadline// would be a constantly-shifting goalpost.ctxWithTimeout, cancel := context.WithDeadline(ctx, time.Now().Add(5*time.Minute))defer cancel()resp, err := performSomeRPCWithRetry(ctxWithTimeout)if err != nil {// TODO: handle err}_ = resp // TODO: use resp if err is nil}
Source Files¶
Directories¶
| Path | Synopsis |
|---|---|
Package apierror implements a wrapper error for parsing error details from API calls. | Package apierror implements a wrapper error for parsing error details from API calls. |
Package callctx provides helpers for storing and retrieving values out of context.Context. | Package callctx provides helpers for storing and retrieving values out of context.Context. |
Package internallog in intended for internal use by generated clients only. | Package internallog in intended for internal use by generated clients only. |
grpclog Package grpclog in intended for internal use by generated clients only. | Package grpclog in intended for internal use by generated clients only. |
internal Package internal provides some common logic and types to other logging sub-packages. | Package internal provides some common logic and types to other logging sub-packages. |
internal/logtest Package logtest is a helper for validating logging tests. | Package logtest is a helper for validating logging tests. |
Package iterator contains helper for working with iterators. | Package iterator contains helper for working with iterators. |