Installation and Setup

Welcome to the installation guide for ThrottleX! This page will walk you through the process of installing and setting up ThrottleX in your development environment. Whether you are testing locally or deploying in a distributed setup, these instructions will help you get started quickly.

Prerequisites

Before you begin, make sure you have the following installed:

• Go 1.17 or later: ThrottleX is a Go library, so you need to have Go installed. You can download the latest version from Go's official website.
• Redis (Optional): If you plan to use Redis as the storage backend for rate limiting, you'll need to have Redis installed and running. You can get Redis from redis.io.

Installing ThrottleX

To install ThrottleX in your Go project, use go get to pull the latest version from GitHub:

go get github.com/neelp03/throttlex

This will add ThrottleX to your Go modules and allow you to import it into your project.

Setting Up ThrottleX

Step 1: Import ThrottleX

In your Go file, import the required packages from ThrottleX:

package main

import (
    "github.com/neelp03/throttlex/ratelimiter"
    "github.com/neelp03/throttlex/store"
    "fmt"
    "time"
)

Step 2: Choose a Storage Backend

ThrottleX supports both in-memory and Redis storage backends. You can choose based on your use case:

• In-Memory Store: Suitable for local testing or low-scale projects.
• Redis Store: Suitable for distributed environments where multiple instances need to share rate-limiting data.

Example: Setting Up an In-Memory Store

func main() {
    // Initialize an in-memory store
    memStore := store.NewMemoryStore()
    
    // Create a rate limiter (e.g., Fixed Window Limiter)
    limiter, err := ratelimiter.NewFixedWindowLimiter(memStore, 10, time.Minute)
    if err != nil {
        fmt.Println("Failed to create limiter:", err)
        return
    }
    
    // Simulate requests
    key := "user1"
    for i := 0; i < 12; i++ {
        allowed, err := limiter.Allow(key)
        if err != nil {
            fmt.Println("Error:", err)
            continue
        }
        if allowed {
            fmt.Printf("Request %d allowed\n", i+1)
        } else {
            fmt.Printf("Request %d blocked\n", i+1)
        }
    }
}

Example: Setting Up a Redis Store

import (
    "github.com/go-redis/redis/v8"
    "github.com/neelp03/throttlex/ratelimiter"
    "github.com/neelp03/throttlex/store"
    "context"
    "fmt"
    "time"
)

func main() {
    // Set up Redis client
    client := redis.NewClient(&redis.Options{
        Addr: "localhost:6379",
    })
    
    // Initialize a Redis store
    redisStore := store.NewRedisStore(client)
    
    // Create a rate limiter (e.g., Sliding Window Limiter)
    limiter, err := ratelimiter.NewSlidingWindowLimiter(redisStore, 10, time.Minute)
    if err != nil {
        fmt.Println("Failed to create limiter:", err)
        return
    }
    
    // Simulate requests
    ctx := context.Background()
    key := "user1"
    for i := 0; i < 12; i++ {
        allowed, err := limiter.Allow(ctx, key)
        if err != nil {
            fmt.Println("Error:", err)
            continue
        }
        if allowed {
            fmt.Printf("Request %d allowed\n", i+1)
        } else {
            fmt.Printf("Request %d blocked\n", i+1)
        }
    }
}

Configuration

Rate Limiting Policies

ThrottleX supports multiple rate-limiting policies, each providing a unique strategy for controlling traffic:

• Fixed Window: Limits requests to a fixed number during a specified time window.
• Sliding Window: Offers a more granular approach by maintaining counts over sliding intervals.
• Token Bucket: Allows for bursts of traffic, provided tokens have accumulated over time.

You can specify these policies when creating a rate limiter, as shown in the examples above.

Running Your Application

Once you've set up your rate limiter, you can run your Go application as usual:

go run main.go

You should see the rate limiting behavior in action, with some requests being allowed and others blocked based on the defined limits.

Troubleshooting

• Redis Connection Issues: If you are using the Redis store and encountering connection issues, make sure Redis is running, and the address (localhost:6379 by default) is correct.
• Rate Limit Not Working as Expected: Double-check your rate-limiting parameters (limit and window duration) and ensure the key being used is consistent across requests.

Next Steps

• Learn more about ThrottleX Rate Limiting Algorithms.
• Contribute to the project by visiting the GitHub Repository.

Feel free to reach out if you have any questions or need help setting up ThrottleX!