-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | WAI Middleware for Request Throttling
--   
--   WAI Middleware for request rate limiting and throttling.
--   
--   Designed to be configured in the spirit of the NGinx module.
@package wai-middleware-throttle
@version 0.2.2.1


-- | Uses a <a>Token Bucket</a> algorithm (from the token-bucket package)
--   to throttle WAI Requests.
--   
--   <h2>Example</h2>
--   
--   <pre>
--   main = do
--     st &lt;- initThrottler
--     let payload  = "{ "api": "return data" }"
--         app = throttle defaultThrottleSettings st
--                 $ _ f -&gt; f (responseLBS status200 [] payload)
--     Warp.run 3000 app
--   </pre>
module Network.Wai.Middleware.Throttle

-- | WAI Request Throttling Middleware.
--   
--   Uses a <a>Request</a>s <a>remoteHost</a> function to resolve the
--   remote IP address.
throttle :: RequestHashable a => ThrottleSettings -> CustomWaiThrottle a -> Application -> Application

-- | A synonym for an IP address throttle
type WaiThrottle = CustomWaiThrottle Address

-- | A throttle for a type implementing <a>RequestHashable</a>
data CustomWaiThrottle a

-- | Initialize an IP address throttler
initThrottler :: IO WaiThrottle

-- | Initialize a "custom" throttler that implements the
--   <a>RequestHashable</a> class
initCustomThrottler :: IO (CustomWaiThrottle a)

-- | Settings which control various behaviors in the middleware.
data ThrottleSettings
ThrottleSettings :: !(Request -> IO Bool) -> !(Word64 -> Response) -> !(Text -> Response) -> !Integer -> !Integer -> !Integer -> ThrottleSettings

-- | Determines whether the <a>Request</a> is throttled
[isThrottled] :: ThrottleSettings -> !(Request -> IO Bool)

-- | Function to run when the request is throttled.
--   
--   The first argument is a <a>Word64</a> containing the amount of
--   microseconds until the next retry should be attempted.
[onThrottled] :: ThrottleSettings -> !(Word64 -> Response)

-- | Function to run when the throttler fails to extract the key.
--   
--   The first argument is a <a>Text</a> containing the error message.
[onRequestError] :: ThrottleSettings -> !(Text -> Response)

-- | Rate
[throttleRate] :: ThrottleSettings -> !Integer
[throttlePeriod] :: ThrottleSettings -> !Integer

-- | Burst rate
[throttleBurst] :: ThrottleSettings -> !Integer

-- | Default settings to throttle requests.
defaultThrottleSettings :: ThrottleSettings
newtype Address
Address :: SockAddr -> Address

-- | A class extracting a hashable key from a <a>Request</a> to store in an
--   in-memory map
class (Eq a, Ord a, Hashable a) => RequestHashable a
requestToKey :: (RequestHashable a, Functor m, Monad m) => Request -> ExceptT Text m a
instance Network.Wai.Middleware.Throttle.RequestHashable Network.Wai.Middleware.Throttle.Address
instance Data.Hashable.Class.Hashable Network.Wai.Middleware.Throttle.Address
instance GHC.Classes.Eq Network.Wai.Middleware.Throttle.Address
instance GHC.Classes.Ord Network.Wai.Middleware.Throttle.Address
