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


-- | WebSockets support for Yesod
--   
--   API docs and the README are available at
--   <a>http://www.stackage.org/package/yesod-websockets</a>
@package yesod-websockets
@version 0.3.0

module Yesod.WebSockets

-- | A transformer for a WebSockets handler.
--   
--   Since 0.1.0
type WebSocketsT = ReaderT Connection

-- | Attempt to run a WebSockets handler. This function first checks if the
--   client initiated a WebSockets connection and, if so, runs the provided
--   application, short-circuiting the rest of your handler. If the client
--   did not request a WebSockets connection, the rest of your handler will
--   be called instead.
--   
--   Since 0.1.0
webSockets :: (MonadUnliftIO m, MonadHandler m) => WebSocketsT m () -> m ()

-- | Varient of <a>webSockets</a> which allows you to specify the
--   <a>AcceptRequest</a> setttings when upgrading to a websocket
--   connection.
--   
--   Since 0.2.4
webSocketsWith :: (MonadUnliftIO m, MonadHandler m) => (RequestHead -> m (Maybe AcceptRequest)) -> WebSocketsT m () -> m ()

-- | Varient of <a>webSockets</a> which allows you to specify the
--   WS.ConnectionOptions setttings when upgrading to a websocket
--   connection.
--   
--   Since 0.2.5
webSocketsOptions :: (MonadUnliftIO m, MonadHandler m) => ConnectionOptions -> WebSocketsT m () -> m ()

-- | Varient of <a>webSockets</a> which allows you to specify both the
--   WS.ConnectionOptions and the <a>AcceptRequest</a> setttings when
--   upgrading to a websocket connection.
--   
--   Since 0.2.5
webSocketsOptionsWith :: (MonadUnliftIO m, MonadHandler m) => ConnectionOptions -> (RequestHead -> m (Maybe AcceptRequest)) -> WebSocketsT m () -> m ()

-- | Receive a piece of data from the client.
--   
--   Since 0.1.0
receiveData :: (MonadIO m, MonadReader Connection m, WebSocketsData a) => m a

-- | Receive a piece of data from the client. Capture SomeException as the
--   result or operation Since 0.2.2
receiveDataE :: (MonadIO m, MonadReader Connection m, WebSocketsData a) => m (Either SomeException a)

-- | Receive an application message. Capture SomeException as the result or
--   operation Since 0.2.3
receiveDataMessageE :: (MonadIO m, MonadReader Connection m) => m (Either SomeException DataMessage)

-- | Send a ping message to the client.
--   
--   Since 0.2.2
sendPing :: (MonadIO m, WebSocketsData a, MonadReader Connection m) => a -> WebSocketsT m ()

-- | Send a ping message to the client. Capture SomeException as the result
--   of operation Since 0.2.2
sendPingE :: (MonadIO m, WebSocketsData a, MonadReader Connection m) => a -> m (Either SomeException ())

-- | Send a close request to the client.
--   
--   Since 0.2.2
sendClose :: (MonadIO m, WebSocketsData a, MonadReader Connection m) => a -> WebSocketsT m ()

-- | Send a close request to the client. Capture SomeException as the
--   result of operation Since 0.2.2
sendCloseE :: (MonadIO m, WebSocketsData a, MonadReader Connection m) => a -> m (Either SomeException ())

-- | Send a textual message to the client.
--   
--   Since 0.1.0
sendTextData :: (MonadIO m, WebSocketsData a, MonadReader Connection m) => a -> m ()

-- | Send a textual message to the client. Capture SomeException as the
--   result or operation and can be used like `either handle_exception
--   return =&lt;&lt; sendTextDataE (<a>Welcome</a> :: Text)` Since 0.2.2
sendTextDataE :: (MonadIO m, WebSocketsData a, MonadReader Connection m) => a -> m (Either SomeException ())

