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.
• Introspectable retry state for logging using RetryStatus.
• Support resetting the retry state when the action is long-running and an attempt works.

API

import Control.Exception (Exception, Handler)
import Control.Monad.IO.Class (MonadIO)
import Data.Time.Clock (DiffTime)

defaults :: RetrySettings

data RetryStatus = RetryStatus
  { attempts :: Int,
    delay :: DiffTime,
    totalDelay :: DiffTime,
    reset :: IO ()
  }

-- Retry on all sync exceptions
retry :: MonadIO m 
      => RetrySettings 
      -> (RetryStatus -> m a)
      -> m a

-- Retry on specific exceptions
retryOnExceptions :: (Exception e, MonadIO m) 
                  => RetrySettings 
                  -> [Handler RetryAction] 
                  -> (RetryStatus -> m a)
                  -> m a

data RetryAction = 
   Skip -- Propagate the exception.
 | Retry  -- Retry with the delay according to the settings.
 | RetryDelay DiffTime -- Retry after the given delay.

Example

import qualified Stamina

main :: IO ()
main = do
    Stamina.retry Stamina.defaults $ \retryStatus -> do
        ... monadic logic that raises exceptions

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.