{"id":18498013,"url":"https://github.com/dream11/lua-circuit-breaker","last_synced_at":"2025-07-11T12:43:22.778Z","repository":{"id":44906584,"uuid":"372465580","full_name":"dream11/lua-circuit-breaker","owner":"dream11","description":"Circuit breaker pattern in Lua","archived":false,"fork":false,"pushed_at":"2023-10-24T08:21:42.000Z","size":106,"stargazers_count":37,"open_issues_count":2,"forks_count":9,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-04-09T17:59:56.287Z","etag":null,"topics":["circuit-breaker","kong","lua","resilience4j"],"latest_commit_sha":null,"homepage":"https://dream11.github.io/lua-circuit-breaker/","language":"Lua","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/dream11.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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-31T10:20:10.000Z","updated_at":"2025-01-31T18:53:23.000Z","dependencies_parsed_at":"2024-11-06T18:16:47.187Z","dependency_job_id":null,"html_url":"https://github.com/dream11/lua-circuit-breaker","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/dream11/lua-circuit-breaker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dream11%2Flua-circuit-breaker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dream11%2Flua-circuit-breaker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dream11%2Flua-circuit-breaker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dream11%2Flua-circuit-breaker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dream11","download_url":"https://codeload.github.com/dream11/lua-circuit-breaker/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dream11%2Flua-circuit-breaker/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264811009,"owners_count":23667651,"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":["circuit-breaker","kong","lua","resilience4j"],"created_at":"2024-11-06T13:37:06.029Z","updated_at":"2025-07-11T12:43:22.730Z","avatar_url":"https://github.com/dream11.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"![lua-circuit-breaker](./docs/lua-circuit-breaker.svg)\n\n[![Continuous Integration](https://github.com/dream11/lua-circuit-breaker/actions/workflows/ci.yml/badge.svg)](https://github.com/dream11/lua-circuit-breaker/actions/workflows/ci.yml)\n[![Code Coverage](https://codecov.io/gh/dream11/lua-circuit-breaker/branch/master/graph/badge.svg?token=6wyFuRgmdG)](https://codecov.io/gh/dream11/lua-circuit-breaker)\n![License](https://img.shields.io/badge/license-MIT-green.svg)\n\n## Overview\n`lua-circuit-breaker` provides circuit-breaker functionality like [resilience4j](https://github.com/resilience4j/resilience4j) i.e. for Java.\n\u003cbr\u003eAny IO function/method that can fail can be wrapped around `lua-circuit-breaker` and can be made to fail fast, leading to improved resiliency and fault tolerance.\n\n## How does it work?\n\n1. The library creates a CB(circuit breaker) object for a function.\n2. Before making the function call, we call `CB._before()`. This will return an error if the circuit breaker is in open state otherwise will increment the counter of total_requests by 1.\n3. After the function call ends, we call `CB._after(CB._generation, ok)`. If ok is true, the success counter is incremented by 1. Otherwise, the failure counter gets incremented by 1.\n4. CB object transitions into three states: closed, open, and half-open based on the settings defined by the user.\n\n## Installation\n\n### luarocks\n```bash\nluarocks install lua-circuit-breaker\n```\n\n### source\nClone this repo and run:\n```bash\nluarocks make\n```\n\n\n## Sample Usage\n\n```lua\n--Import Circuit breaker factory.\nlocal circuit_breaker_lib = require \"lua-circuit-breaker.factory\"\n\n--Create a new instance of the circuit breaker factory. Always set version = 0. This is used for flushing the circuit breakers when the configuration is changed.\nlocal circuit_breakers = circuit_breaker_lib:new()\n\n-- Get a circuit breaker instance from factory. Returns a new instance only if not already created.\nlocal settings = {\n    version = 1,\n    window_time = 10,\n    min_calls_in_window= 20,\n    failure_percent_threshold= 51,\n    wait_duration_in_open_state= 15,\n    wait_duration_in_half_open_state= 120,\n    half_open_max_calls_in_window= 10,\n    half_open_min_calls_in_window= 5,\n    notify = function(name, state)\n        print(string.format(\"Breaker [ %s ] state changed to [ %s ]\", name, state))\n    end,\n}\nlocal cb, err = circuit_breakers:get_circuit_breaker(\n    \"io_call_x\", -- Name of circuit breaker. This should be unique.\n    \"io_calls\", -- Used to group certain CB objects into one.\n    settings,\n)\n\n-- Check state of cb. This function returns an error if the state is open or half_open_max_calls_in_window is breached.\nlocal _, err_cb = cb:_before()\nif err_cb then\n    return false, \"Circuit breaker open error\"\nend\nlocal generation = cb._generation\n\n-- Call IO method for which circuit breaking is required.\nlocal res, err_http = makeIOCall()\n\n-- Update the state of the cb based on successful / failure response.\nlocal ok = res and res.status and res.status \u003c 500\ncb:_after(generation, ok) -- generation is used to update the counter in the correct time bucket.\n```\n\n## Openresty Sample Usage\n\nThere is a sample nginx openresty application (using docker for ease of usage) on [`ngx_lua_sample`](ngx_lua_sample/README.md)\n\n### Parameters\n\n| Key | Default  | Type  | Required | Description |\n| --- | --- | --- | --- | --- |\n| name | NA | string | true | Name of circuit breaker, this should be unique |\n| group | \"default_group\" | string | false | Group to which the CB object will belong |\n| settings.version | NA | number | true | Maintains version of settings object, changing this will create new CB and flush older CB |\n| settings.window_time | 10 | number | true | Window size in seconds |\n| settings.min_calls_in_window | 20 | number | true | Minimum number of calls to be present in the window to start calculation |\n| settings.failure_percent_threshold | 51 | number | true | % of requests that should fail to open the circuit |\n| settings.wait_duration_in_open_state | 15 | number | true | Duration(sec) to wait before automatically transitioning from open to half-open state |\n| settings.wait_duration_in_half_open_state | 120 | number | true | Duration(sec) to wait in half-open state before automatically transitioning to closed state |\n| settings.half_open_min_calls_in_window | 5 | number | true | Minimum number of calls to be present in the half open state to start calculation |\n| settings.half_open_max_calls_in_window | 10 | number | true | Maximum calls to allow in half open state |\n| settings.half_open_to_open | NA | function | false | Overrides transition from half-open to open state |\n| settings.half_open_to_close | NA | function | false | Overrides transition from half-open to closed state |\n| settings.closed_to_open | NA | function | false | Overrides transtition from closed to open state |\n| settings.notify | NA | function | false | Overrides with a custom logger function |\n\n\n## Available Methods\n\n1. `new()` : create a new circuit breaker factory\n2. `get_circuit_breaker(name, group, settings)` : create a new CB object\n3. `check_group(group)` : check if this group is present\n4. `remove_breakers_by_group(group)` : remove all CB objects in a group\n5. `remove_circuit_breaker(name, group)` : remove a particular CB inside a group. if group is not passed, \"default_group\" is assumed.\n\n## Inspired by\n- [moonbreaker](https://github.com/Invizory/moonbreaker)\n- [resilience4j](https://github.com/resilience4j/resilience4j)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdream11%2Flua-circuit-breaker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdream11%2Flua-circuit-breaker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdream11%2Flua-circuit-breaker/lists"}