--- title: "Choosing and stacking decorators" output: litedown::html_format vignette: > %\VignetteIndexEntry{Choosing and stacking decorators} %\VignetteEngine{litedown::vignette} %\VignetteEncoding{UTF-8} --- ```{r setup} library(fnware) ``` ## Which decorator do I want? | The problem | Decorator | Guide | |---|---|---| | A call fails now and then | `retry()` | `vignette("retry")` | | A call hangs | `timeout()` | `vignette("retry")` | | A service is down and callers keep waiting on it | `circuit_breaker()` | `vignette("circuitbreaker")` | | An API allows only so many calls | `rate_limit()` | `?rate_limit` | | A failure should become a default value | `fallback()` | `vignette("fallback")` | | A result is slow to compute and gets asked for again | `lru_cache()`, `cache`, `disk_cache()` | `vignette("caching")` | | Setup should happen a single time | `once` | `vignette("fallback")` | | You want to see what is being called | `log_call()` | `vignette("logging")` | | Bad input or output should be caught early | `validate_args()`, `validate_return()` | `vignette("validation")` | | Setup and teardown around a resource | `contextmanager` | `vignette("contextmanager")` | For a function that returns a promise, every decorator above except `contextmanager` has an `async_` version. See `vignette("async")`. ## Stacking order Decorators stack, and in `a %@% b %@% f`, `a` is outermost. The order changes what each one sees. This is the order that works for the common cases, from outside to inside: ``` validate_args() reject bad input before doing any work fallback() use a default only once everything below has given up circuit_breaker() fail fast when the service is clearly down cache / lru_cache() skip the work for a repeated call retry() try again when a call fails rate_limit() throttle every attempt, retries included timeout() cap each attempt log_call() log the call itself ``` You will rarely need all of them. Skip the ones you do not need and keep the rest in this order. ```{r stack} n <- 0 fetch := validate_args(url = is.character) %@% fallback(value = NA_character_) %@% retry(stop = stop_after_attempt(3)) %@% function(url) { n <<- n + 1 if (n < 3) stop("not yet") paste("response from", url) } fetch("example.com") ``` The reasons behind the order: - **`validate_args()` outermost.** A bad argument is the caller's mistake. Retrying or caching it only repeats the mistake. - **`fallback()` outside `retry()` and `circuit_breaker()`.** The default is used once retries are spent or the circuit is open, not after the first failure. - **`circuit_breaker()` outside `retry()`.** An open circuit rejects the call before any retries happen. - **`rate_limit()` and `timeout()` inside `retry()`.** Each attempt is then throttled and capped. Outside it, only whole calls would be, and retries could still exceed the limit or run without one. Put the caches where you want them to sit. Outside `retry()`, a successful result is cached once. Because only a returned value is stored, an error is never cached.