Отказоустойчивость

Модуль для построения отказоустойчивого приложения с помощью таких механизмов, как CircuitBreaker, Retry, Timeout, RateLimiter и Fallback.

Каждый механизм, кроме Fallback, описывается интерфейсом-спецификацией — типизированным контрактом, который указывает на путь в конфигурации. Аннотация на защищаемом методе ссылается на этот интерфейс, поэтому связь метода с его настройками отказоустойчивости проверяет компилятор, а не строковое совпадение имён.

ResilientModule объединяет CircuitBreakerModule, RetryModule, TimeoutModule, FallbackModule и RateLimiterModule.

Пошаговое введение перед справочником — в разделе Отказоустойчивость.

Подключение¶

implementation "io.koraframework:resilient-kora"

@KoraApp
public interface Application extends ResilientModule { }

implementation("io.koraframework:resilient-kora")

@KoraApp
interface Application : ResilientModule

Обработчик аннотаций (annotation-processors) либо KSP-обработчик (symbol-processors) обязателен: он одновременно генерирует реализации спецификаций и применяет аспекты.

Распределённое состояние¶

По умолчанию каждый ограничитель частоты и бюджет повторов хранит своё состояние в памяти одного экземпляра приложения. Распределённый rate limiter и распределённый бюджет повторов делят это состояние между экземплярами через Redis. Для них нужен дополнительный модуль на клиенте Lettuce:

implementation "io.koraframework:resilient-kora-distributed-redis-lettuce"

@KoraApp
public interface Application extends ResilientModule, LettuceDistributedResilientModule { }

implementation("io.koraframework:resilient-kora-distributed-redis-lettuce")

@KoraApp
interface Application : ResilientModule, LettuceDistributedResilientModule

Артефакт подтягивает resilient-kora-distributed (независимые от хранилища контракты DistributedRateLimiterClient и DistributedRetryBudgetClient, алгоритмы и @RateLimiterDistributedSpec) и redis-lettuce. LettuceDistributedResilientModule расширяет LettuceModule, поэтому подключение настраивается в секции lettuce так же, как для кеша Redis. Поддерживаются и одиночный, и кластерный клиент, а все операции выполняются обычными командами Redis без серверных Lua-скриптов.

Чтобы выделить компонентам отказоустойчивости собственный клиент Redis вместо общего, зарегистрируйте AbstractRedisClient с тегом @Tag(LettuceDistributedResilientModule.class).

Спецификации¶

Спецификация — это интерфейс, который наследует контракт отказоустойчивости и помечен аннотацией с путём конфигурации:

Аннотации методов лежат в подпакете annotation рядом с контрактом, например io.koraframework.resilient.circuitbreaker.annotation.CircuitBreakable.

@RateLimited также принимает интерфейс с аннотацией @RateLimiterDistributedSpec (io.koraframework.resilient.distributed.ratelimiter.annotation), лимит которого общий для всех экземпляров — см. Распределённый rate limiter.

@CircuitBreakerSpec("resilient.circuitbreaker.pet") //(1)!
public interface PetCircuitBreaker extends CircuitBreaker { }

@RetrySpec("resilient.retry.pet")
public interface PetRetry extends Retry { }

@TimeoutSpec("resilient.timeout.pet")
public interface PetTimeouter extends Timeouter { }

@Component
public class PetService {

    @CircuitBreakable(PetCircuitBreaker.class) //(2)!
    @Retryable(PetRetry.class)
    @Timeout(PetTimeouter.class)
    public Optional<Pet> findById(long id) {
        return petRepository.findById(id);
    }
}

@CircuitBreakerSpec("resilient.circuitbreaker.pet") //(1)!
interface PetCircuitBreaker : CircuitBreaker

@RetrySpec("resilient.retry.pet")
interface PetRetry : Retry

@TimeoutSpec("resilient.timeout.pet")
interface PetTimeouter : Timeouter

@Component
open class PetService {

    @CircuitBreakable(PetCircuitBreaker::class) //(2)!
    @Retryable(PetRetry::class)
    @Timeout(PetTimeouter::class)
    open fun findById(id: Long): Pet? = petRepository.findById(id)
}

Что обработчик делает со спецификацией:

• генерирует её реализацию и модуль, который её публикует; модуль подхватывается @KoraApp автоматически — вручную ничего подключать не нужно;
• публикует сам интерфейс спецификации как компонент графа приложения, поэтому его можно внедрить для императивного использования;
• читает конфигурацию ровно из того пути, который указан в аннотации.

Сгенерированные реализации наследуют toString(), который выводит текущее состояние — состояние прерывателя и его счётчики, оставшиеся разрешения локального rate limiter, настройки повтора и токены бюджета повторов, — поэтому по записи внедрённой спецификации в лог или по её виду в отладчике видно, что она делает прямо сейчас.

Типичные ошибки компиляции:

• @CircuitBreakerSpec can only be applied to an interface — аннотация поставлена на класс или запись.
• @CircuitBreakerSpec annotated interface 'X' must extend io.koraframework.resilient.circuitbreaker.CircuitBreaker — интерфейс не наследует контракт.
• config path can't be blank — в значении аннотации пустая строка.
• @CircuitBreakable on 'X#y()' references an invalid resilient component type — класс, переданный в аннотацию метода, не реализует ожидаемый контракт.

