ratelimit

Documentation

Overview

Package ratelimit is a middleware that limits the rate of requests.

`ratelimit` a generic server-side ratelimit middleware for gRPC.

Server Side Ratelimit Middleware

It allows to do grpc rate limit by your own rate limiter (e.g. token bucket, leaky bucket, etc.)

Please see examples for simple examples of use.

Index

• func StreamClientInterceptor(limiter Limiter) grpc.StreamClientInterceptor
• func StreamServerInterceptor(limiter Limiter) grpc.StreamServerInterceptor
• func UnaryClientInterceptor(limiter Limiter) grpc.UnaryClientInterceptor
• func UnaryServerInterceptor(limiter Limiter) grpc.UnaryServerInterceptor
• type Limiter

Examples

• StreamClientInterceptor
• StreamServerInterceptor
• UnaryClientInterceptor
• UnaryServerInterceptor

Functions

func StreamClientInterceptor

func StreamClientInterceptor(limiter Limiter) grpc.StreamClientInterceptor

StreamClientInterceptor returns a new stream client interceptor that performs rate limiting on the request on the client side. This can be helpful for clients that want to limit the number of requests they send in a given time, potentially saving cost.

Example

Simple example of a streaming client initialization code.

package main

import (
	"context"

	"github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/ratelimit"
	"google.golang.org/grpc"
)

// alwaysPassLimiter is an example limiter which implements Limiter interface.
// It does not limit any request because Limit function always returns false.
type alwaysPassLimiter struct{}

func (*alwaysPassLimiter) Limit(_ context.Context) error {

	return nil
}

func main() {
	// Create stream rateLimiter, based on token bucket here.
	// You can implement your own rate-limiter for the interface.
	limiter := &alwaysPassLimiter{}
	_, _ = grpc.DialContext(
		context.Background(),
		":8080",
		grpc.WithChainStreamInterceptor(
			ratelimit.StreamClientInterceptor(limiter),
		),
	)
}

func StreamServerInterceptor

func StreamServerInterceptor(limiter Limiter) grpc.StreamServerInterceptor

StreamServerInterceptor returns a new stream server interceptor that performs rate limiting on the request.

Example

Simple example of a streaming server initialization code.

package main

import (
	"context"

	"github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/ratelimit"
	"google.golang.org/grpc"
)

// alwaysPassLimiter is an example limiter which implements Limiter interface.
// It does not limit any request because Limit function always returns false.
type alwaysPassLimiter struct{}

func (*alwaysPassLimiter) Limit(_ context.Context) error {

	return nil
}

func main() {
	// Create unary/stream rateLimiters, based on token bucket here.
	// You can implement your own rate-limiter for the interface.
	limiter := &alwaysPassLimiter{}
	_ = grpc.NewServer(
		grpc.ChainStreamInterceptor(
			ratelimit.StreamServerInterceptor(limiter),
		),
	)
}

func UnaryClientInterceptor

func UnaryClientInterceptor(limiter Limiter) grpc.UnaryClientInterceptor

UnaryClientInterceptor returns a new unary client interceptor that performs rate limiting on the request on the client side. This can be helpful for clients that want to limit the number of requests they send in a given time, potentially saving cost.

Example

Simple example of a unary client initialization code.

package main

import (
	"context"

	"github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/ratelimit"
	"google.golang.org/grpc"
)

// alwaysPassLimiter is an example limiter which implements Limiter interface.
// It does not limit any request because Limit function always returns false.
type alwaysPassLimiter struct{}

func (*alwaysPassLimiter) Limit(_ context.Context) error {

	return nil
}

func main() {
	// Create stream rateLimiter, based on token bucket here.
	// You can implement your own rate-limiter for the interface.
	limiter := &alwaysPassLimiter{}
	_, _ = grpc.DialContext(
		context.Background(),
		":8080",
		grpc.WithUnaryInterceptor(
			ratelimit.UnaryClientInterceptor(limiter),
		),
	)
}

func UnaryServerInterceptor

func UnaryServerInterceptor(limiter Limiter) grpc.UnaryServerInterceptor

UnaryServerInterceptor returns a new unary server interceptors that performs request rate limiting.

Example

Simple example of a unary server initialization code.

package main

import (
	"context"

	"github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/ratelimit"
	"google.golang.org/grpc"
)

// alwaysPassLimiter is an example limiter which implements Limiter interface.
// It does not limit any request because Limit function always returns false.
type alwaysPassLimiter struct{}

func (*alwaysPassLimiter) Limit(_ context.Context) error {

	return nil
}

func main() {
	// Create unary/stream rateLimiters, based on token bucket here.
	// You can implement your own rate-limiter for the interface.
	limiter := &alwaysPassLimiter{}
	_ = grpc.NewServer(
		grpc.ChainUnaryInterceptor(
			ratelimit.UnaryServerInterceptor(limiter),
		),
	)
}

Types

type Limiter

type Limiter interface {
	Limit(ctx context.Context) error
}

Limiter defines the interface to perform request rate limiting. If Limit function returns an error, the request will be rejected with the gRPC codes.ResourceExhausted and the provided error. Otherwise, the request will pass.