{"id":27127824,"url":"https://github.com/ananto30/cap-em","last_synced_at":"2025-04-07T17:58:01.978Z","repository":{"id":39385550,"uuid":"268130346","full_name":"Ananto30/cap-em","owner":"Ananto30","description":"Highly configurable resource usage/limit tracker","archived":false,"fork":false,"pushed_at":"2024-04-01T18:21:42.000Z","size":95,"stargazers_count":10,"open_issues_count":1,"forks_count":11,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-05-21T06:06:38.952Z","etag":null,"topics":["docker","limiter","python","python3","rate-limit","rate-limiting","rest-api"],"latest_commit_sha":null,"homepage":"","language":"Python","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/Ananto30.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2020-05-30T17:41:54.000Z","updated_at":"2024-01-19T10:27:23.000Z","dependencies_parsed_at":"2024-02-04T05:33:13.898Z","dependency_job_id":"42c1b3ba-db87-43c9-aca8-90a9fc91f0fc","html_url":"https://github.com/Ananto30/cap-em","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ananto30%2Fcap-em","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ananto30%2Fcap-em/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ananto30%2Fcap-em/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ananto30%2Fcap-em/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ananto30","download_url":"https://codeload.github.com/Ananto30/cap-em/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247704511,"owners_count":20982293,"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":["docker","limiter","python","python3","rate-limit","rate-limiting","rest-api"],"created_at":"2025-04-07T17:58:01.401Z","updated_at":"2025-04-07T17:58:01.961Z","avatar_url":"https://github.com/Ananto30.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cap'em\n\n[![GitHub](https://img.shields.io/github/license/Ananto30/cap-em)](/LICENSE.md)\n[![codecov](https://codecov.io/gh/Ananto30/cap-em/branch/main/graph/badge.svg)](https://codecov.io/gh/Ananto30/cap-em)\n[![Docker Image Size (latest by date)](https://img.shields.io/docker/image-size/ananto30/cap-em?logo=docker)](https://hub.docker.com/r/ananto30/cap-em)\n\n[![Maintainability](https://api.codeclimate.com/v1/badges/620b4efcf9e41d74cb00/maintainability)](https://codeclimate.com/github/Ananto30/cap-em/maintainability)\n[![Code Climate technical debt](https://img.shields.io/codeclimate/tech-debt/Ananto30/cap-em?logo=Code%20Climate)](https://codeclimate.com/github/Ananto30/cap-em/trends/technical_debt)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/9bbb9f74a480493f9891e9ea015e4eb0)](https://app.codacy.com/gh/Ananto30/cap-em/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_grade)\n\nEasy to use **resource usage tracker** (can be used as a rate limiter). Define a config file and use it right away! Use the **production ready** [Docker](#run-it-now-🚀) image or run it locally.\n\n## Usage 📝\n\n*   Define a config file (yaml) in the format below -\n\n```yaml\n\u003cresource_name\u003e:\n    \u003ctime\u003e: \u003climit\u003e\n```\n\nAs an example -\n\n```yaml\nemail:\n    1m: 2\n    1h: 5\n    1d: 6\n```\n\nAllowed time units are `s`, `m`, `h`, `d`, `w`, `M`, `y`. The time unit should be in ascending order. For example, `1m: 2, 1h: 5` is valid, but `1h: 5, 1m: 2` is not.\n\n*   Then just use the API to check the limit and track the usage.\n\n    *   Get usage availability\n\n        ```bash\n        curl -H \"Access-ID: 123\" http://localhost:8000/api/v1/usage/email\n        ```\n\n        ```json\n        {\n            \"access_in_ms\": 0\n        }\n        ```\n\n        This means the user can access the resource right now.\n\n    \u003c!----\u003e\n\n    *   Register a usage\n\n        ```bash\n        curl -X POST -H \"Access-ID: 123\" http://localhost:8000/api/v1/usage/email\n        ```\n\nNotice that the `Access-ID` header is required. This is the unique identifier for the user or any other entity that is using the resource. This is used to track the usage for that perticular entity.\n\n## Why Cap'em? 🤔\n\nSay you have a resource called Email. You want to limit this email change capacity for users. This is set to twice per day. You are very happy to code with that, now the requirements come again and said twice per day but not more than one per hour, and monthly limit should be 5 🤬 Now Cap-em will come to the rescue! It's an independent service, so you can deploy in your microservices or SOA.\n\nYou can have different configurations like above or as many configs as you like with several resources. All you need is to make a config file, and use the service right away!\n\n## Run it now! 🚀\n\n    docker pull ananto30/cap-em\n    docker run -p 8000:8000 -e DB_URI=\u003cdatabase_connection_url\u003e -e CONFIG=\u003cbase64_of_config_file\u003e ananto30/cap-em\n\n2 environment variables are required to run the service. `DB_URI` is the database connection url. `CONFIG` is the base64 encoded config file. Check the [Makefile#L6](/Makefile#L6) to see how to encode the config file.\n\nDB\\_URI is in SQLAlchemy format. For example -\n`postgresql://user:password@\\\u003cHOST\u003e:5432/capem`\n\nAlso note that the database should be created before running the service. The service will not create the database for you. It will only create the tables.\n\n## Available APIs 📚\n\n*   **/api/v1/help**\n    *   GET\n        *   Get the help doc\n*   **/api/v1/configs**\n    *   GET\n        *   Check the loaded configs (yaml file)\n*   **/api/v1/usage/{resource\\_name}**\n    *   GET\n        *   Get the usage availability in milliseconds\n    *   POST\n        *   Register a usage\n\n## Local development 🛠\n\n*   Setup project\n\n    ```bash\n    make setup\n    ```\n\n*   Run the service\n\n    ```bash\n    make run\n    ```\n\n### Docker 🐳\n\n*   Build the image\n\n    ```bash\n    make docker-build\n    ```\n*   Run the image\n\n    ```bash\n    make docker-run\n    ```\n\nThe Makefile try to get your IP and set in the `DB_URI` environment variable. If it fails, you need to set it manually.\n\n## Tests 🧪\n\nTests are better to be run with SQLite database. Because there will be entries in DB and those should be cleared after each test is run. So **if you use any other than sqlite, make sure to delete the entries to pass tests**. To use SQLite you need to set the environment variable `DB_URI` -\n\n```bash\nmake test\n```\n\nCustom DB -\n\n```bash\nDB_URI=sqlite:///capem-ut.db make test\n```\n\n## TODO 📝\n\nPriority\n\n*   A persistant way for configs? Like redis, so that multiple workers can get the same config\n*   Local caching is good but how to share the configs with different workers when config get changed\n*   Endpoint(s) to load/update configs, in bulk or single\n\nLess priority\n\n*   gRPC\n*   Messaging (for event-driven services)\n*   Non-relational DB support\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fananto30%2Fcap-em","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fananto30%2Fcap-em","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fananto30%2Fcap-em/lists"}