CircuitBreaker¶

CircuitBreaker — это прокси, который управляет потоком запросов к конкретному методу и может временно запретить его выполнение, если метод бросает много исключений, подходящих под настроенный фильтр.

Смысл применения CircuitBreaker в том, чтобы дать системе время исправить ошибку, вызвавшую сбой, прежде чем позволить приложению повторить операцию. Шаблон CircuitBreaker обеспечивает стабильность на время восстановления системы после сбоя и снижает влияние на производительность. CircuitBreaker может находиться в одном из состояний: CLOSED, OPEN, HALF_OPEN.

• CLOSED: запрос приложения передаётся в защищаемую операцию. Прокси считает недавние отказы в пределах настроенного количества операций (countBased.windowSize), проходящих через него, и увеличивает счётчик, когда операция завершается неуспешно. Если число запросов превысило минимально необходимое для расчёта (minimumRequiredCalls), а доля недавних отказов превысила настроенный порог (failureRateThreshold), прокси переходит в OPEN.
• OPEN: в этом состоянии запрос приложения немедленно завершается ошибкой, и приложению возвращается исключение. В этот момент прокси запускает таймер ожидания (waitDurationInOpenState), по истечении которого переходит в HALF_OPEN.
• HALF_OPEN: ограниченному числу запросов (permittedCallsInHalfOpenState) разрешается пройти и вызвать операцию. Если эти запросы успешны, считается, что ошибка, ранее вызвавшая сбой, устранена, и CircuitBreaker переходит в состояние CLOSED (счётчик отказов сбрасывается). Если хотя бы один запрос завершается отказом, CircuitBreaker считает, что неисправность сохраняется, возвращается в состояние OPEN и перезапускает таймер ожидания (waitDurationInOpenState), давая системе дополнительное время на восстановление.

Состояние HALF_OPEN помогает избежать лавинообразного роста запросов к сервису: после начала восстановления сервис какое-то время может выдерживать лишь ограниченное число запросов.

Изначально находится в состоянии CLOSED.

Декларативное использование¶

Если CircuitBreaker находится в состоянии OPEN, вызов завершается исключением CallNotPermittedException.

@CircuitBreakerSpec("resilient.circuitbreaker.custom")
public interface CustomCircuitBreaker extends CircuitBreaker { }

@Component
public class SomeService {

    @CircuitBreakable(CustomCircuitBreaker.class)
    public String getValue() {
        throw new IllegalStateException("Ops");
    }
}

@CircuitBreakerSpec("resilient.circuitbreaker.custom")
interface CustomCircuitBreaker : CircuitBreaker

@Component
open class SomeService {

    @CircuitBreakable(CustomCircuitBreaker::class)
    open fun value(): String = throw IllegalStateException("Ops")
}

Конфигурация¶

Секция, на которую указывает @CircuitBreakerSpec, описана в классе CircuitBreakerConfig:

resilient {
    circuitbreaker {
        custom {
            type = STRIPED_APPROX //(1)!
            failureRateThreshold = 50 //(2)!
            minimumRequiredCalls = 10 //(3)!
            waitDurationInOpenState = "25s" //(4)!
            permittedCallsInHalfOpenState = 15 //(5)!
            enabled = true //(6)!
            countBased {
                windowSize = 100 //(7)!
                stripedApprox {
                    stripes = 16 //(8)!
                }
            }
        }
    }
}

resilient:
  circuitbreaker:
    custom:
      type: STRIPED_APPROX #(1)!
      failureRateThreshold: 50 #(2)!
      minimumRequiredCalls: 10 #(3)!
      waitDurationInOpenState: "25s" #(4)!
      permittedCallsInHalfOpenState: 15 #(5)!
      enabled: true #(6)!
      countBased:
        windowSize: 100 #(7)!
        stripedApprox:
          stripes: 16 #(8)!

Ключ telemetry внутри той же секции переопределяет общемодульные настройки из раздела Телеметрия.

Метрики модуля описаны в разделе Справочник метрик.

Реализации¶

type выбирает способ сбора статистики в состоянии CLOSED. Сама машина состояний во всех четырёх реализациях одинакова и строго атомарна.

TIME_BASED игнорирует countBased и читает собственную секцию:

resilient {
    circuitbreaker {
        custom {
            type = TIME_BASED
            failureRateThreshold = 50
            minimumRequiredCalls = 10
            waitDurationInOpenState = "25s"
            permittedCallsInHalfOpenState = 15
            timeBased {
                windowDuration = "10s" //(1)!
                sampleCount = 16 //(2)!
                counterStripes = 16 //(3)!
                counterType = ATOMIC //(4)!
            }
        }
    }
}

resilient:
  circuitbreaker:
    custom:
      type: TIME_BASED
      failureRateThreshold: 50
      minimumRequiredCalls: 10
      waitDurationInOpenState: "25s"
      permittedCallsInHalfOpenState: 15
      timeBased:
        windowDuration: "10s" #(1)!
        sampleCount: 16 #(2)!
        counterStripes: 16 #(3)!
        counterType: ATOMIC #(4)!

Фильтрация исключений¶

