add HTTP and example/api docs

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

src/Stamina.hs

@@ -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

stamina.cabal

@@ -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