{"id":22425030,"url":"https://github.com/ayarotsky/redis-shield","last_synced_at":"2026-05-15T22:04:15.049Z","repository":{"id":86496006,"uuid":"231743244","full_name":"ayarotsky/redis-shield","owner":"ayarotsky","description":"A loadable Redis module that implements the token bucket algorithm to do rate limiting as a native command","archived":false,"fork":false,"pushed_at":"2024-11-27T03:58:58.000Z","size":73,"stargazers_count":42,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-11-27T04:28:03.555Z","etag":null,"topics":["redis","redis-module","rust","rust-library","rustlang"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/ayarotsky.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2020-01-04T10:11:57.000Z","updated_at":"2024-11-27T03:59:01.000Z","dependencies_parsed_at":"2024-01-22T23:35:18.436Z","dependency_job_id":"9dd47218-2a0a-4698-ab90-43e22e8422e4","html_url":"https://github.com/ayarotsky/redis-shield","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayarotsky%2Fredis-shield","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayarotsky%2Fredis-shield/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayarotsky%2Fredis-shield/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayarotsky%2Fredis-shield/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ayarotsky","download_url":"https://codeload.github.com/ayarotsky/redis-shield/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228356406,"owners_count":17907191,"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":["redis","redis-module","rust","rust-library","rustlang"],"created_at":"2024-12-05T19:12:07.320Z","updated_at":"2026-05-15T22:04:15.042Z","avatar_url":"https://github.com/ayarotsky.png","language":"Rust","funding_links":[],"categories":["Applications"],"sub_categories":["Database"],"readme":"# Redis Shield\n\n![Build Status](https://github.com/ayarotsky/redis-shield/actions/workflows/ci.yml/badge.svg?branch=main)\n![Nightly Builds](https://github.com/ayarotsky/redis-shield/actions/workflows/nightly_builds.yml/badge.svg?branch=main)\n\nRedis Shield is a loadable module for [Redis](https://redis.io) and\n[Valkey](https://valkey.io) that implements the\n[token bucket algorithm](https://en.wikipedia.org/wiki/Token_bucket)\nto do rate limiting as a native command. The same compiled artifact loads into either server.\n\n## Algorithm\n\nThe token bucket algorithm is based on an analogy of a fixed capacity bucket into which\ntokens are added at a fixed rate. When a request is to be checked for conformance to\nthe defined limits, the bucket is inspected to see if it contains sufficient tokens\nat that time. If so, the appropriate number of tokens, e.g. equivalent to the number\nof HTTP requests, are removed, and the request is passed.\n\nThe request does not conform if there are insufficient tokens in the bucket.\n\n## Install\n\nClone and build the project from source.\n\n    $ git clone https://github.com/ayarotsky/redis-shield.git\n    $ cd redis-shield\n    $ cargo build --release\n    $ # extension will be **.dylib** instead of **.so** for Mac releases\n    $ cp target/release/libredis_shield.so /path/to/modules/\n\nRun `redis-server` or `valkey-server` pointing to the newly built module:\n\n    redis-server  --loadmodule /path/to/modules/libredis_shield.so\n    valkey-server --loadmodule /path/to/modules/libredis_shield.so\n\n**Or** add the following to a `redis.conf` or `valkey.conf` file:\n\n    loadmodule /path/to/modules/libredis_shield.so\n\n## Usage\n\n    SHIELD.absorb \u003ckey\u003e \u003ccapacity\u003e \u003cperiod\u003e [\u003ctokens\u003e]\n\nWhere `key` is a unique bucket identifier. Examples:\n\n* User ID\n* Request's IP address\n\nFor example:\n\n    SHIELD.absorb ip-127.0.0.1 30 60 11\n                    ▲           ▲  ▲ ▲\n                    |           |  | └─── take 11 token (default is 1 if omitted)\n                    |           |  └───── 60 seconds\n                    |           └──────── 30 tokens\n                    └──────────────────── key \"ip-127.0.0.1\"\n\nThe command responds with the number of tokens left in the bucket.\n`-1` is returned when the bucket is overflown.\n\n    127.0.0.1:6379\u003e SHIELD.absorb user123 30 60 13\n    (integer) 17\n    127.0.0.1:6379\u003e SHIELD.absorb user123 30 60 13\n    (integer) 4\n    127.0.0.1:6379\u003e SHIELD.absorb user123 30 60 13\n    (integer) -1\n\n## Contributing\n\nInterested in contributing? See **[CONTRIBUTING.md](CONTRIBUTING.md)** for:\n\n- Development setup\n- Running tests and benchmarks\n- Code style guidelines\n- Pull request process\n\n## License\n\nThis is free software under the terms of MIT the license (see the file\n`LICENSE` for details).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayarotsky%2Fredis-shield","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fayarotsky%2Fredis-shield","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayarotsky%2Fredis-shield/lists"}