{"id":13813043,"url":"https://github.com/pjwerneck/bouncer","last_synced_at":"2026-01-12T02:43:12.305Z","repository":{"id":56863780,"uuid":"72048183","full_name":"pjwerneck/bouncer","owner":"pjwerneck","description":"Throttling, rate-limiting and synchronization for distributed applications.","archived":false,"fork":false,"pushed_at":"2025-02-04T23:08:20.000Z","size":278,"stargazers_count":16,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-04T23:27:58.497Z","etag":null,"topics":["lock","rate-limiting","semaphore","token-bucket"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pjwerneck.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-10-26T22:02:35.000Z","updated_at":"2025-02-04T23:08:24.000Z","dependencies_parsed_at":"2024-08-04T04:03:19.744Z","dependency_job_id":"d8737878-e54b-439c-9602-143b9f52c817","html_url":"https://github.com/pjwerneck/bouncer","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pjwerneck%2Fbouncer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pjwerneck%2Fbouncer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pjwerneck%2Fbouncer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pjwerneck%2Fbouncer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pjwerneck","download_url":"https://codeload.github.com/pjwerneck/bouncer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254239648,"owners_count":22037744,"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":["lock","rate-limiting","semaphore","token-bucket"],"created_at":"2024-08-04T04:01:00.806Z","updated_at":"2026-01-12T02:43:12.299Z","avatar_url":"https://github.com/pjwerneck.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# Bouncer\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/pjwerneck/bouncer)](https://goreportcard.com/report/github.com/pjwerneck/bouncer)\n[![Build Status](https://github.com/pjwerneck/bouncer/actions/workflows/go.yml/badge.svg?branch=master)](https://github.com/pjwerneck/bouncer/actions/workflows/go.yml?branch=master)\n\n\n![bouncer logo](https://s3.amazonaws.com/www.pedrowerneck.com/images/bouncer-sm.png)\n\n\nA lightweight RPC service for distributed application control - replaces\nmakeshift solutions using memcached or Redis.\n\n## Quick Start\n\nRun the server:\n```bash\ndocker run -p 5505:5505 pjwerneck/bouncer:latest\n```\n\nView the API documentation:\n```bash\n# Open Swagger UI in your browser\nhttp://localhost:5505/docs\n```\n\n### Examples\n\n#### *\"I want to limit something to only one operation per second\"*\n```bash\n# Use a token bucket\ncurl http://localhost:5505/tokenbucket/myapp/acquire\n```\n\n#### *\"How to increase the limit to twenty per second?\"*\n```bash\n# Set size=20\ncurl http://localhost:5505/tokenbucket/myapp/acquire?size=20\n```\n\n#### *\"But I can't have all twenty starting at the same time!\"*\n```bash\n# Set interval to 1000/rate for smoother distribution\ncurl http://localhost:5505/tokenbucket/myapp/acquire?interval=50\n```\n\n#### *\"What if I have a resource that can be used by only one client at a time?\"*\n```bash\n# Use a semaphore\nKEY=$(curl http://localhost:5505/semaphore/myapp/acquire)\n# ... do work ...\ncurl http://localhost:5505/semaphore/myapp/release?key=$KEY\n```\n\n#### *\"Now I need to limit it to ten concurrent clients.\"*\n```bash\n# Use a semaphore with size=10\nKEY=$(curl http://localhost:5505/semaphore/myapp/acquire?size=10)\n# ... do work ...\ncurl http://localhost:5505/semaphore/myapp/release?key=$KEY\n```\n\n#### *\"I have some clients that must wait for something else to finish.\"*\n```bash\n# Waiting clients\ncurl http://localhost:5505/event/myapp/wait\n\n# Triggering client\ncurl http://localhost:5505/event/myapp/send?message=wakeup\n```\n\n#### *\"I need to count how many times something happens across multiple services\"*\n```bash\n# Increment counter by 1\ncurl http://localhost:5505/counter/myapp/count\n\n# Increment by specific amount\ncurl http://localhost:5505/counter/myapp/count?amount=5\n\n# Get current value\ncurl http://localhost:5505/counter/myapp/value\n\n# Reset counter\ncurl http://localhost:5505/counter/myapp/reset\n```\n\n#### *\"I want multiple clients to wait until exactly N of them are ready\"*\n```bash\n# Create a barrier for 3 clients\n# Each client does:\ncurl http://localhost:5505/barrier/myapp/wait?size=3\n\n# The barrier triggers automatically when the 3rd client arrives\n```\n\n#### *\"I need to know if a periodic task stops running\"*\n```bash\n# Monitoring clients\ncurl http://localhost:5505/watchdog/myapp/wait\n\n# Task that should be monitored\nwhile true; do\n    curl http://localhost:5505/watchdog/myapp/kick?expires=60000\n    sleep 30\ndone\n\n# If the task fails to kick within expires time,\n# all waiting clients will be notified\n```\n\n## Configuration\n\nEnvironment variables for customizing server behavior:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `BOUNCER_HOST` | `0.0.0.0` | Server listen address |\n| `BOUNCER_PORT` | `5505` | Server listen port |\n| `BOUNCER_LOGLEVEL` | `INFO` | Log level (TRACE, DEBUG,INFO,WARN,ERROR,FATAL,PANIC) |\n| `BOUNCER_READ_TIMEOUT` | `30` | HTTP read timeout (seconds) |\n| `BOUNCER_WRITE_TIMEOUT` | `30` | HTTP write timeout (seconds) |\n\n\n\u003e [!WARNING]\n\u003e If your controllers require a `maxwait` time that exceeds the\n\u003e default write timeout of `30` seconds, increase the `BOUNCER_WRITE_TIMEOUT`\n\u003e value accordingly, otherwise the server might close the connection before the\n\u003e response is available","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpjwerneck%2Fbouncer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpjwerneck%2Fbouncer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpjwerneck%2Fbouncer/lists"}