{"id":18331316,"url":"https://github.com/coveooss/spillway","last_synced_at":"2025-05-02T22:31:18.874Z","repository":{"id":37546060,"uuid":"56723673","full_name":"coveooss/spillway","owner":"coveooss","description":"A simple, distributed and flexible rate limiter","archived":false,"fork":false,"pushed_at":"2025-04-05T19:14:59.000Z","size":269,"stargazers_count":35,"open_issues_count":13,"forks_count":13,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-04-05T20:22:56.032Z","etag":null,"topics":["java","rate-limit"],"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/coveooss.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":"2016-04-20T21:56:55.000Z","updated_at":"2025-01-30T21:27:31.000Z","dependencies_parsed_at":"2024-02-08T18:26:36.353Z","dependency_job_id":"a460d7e7-811d-4e81-b1fd-aff9f63c553a","html_url":"https://github.com/coveooss/spillway","commit_stats":null,"previous_names":["coveo/spillway"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coveooss%2Fspillway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coveooss%2Fspillway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coveooss%2Fspillway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coveooss%2Fspillway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coveooss","download_url":"https://codeload.github.com/coveooss/spillway/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252116223,"owners_count":21697338,"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-limit"],"created_at":"2024-11-05T19:30:00.465Z","updated_at":"2025-05-02T22:31:13.864Z","avatar_url":"https://github.com/coveooss.png","language":"Java","funding_links":[],"categories":["容错组件"],"sub_categories":[],"readme":"# Spillway\n[![Build Status](https://travis-ci.org/coveo/spillway.svg?branch=master)](https://travis-ci.org/coveo/spillway)\n[![license](http://img.shields.io/badge/license-MIT-brightgreen.svg)](https://github.com/coveo/spillway/blob/master/LICENSE)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.coveo/spillway/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.coveo/spillway)\n\n## A distributed throttling solution\n\nSpillway is an easy to use solution to add distributed throttling at the software level in your public API.\nThis is particularly useful if multiple services are running in different JVMs.\nIt is also possible to quickly to react when throttling happens with our built-in call-back mechanism.\n\nStorage backend currently supported:\n- In memory (for usage within the same JVM)\n- Redis\n\nAll external storage can be (and should be) wrapped in our asynchronous storage to avoid slowing down/stopping queries if external problems occurs with the external storage.\n\n## Getting Started\n#### Add Spillway to your project pom\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.coveo\u003c/groupId\u003e\n    \u003cartifactId\u003espillway\u003c/artifactId\u003e\n    \u003cversion\u003e2.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n#### Documentation\nThe java documentation is available here: https://coveooss.github.io/spillway/\n\n#### Usage\n###### Sample 1\n```java\n    LimitUsageStorage storage = new AsyncLimitUsageStorage(new RedisStorage(\"localhost\"));\n    SpillwayFactory spillwayFactory = new SpillwayFactory(storage);\n\n    Limit\u003cString\u003e myLimit = LimitBuilder.of(\"myLimit\").to(2).per(Duration.ofMinutes(1)).build();\n    Spillway\u003cString\u003e spillway = spillwayFactory.enforce(\"myResource\", myLimit);\n    \n    spillway.call(\"myLimit\"); // nothing happens\n    spillway.call(\"myLimit\"); // nothing happens\n    spillway.call(\"myLimit\"); // throws SpillwayLimitExceededException\n``` \n\n###### Sample 2\n```java\n    LimitUsageStorage storage = new InMemoryStorage();\n    SpillwayFactory spillwayFactory = new SpillwayFactory(storage);\n\n    Limit\u003cUser\u003e userLimit = LimitBuilder.of(\"perUser\", User::getName).to(3).per(Duration.ofHours(1)).build();\n    Limit\u003cUser\u003e ipLimit = LimitBuilder.of(\"perIp\", User::getIp).to(3).per(Duration.ofHours(1)).withExceededCallback(myCallback).build();\n    Spillway\u003cUser\u003e spillway = spillwayFactory.enforce(\"myResource\", userLimit, ipLimit);\n\n    User john = new User(\"john\", \"127.0.0.1\");\n    User gina = new User(\"gina\", \"127.0.0.1\");\n\n    spillway.tryCall(john); // true\n    spillway.tryCall(gina); // true\n    spillway.tryCall(john); // true\n    spillway.tryCall(gina); // false, perIp limit exceeded.\n```\n\n###### Sample 3\n```java\n    LimitUsageStorage storage = new InMemoryStorage();\n    SpillwayFactory spillwayFactory = new SpillwayFactory(storage);\n    \n    LimitOverride override = LimitOverrideBuilder.of(\"john\").to(10).per(Duration.ofHours(1)).build();\n    Limit\u003cString\u003e userLimit = LimitBuilder.of(\"perUser\").to(30).per(Duration.ofHours(1)).withLimitOverride(override).build();\n    Spillway\u003cUser\u003e spillway = spillwayFactory.enforce(\"myResource\", userLimit);\n\n    spillway.tryCall(\"john\", 11); // false\n    spillway.tryCall(\"gina\", 20); // true\n```\n\n## External Resources\n\n[cirrus-up-cloud](https://github.com/cirrus-up-cloud) wrote a [nice blog post](https://www.cirrusup.cloud/limit-accepted-requests-using-aws-elasticache/) about using Spillway on AWS with Elasticache.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoveooss%2Fspillway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoveooss%2Fspillway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoveooss%2Fspillway/lists"}