{"id":20555523,"url":"https://github.com/thewaterfall/spring-rate-throttler","last_synced_at":"2026-02-15T13:34:55.339Z","repository":{"id":163989428,"uuid":"639430382","full_name":"thewaterfall/spring-rate-throttler","owner":"thewaterfall","description":"A library for rate-limiting (throttling) HTTP requests in Spring applications. It provides annotations to be used on controller methods or classes to enforce rate-limiting and uses a token bucket algorithm to limit the number of requests that can be made in a certain period of time.","archived":false,"fork":false,"pushed_at":"2025-02-02T16:06:28.000Z","size":87,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-28T01:53:35.282Z","etag":null,"topics":["java","rate-limiter","rate-limiting","request-limit","request-limiter","request-throttler","request-throttling","spring","spring-boot","springboot","springframework","throttle","throttle-requests","throttler","throttling"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thewaterfall.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-11T13:11:04.000Z","updated_at":"2025-03-17T16:58:57.000Z","dependencies_parsed_at":"2024-07-07T09:43:37.311Z","dependency_job_id":"3eb4ffb2-c8fe-4c2f-8290-a6bc87dfee09","html_url":"https://github.com/thewaterfall/spring-rate-throttler","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thewaterfall%2Fspring-rate-throttler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thewaterfall%2Fspring-rate-throttler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thewaterfall%2Fspring-rate-throttler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thewaterfall%2Fspring-rate-throttler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thewaterfall","download_url":"https://codeload.github.com/thewaterfall/spring-rate-throttler/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248883427,"owners_count":21177209,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","rate-limiter","rate-limiting","request-limit","request-limiter","request-throttler","request-throttling","spring","spring-boot","springboot","springframework","throttle","throttle-requests","throttler","throttling"],"created_at":"2024-11-16T03:18:53.455Z","updated_at":"2025-10-06T12:06:20.705Z","avatar_url":"https://github.com/thewaterfall.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spring Rate Throttler\n\nSpring Rate Throttler is a library designed for rate limiting or throttling incoming HTTP requests in a Spring \napplication using annotations and application properties. Rate limiting is a common technique used to control the flow\nof incoming requests to prevent overloading of server resources, ensuring that the server can function effectively for \nall clients.\n\nWith Spring Rate Throttler, you can easily define rate limiting policies based on criteria such as throttle key,\nnumber of requests per unit of time, or other custom parameters. The library provides a customizable way to define these\npolicies through annotations or application properties, so you can quickly and easily add rate limiting capabilities \nto your Spring application.\n\n## Features\n- Easy integration with Spring Boot applications.\n- Annotation and application properties based.\n- Configurable rate limiting policies based on different criteria (global level, class level and method level configuration).\n- Support for customizable rate limiting exception handling.\n- [Caffeine](https://github.com/ben-manes/caffeine) in-memory caching for high performance.\n- [Token bucket](https://github.com/bbeck/token-bucket) algorithm for rate limiting.\n- [Ip4j](https://github.com/thewaterfall/ip4j) tiny library for retrieving request IP address for rate limiting.\n\n## Installation\nSpring Rate Throttler can be easily installed using JitPack, see Gradle and Maven examples below.\n\n### Gradle\nAdd the following to your build.gradle file:\n\n```\nrepositories {\n    mavenCentral()\n    maven { url \"https://jitpack.io\" }\n}\n\ndependencies {\n    implementation 'com.github.thewaterfall:spring-rate-throttler:1.0.1'\n}\n```\n\n### Maven\nAdd the following to your pom.xml file:\n\n```\n\u003crepositories\u003e\n    \u003crepository\u003e\n        \u003cid\u003ejitpack.io\u003c/id\u003e\n        \u003curl\u003ehttps://jitpack.io\u003c/url\u003e\n    \u003c/repository\u003e\n\u003c/repositories\u003e\n\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003ecom.github.thewaterfall\u003c/groupId\u003e\n        \u003cartifactId\u003espring-rate-throttler\u003c/artifactId\u003e\n        \u003cversion\u003e1.0.2\u003c/version\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\n## Usage \u0026 configuration\n\nThere are three levels of configuration that can be applied: global, class and method. Lower level overrides higher \nlevels. From the lowest (strongest) to the highest levels (weakest): method level \u003e class level \u003e global level. \n\nLibrary is based on such terms and properties as:\n- **Throttle capacity**: initial and maximum capacity of requests\n- **Throttle refill**: number of requests that are refilled (usually is equal to capacity)\n- **Throttle refill period**: the period per which a number of requests (see refill property) are refilled\n- **Throttle refill period unit**: the unit of time used for the refill period (in ChronoUnit, e.g. SECONDS, MINUTES, etc.)\n- **Throttle key**: the type of key used to identify the source or user of the request (supported: IP_ADDRESS, HEADER)\n- **Throttle key source**: the source of the key used to retrieve value from (header name, etc.)\n\n### Throttler enabling\n\nAdd `@EnableThrottler` to enable throttler:\n\n```\n@EnableThrottler\n@SpringBootApplication\npublic class Application {\n\tpublic static void main(String[] args) {\n\t\tApplication.run(Application.class, args);\n\t}\n}\n```\n\n### Exception catching\n\nWhen rate limit is exceeded, a `ThrottleException` will be thrown that can be caught and processed, see example\nbelow.\n\n```\n@ControllerAdvice\npublic class ErrorHandler {\n  @ExceptionHandler(value = ThrottleException.class)\n  protected ResponseEntity\u003cObject\u003e handleThrottleException(ThrottleException e,\n                                                           HttpServletRequest request) {\n    return new ResponseEntity\u003c\u003e(response, TOO_MANY_REQUESTS);\n  }\n}\n```\n\n### Global level configuration\n\nGlobal configuration is applied to all the requests and endpoints. Additionally, cache can be configured.\n\n| Property                                              | Description                                                                                                                                                                                                                  |\n|-------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| throttler.global.enabled                              | enables global configuration                                                                                                                                                                                                 |\n| throttler.global.capacity                             | initial and maximum capacity of requests                                                                                                                                                                                     |\n| throttler.global.refill                               | number of requests that are refilled (usually is equal to capacity)                                                                                                                                                          |\n| throttler.global.refill-period                        | the period per which a number of requests (see refill property) are refilled                                                                                                                                                 |\n| throttler.global.refill-period-unit                   | the unit of time used for the refill period (in ChronoUnit, e.g. SECONDS, MINUTES, etc.)                                                                                                                                     |\n| throttler.global.key-type                             | the type of key used to identify the source or user of the request (supported: IP_ADDRESS, HEADER, COOKIE)                                                                                                                   |\n| throttler.global.key-source                           | the source of the key used to retrieve value from (header name, cookie name)                                                                                                                                                 |\n| throttler.global.ignore-paths                         | comma separated list of paths to ignore (wildcards are supported, more on path patterns see [AntPathMatcher](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/util/AntPathMatcher.html)) |\n| throttler.cache.in-memory.expire-after-access-seconds | instructs cache to expire after specified amount of seconds being not accessed (stale)                                                                                                                                       |\n| throttler.cache.in-memory.max-size                    | sets up maximum size of cache                                                                                                                                                                                                |\n\n### Class and method level configuration\n\nClass level configuration overrides global level and method level overrides class level. Apply the `@Throttle` annotation\nto enable throttle for the method (or whole class, i.e., every method).\n\nUse `@Throttle(skip = true)` to exclude method from being throttled.\n\n```\n\n@Throttle(capacity = 10, refill = 10, period = 1, unit = ChronoUnit.MINUTES, key = ThrottlerKeyType.IP_ADDRESS)\n@RestController\npublic class StorageController {\n    @GetMapping(\"/images\")\n    public ResponseEntity\u003cResource\u003e getImage(String name) {\n        // Your endpoint logic here\n    }\n    \n    @Throttle(capacity = 5, refill = 5, period = 1, unit = ChronoUnit.MINUTES, key = ThrottlerKeyType.IP_ADDRESS)\n    @GetMapping(\"/videos\")\n    public ResponseEntity\u003cResource\u003e getVideo(String name) {\n        // Your endpoint logic here\n    }\n    \n    @Throttle(skip = true)\n    @GetMapping(\"/metadata\")\n    public ResponseEntity\u003cString\u003e getMetadata(String name) {\n        // Your endpoint logic here\n    }\n}\n```\nExample description:\n- StorageController is annotated with class level annotation that instructs to throttle all endpoints (class methods) as \nrequests as 10 requests per minute for all. \n- Method \"getVideo(..)\" is overridden with method level annotation that instructs to throttle as 5 requests per minute. \n- Method \"getMetadata(..)\" is overridden with method level annotation that instructs to skip throttle and allow any rate.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthewaterfall%2Fspring-rate-throttler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthewaterfall%2Fspring-rate-throttler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthewaterfall%2Fspring-rate-throttler/lists"}