mirror of
https://github.com/cachix/stamina.hs.git
synced 2024-09-11 18:37:48 +03:00
add HTTP and example/api docs
This commit is contained in:
parent
62b70008f2
commit
b9c3b23cef
44
README.md
44
README.md
@ -1,14 +1,49 @@
|
||||
# Stamina.hs
|
||||
|
||||
**WIP: doesn't work yet, in design phase.**
|
||||
|
||||
[![Hackage](https://img.shields.io/hackage/v/stamina.svg?style=flat)](https://hackage.haskell.org/package/stamina) ![CI status](https://github.com/cachix/stamina.hs/actions/workflows/ci.yml/badge.svg)
|
||||
|
||||
A retry Haskell library for humans:
|
||||
|
||||
- Exponential backoff with jitter between retries.
|
||||
- Limit the number of retries and total time.
|
||||
- `Stamina.HTTP` for retrying retriable HTTP Exceptions
|
||||
- Introspectable retry state for logging
|
||||
|
||||
## Design goals
|
||||
|
||||
- Defaults that make sense most of the time.
|
||||
- Simple interface.
|
||||
- Documented.
|
||||
|
||||
Heavily inspired by [stamina for Python](https://stamina.hynek.me/en/stable/tutorial.html#retries).
|
||||
## API
|
||||
|
||||
```haskell
|
||||
|
||||
defaultRetrySettings :: RetrySettings
|
||||
|
||||
-- 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 | Retry | RetryAfter Int
|
||||
```
|
||||
|
||||
## Example
|
||||
|
||||
```haskell
|
||||
|
||||
import qualified Stamina
|
||||
|
||||
main :: IO ()
|
||||
main = do
|
||||
Stamina.retry Stamina.defaultRetrySettings $ \retryStatus -> do
|
||||
... monadic logic that raises exceptions
|
||||
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
@ -16,4 +51,9 @@ Heavily inspired by [stamina for Python](https://stamina.hynek.me/en/stable/tuto
|
||||
|
||||
2. `devenv shell`
|
||||
|
||||
3. `stack build`
|
||||
3. `stack build`
|
||||
|
||||
## Credits
|
||||
|
||||
- Heavily inspired by [stamina for Python](https://stamina.hynek.me/en/stable/tutorial.html#retries).
|
||||
- [retry](https://github.com/Soostone/retry) as case study for what needs to be supported
|
@ -8,15 +8,15 @@ Inspired by https://stamina.hynek.me/en/stable/api.html
|
||||
-}
|
||||
module Stamina
|
||||
( retry,
|
||||
retryOnException,
|
||||
retryOnOutput,
|
||||
retryOnExceptions,
|
||||
RetrySettings (..),
|
||||
defaultRetrySettings,
|
||||
RetryAction (..),
|
||||
RetryStatus (..),
|
||||
)
|
||||
where
|
||||
|
||||
import Control.Exception (Exception)
|
||||
import Control.Exception (Exception, Handler)
|
||||
import Control.Monad.IO.Class (MonadIO)
|
||||
|
||||
data RetrySettings = RetrySettings
|
||||
@ -67,9 +67,5 @@ retry :: MonadIO m => RetrySettings -> (RetryStatus -> m a) -> m a
|
||||
retry settings action = undefined
|
||||
|
||||
-- Same as retry, but only retry on the given exceptions.
|
||||
retryOnException :: (Exception e, MonadIO m) => RetrySettings -> (e -> m RetryAction) -> (RetryStatus -> m a) -> m a
|
||||
retryOnException settings willRetry action = undefined
|
||||
|
||||
-- Same as retry, but only retry if the given predicate returns True on the output.
|
||||
retryOnOutput :: MonadIO m => RetrySettings -> (RetryStatus -> a -> m RetryAction) -> (RetryStatus -> m a) -> m a
|
||||
retryOnOutput settings willRetry action = undefined
|
||||
retryOnExceptions :: MonadIO m => RetrySettings -> [Handler RetryAction] -> (RetryStatus -> m a) -> m a
|
||||
retryOnExceptions settings handlers action = undefined
|
||||
|
@ -62,7 +62,9 @@ library
|
||||
import: warnings
|
||||
|
||||
-- Modules exported by the library.
|
||||
exposed-modules: Stamina
|
||||
exposed-modules:
|
||||
Stamina
|
||||
, Stamina.HTTP
|
||||
|
||||
-- Modules included in this library but not exported.
|
||||
-- other-modules:
|
||||
@ -71,7 +73,7 @@ library
|
||||
-- other-extensions:
|
||||
|
||||
-- Other library packages from which modules are imported.
|
||||
build-depends: base
|
||||
build-depends: base, http-client
|
||||
|
||||
-- Directories containing source files.
|
||||
hs-source-dirs: src
|
||||
|
Loading…
Reference in New Issue
Block a user