По умолчанию CircuitBreaker считает отказом любую ошибку, кроме исключений, реализующих интерфейс-маркер NonCircuitableException. Пометить им собственный тип исключения — самый простой способ не пускать ожидаемую бизнес-ошибку в статистику прерывателя, а тот же тип может реализовать и NonRetryableException, чтобы не попадать под Retry:

public final class InvalidPetException extends RuntimeException
    implements NonCircuitableException, NonRetryableException { //(1)!

    public InvalidPetException(String message) {
        super(message);
    }
}

class InvalidPetException(message: String) : RuntimeException(message),
    NonCircuitableException, NonRetryableException //(1)!

Если решение нельзя выразить через тип исключения, изменить поведение по умолчанию можно двумя способами.

Первый — переопределить isFailure прямо в интерфейсе-спецификации: без отдельного компонента и без конфигурации:

@CircuitBreakerSpec("resilient.circuitbreaker.custom")
public interface CustomCircuitBreaker extends CircuitBreaker {

    @Override
    default boolean isFailure(Throwable throwable) {
        return !(throwable instanceof HttpServerResponseException e) || e.code() >= 500;
    }
}

@CircuitBreakerSpec("resilient.circuitbreaker.custom")
interface CustomCircuitBreaker : CircuitBreaker {

    override fun isFailure(throwable: Throwable): Boolean =
        throwable !is HttpServerResponseException || throwable.code() >= 500
}

Второй способ — компонент CircuitBreakerPredicate, привязанный к спецификации через @Tag. Он имеет приоритет над isFailure и подходит, когда самому фильтру нужны зависимости:

@Tag(CustomCircuitBreaker.class) //(1)!
@Component
public final class MyFailurePredicate implements CircuitBreakerPredicate {

    @Override
    public boolean isCircuitBreakerFailure(Throwable throwable) { //(2)!
        return !(throwable instanceof HttpServerResponseException e) || e.code() >= 500;
    }
}

@Tag(CustomCircuitBreaker::class) //(1)!
@Component
class MyFailurePredicate : CircuitBreakerPredicate {

    override fun isCircuitBreakerFailure(throwable: Throwable): Boolean = //(2)!
        throwable !is HttpServerResponseException || throwable.code() >= 500
}

Исключение, отклонённое фильтром, не засчитывается ни как отказ, ни как успех: circuit breaker его просто игнорирует, а вызывающему коду оно возвращается без изменений.

Императивное использование¶

Интерфейс спецификации — обычный компонент графа приложения, поэтому в императивном коде его достаточно внедрить напрямую:

@Component
public final class SomeService {

    private final CustomCircuitBreaker circuitBreaker;

    public SomeService(CustomCircuitBreaker circuitBreaker) {
        this.circuitBreaker = circuitBreaker;
    }

    public String doWork() {
        return circuitBreaker.accept(this::doSomeWork);
    }

    private String doSomeWork() {
        // do some work
    }
}

@Component
class SomeService(private val circuitBreaker: CustomCircuitBreaker) {

    fun doWork(): String {
        return circuitBreaker.accept(ThrowableCallable { doSomeWork() })
    }

    private fun doSomeWork(): String {
        // do some work
    }
}

Методы accept принимают ThrowableCallable<T, E> или ThrowableRunnable<E> из пакета io.koraframework.resilient.common, поэтому защищаемый код может бросать проверяемые исключения.

Чтобы в состоянии OPEN вернуть резервное значение вместо CallNotPermittedException, используйте перегрузку accept со вторым аргументом:

public String doWork() {
    return circuitBreaker.accept(this::doSomeWork, () -> "fallback");
}

fun doWork(): String {
    return circuitBreaker.accept(ThrowableCallable { doSomeWork() }, ThrowableCallable { "fallback" })
}

Если защищаемый вызов не удаётся обернуть в один callable, разрешение можно получать и освобождать вручную. Вызовите acquire() (бросает CallNotPermittedException, когда состояние OPEN либо HALF_OPEN и все пробные вызовы уже израсходованы), а затем обязательно сообщите результат через releaseOnSuccess() или releaseOnError(Throwable) — иначе разрешение утечёт и учёт вызовов станет неверным:

public String doWork() {
    circuitBreaker.acquire(); // throws CallNotPermittedException when the call is not permitted
    try {
        var result = doSomeWork();
        circuitBreaker.releaseOnSuccess();
        return result;
    } catch (Throwable e) {
        circuitBreaker.releaseOnError(e);
        throw e;
    }
}

fun doWork(): String {
    circuitBreaker.acquire() // throws CallNotPermittedException when the call is not permitted
    try {
        val result = doSomeWork()
        circuitBreaker.releaseOnSuccess()
        return result
    } catch (e: Throwable) {
        circuitBreaker.releaseOnError(e)
        throw e
    }
}

tryAcquire() — вариант без исключения: он возвращает false, когда вызов не разрешён, и позволяет ветвиться без перехвата CallNotPermittedException. Если же acquire() бросил исключение, текущее состояние (OPEN или HALF_OPEN) доступно через CallNotPermittedException#state().

Retry¶

Retry даёт возможность настроить повторные вызовы аннотированных методов. Он позволяет указать, когда метод следует повторить, и настроить параметры повторов, если метод бросает исключение, подходящее под настроенный фильтр.

Декларативное использование¶

Когда все попытки исчерпаны, вызов завершается исключением RetryExhaustedException.

