SDK Documentation

Overview

The Go SDK provides a built‑in rate limiter to protect your application from exceeding API quotas. It supports token‑bucket and leaky‑bucket algorithms, configurable burst capacity, and automatic back‑off.

Basic Usage

Instantiate a RateLimiter and wrap your API calls.

package main

import (
    "context"
    "log"
    "time"

    "example.com/sdk"
    "example.com/sdk/ratelimit"
)

func main() {
    // Create a client with a rate limiter: 100 requests per minute
    limiter := ratelimit.NewTokenBucket(100, time.Minute)
    client := sdk.NewClient(sdk.Options{
        RateLimiter: limiter,
    })

    ctx := context.Background()
    for i := 0; i < 5; i++ {
        resp, err := client.GetResource(ctx, "resource-id")
        if err != nil {
            log.Fatalf("API error: %v", err)
        }
        log.Printf("Result %d: %s", i+1, resp.Data)
    }
}
Copy

Advanced Configuration

You can customize the bucket size, refill interval, and enable jitter to spread out bursts.

limiter := ratelimit.NewLeakyBucket(
    ratelimit.Config{
        Capacity:      200,               // max tokens
        RefillRate:    200,               // tokens per minute
        RefillPeriod:  time.Minute,
        Jitter:        true,              // randomize refill timing
    },
)
client := sdk.NewClient(sdk.Options{RateLimiter: limiter})
Copy

Reference

type RateLimiter

Interface implemented by all limiters.

type RateLimiter interface {
    // Wait blocks until a token is available or context is cancelled.
    Wait(ctx context.Context) error
    // Reserve returns a reservation without blocking.
    Reserve() (Reservation, error)
}

type TokenBucket

Standard token‑bucket implementation.

func NewTokenBucket(rate int, period time.Duration) *TokenBucket

type LeakyBucket

Leaky‑bucket with optional jitter.

type Config struct {
    Capacity     int
    RefillRate   int
    RefillPeriod time.Duration
    Jitter       bool
}
func NewLeakyBucket(cfg Config) *LeakyBucket