Documentation
¶
Overview ¶
Package retry provides a YARPC middleware which is able to retry failed outbound unary requests.
Usage ¶
To build a retry middleware from config, first decode your configuration into a `map[string]interface{}` and pass it into the `NewOutboundMiddlewareFromConfig` function.
var data map[string]interface{}
err := yaml.Unmarshal(myYAMLConfig, &data)
mw, err := retry.NewOutboundMiddlewareFromConfig(data)
Retry middleware can also be built by creating a PolicyProvider and passing it in as an option to the `NewOutboundMiddleware` function.
mw := retry.NewOutboundMiddleware(retry.WithPolicyProvider(policyProvider))
Check out the PolicyProvider docs for more details.
Configuration ¶
The configuration may be specified in YAML or as any Go-level map[string]interface{}. The examples below use YAML for illustration purposes but other markup formats may be parsed into map[string]interface{} as long as the information provided is the same.
The configuration accepts the following top-level attributes: policies, default, and overrides.
policies: # ... default: ... overrides: # ...
See the following sections for details on the policies, default, and overrides keys in the configuration.
Policies Configuration ¶
The 'policies' attribute is a map from a policy name to the configuration for that policy.
policies:
fastretry:
retries: 5
maxTimeout: 10ms
backoff:
exponential:
first: 5ms
max: 1s
slowretry:
retries: 3
maxTimeout: 100ms
backoff:
exponential:
first: 5ms
max: 10s
This configuration would create two retry policies we could use later.
The fastretry policy will enforce a per-request timeout of 10 milliseconds, making 5 more attempts after the first failure, with an exponential backoff starting at 5 milliseconds between requests and a maximum of 1 second.
The slowretry policy will enforce a per-request timeout of 100 milliseconds, and will make 3 more attempts after the first failure, with an exponential backoff starting at 5 milliseconds between requests and a maximum of 10 seconds.
Default Configuration ¶
The 'default' attributes indicates which policy will be the default for all retry attempts. The value must be a policy name from the 'policies' section, if unspecified, no retries will be performed by default.
default: slowretry
'slowretry' needs to be a defined policy in the 'policies' section (or it needs to be one of the default policies we've provided).
Overrides Configuration ¶
The 'overrides' attribute configures custom retry policies for specific services or procedures.
overrides:
- service: fastservice
with: fastretry
- service: fastservice
procedure: slowprocedure
with: slowretry
- procedure: fastprocedure
with: fastretry
Each override specifies which policy will be used based on the `with` attribute, which must point to one of the 'policies' we've defined in the 'policies' section. We can specify policies with varying levels of granularity. We can specify both, 'service' and 'procedure' to apply the policy to requests made to that procedure of that service, or we can specify just 'service' to apply the given policy to all requests made to that service, or we can specify a 'procedure' that will get applied to all requests made to a procedure name.
In terms of preference, the order of importance for policies will be:
- "service" and "procedure" overrides
- "service" overrides
- "procedure" overrides
- default policy
Index ¶
- type MiddlewareConfig
- type MiddlewareOption
- type OutboundMiddleware
- type Policy
- type PolicyConfig
- type PolicyOption
- type PolicyOverrideConfig
- type PolicyProvider
- type ProcedurePolicyProvider
- func (ppp *ProcedurePolicyProvider) Policy(_ context.Context, req *transport.Request) *Policy
- func (ppp *ProcedurePolicyProvider) RegisterProcedure(procedure string, pol *Policy)
- func (ppp *ProcedurePolicyProvider) RegisterService(service string, pol *Policy)
- func (ppp *ProcedurePolicyProvider) RegisterServiceProcedure(service, procedure string, pol *Policy)
- func (ppp *ProcedurePolicyProvider) SetDefault(pol *Policy)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type MiddlewareConfig ¶
type MiddlewareConfig struct {
// NameToPolicies is a map of names to policy configs which can be
// referenced later.
NameToPolicies map[string]PolicyConfig `config:"policies"`
// Default is the name of the default policy that will be used.
Default string `config:"default"`
// PolicyOverrides allow changing the retry policies for requests matching
// certain criteria.
PolicyOverrides []PolicyOverrideConfig `config:"overrides"`
}
MiddlewareConfig is a definition of how to create a retry middleware.
type MiddlewareOption ¶
type MiddlewareOption interface {
// contains filtered or unexported methods
}
MiddlewareOption customizes the behavior of a retry middleware.
func WithLogger ¶ added in v1.14.0
func WithLogger(logger *zap.Logger) MiddlewareOption
WithLogger sets a zap Logger that will be used to record retry logs.
func WithPolicyProvider ¶
func WithPolicyProvider(provider PolicyProvider) MiddlewareOption
WithPolicyProvider allows a custom retry policy to be used in the retry middleware.
func WithTally ¶
func WithTally(scope tally.Scope) MiddlewareOption
WithTally sets a Tally scope that will be used to record retry metrics.
type OutboundMiddleware ¶
type OutboundMiddleware struct {
// contains filtered or unexported fields
}
OutboundMiddleware is a retry middleware that wraps a UnaryOutbound with Middleware.
func NewUnaryMiddleware ¶
func NewUnaryMiddleware(opts ...MiddlewareOption) *OutboundMiddleware
NewUnaryMiddleware creates a new Retry Middleware
func NewUnaryMiddlewareFromConfig ¶
func NewUnaryMiddlewareFromConfig(src interface{}, opts ...MiddlewareOption) (*OutboundMiddleware, error)
NewUnaryMiddlewareFromConfig creates a new policy provider that can be used in retry middleware.
func (*OutboundMiddleware) Call ¶
func (r *OutboundMiddleware) Call(ctx context.Context, request *transport.Request, out transport.UnaryOutbound) (resp *transport.Response, err error)
Call implements the middleware.UnaryOutbound interface.
func (*OutboundMiddleware) Stop ¶ added in v1.14.0
func (r *OutboundMiddleware) Stop() error
Stop tells the retry middleware to clean itself up before the process stops. We currently use this to stop sending metrics to Tally.
type Policy ¶
type Policy struct {
// contains filtered or unexported fields
}
Policy defines how a retry will be applied. It contains all the information needed to perform a retry.
func NewPolicy ¶
func NewPolicy(opts ...PolicyOption) *Policy
NewPolicy creates a new retry Policy that can be used in retry middleware.
type PolicyConfig ¶
type PolicyConfig struct {
// Retries indicates the number of retries that will be attempted on failed
// requests.
Retries uint `config:"retries"`
// MaxTimeout indicates the max timeout that every request through the retry
// middleware will have. If the timeout is greater than the request timeout
// we'll use the request timeout instead.
MaxTimeout time.Duration `config:"maxTimeout"`
// BackoffStrategy defines a backoff strategy in place by embedding a
// backoff config.
BackoffStrategy yarpcconfig.Backoff `config:"backoff"`
}
PolicyConfig defines how to construct a retry Policy.
type PolicyOption ¶
type PolicyOption interface {
// contains filtered or unexported methods
}
PolicyOption customizes the behavior of a retry policy.
func BackoffStrategy ¶
func BackoffStrategy(strategy backoff.Strategy) PolicyOption
BackoffStrategy sets the backoff strategy that will be used after each failed request.
Defaults to no backoff.
func MaxRequestTimeout ¶
func MaxRequestTimeout(timeout time.Duration) PolicyOption
MaxRequestTimeout is the Timeout we will enforce per request (if this is greater than the context deadline, we'll use that instead).
Defaults to 1 second.
func Retries ¶
func Retries(retries uint) PolicyOption
Retries is the number of times we will retry the request (after the initial attempt).
Defaults to 1.
type PolicyOverrideConfig ¶
type PolicyOverrideConfig struct {
// Service is a YARPC service name for an override.
Service string `config:"service"`
// Procedure is a YARPC procedure name for an override.
Procedure string `config:"procedure"`
// WithPolicy specifies the policy name to use for the override. It MUST
// reference an existing policy.
WithPolicy string `config:"with"`
}
PolicyOverrideConfig defines per service or per service+procedure Policies that will be applied in the PolicyProvider.
type PolicyProvider ¶
type PolicyProvider interface {
// Policy returns a policy to use for retries.
Policy(context.Context, *transport.Request) *Policy
}
PolicyProvider returns a retry policy to use for the given context and request. Nil responses will be interpreted as "no retries".
type ProcedurePolicyProvider ¶
type ProcedurePolicyProvider struct {
// contains filtered or unexported fields
}
ProcedurePolicyProvider is a PolicyProvider that keeps a registry of three types of Policies with ordered precedence:
- Policies that should be applied to a specific Service and Procedure match.
- Policies that should be applied to a specific Service match.
- A Default policy that will be applied of there are no matches.
func NewProcedurePolicyProvider ¶
func NewProcedurePolicyProvider() *ProcedurePolicyProvider
NewProcedurePolicyProvider creates a new ProcedurePolicyProvider.
func (*ProcedurePolicyProvider) Policy ¶
Policy returns a policy for the provided context and request.
func (*ProcedurePolicyProvider) RegisterProcedure ¶ added in v1.11.0
func (ppp *ProcedurePolicyProvider) RegisterProcedure(procedure string, pol *Policy)
RegisterProcedure specifies the retry policy for requests that match the given procedure name.
func (*ProcedurePolicyProvider) RegisterService ¶
func (ppp *ProcedurePolicyProvider) RegisterService(service string, pol *Policy)
RegisterService specifies the retry policy for requests that match the given service name.
func (*ProcedurePolicyProvider) RegisterServiceProcedure ¶
func (ppp *ProcedurePolicyProvider) RegisterServiceProcedure(service, procedure string, pol *Policy)
RegisterServiceProcedure specifies the retry policy for requests that match the given service and procedure name.
func (*ProcedurePolicyProvider) SetDefault ¶
func (ppp *ProcedurePolicyProvider) SetDefault(pol *Policy)
SetDefault specifies the default retry Policy that will be used if there are no matches for any other policy (based on Service or Procedure).
Source Files