https://github.com/rossheat/tonic

A distributed rate limiter for Gin
https://github.com/rossheat/tonic

gin go golang rate-limiting

Last synced: about 1 month ago
JSON representation

A distributed rate limiter for Gin

• Host: GitHub
• URL: https://github.com/rossheat/tonic
• Owner: rossheat
• License: mit
• Created: 2024-07-06T13:47:19.000Z (4 months ago)
• Default Branch: main
• Last Pushed: 2024-07-06T15:15:18.000Z (4 months ago)
• Last Synced: 2024-10-02T05:21:29.421Z (about 1 month ago)
• Topics: gin, go, golang, rate-limiting
• Language: Go
• Homepage:
• Size: 9.77 KB
• Stars: 2
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# tonic

Looking for a simple rate limiter for the Gin web framework? 

tonic is a distributed, fixed-window rate limiter for Gin, using Redis for storage.

## Features

- Easy integration with Gin

- Flexible rate limiting based on request path and client IP

- Supports limits per second, minute, and hour

- Distributed rate limiting using Redis

## Installation

To install tonic, use the following command:

```bash

go get -u github.com/rossheat/tonic

```

## Usage

Here's an example of how to use tonic in your Gin application:

```go

package main

import (

	"net/http"

	"github.com/gin-gonic/gin"

	"github.com/rossheat/tonic"

)

func main() {

	redisUrl := "redis://:my_password@localhost:6379/0?protocol=3"

	limiter, err := tonic.New(redisUrl)

	if err != nil {

		panic(err)

	}

	router := gin.Default()

	router.GET("/fast", limiter.Limit("100/second"), Fast)

	router.GET("/slow", limiter.Limit("5/minute"), Slow)

	// These routes each have a rate limit of 100 requests per hour.

	slowGroup := router.Group("/slow-group", limiter.Limit("100/hour"))

	{

		slowGroup.GET("one", SlowOne)

		slowGroup.GET("two", SlowTwo)

	}

	router.Run(":8080")

}

```

You can find the complete version of this example [here](./example//example.go).

## Configuration

The `New` function creates a new Limiter instance. It requires a Redis URL string:

```go

limiter, err := tonic.New(redisURL)

```

Note that you should create only one instance of the limiter. 

## Rate Limiting

Use the `Limit` method to apply rate limiting to routes or groups. The limit is specified as a string in the format `"/"`, where duration can be "second", "minute", or "hour":

```go

router.GET("/path", limiter.Limit("100/minute"), HandlerFunc)

```

## Error Handling

tonic will automatically abort the request with a `429 Too Many Requests` status code when the rate limit is exceeded. Other errors (e.g., Redis connection issues) will result in a `500 Internal Server Error`.

## Testing

To run the tests for tonic, use the following command:

```bash

go test ./...

```

Ensure you have a Redis instance running and accessible for the tests to pass.

## Contributing

At this time, we are not accepting contributions to tonic. We appreciate your interest, but the project is currently maintained internally.

## License

This project is licensed under the [MIT License](LICENSE.md).