github.com/cloudwego/kitex@v0.9.0/pkg/retry/policy.go

/*
 * Copyright 2021 CloudWeGo Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package retry

import (
	"fmt"

	"github.com/cloudwego/kitex/pkg/rpcinfo"
)

// Type is retry type include FailureType, BackupType
type Type int

// retry types
const (
	FailureType Type = iota
	BackupType
)

// String prints human readable information.
func (t Type) String() string {
	switch t {
	case FailureType:
		return "Failure"
	case BackupType:
		return "Backup"
	}
	return ""
}

// BuildFailurePolicy is used to build Policy with *FailurePolicy
func BuildFailurePolicy(p *FailurePolicy) Policy {
	if p == nil {
		return Policy{}
	}
	return Policy{Enable: true, Type: FailureType, FailurePolicy: p}
}

// BuildBackupRequest is used to build Policy with *BackupPolicy
func BuildBackupRequest(p *BackupPolicy) Policy {
	if p == nil {
		return Policy{}
	}
	return Policy{Enable: true, Type: BackupType, BackupPolicy: p}
}

// Policy contains all retry policies
// DON'T FORGET to update Equals() and DeepCopy() if you add new fields
type Policy struct {
	Enable bool `json:"enable"`
	// 0 is failure retry, 1 is backup
	Type Type `json:"type"`
	// notice: only one retry policy can be enabled, which one depend on Policy.Type
	FailurePolicy *FailurePolicy `json:"failure_policy,omitempty"`
	BackupPolicy  *BackupPolicy  `json:"backup_policy,omitempty"`
}

func (p *Policy) DeepCopy() *Policy {
	if p == nil {
		return nil
	}
	return &Policy{
		Enable:        p.Enable,
		Type:          p.Type,
		FailurePolicy: p.FailurePolicy.DeepCopy(),
		BackupPolicy:  p.BackupPolicy.DeepCopy(),
	}
}

// FailurePolicy for failure retry
// DON'T FORGET to update Equals() and DeepCopy() if you add new fields
type FailurePolicy struct {
	StopPolicy        StopPolicy         `json:"stop_policy"`
	BackOffPolicy     *BackOffPolicy     `json:"backoff_policy,omitempty"`
	RetrySameNode     bool               `json:"retry_same_node"`
	ShouldResultRetry *ShouldResultRetry `json:"-"`

	// Extra is not used directly by kitex. It's used for better integrating your own config source.
	// After loading FailurePolicy from your config source, `Extra` can be decoded into a user-defined schema,
	// with which, more complex strategies can be implemented, such as modifying the `ShouldResultRetry`.
	Extra string `json:"extra"`
}

// IsRespRetryNonNil is used to check if RespRetry is nil
func (p FailurePolicy) IsRespRetryNonNil() bool {
	return p.ShouldResultRetry != nil && p.ShouldResultRetry.RespRetry != nil
}

// IsErrorRetryNonNil is used to check if ErrorRetry is nil
func (p FailurePolicy) IsErrorRetryNonNil() bool {
	return p.ShouldResultRetry != nil && p.ShouldResultRetry.ErrorRetry != nil
}

// IsRetryForTimeout is used to check if timeout error need to retry
func (p FailurePolicy) IsRetryForTimeout() bool {
	return p.ShouldResultRetry == nil || !p.ShouldResultRetry.NotRetryForTimeout
}

// BackupPolicy for backup request
// DON'T FORGET to update Equals() and DeepCopy() if you add new fields
type BackupPolicy struct {
	RetryDelayMS  uint32     `json:"retry_delay_ms"`
	StopPolicy    StopPolicy `json:"stop_policy"`
	RetrySameNode bool       `json:"retry_same_node"`
}

// StopPolicy is a group policies to decide when stop retry
type StopPolicy struct {
	MaxRetryTimes    int      `json:"max_retry_times"`
	MaxDurationMS    uint32   `json:"max_duration_ms"`
	DisableChainStop bool     `json:"disable_chain_stop"`
	DDLStop          bool     `json:"ddl_stop"`
	CBPolicy         CBPolicy `json:"cb_policy"`
}

const (
	defaultCBErrRate = 0.1
	cbMinSample      = 10
)

// CBPolicy is the circuit breaker policy
type CBPolicy struct {
	ErrorRate float64 `json:"error_rate"`
}

// BackOffPolicy is the BackOff policy.
// DON'T FORGET to update Equals() and DeepCopy() if you add new fields
type BackOffPolicy struct {
	BackOffType BackOffType               `json:"backoff_type"`
	CfgItems    map[BackOffCfgKey]float64 `json:"cfg_items,omitempty"`
}

// BackOffType means the BackOff type.
type BackOffType string

// all back off types
const (
	NoneBackOffType   BackOffType = "none"
	FixedBackOffType  BackOffType = "fixed"
	RandomBackOffType BackOffType = "random"
)

// BackOffCfgKey represents the keys for BackOff.
type BackOffCfgKey string

// the keys of all back off configs
const (
	FixMSBackOffCfgKey      BackOffCfgKey = "fix_ms"
	MinMSBackOffCfgKey      BackOffCfgKey = "min_ms"
	MaxMSBackOffCfgKey      BackOffCfgKey = "max_ms"
	InitialMSBackOffCfgKey  BackOffCfgKey = "initial_ms"
	MultiplierBackOffCfgKey BackOffCfgKey = "multiplier"
)

// ShouldResultRetry is used for specifying which error or resp need to be retried
type ShouldResultRetry struct {
	ErrorRetry func(err error, ri rpcinfo.RPCInfo) bool
	RespRetry  func(resp interface{}, ri rpcinfo.RPCInfo) bool
	// disable the default timeout retry in specific scenarios (e.g. the requests are not non-idempotent)
	NotRetryForTimeout bool
}

// Equals to check if policy is equal
func (p Policy) Equals(np Policy) bool {
	if p.Enable != np.Enable {
		return false
	}
	if p.Type != np.Type {
		return false
	}
	if !p.FailurePolicy.Equals(np.FailurePolicy) {
		return false
	}
	if !p.BackupPolicy.Equals(np.BackupPolicy) {
		return false
	}
	return true
}

// Equals to check if FailurePolicy is equal
func (p *FailurePolicy) Equals(np *FailurePolicy) bool {
	if p == nil {
		return np == nil
	}
	if np == nil {
		return false
	}
	if p.StopPolicy != np.StopPolicy {
		return false
	}
	if !p.BackOffPolicy.Equals(np.BackOffPolicy) {
		return false
	}
	if p.RetrySameNode != np.RetrySameNode {
		return false
	}
	if p.Extra != np.Extra {
		return false
	}
	// don't need to check `ShouldResultRetry`, ShouldResultRetry is only setup by option
	// in remote config case will always return false if check it
	return true
}

func (p *FailurePolicy) DeepCopy() *FailurePolicy {
	if p == nil {
		return nil
	}
	return &FailurePolicy{
		StopPolicy:        p.StopPolicy,
		BackOffPolicy:     p.BackOffPolicy.DeepCopy(),
		RetrySameNode:     p.RetrySameNode,
		ShouldResultRetry: p.ShouldResultRetry, // don't need DeepCopy
		Extra:             p.Extra,
	}
}

// Equals to check if BackupPolicy is equal
func (p *BackupPolicy) Equals(np *BackupPolicy) bool {
	if p == nil {
		return np == nil
	}
	if np == nil {
		return false
	}
	if p.RetryDelayMS != np.RetryDelayMS {
		return false
	}
	if p.StopPolicy != np.StopPolicy {
		return false
	}
	if p.RetrySameNode != np.RetrySameNode {
		return false
	}

	return true
}

func (p *BackupPolicy) DeepCopy() *BackupPolicy {
	if p == nil {
		return nil
	}
	return &BackupPolicy{
		RetryDelayMS:  p.RetryDelayMS,
		StopPolicy:    p.StopPolicy, // not a pointer, will copy the value here
		RetrySameNode: p.RetrySameNode,
	}
}

// Equals to check if BackOffPolicy is equal.
func (p *BackOffPolicy) Equals(np *BackOffPolicy) bool {
	if p == nil {
		return np == nil
	}
	if np == nil {
		return false
	}
	if p.BackOffType != np.BackOffType {
		return false
	}
	if len(p.CfgItems) != len(np.CfgItems) {
		return false
	}
	for k := range p.CfgItems {
		if p.CfgItems[k] != np.CfgItems[k] {
			return false
		}
	}

	return true
}

func (p *BackOffPolicy) DeepCopy() *BackOffPolicy {
	if p == nil {
		return nil
	}
	return &BackOffPolicy{
		BackOffType: p.BackOffType,
		CfgItems:    p.copyCfgItems(),
	}
}

func (p *BackOffPolicy) copyCfgItems() map[BackOffCfgKey]float64 {
	if p.CfgItems == nil {
		return nil
	}
	cfgItems := make(map[BackOffCfgKey]float64, len(p.CfgItems))
	for k, v := range p.CfgItems {
		cfgItems[k] = v
	}
	return cfgItems
}

func checkCBErrorRate(p *CBPolicy) error {
	if p.ErrorRate <= 0 || p.ErrorRate > 0.3 {
		return fmt.Errorf("invalid retry circuit breaker rate, errRate=%0.2f", p.ErrorRate)
	}
	return nil
}