feat(http): implement server-side rate limiter middleware

[sammy200-ui]

Description
Implements HTTP server-side rate limiting middleware using token bucket algorithm for #2551 (HTTP portion).

Changes

• Add RateLimiter middleware using golang.org/x/time/rate
• Support per-IP and global rate limiting modes
• Add ErrorTooManyRequests (HTTP 429) error type
• Include 9 comprehensive test cases (all passing)
• Add example application with full documentation
• Auto-skip rate limiting for health check endpoints
• Automatic cleanup of stale per-IP limiters every 5 minutes

Features

• Token Bucket Algorithm: Smooth rate limiting with configurable burst
• Per-IP Limiting: Each client IP gets independent rate limit (configurable)
• Health Check Exemption: /.well-known/alive and /.well-known/health always accessible
• Prometheus Metrics: Track rate limit violations via app_http_rate_limit_exceeded_total
• IP Extraction: Supports X-Forwarded-For, X-Real-IP, and RemoteAddr

Testing
All tests pass:

go test ./pkg/gofr/http/middleware/... -v -run TestRateLimiter
# PASS: 9/9 tests

Additional Information:

Uses golang.org/x/time/rate (already in dependencies)
Metrics exposed: app_http_rate_limit_exceeded_total counter
Example application available at using-rate-limiter
Complete documentation in example README with testing instructions
This PR implements the HTTP portion of #2551.

Checklist:

• I have formatted my code using goimport and golangci-lint.
• All new code is covered by unit tests.
• This PR does not decrease the overall code coverage.
• I have reviewed the code comments and documentation for clarity.

Thank you for your contribution!

[sammy200-ui]

@coolwednesday i have raised the pr , you can review it

[sammy200-ui]

@Umang01-hash just a follow up on the pr, any changes or fixes for the feat

[Umang01-hash]

@sammy200-ui We will review your PR soon. Once reviewed we will let you know about any changes required for it.

Thanks for contributing to GoFr.

[coolwednesday]

@sammy200-ui , is this feature only for single pod servers. How do you think we should handle rate limiting in case of distributed systems ?

[sammy200-ui]

@coolwednesday Yes, currently this works for single-pod deployments. For distributed systems, each pod would enforce limits independently, so a client could exceed the global limit by hitting different pods, to handle this we would need ,redis-backed limiter or api gateway rate limiting or have document the limitation and keep it simple for v1

[coolwednesday]

@sammy200-ui, Let's keep it simple and create another issue for that linking it to this. Also document this behaviour. However, I would suggest at least to make the factory function configurable enough to be extensive to Redis in future.

[sammy200-ui]

@coolwednesday ok so i will add limiterBackend interface that will makes it easy to add Redis/other backends in future , add notes in code comments and example README explaining single-pod behavior , would that be good for this?? ,also do you want me to create a follow up issue for redis backed limiter or would you like to assign to someone else?

[Umang01-hash]

@coolwednesday ok so i will add limiterBackend interface that will makes it easy to add Redis/other backends in future , add notes in code comments and example README explaining single-pod behavior , would that be good for this?? ,also do you want me to create a follow up issue for redis backed limiter or would you like to assign to someone else?

@sammy200-ui I already defined one RateLimiterStore interface while implementing it for http-service option. Maybe you can have a look and use it :

// RateLimiterStore abstracts the storage and cleanup for rate limiter buckets.
type RateLimiterStore interface {
	Allow(ctx context.Context, key string, config RateLimiterConfig) (allowed bool, retryAfter time.Duration, err error)
	StartCleanup(ctx context.Context)
	StopCleanup()
}

The goal then will be we will use a single implementation for rate limiter of http service also and http or grpc also. This helps us to resuing the same code and having a consistent functionality throughout. You can make it a part of another ticket for time.

@coolwednesday thoughts?

[sammy200-ui]

@Umang01-hash @coolwednesday The RateLimiterStore interface is for outbound HTTP client rate limiting, while my implementation is for incoming HTTP middleware.
They serve different purposes:
Your interface: Limits outbound requests to other services
My implementation: Limits incoming requests to the server

However, I see the value in consistency. Two options:

1 : Keep this PR simple (in-memory only) and create a follow-up ticket to align both implementations with a shared interface + add Redis support for both.

2: Refactor now to use RateLimiterStore, but it may delay this PR.

I prefer 1 to keep this focused. Thoughts?

[coolwednesday]

