Skip to content

baldur.services — Retry

Retry policy and configuration types, the per-attempt action/result records, and the exhaustion exception.

RetryPolicy 

RetryPolicy(
    config: RetryPolicyConfig,
    backoff: BackoffStrategy | None = None,
    rate_limit_coordinator: (
        RateLimitCoordinator | None
    ) = None,
    retry_budget: AdaptiveRetryBudget | None = None,
    sleeper: Callable[[float], None] | None = None,
)

Bases: ResiliencePolicy[T]

Pure retry Policy.

External concerns such as Kill Switch, ErrorBudgetGate, Audit, and DLQ are handled by PolicyComposer's Guard/Hook/Sink.

Idempotency contract

Functions passed to execute() MUST be idempotent. Use IdempotencyGuard + IdempotencyHook via PolicyComposer for framework-level enforcement, or implement idempotency in your handler.

Collaborator: - retry_budget: state mutates on every in-loop attempt (Guard-unsuitable) - rate_limit_coordinator: bundles wait / success-signal / cooldown - backoff: reuses core/backoff.py BackoffStrategy ABC - sleeper: between-attempt wait function. None (default) -> time.sleep; pass lambda _: None to defer waiting to an external scheduler.

execute 

execute(
    func: Callable[..., T],
    *args: Any,
    context: PolicyContext | None = None,
    **kwargs: Any
) -> PolicyResult[T]

Pure retry execution.

Kill Switch, ErrorBudgetGate, Audit, and DLQ are handled by PolicyComposer via Guard/Hook/Sink.

RetryPolicyConfig dataclass 

RetryPolicyConfig(
    max_attempts: int = 3,
    backoff_base: int = 4,
    backoff_max: int = 180,
    jitter_percent: int = 25,
    retryable_exceptions: tuple[type[Exception], ...] = (
        lambda: (Exception,)
    )(),
    non_retryable_exceptions: tuple[
        type[Exception], ...
    ] = non_retryable_exceptions(),
    domain: str = "default",
    enable_dlq: bool = True,
)

Configuration dedicated to the pure retry Policy. Does not include externally dependent settings.

from_settings classmethod 

from_settings(domain: str = 'default') -> RetryPolicyConfig

Load only the pure retry settings from Settings.

Parameters:

Name Type Description Default
domain str

Domain name for per-domain overrides

 'default'

Returns:

Type Description
RetryPolicyConfig

RetryPolicyConfig instance

from_retry_config classmethod 

from_retry_config(config: RetryConfig) -> RetryPolicyConfig

Extract only the pure retry settings from an existing RetryConfig.

RetryConfig dataclass 

RetryConfig(
    max_attempts: int = 3,
    backoff_base: int = 4,
    backoff_max: int = 180,
    jitter_percent: int = 25,
    retryable_exceptions: tuple[type[Exception], ...] = (
        lambda: (Exception,)
    )(),
    non_retryable_exceptions: tuple[
        type[Exception], ...
    ] = non_retryable_exceptions(),
    enable_dlq: bool = True,
    domain: str = "default",
    rate_limit_aware: bool = True,
    rate_limit_key: str | None = None,
    throttle_aware: bool = True,
    throttle_backoff_multiplier_cap: float = 4.0,
    critical_tier_full_stop_grace_retries: int = 1,
    critical_tier_full_stop_max_delay: int = 720,
)

Configuration for retry behavior.

critical_tier_full_stop_grace_retries class-attribute instance-attribute 

critical_tier_full_stop_grace_retries: int = 1

Number of extra retries allowed for CRITICAL-tier requests even in FULL_STOP

critical_tier_full_stop_max_delay class-attribute instance-attribute 

critical_tier_full_stop_max_delay: int = 720

Maximum wait time for CRITICAL-tier requests in FULL_STOP (12 minutes)

from_settings classmethod 

from_settings(domain: str = 'default') -> RetryConfig

Load configuration from RuntimeConfigManager (preferred) or core config.

Parameters:

Name Type Description Default
domain str

Domain name for per-domain overrides

 'default'

Returns:

Type Description
RetryConfig

RetryConfig instance

RetryResult dataclass 

RetryResult(
    success: bool,
    action: RetryAction,
    attempt: int,
    value: Any = None,
    error: Exception | None = None,
    dlq_id: int | None = None,
    next_delay: int | None = None,
)

Result of a retry operation.

should_retry property 

should_retry: bool

Whether another retry should be attempted.

was_retried property 

was_retried: bool

Whether this result came from a retry (not first attempt).

to_policy_result 

to_policy_result() -> PolicyResult

Convert to the unified PolicyResult result type.

RetryAction

Bases: str, Enum

Actions that can be taken after a failure.

MaxRetriesExceededError 

MaxRetriesExceededError(
    message: str,
    retry_count: int,
    max_retries: int,
    last_error: Exception | None = None,
)

Bases: RetryExhaustedError

Raised when maximum retry attempts have been exhausted.