polaris

README

tRPC-Gateway Polaris Distributed Rate Limiting Plugin

This plugin is a wrapper based on the polaris limiter and is used to dynamically add rate limiting configurations to the gateway interfaces. For more information on Polaris rate limiting capabilities.

Usage Instructions

Add the corresponding rate limiting configurations in the Polaris console of the gateway service.

Please refer to the ratelimit for details.

Import the plugin in the main.go file of the gateway project.

import (
_ "trpc.group/trpc-go/trpc-gateway/plugin/limiter/polaris"
)

• Configure the tRPC framework in the configuration file of the gateway project to enable the polaris_limiter interceptor.

Note: Make sure to register it in server.service.filter instead of server.filter.

global:                             # Global configuration
server: # Server configuration
  filter:                                          # Interceptor list for all service handler functions
  service: # Business services provided, can have multiple
    - name: trpc.inews.trpc.gateway      # Route name of the service
      filter:
        - polaris_limiter # Gateway plugin registered in the service filter, so that it can be dynamically loaded in router.yaml
plugins: # Plugin configuration
  log:                                            # Log configuration
  gateway: # Plugin type is gateway
    polaris_limiter: # Polaris rate limiting plugin
      timeout: 500 # Default timeout for rate limiting quotas
      max_retries: 3 # Default maximum retries for rate limiting quotas

Configure the plugin in the router.yaml file of the gateway project. It supports global, service, and router-level plugin configurations.

router: # Router configuration
  - method: /v1/user/info
    target_service:
      - service: trpc.user.service
    plugins:
      - name: polaris_limiter
        props:
          # Custom rate limiting labels that will be queried from request query parameters and cookies
          labels: [ "suid" ]
          # Response body after rate limiting, corresponding to HTTP status code 429
          limited_rsp_body: '{"code":429,"msg":"too many request"}'
          # Timeout for rate limiting quotas
          timeout: 500
          # Maximum number of retries for rate limiting quotas
          max_retries: 3
          # Rate limiting cluster namespace, default to the namespace of the gateway instance
          namespace: "Production"
          # Rate limiting service, default to the rate limiting configuration of the gateway instance
          service: "trpc.user.service"

client: # Upstream service configuration, consistent with the tRPC protocol
  - name: trpc.user.service
    plugins:
      - name: request_transformer # Service-level configuration, effective for interfaces forwarded to this service
        props:
plugins:
  - name: request_transformer # Global configuration, effective for all interfaces
    props:

Rate limiting labels related operations

Default labels

method: The interface name, generally rate limiting can be done according to the interface.

router_id: Gateway route ID, when the interface is duplicated, you can use router_id to configure rate limiting.

Custom labels fetching function

You can override the DefaultGetLabelFunc function to implement custom labels fetching logic.

The plugin can also be used through the gateway console.

Documentation

Overview

Package polaris is a rate limiting plugin for tRPC-Gateway based on Polaris.

Index

• Constants
• Variables
• type GetLabelFunc
• type Limiter
  • func (l *Limiter) InterceptServer(ctx context.Context, req interface{}, handler filter.ServerHandleFunc) (interface{}, error)
• type Opt
  • func WithMaxRetries(maxRetries int) Opt
  • func WithTimeout(timeout int) Opt
• type Options
• type PluginFactory
  • func (p *PluginFactory) CheckConfig(name string, decoder plugin.Decoder) error
  • func (p *PluginFactory) Setup(_ string, decoder plugin.Decoder) error
  • func (p *PluginFactory) Type() string

Constants

const (
	// PluginName is the name of the plugin.
	PluginName = "polaris_limiter"
	// ErrLimit indicates that the request has been rate limited.
	ErrLimit = 10003
)

Variables

var New = func(opts ...Opt) (*Limiter, error) {
	l := &Limiter{}
	for _, o := range opts {
		o(l)
	}
	cfg := config.NewDefaultConfigurationWithDomain()
	limitAPI, err := api.NewLimitAPIByConfig(cfg)
	if err != nil {
		return nil, fmt.Errorf("failed to create limitAPI from default configuration, err: %w", err)
	}
	l.API = limitAPI

	return l, nil
}

New creates a new Limiter.

Types

type GetLabelFunc

type GetLabelFunc func(ctx context.Context, key string) string

GetLabelFunc defines the function to get label.

var DefaultGetLabelFunc GetLabelFunc = func(ctx context.Context, label string) string {
	fctx := http.RequestContext(ctx)
	if fctx == nil {
		return ""
	}
	if val := http.GetString(fctx, label); val != "" {
		return val
	}
	return ""
}

DefaultGetLabelFunc is a function to get parameters, which can be overridden by yourself.

type Limiter

type Limiter struct {
	// Timeout for individual quota queries, in milliseconds
	Timeout int `yaml:"timeout"`
	// Number of retries
	MaxRetries int `yaml:"max_retries"`
	// Global rate limiting object
	API api.LimitAPI
}

Limiter is the Polaris rate limiter.

func (*Limiter) InterceptServer

func (l *Limiter) InterceptServer(ctx context.Context, req interface{},
	handler filter.ServerHandleFunc) (interface{}, error)

InterceptServer implements the server-side rate limiting interceptor.

type Opt

type Opt func(*Limiter)

Opt allows customization of the Limiter.

func WithMaxRetries

func WithMaxRetries(maxRetries int) Opt

WithMaxRetries sets the maximum number of retries for failed rate limiting requests.

func WithTimeout

func WithTimeout(timeout int) Opt

WithTimeout sets the timeout for rate limiting requests.

type Options

type Options struct {
	// Business fields
	Labels []string `yaml:"labels" json:"labels"`
	// Timeout for quota query, in milliseconds
	Timeout int `yaml:"timeout" json:"timeout"`
	// Number of retries
	MaxRetries int `yaml:"max_retries" json:"max_retries"`
	// Polaris rate limiting service name, defaults to the gateway project's rate limiting configuration, can be overridden
	Service string `yaml:"service" json:"service"`
	// Polaris rate limiting namespace, defaults to the gateway instance's namespace
	Namespace string `yaml:"namespace" json:"namespace"`
	// Response body after rate limiting
	LimitedRspBody string `yaml:"limited_rsp_body" json:"limited_rsp_body"`
	// Retrieve rate limiting parameters from JSON request body
	ParseJSONBody bool `yaml:"parse_json_body" json:"parse_json_body"`
}

Options for rate limiting

type PluginFactory

type PluginFactory struct {
	// Default timeout for rate limiting requests
	Timeout int `yaml:"timeout"`
	// Default number of retries for rate limiting requests
	MaxRetries int `yaml:"max_retries"`
}

PluginFactory is the plugin factory

func (*PluginFactory) CheckConfig

func (p *PluginFactory) CheckConfig(name string, decoder plugin.Decoder) error

CheckConfig validates the plugin configuration and returns a parsed configuration object. Used in the ServerFilter method.

func (*PluginFactory) Setup

func (p *PluginFactory) Setup(_ string, decoder plugin.Decoder) error

Setup implements the Setup method of plugin.Factory, initializes and registers the interceptor.

func (*PluginFactory) Type

func (p *PluginFactory) Type() string

Type implements the Type method of plugin.Factory.