resilient-ktor/com.santimattius.resilient.ktor/ResilientPluginConfig

ResilientPluginConfig

Choose exactly ONE of the two policy-source paths:

Path A — Bring-Your-Own policy:

install(ResilientPlugin) {
    policy = myExistingPolicy
}

The plugin uses the provided policy and does NOT close it when the client closes. Note: shouldRetryOnStatus is inert in this path; configure status-based retry inside the policy's own RetryPolicyConfig.shouldRetryResult.

Path B — Inline DSL:

install(ResilientPlugin) {
    scope = appScope.asResilientScope()
    retry { maxAttempts = 3 }
    shouldRetryOnStatus = { it.value >= 500 }
}

The plugin builds an internal ResilientPolicy and closes it when the client closes. shouldRetryOnStatus is bridged into RetryPolicyConfig.shouldRetryResult automatically.

Setting both policy and inline DSL blocks, or neither, fails with IllegalStateException at client construction time.

Constructors

ResilientPluginConfig

constructor()

Properties

policy

var policy: ResilientPolicy?

Provide a pre-built ResilientPolicy. The plugin will NOT close this policy on client close. Mutually exclusive with inline DSL blocks (retry, circuitBreaker, etc.).

retryOnlyIdempotent

var retryOnlyIdempotent: Boolean

When true (default), POST and PATCH requests bypass the policy entirely — no retry, no circuit breaker, no timeout — preserving at-most-once semantics for non-idempotent methods. Set to false to allow the policy to wrap all HTTP methods.

scope

var scope: ResilientScope?

The ResilientScope used to build the policy inline. Required when using inline DSL blocks (retry, circuitBreaker, etc.). Ignored when policy is set.

shouldRetryOnStatus

var shouldRetryOnStatus: (HttpStatusCode) -> Boolean

Determines whether a response status code should trigger a retry. Defaults to { it.value >= 500 } (any 5xx is retryable). Only applied in the inline DSL path; BYO policy users must configure this inside their own policy.

Functions

bulkhead

fun bulkhead(block: BulkheadConfig.() -> Unit)

Configures a bulkhead when using the inline DSL path.

circuitBreaker

fun circuitBreaker(block: CircuitBreakerConfig.() -> Unit)

Configures a circuit breaker when using the inline DSL path.

rateLimiter

fun rateLimiter(block: RateLimiterConfig.() -> Unit)

Configures a rate limiter when using the inline DSL path.

retry

fun retry(block: RetryPolicyConfig.() -> Unit)

Configures a retry policy when using the inline DSL path.

timeout

fun timeout(block: TimeoutConfig.() -> Unit)

Configures a timeout policy when using the inline DSL path.