Skip to content

Getting Started

Installation

Using Go Install

go install github.com/GiGurra/gocc@latest

From Source

git clone https://github.com/GiGurra/gocc.git
cd gocc
go build .

Docker

docker pull ghcr.io/gigurra/gocc:latest
docker run -p 8080:8080 ghcr.io/gigurra/gocc:latest

Running GoCC

Basic Usage

Start with default settings (100 requests/second per key):

gocc

Custom Settings

gocc --max-requests 200 --window-millis 5000 --port 9090

View All Options

gocc --help

Your First Rate Limit

With GoCC running, let's test rate limiting:

# First request - approved
curl -X POST http://localhost:8080/rate/test-key
# {"request_id":"abc123..."}

# Make many requests quickly
for i in {1..150}; do
  curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:8080/rate/test-key
done
# First 100: 200
# Rest: 429

Using the Queue

When rate limited, clients can wait in a queue:

# This will wait if rate limited (instead of returning 429)
curl -X POST "http://localhost:8080/rate/test-key?canWait=true"

Debug Endpoints

View the state of all rate limiters:

curl http://localhost:8080/debug | jq

View a specific key:

curl http://localhost:8080/debug/test-key | jq

Health Check

curl http://localhost:8080/healthz
# OK

Next Steps