gax - ActiveState ActiveGo 1.8

Package gax

import ""

Overview ▾

Package gax contains a set of modules which aid the development of APIs for 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 it to simplify code generation and to provide more convenient and idiomatic API surfaces.

This project is currently experimental and not supported.


const Version = "0.1.0"

func Invoke

func Invoke(ctx context.Context, call APICall, opts ...CallOption) error

Invoke calls the given APICall, performing retries as specified by opts, if any.

func Sleep

func Sleep(ctx context.Context, d time.Duration) error

Sleep is similar to time.Sleep, but it can be interrupted by ctx.Done() closing. If interrupted, Sleep returns ctx.Err().

func XGoogHeader

func XGoogHeader(keyval ...string) string

XGoogHeader is for use by the Google Cloud Libraries only.

XGoogHeader formats key-value pairs. The resulting string is suitable for x-goog-api-client header.

type APICall

A user defined call stub.

type APICall func(context.Context, CallSettings) error

type Backoff

Backoff implements exponential backoff. The wait time between retries is a random value between 0 and the "retry envelope". The envelope starts at Initial and increases by the factor of Multiplier every retry, but is capped at Max.

type Backoff struct {
    // Initial is the initial value of the retry envelope, defaults to 1 second.
    Initial time.Duration

    // Max is the maximum value of the retry envelope, defaults to 30 seconds.
    Max time.Duration

    // Multiplier is the factor by which the retry envelope increases.
    // It should be greater than 1 and defaults to 2.
    Multiplier float64
    // contains filtered or unexported fields

func (*Backoff) Pause

func (bo *Backoff) Pause() time.Duration

type CallOption

CallOption is an option used by Invoke to control behaviors of RPC calls. CallOption works by modifying relevant fields of CallSettings.

type CallOption interface {
    // Resolve applies the option by modifying cs.
    Resolve(cs *CallSettings)

func WithGRPCOptions

func WithGRPCOptions(opt ...grpc.CallOption) CallOption

func WithRetry

func WithRetry(fn func() Retryer) CallOption

WithRetry sets CallSettings.Retry to fn.

type CallSettings

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

type ParseError

type ParseError struct {
    Pos      int
    Template string
    Message  string

func (ParseError) Error

func (pe ParseError) Error() string

type PathTemplate

PathTemplate manages the template to build and match with paths used by API services. It holds a template and variable names in it, and it can extract matched patterns from a path string or build a path string from a binding.

See http.proto in for the details of the template syntax.

type PathTemplate struct {
    // contains filtered or unexported fields

func MustCompilePathTemplate

func MustCompilePathTemplate(template string) *PathTemplate

MustCompilePathTemplate is like NewPathTemplate but panics if the expression cannot be parsed. It simplifies safe initialization of global variables holding compiled regular expressions.

func NewPathTemplate

func NewPathTemplate(template string) (*PathTemplate, error)

NewPathTemplate parses a path template, and returns a PathTemplate instance if successful.

func (*PathTemplate) Match

func (pt *PathTemplate) Match(path string) (map[string]string, error)

Match attempts to match the given path with the template, and returns the mapping of the variable name to the matched pattern string.

func (*PathTemplate) Render

func (pt *PathTemplate) Render(binding map[string]string) (string, error)

Render creates a path string from its template and the binding from the variable name to the value.

type Retryer

Retryer is used by Invoke to determine retry behavior.

type Retryer interface {
    // Retry reports whether a request should be retriedand how long to pause before retrying
    // if the previous attempt returned with err. Invoke never calls Retry with nil error.
    Retry(err error) (pause time.Duration, shouldRetry bool)

func OnCodes

func OnCodes(cc []codes.Code, bo Backoff) Retryer

OnCodes returns a Retryer that retries if and only if the 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.