@RetrySpec("resilient.retry.custom")
public interface CustomRetry extends Retry { }

@Component
public class SomeService {

    @Retryable(CustomRetry.class)
    public String getValue() {
        throw new IllegalStateException("Ops");
    }
}

@RetrySpec("resilient.retry.custom")
interface CustomRetry : Retry

@Component
open class SomeService {

    @Retryable(CustomRetry::class)
    open fun execute(arg: String): Unit = throw IllegalStateException("Ops")
}

Конфигурация¶

Секция, на которую указывает @RetrySpec, описана в классе RetryConfig:

resilient {
    retry {
        custom {
            delay = "100ms" //(1)!
            attempts = 2 //(2)!
            delayStep = "100ms" //(3)!
            enabled = true //(4)!
        }
    }
}

resilient:
  retry:
    custom:
      delay: "100ms" #(1)!
      attempts: 2 #(2)!
      delayStep: "100ms" #(3)!
      enabled: true #(4)!

Необязательные секции backoff, jitter и retryBudget описаны в разделах Backoff и jitter и Бюджет повторов, а ключ telemetry переопределяет настройки из раздела Телеметрия.

Backoff и jitter¶

Секция backoff заменяет линейный рост delayStep на экспоненциальный, а jitter разводит задержки параллельных вызовов, чтобы они не повторяли запрос синхронно:

resilient {
    retry {
        custom {
            delay = "100ms"
            attempts = 4
            backoff {
                type = EXPONENTIAL //(1)!
                multiplier = 2.0 //(2)!
                delayMax = "5s" //(3)!
            }
            jitter {
                type = FULL //(4)!
                ratio = 1.0 //(5)!
            }
        }
    }
}

resilient:
  retry:
    custom:
      delay: "100ms"
      attempts: 4
      backoff:
        type: EXPONENTIAL #(1)!
        multiplier: 2.0 #(2)!
        delayMax: "5s" #(3)!
      jitter:
        type: FULL #(4)!
        ratio: 1.0 #(5)!

С приведёнными настройками вычисленная задержка для попытки n равна delay * multiplier^(n-1) и ограничена сверху delayMax: 100ms, 200ms, 400ms, 800ms. Затем jitter выбирает фактическую задержку равномерно из отрезка [computed - computed * ratio, computed], поэтому ratio = 1.0 означает любое значение от 0 до вычисленной задержки.

Бюджет повторов¶

Бюджет повторов ограничивает, сколько дополнительной нагрузки могут создать повторы. Это ведро токенов: каждый повтор забирает один токен, каждый успешный вызов возвращает ratio токенов, а когда ведро пусто, повтор запрещается и исходное исключение пробрасывается как есть — без ожидания и без RetryExhaustedException.

resilient {
    retry {
        custom {
            delay = "100ms"
            attempts = 3
            retryBudget {
                enabled = true //(1)!
                ratio = 0.1 //(2)!
                tokensMax = 100 //(3)!
                tokensInitial = 10 //(4)!
                minTokensPerSecond = 0.0 //(5)!
            }
        }
    }
}

resilient:
  retry:
    custom:
      delay: "100ms"
      attempts: 3
      retryBudget:
        enabled: true #(1)!
        ratio: 0.1 #(2)!
        tokensMax: 100 #(3)!
        tokensInitial: 10 #(4)!
        minTokensPerSecond: 0.0 #(5)!

Собственный и распределённый бюджет¶

Сам бюджет — это RetryBudget (tryAcquireRetryToken(), onSuccess(), availableTokens()), и каждая спецификация повтора получает свой экземпляр от компонента RetryBudgetFactory через get(name, config), где name — простое имя интерфейса-спецификации, а config — её RetryConfig. Если фабрика возвращает null, повтор работает без бюджета. RetryModule регистрирует DefaultRetryBudgetFactory, которая строит хранящийся в памяти KoraRetryBudget из секции retryBudget, поэтому по умолчанию у каждого экземпляра приложения своя корзина.

Фабрика заменяется обычным способом: компонент RetryBudgetFactory без тега переопределяет фабрику по умолчанию для всех повторов, а фабрика с тегом спецификации, @Tag(PetRetry.class), используется только для этого повтора и имеет приоритет над фабрикой без тега.

DistributedRetryBudgetFactory из распределённого модуля хранит один баланс токенов на спецификацию в Redis, поэтому бюджет ограничивает повторы всех экземпляров вместе. Автоматически она не регистрируется:

@KoraApp
public interface Application extends ResilientModule, LettuceDistributedResilientModule {

    default RetryBudgetFactory distributedRetryBudgetFactory(DistributedRetryBudgetClient client) { //(1)!
        return new DistributedRetryBudgetFactory(client);
    }

    @Tag(PetRetry.class) //(2)!
    default RetryBudgetFactory petRetryBudgetFactory(DistributedRetryBudgetClient client) {
        return new DistributedRetryBudgetFactory(client, "pets:retrybudget", Duration.ofMinutes(30)); //(3)!
    }
}

@KoraApp
interface Application : ResilientModule, LettuceDistributedResilientModule {

    fun distributedRetryBudgetFactory(client: DistributedRetryBudgetClient): RetryBudgetFactory = //(1)!
        DistributedRetryBudgetFactory(client)

