En/rate limiter

docs/advanced-guide/http-communication/page.md

@@ -95,10 +95,13 @@ GoFr provides its user with additional configurational options while registering
 - **DefaultHeaders** - This option allows user to set some default headers that will be propagated to the downstream HTTP Service every time it is being called.
 - **HealthConfig** - This option allows user to add the `HealthEndpoint` along with `Timeout` to enable and perform the timely health checks for downstream HTTP Service.
 - **RetryConfig** - This option allows user to add the maximum number of retry count if before returning error if any downstream HTTP Service fails.
+- **RateLimiterConfig** -  This option allows user to configure rate limiting for downstream service calls using token bucket algorithm. It controls the request rate to prevent overwhelming dependent services and supports both in-memory and Redis-based implementations.
 
 #### Usage:
 
 ```go
+rc := redis.NewClient(cfg, a.Logger(), a.Metrics())
+
 a.AddHTTPService("cat-facts", "https://catfact.ninja",
 	service.NewAPIKeyConfig("some-random-key"),
 	service.NewBasicAuthConfig("username", "password"),
@@ -119,5 +122,11 @@ a.AddHTTPService("cat-facts", "https://catfact.ninja",
   &service.RetryConfig{
       MaxRetries: 5
   },
+
+  &service.RateLimiterConfig{
+      Rate:      5,
+      Burst:     10,
+      RedisClient: rc, // if RedisClient is nil, in-memory rate limiter will be used
+    },
 )
 ```

pkg/gofr/container/container.go

@@ -260,6 +260,9 @@ func (c *Container) registerFrameworkMetrics() {
 		httpBuckets := []float64{.001, .003, .005, .01, .02, .03, .05, .1, .2, .3, .5, .75, 1, 2, 3, 5, 10, 30}
 		c.Metrics().NewHistogram("app_http_response", "Response time of HTTP requests in seconds.", httpBuckets...)
 		c.Metrics().NewHistogram("app_http_service_response", "Response time of HTTP service requests in seconds.", httpBuckets...)
+		c.Metrics().NewCounter("app_rate_limiter_requests_total", "Total rate limiter requests")
+		c.Metrics().NewCounter("app_rate_limiter_denied_total", "Total denied requests")
+		c.Metrics().NewGauge("app_rate_limiter_tokens_available", "Current tokens available")
 	}
 
 	{ // Redis metrics

pkg/gofr/service/circuit_breaker_test.go

@@ -592,6 +592,14 @@ func (m *mockMetrics) RecordHistogram(ctx context.Context, name string, value fl
 	m.Called(ctx, name, value, labels)
 }
 
+func (m *mockMetrics) IncrementCounter(ctx context.Context, name string, labels ...string) {
+	m.Called(ctx, name, labels)
+}
+
+func (m *mockMetrics) SetGauge(name string, value float64, labels ...string) {
+	m.Called(name, value, labels)
+}
+
 type customTransport struct {
 }
 

pkg/gofr/service/logger.go

@@ -8,6 +8,7 @@ import (
 
 type Logger interface {
 	Log(args ...any)
+	Debug(args ...any)
 }
 
 type Log struct {

pkg/gofr/service/metrics.go

@@ -3,5 +3,7 @@ package service
 import "context"
 
 type Metrics interface {
+	IncrementCounter(ctx context.Context, name string, labels ...string)
+	SetGauge(name string, value float64, labels ...string)
 	RecordHistogram(ctx context.Context, name string, value float64, labels ...string)
 }

pkg/gofr/service/oauth.go

@@ -79,7 +79,7 @@ func validateTokenURL(tokenURL string) error {
 		return AuthErr{nil, "invalid host pattern, contains `..`"}
 	case strings.HasSuffix(u.Host, "."):
 		return AuthErr{nil, "invalid host pattern, ends with `.`"}
-	case u.Scheme != "http" && u.Scheme != "https":
+	case u.Scheme != methodHTTP && u.Scheme != methodHTTPS:
 		return AuthErr{nil, "invalid scheme, allowed http and https only"}
 	default:
 		return nil

pkg/gofr/service/rate_limiter.go

@@ -0,0 +1,108 @@
+package service
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+	"time"
+
+	gofrRedis "gofr.dev/pkg/gofr/datasource/redis"
+)
+
+var (
+	errInvalidRequestRate     = errors.New("requestsPerSecond must be greater than 0")
+	errInvalidBurstSize       = errors.New("burst must be greater than 0")
+	errInvalidRedisResultType = errors.New("unexpected Redis result type")
+)
+
+// RateLimiterConfig with custom keying support.
+type RateLimiterConfig struct {
+	RequestsPerSecond float64                    // Token refill rate (must be > 0)
+	Burst             int                        // Maximum burst capacity (must be > 0)
+	KeyFunc           func(*http.Request) string // Optional custom key extraction
+	RedisClient       *gofrRedis.Redis           `json:"-"` // Optional Redis for distributed limiting
+}
+
+// defaultKeyFunc extracts a normalized service key from an HTTP request.
+func defaultKeyFunc(req *http.Request) string {
+	if req == nil || req.URL == nil {
+		return "unknown"
+	}
+
+	scheme := req.URL.Scheme
+	host := req.URL.Host
+
+	if scheme == "" {
+		if req.TLS != nil {
+			scheme = methodHTTPS
+		} else {
+			scheme = methodHTTP
+		}
+	}
+
+	if host == "" {
+		host = req.Host
+	}
+
+	if host == "" {
+		host = unknownServiceKey
+	}
+
+	return scheme + "://" + host
+}
+
+// Validate checks if the configuration is valid.
+func (config *RateLimiterConfig) Validate() error {
+	if config.RequestsPerSecond <= 0 {
+		return fmt.Errorf("%w: %f", errInvalidRequestRate, config.RequestsPerSecond)
+	}
+
+	if config.Burst <= 0 {
+		return fmt.Errorf("%w: %d", errInvalidBurstSize, config.Burst)
+	}
+
+	// Set default key function if not provided.
+	if config.KeyFunc == nil {
+		config.KeyFunc = defaultKeyFunc
+	}
+
+	return nil
+}
+
+// AddOption implements the Options interface.
+func (config *RateLimiterConfig) AddOption(h HTTP) HTTP {
+	if err := config.Validate(); err != nil {
+		if httpSvc, ok := h.(*httpService); ok {
+			httpSvc.Logger.Log("Invalid rate limiter config, disabling rate limiting", "error", err)
+		}
+
+		return h
+	}
+
+	// Choose implementation based on Redis client availability.
+	if config.RedisClient != nil {
+		return NewDistributedRateLimiter(*config, h)
+	}
+
+	// Log warning for local rate limiting.
+	if httpSvc, ok := h.(*httpService); ok {
+		httpSvc.Logger.Log("Using local rate limiting - not suitable for multi-instance deployments")
+	}
+
+	return NewLocalRateLimiter(*config, h)
+}
+
+// RateLimitError represents a rate limiting error.
+type RateLimitError struct {
+	ServiceKey string
+	RetryAfter time.Duration
+}
+
+func (e *RateLimitError) Error() string {
+	return fmt.Sprintf("rate limit exceeded for service: %s, retry after: %v", e.ServiceKey, e.RetryAfter)
+}
+
+// StatusCode Implement StatusCodeResponder so Responder picks correct HTTP code.
+func (*RateLimitError) StatusCode() int {
+	return http.StatusTooManyRequests // 429
+}