stamina: Retries for humans

[ apache, control, library, program ] [ Propose Tags ]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.0.0, 0.1.0.1, 0.1.0.2, 0.1.0.3
Change log CHANGELOG.md
Dependencies base (>=4.2 && <5), exceptions, http-client, http-types, random, stamina, time [details]
License Apache-2.0
Author Domen Kožar
Maintainer domen@cachix.org
Category Control
Home page https://github.com/cachix/stamina.hs
Uploaded by domenkozar at 2024-01-26T20:56:21Z
Distributions NixOS:0.1.0.3, Stackage:0.1.0.3
Executables readme
Downloads 142 total (18 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs uploaded by user [build log]
All reported builds failed as of 2024-01-26 [all 2 reports]

Readme for stamina-0.1.0.3

[back to package description]

Stamina

Active – The project has reached a stable, usable state and is being actively developed. Hackage CI status

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

Test setup
main = undefined