    @Tag(PetRetry::class) //(2)!
    fun petRetryBudgetFactory(client: DistributedRetryBudgetClient): RetryBudgetFactory =
        DistributedRetryBudgetFactory(client, "pets:retrybudget", Duration.ofMinutes(30)) //(3)!
}

Баланс хранится под ключом <keyPrefix>:<простое имя спецификации>, и каждое изменение продлевает срок жизни ключа, поэтому неиспользуемый бюджет исчезает из Redis и начинается заново с tokensInitial. Сервисы, работающие с одним Redis и использующие спецификации с одинаковым простым именем, делят один баланс, если их префиксы ключей не различаются.

Фильтрация исключений¶

По умолчанию Retry повторяет вызов при любой ошибке, кроме исключений, реализующих интерфейс-маркер NonRetryableException (см. пример в разделе circuit breaker). Два способа сузить это дальше повторяют подход circuit breaker: переопределить isFailure в спецификации либо зарегистрировать компонент RetryPredicate с тегом спецификации. Если есть оба, побеждает компонент с тегом, и любой из них заменяет проверку NonRetryableException по умолчанию.

@RetrySpec("resilient.retry.custom")
public interface CustomRetry extends Retry {

    @Override
    default boolean isFailure(Throwable throwable) {
        return throwable instanceof IOException;
    }
}

@Tag(CustomRetry.class)
@Component
public final class MyRetryPredicate implements RetryPredicate {

    @Override
    public boolean isRetryFailure(Throwable throwable) {
        return throwable instanceof IOException;
    }
}

@RetrySpec("resilient.retry.custom")
interface CustomRetry : Retry {

    override fun isFailure(throwable: Throwable): Boolean = throwable is IOException
}

@Tag(CustomRetry::class)
@Component
class MyRetryPredicate : RetryPredicate {

    override fun isRetryFailure(throwable: Throwable): Boolean = throwable is IOException
}

Исключение, отклонённое фильтром, пробрасывается сразу — без дальнейших попыток и без оборачивания в RetryExhaustedException.

Императивное использование¶

Внедрите интерфейс спецификации и вызывайте его напрямую:

@Component
public final class SomeService {

    private final CustomRetry retry;

    public SomeService(CustomRetry retry) {
        this.retry = retry;
    }

    public String doWork() {
        return retry.retry(this::doSomeWork);
    }

    private String doSomeWork() {
        // do some work
    }
}

@Component
class SomeService(private val retry: CustomRetry) {

    fun doWork(): String {
        return retry.retry(ThrowableCallable { doSomeWork() })
    }

    private fun doSomeWork(): String {
        // do some work
    }
}

Чтобы после исчерпания всех попыток вернуть резервное значение вместо RetryExhaustedException, передайте второй callable:

return retry.retry(this::doSomeWork, () -> "fallback");

return retry.retry(ThrowableCallable { doSomeWork() }, ThrowableCallable { "fallback" })

Для асинхронного императивного кода есть перегрузка, которая повторяет Supplier<CompletionStage<T>> и возвращает CompletionStage<T>, планируя каждую попытку после настроенной задержки и не блокируя вызывающий поток.

Ручное управление состоянием повтора¶

Для полного контроля над циклом повторов используйте retry.asState(), возвращающий Retry.RetryState. Он реализует AutoCloseable, поэтому оборачивайте его в try-with-resources (Java) или use (Kotlin), чтобы метрики записались по завершении. На каждое пойманное исключение вызывайте onException(Throwable), который возвращает RetryStatus:

• ACCEPTED — очередная попытка разрешена; вызовите doDelay() (блокирует на текущую задержку) и повторите вызов.
• REJECTED — исключение отклонено фильтром либо бюджет повторов исчерпан, повторять нельзя; пробросьте его дальше.
• EXHAUSTED — все попытки израсходованы; бросьте RetryExhaustedException (или верните значение по умолчанию).

getAttempts() / getAttemptsMax() показывают прогресс, а getDelayNanos() возвращает следующую задержку.

public String doWork() {
    try (var state = retry.asState()) {
        while (true) {
            try {
                return doSomeWork();
            } catch (Exception e) {
                switch (state.onException(e)) {
                    case ACCEPTED -> state.doDelay();   // wait, then loop and retry
                    case REJECTED -> throw e;           // not retryable
                    case EXHAUSTED -> throw new RetryExhaustedException("custom", state.getAttemptsMax(), e);
                }
            }
        }
    }
}

fun doWork(): String {
    retry.asState().use { state ->
        while (true) {
            try {
                return doSomeWork()
            } catch (e: Exception) {
                when (state.onException(e)) {
                    Retry.RetryState.RetryStatus.ACCEPTED -> state.doDelay()   // wait, then loop and retry
                    Retry.RetryState.RetryStatus.REJECTED -> throw e           // not retryable
                    Retry.RetryState.RetryStatus.EXHAUSTED -> throw RetryExhaustedException("custom", state.attemptsMax, e)
                }
            }
        }
    }
}

Timeout¶

Timeout задаёт максимальное время выполнения аннотированного метода. Синхронные методы выполняются на виртуальном потоке и прерываются по достижении лимита, а для Kotlin suspend-функций корутина отменяется через withTimeout.

Декларативное использование¶

Если метод не завершается в пределах duration, вызов падает с TimeoutExhaustedException.