@Umang01-hash @coolwednesday The RateLimiterStore interface is for outbound HTTP client rate limiting, while my implementation is for incoming HTTP middleware. They serve different purposes: Your interface: Limits outbound requests to other services My implementation: Limits incoming requests to the server

However, I see the value in consistency. Two options:

1 : Keep this PR simple (in-memory only) and create a follow-up ticket to align both implementations with a shared interface + add Redis support for both.

2: Refactor now to use RateLimiterStore, but it may delay this PR.

I prefer 1 to keep this focused. Thoughts?

You can implement the interface and return errors as not supported when redis configs are passed. You can then pick this up in a subsequent PR.

[sammy200-ui]

@Umang01-hash @coolwednesday I've refactored the rate limiter to use the RateLimiterStore interface pattern.

Changes made:

Created rate_limiter_store.go with the RateLimiterStore interface and memoryRateLimiterStore implementation
Refactored RateLimiter middleware to use the store pattern via an optional Store field in config
In-memory implementation works now with automatic cleanup
All tests passing with backward compatibility maintained
Added documentation about single-pod limitation

Redis support: As you suggested, I've left Redis implementation for a future PR. The store interface makes it easy to add later without breaking changes.

Let me know if you'd like any adjustments!

[sammy200-ui]

@coolwednesday @Umang01-hash any new changes to be expected ?

[sammy200-ui]

@Umang01-hash @coolwednesday just a follow up on the pr

[Copilot]

Pull request overview

This PR implements HTTP server-side rate limiting middleware using the token bucket algorithm to protect APIs from abuse and ensure fair resource distribution. The implementation supports both per-IP and global rate limiting modes with automatic cleanup of stale limiters.

Key Changes:

• Added RateLimiter middleware with configurable request rate and burst capacity
• Implemented in-memory rate limiter store with automatic cleanup of stale entries
• Added ErrorTooManyRequests HTTP error type for 429 responses
• Included comprehensive test suite with 9 test cases covering various scenarios
• Provided example application with detailed documentation

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
pkg/gofr/http/middleware/rate_limiter.go	Core middleware implementation with IP extraction and rate limit enforcement
pkg/gofr/http/middleware/rate_limiter_store.go	In-memory storage backend with periodic cleanup of stale limiters
pkg/gofr/http/middleware/rate_limiter_test.go	Comprehensive test suite covering global/per-IP limits, health endpoints, concurrency, and token refill
pkg/gofr/http/errors.go	Added ErrorTooManyRequests error type with 429 status code and WARN log level
examples/using-rate-limiter/main.go	Example application demonstrating rate limiter configuration and usage
examples/using-rate-limiter/README.md	Detailed documentation with configuration options, testing instructions, and deployment considerations

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sammy200-ui]

Hey @Umang01-hash do i need to resolve the co-pilot requests?

[Umang01-hash]

Hey @Umang01-hash do i need to resolve the co-pilot requests?

Yes @sammy200-ui if the comments given by co-pilot seems meaningful you should definitely resolve it. If not please comment why you think the given review comment is not useful/meaninful.

[sammy200-ui]

Hello @Umang01-hash I have addressed all 8 Copilot review comments , let me know if there are any more changes

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 9 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sammy200-ui]

@Umang01-hash Sounds good. Let me know if you need any changes from my end.

[Umang01-hash]

@sammy200-ui Creating a separate example for this functionality may not be a very good option. Either we can try to fit it in an already existing example or only update the documentation. Also we always try and keep our documentation simple to the point and clear. I think we can remove Running the example, Testing, monitoring, etc from the docs you created.

You should create a new documentation inside the docs directory and delete this new using-rate-limiter directory from examples.

[Umang01-hash]

@sammy200-ui Please also resolve these code quality issues in the PR. Thanks for the patience.

[sammy200-ui]

Hello @Umang01-hash All review feedback has been addressed!
Let me know if you need any changes from my end.

[sammy200-ui]

@Umang01-hash some code quality errors that are fixed , you can run the test again

[sammy200-ui]

@Umang01-hash Hi! Just checking in on this PR since it’s already approved.
Let me know if there’s anything else needed from my side before merge. Thanks!

[Umang01-hash]

@sammy200-ui Hey! Your PR has some review comments on it. Can you please resolve it so we can re-review and proceed towards merging if all things have been addressed. Please let us know if you need any assistance for the same.

[sammy200-ui]

@Umang01-hash @coolwednesday oks sure i will make these changes

[sammy200-ui]

Hello @Umang01-hash @coolwednesday done with the changes , you can review the pr again. let me know if any more changes to be made