{"id":20572175,"url":"https://github.com/mcaimi/libvmod-calmdown","last_synced_at":"2025-07-27T07:40:15.644Z","repository":{"id":69446922,"uuid":"92153648","full_name":"mcaimi/libvmod-calmdown","owner":"mcaimi","description":"A simple rate limit VMOD for Varnish Cache 5.1","archived":false,"fork":false,"pushed_at":"2017-05-26T09:14:51.000Z","size":26,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-16T21:16:05.389Z","etag":null,"topics":["rate-limit","token-bucket","varnish-cache","vmod"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mcaimi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","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":"2017-05-23T09:19:32.000Z","updated_at":"2023-12-08T05:09:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"31066f8a-04fd-47b4-9eee-c9eee8d54d47","html_url":"https://github.com/mcaimi/libvmod-calmdown","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/mcaimi%2Flibvmod-calmdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcaimi%2Flibvmod-calmdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcaimi%2Flibvmod-calmdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcaimi%2Flibvmod-calmdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mcaimi","download_url":"https://codeload.github.com/mcaimi/libvmod-calmdown/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242187809,"owners_count":20086224,"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":["rate-limit","token-bucket","varnish-cache","vmod"],"created_at":"2024-11-16T05:18:39.544Z","updated_at":"2025-03-06T10:20:55.615Z","avatar_url":"https://github.com/mcaimi.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vmod-calmdown\n\n## SYNOPSIS\n\n    import calmdown;\n\n## DESCRIPTION\n\nA simple rate-limit module for Varnish Cache version 5.1.\n\nThis module implements a rate limiting feature in Varnish that allows an user to set\nlimits on how often a resource should be requested by the same source client. This is\nuseful for example for internet-facing API providers, high-traffic services or websites\nin general.\n\nThe algorithm used is a variant of the [Token-Bucket algorithm](https://en.wikipedia.org/wiki/Token_bucket)\n\nThe module works by:\n1. instantiating an list of linked lists (the bucket queues) and associating a pthread mutex to every item\n2. The string \"compound_key\" is created from the concatenation of (source key) + (resource key)\n3. for every request the module computes the SHA256 hash of the compound_key and determine which queue will handle the request\n4. once a queue is selected, a bucket is allocated for the current source IP hash.\n\nFor every request, the time between the last call timestamp and the current is evaluated and the token counter is:\n1. Decreased by one\n2. Increased by a value proportional to the timestamp difference.\n\nIf a source hash consumes all its tokens, the user receives a \"calm down\" error from varnish. The module was inspired by the\nthrottle module.\n\nThe module can apply the same bucket value to every requested URL or can handle different bucket values for different URLs.\n\n## FUNCTIONS\n\n    *calmdown()*\n\n### Prototype:\n\n    calmdown(STRING S, STRING R, INT I, DURATION D)\n\n### Return value:\n\nBOOL\n\n### Description\n\n  Rate limits access to resources.\n\n* S: is the requester identificator (can be the source IP address or whatever)\n* R: is the URL you want to rate limit. (can be a fixed string, in case every URL must be equally limited)\n* I: is the initial token (number of calls) number associated to every bucket\n* D: the minimum interval in which varnish will let pass at most 'I' calls.\n\n### Usage Examples\n\nRate limiting everything by the same ruleset (same bucket value), only a single call to the module is needed in the VCL.\nThe \"R\" parameter needs to be a fixed string, such as \"/\":\n\n    sub vcl_recv {\n      if (calmdown.calmdown(client.identity, \"/\", 15, 10s)) {\n      # Client has exceeded 15 reqs per 10s\n      return (synth(429, \"Calm Down\"));\n    }\n\nThe ratelimiting function can be used multiple times to limit URLs by different bucket values:\n\n    sub vlc_recv {\n      if (req.url ~ \"/api/v1.0\") {\n        if (calmdown.calmdown(client.identity, req.url, 15, 10s)) {\n          # Client has exceeded 15 reqs per 10s\n          return (synth(429, \"Calm Down\"));\n        }\n      }\n    }\n\nOtherwise every possible (request identifier / resource requested) pair can be ratelimitied differently. For example, one could\nrate limit accesses by browser user-agent:\n\n    sub vcl_recv {\n      if (req.http.user-agent ~ \"Mozilla\") {\n        if (calmdown.calmdown(client.identity, req.http.user-agent, 15, 10s)) {\n            # Client has exceeded 15 reqs per 10s\n            return (synth(429, \"Calm Down\"));\n          }\n      }\n    }\n\n## INSTALLATION\n\nThe source tree is based on autotools to configure the building.\nBuilding requires the Varnish header files and uses pkg-config to find\nthe necessary paths.\n\nUsage:\n\n    ./autogen.sh\n    ./configure\n\nIf you have installed Varnish to a non-standard directory, call\n``autogen.sh`` and ``configure`` with ``PKG_CONFIG_PATH`` pointing to\nthe appropriate path. For instance, when varnishd configure was called\nwith ``--prefix=$PREFIX``, use\n\n    export PKG_CONFIG_PATH=${PREFIX}/lib/pkgconfig\n    export ACLOCAL_PATH=${PREFIX}/share/aclocal\n\nThe module will inherit its prefix from Varnish, unless you specify a\ndifferent ``--prefix`` when running the ``configure`` script for this\nmodule.\n\nMake targets:\n\n* make - builds the vmod.\n* make install - installs your vmod.\n\nIn addition to these steps, you need to install the config YAML file:\n\n* copy src/conf/settings.yaml into /etc/vmod-calmdown/calmdown.yaml\n\nas of now you *need* to create that specific folder in /etc, as the \nsoftware will search for that hardcoded path.\n\n### Installation directories\n\nBy default, the vmod ``configure`` script installs the built vmod in the\ndirectory relevant to the prefix. The vmod installation directory can be\noverridden by passing the ``vmoddir`` variable to ``make install``.\n\n## COMMON PROBLEMS\n\n* configure: error: Need varnish.m4 -- see README.rst\n\n  Check whether ``PKG_CONFIG_PATH`` and ``ACLOCAL_PATH`` were set correctly\n  before calling ``autogen.sh`` and ``configure``\n\n* Incompatibilities with different Varnish Cache versions\n\n  Make sure you build this vmod against its correspondent Varnish Cache version.\n  For instance, to build against Varnish Cache 5.1, this vmod must be built from\n  branch 5.1.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcaimi%2Flibvmod-calmdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmcaimi%2Flibvmod-calmdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcaimi%2Flibvmod-calmdown/lists"}