@TimeoutSpec("resilient.timeout.custom")
public interface CustomTimeouter extends Timeouter { }

@Component
public class SomeService {

    @Timeout(CustomTimeouter.class)
    public String getValue() {
        try {
            Thread.sleep(3000);
            return "OK";
        } catch (InterruptedException e) {
            throw new IllegalStateException(e);
        }
    }
}

@TimeoutSpec("resilient.timeout.custom")
interface CustomTimeouter : Timeouter

@Component
open class SomeService {

    @Timeout(CustomTimeouter::class)
    open fun value(): String = try {
        Thread.sleep(3000)
        "OK"
    } catch (e: InterruptedException) {
        throw IllegalStateException(e)
    }
}

Конфигурация¶

Секция, на которую указывает @TimeoutSpec, описана в классе TimeoutConfig:

resilient {
    timeout {
        custom {
            duration = "1s" //(1)!
            enabled = true //(2)!
        }
    }
}

resilient:
  timeout:
    custom:
      duration: "1s" #(1)!
      enabled: true #(2)!

Ключ telemetry внутри той же секции переопределяет общемодульные настройки из раздела Телеметрия.

Императивное использование¶

Внедрите интерфейс спецификации и вызывайте его напрямую:

@Component
public final class SomeService {

    private final CustomTimeouter timeouter;

    public SomeService(CustomTimeouter timeouter) {
        this.timeouter = timeouter;
    }

    public String doWork() {
        return timeouter.execute(this::doSomeWork);
    }

    private String doSomeWork() {
        // do some work
    }
}

@Component
class SomeService(private val timeouter: CustomTimeouter) {

    fun doWork(): String {
        return timeouter.execute(ThrowableCallable { doSomeWork() })
    }

    private fun doSomeWork(): String {
        // do some work
    }
}

У Timeouter также есть перегрузка execute для операций, ничего не возвращающих, а timeout() возвращает настроенный Duration:

Duration limit = timeouter.timeout();  // configured duration
timeouter.execute(this::cleanup);      // void operation, throws TimeoutExhaustedException on timeout

val limit: Duration = timeouter.timeout()           // configured duration
timeouter.execute(ThrowableRunnable { cleanup() })  // void operation, throws TimeoutExhaustedException on timeout

RateLimiter¶

RateLimiter ограничивает, сколько раз метод может быть вызван за период: limitForPeriod разрешений на limitRefreshPeriod. Способ выдачи разрешений определяет алгоритм, по умолчанию это token bucket. Получение разрешения никогда не блокирует — вызов, для которого нет доступного разрешения, сразу падает с RateLimitExceededException.

Декларативное использование¶

@RateLimiterSpec("resilient.ratelimiter.custom")
public interface CustomRateLimiter extends RateLimiter { }

@Component
public class SomeService {

    @RateLimited(CustomRateLimiter.class)
    public String getValue() {
        return "OK";
    }
}

@RateLimiterSpec("resilient.ratelimiter.custom")
interface CustomRateLimiter : RateLimiter

@Component
open class SomeService {

    @RateLimited(CustomRateLimiter::class)
    open fun value(): String = "OK"
}

Конфигурация¶

Секция, на которую указывает @RateLimiterSpec, описана в классе RateLimiterConfig:

resilient {
    ratelimiter {
        custom {
            limitForPeriod = 100 //(1)!
            limitRefreshPeriod = "1s" //(2)!
            type = TOKEN_BUCKET //(3)!
            enabled = true //(4)!
        }
    }
}

resilient:
  ratelimiter:
    custom:
      limitForPeriod: 100 #(1)!
      limitRefreshPeriod: "1s" #(2)!
      type: TOKEN_BUCKET #(3)!
      enabled: true #(4)!

Ключ telemetry внутри той же секции переопределяет общемодульные настройки из раздела Телеметрия.

Алгоритмы¶

Ключ type выбирает одну из двух неблокирующих реализаций, каждая из которых хранит всё состояние в одном атомарном значении:

FIXED_WINDOW упаковывает счётчик в 24 бита, поэтому его limitForPeriod должен быть меньше 16777216.

Императивное использование¶

Внедрите интерфейс спецификации и вызывайте его напрямую:

@Component
public final class SomeService {

    private final CustomRateLimiter rateLimiter;

    public SomeService(CustomRateLimiter rateLimiter) {
        this.rateLimiter = rateLimiter;
    }

    public String doWork() {
        return rateLimiter.execute(this::doSomeWork); //(1)!
    }

    public boolean doWorkIfPermitted() {
        if (!rateLimiter.tryAcquire()) { //(2)!
            return false;
        }
        doSomeWork();
        return true;
    }

    private String doSomeWork() {
        // do some work
    }
}

@Component
class SomeService(private val rateLimiter: CustomRateLimiter) {

    fun doWork(): String {
        return rateLimiter.execute(ThrowableCallable { doSomeWork() }) //(1)!
    }

    fun doWorkIfPermitted(): Boolean {
        if (!rateLimiter.tryAcquire()) { //(2)!
            return false
        }
        doSomeWork()
        return true
    }

    private fun doSomeWork(): String {
        // do some work
    }
}

acquire() забирает разрешение, ничего не выполняя, и бросает RateLimitExceededException, когда разрешений не осталось.

Распределённый rate limiter¶

