-- 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.3.0.0

module Network.Wai.Middleware.Throttle.Internal
newtype Address
Address :: SockAddr -> Address
extractAddress :: Request -> Either Response Address
data CacheState a
CacheStatePresent :: a -> CacheState a
CacheStateInitializing :: CacheState a
data CacheResult a
CacheResultExists :: a -> CacheResult a
CacheResultEmpty :: CacheResult a

-- | A throttle for a hashable key type. Initialize using
--   <a>initThrottler</a> with <a>defaultThrottleSettings</a>.
data Throttle a
Throttle :: ThrottleSettings -> Cache a (CacheState TokenBucket) -> (Request -> Either Response a) -> Throttle a

-- | The throttle settings
[throttleSettings] :: Throttle a -> ThrottleSettings

-- | The cache, initialized in <a>initThrottler</a>
[throttleCache] :: Throttle a -> Cache a (CacheState TokenBucket)

-- | The function to extract a throttle key from a <a>Request</a>
[throttleGetKey] :: Throttle a -> Request -> Either Response a

-- | Throttle settings for controlling token bucket algorithm and cache
--   expiration.
data ThrottleSettings
ThrottleSettings :: Double -> Double -> Word64 -> TimeSpec -> (Request -> Bool) -> (Word64 -> Response) -> ThrottleSettings

-- | Number of requests per throttle period allowed, defaults to 1
[throttleSettingsRate] :: ThrottleSettings -> Double

-- | Microseconds, defaults to 1 second
[throttleSettingsPeriod] :: ThrottleSettings -> Double

-- | Number of concurrent requests allowed - should be greater than rate /
--   period, defaults to 1
[throttleSettingsBurst] :: ThrottleSettings -> Word64

-- | The amount of time before a stale token bucket is purged from the
--   cache
[throttleSettingsCacheExpiration] :: ThrottleSettings -> TimeSpec

-- | Whether or not a request is throttled, defaults to true
[throttleSettingsIsThrottled] :: ThrottleSettings -> Request -> Bool

-- | The response when a request is throttled - defaults to a vanilla 429
[throttleSettingsOnThrottled] :: ThrottleSettings -> Word64 -> Response

-- | Default throttle settings.
defaultThrottleSettings :: TimeSpec -> ThrottleSettings
initThrottler :: ThrottleSettings -> IO (Throttle Address)

-- | Initialize a throttle using settings and a way to extract the key from
--   the request.
initCustomThrottler :: ThrottleSettings -> (Request -> Either Response a) -> IO (Throttle a)

-- | Internal use only. Retrieve a token bucket from the cache.
retrieveCache :: (Eq a, Hashable a) => Throttle a -> TimeSpec -> a -> STM (CacheResult TokenBucket)

-- | Internal use only. Create a token bucket if it wasn't in the cache.
processCacheResult :: (Eq a, Hashable a) => Throttle a -> a -> CacheResult TokenBucket -> IO TokenBucket

-- | Internal use only. Retrieve or initialize a token bucket depending on
--   if it was found in the cache.
retrieveOrInitializeBucket :: (Eq a, Hashable a) => Throttle a -> a -> IO TokenBucket

-- | Internal use only. Throttle a request by the throttle key.
throttleRequest :: (Eq a, Hashable a) => Throttle a -> a -> IO Word64

-- | Run the throttling middleware given a throttle that has been
--   initialized.
throttle :: (Eq a, Hashable a) => Throttle a -> Application -> Application
instance GHC.Show.Show (Network.Wai.Middleware.Throttle.Internal.CacheResult a)
instance GHC.Show.Show (Network.Wai.Middleware.Throttle.Internal.CacheState a)
instance Data.Hashable.Class.Hashable Network.Wai.Middleware.Throttle.Internal.Address
instance GHC.Classes.Eq Network.Wai.Middleware.Throttle.Internal.Address
instance GHC.Classes.Ord Network.Wai.Middleware.Throttle.Internal.Address


-- | Uses a <a>Token Bucket</a> algorithm (from the token-bucket package)
--   to throttle WAI Requests.
--   
--   <h2>Example</h2>
--   
--   <pre>
--   main = do
--     let expirationSpec = TimeSpec 5 0 -- five seconds
--     th &lt;- initThrottler (defaultThrottleSettings expirationSpec) (const $ Right 1)
--     let appl = throttle th $  _ f -&gt; f $
--           responseLBS ok200 [] "ok"
--     Warp.run 3000 app
--   </pre>
module Network.Wai.Middleware.Throttle

-- | Throttle settings for controlling token bucket algorithm and cache
--   expiration.
data ThrottleSettings
ThrottleSettings :: Double -> Double -> Word64 -> TimeSpec -> (Request -> Bool) -> (Word64 -> Response) -> ThrottleSettings

-- | Number of requests per throttle period allowed, defaults to 1
[throttleSettingsRate] :: ThrottleSettings -> Double

-- | Microseconds, defaults to 1 second
[throttleSettingsPeriod] :: ThrottleSettings -> Double

-- | Number of concurrent requests allowed - should be greater than rate /
--   period, defaults to 1
[throttleSettingsBurst] :: ThrottleSettings -> Word64

-- | The amount of time before a stale token bucket is purged from the
--   cache
[throttleSettingsCacheExpiration] :: ThrottleSettings -> TimeSpec

-- | Whether or not a request is throttled, defaults to true
[throttleSettingsIsThrottled] :: ThrottleSettings -> Request -> Bool

-- | The response when a request is throttled - defaults to a vanilla 429
[throttleSettingsOnThrottled] :: ThrottleSettings -> Word64 -> Response

-- | A throttle for a hashable key type. Initialize using
--   <a>initThrottler</a> with <a>defaultThrottleSettings</a>.
data Throttle a
Throttle :: ThrottleSettings -> Cache a (CacheState TokenBucket) -> (Request -> Either Response a) -> Throttle a

-- | The throttle settings
[throttleSettings] :: Throttle a -> ThrottleSettings

-- | The cache, initialized in <a>initThrottler</a>
[throttleCache] :: Throttle a -> Cache a (CacheState TokenBucket)

-- | The function to extract a throttle key from a <a>Request</a>
[throttleGetKey] :: Throttle a -> Request -> Either Response a
newtype Address
Address :: SockAddr -> Address
extractAddress :: Request -> Either Response Address

-- | Default throttle settings.
defaultThrottleSettings :: TimeSpec -> ThrottleSettings
initThrottler :: ThrottleSettings -> IO (Throttle Address)

-- | Initialize a throttle using settings and a way to extract the key from
--   the request.
initCustomThrottler :: ThrottleSettings -> (Request -> Either Response a) -> IO (Throttle a)

-- | Run the throttling middleware given a throttle that has been
--   initialized.
throttle :: (Eq a, Hashable a) => Throttle a -> Application -> Application
