Circuit Breaker

dkmio includes a built-in circuit breaker that protects your application from cascading failures when DynamoDB is unavailable or under severe throttling.

How It Works

CLOSED (normal) → N consecutive infra failures → OPEN (rejects all calls instantly)
                                                       ↓ after recovery_timeout seconds
                                                  HALF_OPEN (one probe request allowed)
                                                       ↓ if probe succeeds
                                                  CLOSED (back to normal)

State	Behavior
CLOSED	All calls pass through normally.
OPEN	Every call raises CircuitOpenError immediately, without touching DynamoDB. Users get a fast error instead of waiting for timeouts to cascade.
HALF_OPEN	One probe request is allowed through to test if DynamoDB recovered. Success → CLOSED. Failure → back to OPEN.

The circuit only trips on infrastructure errors (throttling, outages, unclassified AWS errors). Client errors like ConditionError, ValidationError, and MissingKeyError never count — those are logic bugs, not infra failures.

Default Configuration

The circuit breaker is active by default with sensible settings:

# Default: failure_threshold=5, recovery_timeout=30s
db = DynamoDB(region_name="us-east-1")

Custom Configuration

from dkmio import DynamoDB, CircuitBreakerConfig

db = DynamoDB(
    region_name="us-east-1",
    circuit_breaker=CircuitBreakerConfig(
        failure_threshold=3,   # open after 3 consecutive infra failures
        recovery_timeout=60,   # wait 60s before probing
    ),
)

Disable the Circuit Breaker

db = DynamoDB(region_name="us-east-1", circuit_breaker=None)

Catching CircuitOpenError

Use it to implement fallback logic (cache, degraded mode, etc.):

from dkmio.exceptions import CircuitOpenError

try:
    order = orders.get(user_id="usr_123", order_id="ord_456")
except CircuitOpenError:
    order = cache.get("usr_123:ord_456")  # serve from cache

Inspecting and Resetting State

# Useful for health-check endpoints
db.circuit_breaker.state  # "closed" | "open" | "half_open"

# Manual reset (e.g. after a deployment or admin action)
db.circuit_breaker.reset()