Локальный ограничитель считает только вызовы своего экземпляра. Когда лимит относится ко всему сервису — например, квота API партнёра, — объявите спецификацию через @RateLimiterDistributedSpec вместо @RateLimiterSpec: тогда лимит соблюдается через Redis для всех экземпляров вместе. Распределённый модуль должен быть подключён.

@RateLimiterDistributedSpec("resilient.ratelimiter.partner") //(1)!
public interface PartnerRateLimiter extends RateLimiter { }

@Component
public class PartnerService {

    @RateLimited(PartnerRateLimiter.class) //(2)!
    public String getValue() {
        return "OK";
    }
}

@RateLimiterDistributedSpec("resilient.ratelimiter.partner") //(1)!
interface PartnerRateLimiter : RateLimiter

@Component
open class PartnerService {

    @RateLimited(PartnerRateLimiter::class) //(2)!
    open fun value(): String = "OK"
}

Секция описана классом DistributedRateLimiterConfig:

resilient {
    ratelimiter {
        partner {
            limitForPeriod = 100 //(1)!
            limitRefreshPeriod = "1s" //(2)!
            keyPrefix = "pets" //(3)!
            algorithm = TOKEN_BUCKET //(4)!
            enabled = true //(5)!
        }
    }
}

resilient:
  ratelimiter:
    partner:
      limitForPeriod: 100 #(1)!
      limitRefreshPeriod: "1s" #(2)!
      keyPrefix: "pets" #(3)!
      algorithm: TOKEN_BUCKET #(4)!
      enabled: true #(5)!

Ключ telemetry и настройки resilient.telemetry.rateLimiter действуют так же, как для локального ограничителя.

Как это работает:

• Сгенерированная реализация наследует KoraDistributedRateLimiter и требует DistributedRateLimiterClient в графе; его предоставляет LettuceDistributedResilientModule.
• Состояние ограничителя хранится под ключом <keyPrefix>:<простое имя спецификации>. FIXED_WINDOW использует отдельный ключ на каждое окно, <keyPrefix>:<простое имя спецификации>:<номер окна>, причём окна выровнены по системным часам, а не по моменту запуска приложения. Ключи истекают сами, когда становятся не нужны.
• TOKEN_BUCKET берёт текущее время из системных часов вызывающего экземпляра, поэтому расхождение часов между экземплярами делает лимит приблизительным. Он также немного приблизителен сразу после простоя и точен в установившемся режиме.
• Каждое разрешение стоит синхронных команд Redis, то есть добавляет к защищаемому вызову сетевой обмен. Ошибка Redis не подавляется: она выходит из @RateLimited к вызывающему коду.

Fallback¶

Fallback указывает метод, который будет вызван при сбое аннотированного метода. В отличие от остальных механизмов у него нет ни интерфейса-спецификации, ни собственной секции конфигурации: весь контракт — это сам резервный метод.

Резервный метод обязан совпадать по типу возвращаемого значения с аннотированным методом и должен быть объявлен в том же классе.

Декларативное использование¶

Пример резервного метода без аргументов:

@Component
public class SomeService {

    @Fallback(method = "getFallback()")
    public String getValue() {
        return "value";
    }

    protected String getFallback() {
        return "fallback";
    }
}

@Component
open class SomeService {

    @Fallback(method = "getFallback()")
    open fun value(): String = "value"

    fun getFallback(): String = "fallback"
}

Пример Fallback с аргументами:

@Component
public class SomeService {

    @Fallback(method = "getFallback(arg3, arg1)")     // Passes the arguments of the annotated method in the specified order to the Fallback method
    public String getValue(String arg1, Integer arg2, Long arg3) {
        return "value";
    }

    protected String getFallback(Long argLong, String argString) {
        return "fallback";
    }
}

@Component
open class SomeService {

    // Passes the arguments of the annotated method in the specified order to the Fallback method
    @Fallback(method = "getFallback(arg3, arg1)")
    open fun getValue(arg1: String, arg2: Int, arg3: Long): String = "value"

    fun getFallback(argLong: Long, argString: String): String = "fallback"
}

Ссылка проверяется на этапе компиляции. Типичные ошибки:

• @Fallback method reference '…' has invalid syntax — значение должно иметь вид name() или name(arg1, arg2).
• @Fallback method reference '…' uses unknown source arguments — указан аргумент, которого нет у аннотированного метода.
• @Fallback method '…' was not found — метода с таким именем нет в том же классе.
• @Fallback method '…' does not match requested signature — резервный метод должен принимать ровно перечисленные аргументы плюс необязательный параметр @Fallback.Reason.

Фильтрация исключений¶

По умолчанию резервный метод вызывается на любой Throwable. Единственный параметр @Fallback.Reason в резервном методе одновременно передаёт вызвавшее фолбэк исключение и сужает условие срабатывания: исключение, не являющееся экземпляром объявленного типа параметра, пробрасывается дальше, а резервный метод не вызывается.

@Component
public class SomeService {

    @Fallback(method = "getFallback()")
    public String getValue() {
        throw new IllegalStateException("Ops");
    }

    protected String getFallback(@Fallback.Reason RuntimeException reason) { //(1)!
        return "fallback: " + reason.getMessage();
    }
}

@Component
open class SomeService {

