stamina.hs/README.md

Stamina

A retry Haskell library for humans:

• Exponential backoff with jitter between retries.
• Limit the attempts of retries and total time.
• Stamina.HTTP for retrying retriable Network.HTTP.Client exceptions respecting Retry-After headers.
• Introspectable retry state for logging using RetryStatus, including the last exception that occurred.
• Support resetting the retry state when for long-running tasks with an attempt that works.

API

Basics

• Stamina.defaults :: (MonadIO m) => m RetrySettings
• Stamina.RetryStatus = RetryStatus { attempts :: Int, delay :: NominalDiffTime, totalDelay :: NominalDiffTime, resetInitial :: IO (), lastException :: Maybe SomeException }
• Stamina.retry :: (MonadCatch m, MonadIO m) => RetrySettings -> (RetryStatus -> m a) -> m a

Exceptions

• Stamina.RetryAction = RaiseException | Retry | RetryDelay NominalDiffTime | RetryTime UTCTime
• Stamina.retryFor :: (MonadCatch m, MonadIO m, Exception exc) => RetrySettings -> (exc -> m RetryAction) -> (RetryStatus -> m a) -> m a

HTTP

• Stamina.HTTP.retry :: (MonadIO m, MonadCatch m) => Stamina.RetrySettings -> (Stamina.RetryStatus -> m a) -> m a

Basic example

import qualified Stamina
import Control.Monad.Catch (throwM)
import Control.Monad.IO.Class (MonadIO)

go :: IO ()
go = Stamina.retry Stamina.defaults $ \retryStatus -> do
  throwM $ userError "nope"

Example to catch specific exceptions

handler :: (MonadIO m) => IOError -> m Stamina.RetryAction
handler _ = return Stamina.Retry

go2 :: IO ()
go2 = Stamina.retryFor Stamina.defaults handler $ \retryStatus -> do
  throwM $ userError "nope"

Development

1. Install devenv.sh.

2. devenv shell

3. stack build

Credits

• Heavily inspired by stamina for Python.
• retry as case study for what needs to be supported.

Test setup

main = undefined