@radzor/circuit-breaker

Circuit breaker pattern for fault-tolerant external service calls. Tracks failure rates, opens the circuit to fast-fail requests when a threshold is exceeded, and probes recovery with half-open state. Zero dependencies.

Networkingv0.1.0typescriptpythonUniversalcircuit-breakerresiliencefault-toleranceretryavailabilitypatternby Radzor

Install

View source on GitHub →

$npx radzor@latest add circuit-breaker

⚠ Constraints: Create one circuit breaker instance per external dependency, not per request. State is in-memory — resets on process restart. Wrap @radzor/http-client calls or any external service call inside execute().

Inputs

Name	Type	Default	Description
threshold	number	5	Number of consecutive failures before the circuit opens.
timeout	number	60000	Time in milliseconds the circuit stays open before moving to half-open.
halfOpenRequests	number	1	Number of probe requests allowed in half-open state.
volumeThreshold	number	10	Minimum number of requests in a window before the failure rate is evaluated.

thresholdnumber

Number of consecutive failures before the circuit opens.

default: 5

timeoutnumber

{ "llm": { "constraints": "Create one circuit breaker instance per external dependency, not per request. State is in-memory — resets on process restart. Wrap @radzor/http-client calls or any external service call inside execute().", "usageExamples": "llm/examples.md", "integrationPrompt": "llm/integration.md" }, "name": "@radzor/circuit-breaker", "tags": [ "circuit-breaker", "resilience", "fault-tolerance", "retry", "availability", "pattern" ], "events": [ { "name": "onOpen", "payload": { "at": "number", "failures": "number" }, "description": "Fired when the circuit opens due to too many failures." }, { "name": "onHalfOpen", "payload": { "at": "number" }, "description": "Fired when the circuit transitions to half-open to probe recovery." }, { "name": "onClose", "payload": { "at": "number" }, "description": "Fired when the circuit closes (service recovered)." }, { "name": "onRejected", "payload": { "state": "string" }, "description": "Fired when a request is fast-failed because the circuit is open." }, { "name": "onError", "payload": { "code": "string", "message": "string" }, "description": "Fired on unexpected internal error." } ], "inputs": [ { "name": "threshold", "type": "number", "default": 5, "required": false, "description": "Number of consecutive failures before the circuit opens." }, { "name": "timeout", "type": "number", "default": 60000, "required": false, "description": "Time in milliseconds the circuit stays open before moving to half-open." }, { "name": "halfOpenRequests", "type": "number", "default": 1, "required": false, "description": "Number of probe requests allowed in half-open state." }, { "name": "volumeThreshold", "type": "number", "default": 10, "required": false, "description": "Minimum number of requests in a window before the failure rate is evaluated." } ], "radzor": "1.0.0", "actions": [ { "name": "execute", "params": [ { "name": "fn", "type": "() => Promise<T>", "description": "Async function to protect with the circuit breaker." } ], "returns": "Promise<T>", "description": "Execute a function through the circuit breaker. Throws CircuitOpenError if the circuit is open." }, { "name": "getState", "params": [], "returns": "'closed' | 'open' | 'half-open'", "description": "Get the current circuit state." }, { "name": "getMetrics", "params": [], "returns": "{ totalRequests: number; failures: number; successes: number; lastFailureAt: number | null }", "description": "Get cumulative request metrics." }, { "name": "reset", "params": [], "returns": "void", "description": "Manually reset the circuit to closed state and clear metrics." } ], "outputs": [ { "name": "state", "type": "'closed' | 'open' | 'half-open'", "description": "Current circuit state." }, { "name": "metrics", "type": "{ totalRequests: number; failures: number; successes: number; lastFailureAt: number | null }", "description": "Cumulative circuit metrics." } ], "runtime": "universal", "version": "0.1.0", "category": "networking", "languages": [ "typescript", "python" ], "description": "Circuit breaker pattern for fault-tolerant external service calls. Tracks failure rates, opens the circuit to fast-fail requests when a threshold is exceeded, and probes recovery with half-open state. Zero dependencies.", "dependencies": { "packages": {} }, "composability": { "connectsTo": [ { "event": "onOpen", "description": "Alert when circuit breaker opens (service degraded)", "compatibleWith": [ "@radzor/notification-hub.action.send.body", "@radzor/slack-bot.action.sendMessage.text", "@radzor/error-tracker.action.captureMessage.message" ] }, { "event": "onClose", "description": "Notify when circuit recovers", "compatibleWith": [ "@radzor/slack-bot.action.sendMessage.text", "@radzor/log-aggregator.action.info.message" ] } ] } }

@radzor/circuit-breaker

Install

Inputs

Outputs

Actions

Events

Composability

radzor.manifest.json

Version History

Name	Type	Description
state	'closed' \| 'open' \| 'half-open'	Current circuit state.
metrics	{ totalRequests: number; failures: number; successes: number; lastFailureAt: number \| null }	Cumulative circuit metrics.