    @Fallback(method = "getFallback()")
    open fun value(): String = throw IllegalStateException("Ops")

    fun getFallback(@Fallback.Reason reason: RuntimeException): String = //(1)!
        "fallback: " + reason.message
}

В Java тип параметра должен соответствовать тому, что может бросить аннотированный метод: RuntimeException, если у него нет throws, Exception, если объявлены проверяемые исключения, и Throwable, если объявлено throws Throwable. Более узкий тип приводит к ошибке компиляции, поэтому для более тонкой фильтрации используйте обычную проверку instanceof внутри резервного метода.

Телеметрия¶

Логирование, метрики и трассировка настраиваются отдельно для каждого механизма в секции resilient.telemetry, а любая спецификация может переопределить общемодульные значения ключом telemetry внутри своей секции конфигурации:

resilient {
    telemetry {
        circuitBreaker { //(1)!
            logging.enabled = false //(2)!
            metrics {
                enabled = false //(3)!
                tags { "service" = "pets" } //(4)!
            }
            tracing {
                enabled = false //(5)!
                attributes { "component" = "resilient" } //(6)!
            }
        }
        retry {}
        timeout {}
        fallback {}
        rateLimiter {}
    }
    circuitbreaker {
        custom {
            telemetry.metrics.enabled = true //(7)!
        }
    }
}

resilient:
  telemetry:
    circuitBreaker: #(1)!
      logging:
        enabled: false #(2)!
      metrics:
        enabled: false #(3)!
        tags:
          service: "pets" #(4)!
      tracing:
        enabled: false #(5)!
        attributes:
          component: "resilient" #(6)!
    retry: {}
    timeout: {}
    fallback: {}
    rateLimiter: {}
  circuitbreaker:
    custom:
      telemetry:
        metrics:
          enabled: true #(7)!

Весь блок resilient.telemetry необязателен — если его не указывать, все механизмы получат перечисленные значения по умолчанию. Имена метрик перечислены в разделе Справочник метрик.

Комбинирование¶

Все перечисленные аннотации можно комбинировать одновременно над одним методом.

Порядок применения аннотаций зависит от порядка их объявления. Порядок можно менять как угодно и сочетать с другими аннотациями, которые также применяются в порядке объявления.

@Component
public class SomeService {

    @Fallback(method = "getFallback(arg1)")           // 4
    @CircuitBreakable(CustomCircuitBreaker.class)     // 3
    @Retryable(CustomRetry.class)                     // 2
    @Timeout(CustomTimeouter.class)                   // 1
    public String getValueSync(String arg1) {
        return "result-" + arg1;
    }

    protected String getFallback(String arg1) {       // 4
        return "fallback-" + arg1;
    }
}

@Component
open class SomeService {

    @Fallback(method = "getFallback(arg1)")             // 4
    @CircuitBreakable(CustomCircuitBreaker::class)      // 3
    @Retryable(CustomRetry::class)                      // 2
    @Timeout(CustomTimeouter::class)                    // 1
    open fun getValueSync(arg1: String): String = "result-$arg1"

    protected fun getFallback(arg1: String): String = "fallback-$arg1"  // 4
}

В примере выше:

1. Применяется @Timeout и проверяет, что метод не выполняется дольше указанного в конфигурации времени.
2. Применяется @Retryable и повторяет выполнение метода настроенное число раз, если в цепочке возникло исключение, в том числе исключение от @Timeout.
3. Применяется @CircuitBreakable и работает согласно своей конфигурации и состоянию, в зависимости от успешного результата метода или исключения в цепочке, включая исключения от @Timeout и @Retryable.
4. Применяется @Fallback и вызывает метод getFallback с аргументом arg1, если в цепочке возникло исключение, включая исключения от @Timeout, @Retryable и @CircuitBreakable.

Порядок вызова аспектов соответствует порядку аннотаций на методе: сверху вниз, то есть самая верхняя аннотация — самая внешняя обёртка. @RateLimited встраивается в ту же цепочку и обычно ставится выше @CircuitBreakable, чтобы отклонённые вызовы вообще не доходили до circuit breaker.

Пример конфигурации для всех аспектов:

resilient {
    circuitbreaker {
        custom {
            type = FIXED_WINDOW
            countBased.windowSize = 1
            minimumRequiredCalls = 1
            failureRateThreshold = 100
            permittedCallsInHalfOpenState = 1
            waitDurationInOpenState = "1s"
        }
    }
    timeout {
        custom {
            duration = "300ms"
        }
    }
    retry {
        custom {
            delay = "100ms"
            attempts = 2
        }
    }
    ratelimiter {
        custom {
            limitForPeriod = 100
            limitRefreshPeriod = "1s"
        }
    }
}

resilient:
  circuitbreaker:
    custom:
      type: FIXED_WINDOW
      countBased:
        windowSize: 1
      minimumRequiredCalls: 1
      failureRateThreshold: 100
      permittedCallsInHalfOpenState: 1
      waitDurationInOpenState: "1s"
  timeout:
    custom:
      duration: "300ms"
  retry:
    custom:
      delay: "100ms"
      attempts: 2
  ratelimiter:
    custom:
      limitForPeriod: 100
      limitRefreshPeriod: "1s"

Порядок политик на практике¶

При явных вызовах API порядок применения механизмов виден непосредственно в коде: