Documentation
¶
Overview ¶
Package router provides an intelligent multi-processor payment routing layer.
The Router implements processor.PaymentProcessor so it can be used as a drop-in replacement anywhere a single processor is expected. Internally it delegates to real processors selected by one of five configurable strategies:
- PrimaryFallback: try a designated primary, fall back through the list
- RoundRobin: distribute requests evenly across processors
- CurrencyBased: route by currency code to a designated processor
- WeightedRandom: probabilistic distribution according to configured weights
- LeastLoad: pick the processor with the fewest in-flight requests
Each processor is wrapped in a circuit breaker that opens after consecutive failures and probes with limited requests before fully closing again.
Transaction IDs returned by the router are prefixed with the processor type (e.g. "square:ch_xxx") so that Capture and Refund operations can be routed back to the exact processor that handled the original authorization or charge.
Index ¶
- type CircuitBreakerConfig
- type Config
- type Router
- func (r *Router) Authorize(ctx context.Context, req processor.PaymentRequest) (*processor.PaymentResult, error)
- func (r *Router) Capture(ctx context.Context, transactionID string, amount currency.Cents) (*processor.PaymentResult, error)
- func (r *Router) Charge(ctx context.Context, req processor.PaymentRequest) (*processor.PaymentResult, error)
- func (r *Router) GetTransaction(ctx context.Context, txID string) (*processor.Transaction, error)
- func (r *Router) IsAvailable(ctx context.Context) bool
- func (r *Router) Refund(ctx context.Context, req processor.RefundRequest) (*processor.RefundResult, error)
- func (r *Router) SupportedCurrencies() []currency.Type
- func (r *Router) Type() processor.ProcessorType
- func (r *Router) ValidateWebhook(ctx context.Context, payload []byte, signature string) (*processor.WebhookEvent, error)
- type Strategy
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CircuitBreakerConfig ¶
type CircuitBreakerConfig struct {
// FailureThreshold is the number of consecutive failures before the
// breaker opens. Default 5.
FailureThreshold int
// ResetTimeout is how long the breaker stays open before transitioning
// to half-open. Default 30s.
ResetTimeout time.Duration
// HalfOpenMax is the maximum number of probe requests allowed while the
// breaker is half-open. Default 1.
HalfOpenMax int
}
CircuitBreakerConfig tunes the per-processor circuit breaker.
type Config ¶
type Config struct {
// Strategy selects the routing algorithm.
Strategy Strategy
// Primary is the preferred processor for PrimaryFallback strategy.
Primary processor.ProcessorType
// Processors is the ordered list of processors the router may use.
// For PrimaryFallback the primary is tried first, then this list in order.
Processors []processor.ProcessorType
// CurrencyMap maps currency codes to processors (CurrencyBased strategy).
CurrencyMap map[string]processor.ProcessorType
// Weights assigns relative weights to processors (WeightedRandom strategy).
Weights map[processor.ProcessorType]int
// MaxRetries is the maximum number of fallback processors to try after
// the first selection fails. 0 means try every configured processor.
MaxRetries int
// CircuitBreaker configures per-processor circuit breakers.
CircuitBreaker CircuitBreakerConfig
}
Config controls the router's behaviour.
type Router ¶
type Router struct {
*processor.BaseProcessor
// contains filtered or unexported fields
}
Router is a PaymentProcessor that delegates to real processors via configurable strategies and per-processor circuit breakers.
func NewRouter ¶
NewRouter creates a Router backed by the given registry and config. It initialises a circuit breaker for every processor listed in config.Processors.
func (*Router) Authorize ¶
func (r *Router) Authorize(ctx context.Context, req processor.PaymentRequest) (*processor.PaymentResult, error)
Authorize authorizes a payment without capturing.
func (*Router) Capture ¶
func (r *Router) Capture(ctx context.Context, transactionID string, amount currency.Cents) (*processor.PaymentResult, error)
Capture captures a previously authorized payment. The transactionID must be router-prefixed ("processor:txid").
func (*Router) Charge ¶
func (r *Router) Charge(ctx context.Context, req processor.PaymentRequest) (*processor.PaymentResult, error)
Charge processes a payment through a selected processor.
func (*Router) GetTransaction ¶
GetTransaction searches all processors for the given transaction. If the ID is router-prefixed, only the matching processor is queried.
func (*Router) IsAvailable ¶
IsAvailable returns true if any configured processor is available.
func (*Router) Refund ¶
func (r *Router) Refund(ctx context.Context, req processor.RefundRequest) (*processor.RefundResult, error)
Refund processes a refund on the processor that handled the original charge.
func (*Router) SupportedCurrencies ¶
SupportedCurrencies returns the union of all processors' currencies.
func (*Router) ValidateWebhook ¶
func (r *Router) ValidateWebhook(ctx context.Context, payload []byte, signature string) (*processor.WebhookEvent, error)
ValidateWebhook tries each configured processor until one validates.
type Strategy ¶
type Strategy string
Strategy controls how the router selects a processor for each request.
const ( // PrimaryFallback tries the primary processor first, then iterates // through the Processors list on failure. PrimaryFallback Strategy = "primary_fallback" // RoundRobin distributes requests evenly across all configured processors. RoundRobin Strategy = "round_robin" // CurrencyBased selects a processor based on the payment currency. CurrencyBased Strategy = "currency_based" // WeightedRandom selects processors with probability proportional to // their configured weights. WeightedRandom Strategy = "weighted_random" // LeastLoad routes to the processor with the fewest in-flight requests. LeastLoad Strategy = "least_load" )
Source Files