-- | Send a binary message to the client.
--   
--   Since 0.1.0
sendBinaryData :: (MonadIO m, WebSocketsData a, MonadReader Connection m) => a -> m ()

-- | Send a binary message to the client. Capture SomeException as the
--   result of operation Since 0.2.2
sendBinaryDataE :: (MonadIO m, WebSocketsData a, MonadReader Connection m) => a -> m (Either SomeException ())

-- | Send a DataMessage to the client. Capture SomeException as the result
--   of operation Since 0.2.3
sendDataMessageE :: (MonadIO m, MonadReader Connection m) => DataMessage -> m (Either SomeException ())

-- | A <tt>Source</tt> of WebSockets data from the user.
--   
--   Since 0.1.0
sourceWS :: (MonadIO m, WebSocketsData a, MonadReader Connection m) => ConduitT i a m ()

-- | A <tt>Sink</tt> for sending textual data to the user.
--   
--   Since 0.1.0
sinkWSText :: (MonadIO m, WebSocketsData a, MonadReader Connection m) => ConduitT a o m ()

-- | A <tt>Sink</tt> for sending binary data to the user.
--   
--   Since 0.1.0
sinkWSBinary :: (MonadIO m, WebSocketsData a, MonadReader Connection m) => ConduitT a o m ()

-- | Unlifted <a>race</a>.
race :: MonadUnliftIO m => m a -> m b -> m Either a b

-- | Unlifted <a>race_</a>.
race_ :: MonadUnliftIO m => m a -> m b -> m ()

-- | Unlifted <a>concurrently</a>.
concurrently :: MonadUnliftIO m => m a -> m b -> m (a, b)

-- | Unlifted <a>concurrently_</a>.
concurrently_ :: MonadUnliftIO m => m a -> m b -> m ()

-- | The default connection options:
--   
--   <ul>
--   <li>Nothing happens when a pong is received.</li>
--   <li>Compression is disabled.</li>
--   <li>Lenient unicode decoding.</li>
--   </ul>
defaultConnectionOptions :: ConnectionOptions

-- | Set options for a <tt>Connection</tt>. Please do not use this
--   constructor directly, but rather use <a>defaultConnectionOptions</a>
--   and then set the fields you want, e.g.:
--   
--   <pre>
--   myOptions = defaultConnectionOptions {connectionStrictUnicode = True}
--   </pre>
--   
--   This way your code does not break if the library introduces new
--   fields.
data ConnectionOptions
ConnectionOptions :: !IO () -> !CompressionOptions -> !Bool -> !SizeLimit -> !SizeLimit -> ConnectionOptions

-- | Whenever a <tt>pong</tt> is received, this IO action is executed. It
--   can be used to tickle connections or fire missiles.
[connectionOnPong] :: ConnectionOptions -> !IO ()

-- | Enable <a>PermessageDeflate</a>.
[connectionCompressionOptions] :: ConnectionOptions -> !CompressionOptions

-- | Enable strict unicode on the connection. This means that if a client
--   (or server) sends invalid UTF-8, we will throw a
--   <tt>UnicodeException</tt> rather than replacing it by the unicode
--   replacement character U+FFFD.
[connectionStrictUnicode] :: ConnectionOptions -> !Bool

-- | The maximum size for incoming frame payload size in bytes. If a frame
--   exceeds this limit, a <tt>ParseException</tt> is thrown.
[connectionFramePayloadSizeLimit] :: ConnectionOptions -> !SizeLimit

-- | <tt>connectionFrameSizeLimit</tt> is often not enough since a
--   malicious client can send many small frames to create a huge message.
--   This limit allows you to protect from that. If a message exceeds this
--   limit, a <tt>ParseException</tt> is thrown.
--   
--   Note that, if compression is enabled, we check the size of the
--   compressed messages, as well as the size of the uncompressed messages
--   as we are deflating them to ensure we don't use too much memory in any
--   case.
[connectionMessageDataSizeLimit] :: ConnectionOptions -> !SizeLimit
