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


-- | Simple interface to WebSockets.
--   
--   Simple interface to WebSockets.
@package network-simple-ws
@version 0.2


-- | Simple tools for establishing and using insecure WebSockets
--   connections on top of TCP (i.e, <tt>ws://</tt>).
--   
--   See the <a>network-simple-wss</a> package for Secure WebSockets (i.e,
--   <tt>wss://</tt>) support.
--   
--   Notice that, currently, this is package offers tools that are mostly
--   intreresting from a client's point of view. Server side support will
--   come later.
module Network.Simple.WS
data Connection

-- | Receive a single full WebSockets message from the remote end as a lazy
--   <a>ByteString</a> (potentially <a>empty</a>).
--   
--   Throws <a>IOException</a> if there is an unexpected <a>Connection</a>
--   error.
--   
--   If the remote end requested the <a>Connection</a> to be closed, then
--   <a>Left</a> will be returned instead, with a close code and reason
--   description.
--   
--   <ul>
--   <li>See
--   <a>https://datatracker.ietf.org/doc/html/rfc6455#section-7.4</a> for
--   details about the close codes.</li>
--   <li>Do not use <a>recv</a> after receiving a close request.</li>
--   <li>If you receive a close request after after having sent a close
--   request yourself (see <a>close</a>), then the WebSocket
--   <a>Connection</a> is considered closed and you can proceed to close
--   the underlying transport.</li>
--   <li>If you didn't send a close request before, then you may continue
--   to use <a>send</a>, but you are expected to perform <a>close</a> as
--   soon as possible in order to indicate a graceful closing of the
--   connection.</li>
--   </ul>
recv :: MonadIO m => Connection -> m (Either (Word16, ByteString) ByteString)

-- | Send a lazy <a>ByteString</a> (potentially <a>empty</a>) to the remote
--   end as a single WebSockets message, in potentially multiple frames.
--   
--   If there is an issue with the <a>Connection</a>, an exception
--   originating from the underlying <a>Stream</a> will be thrown.
send :: MonadIO m => Connection -> ByteString -> m ()

-- | Send a close request to the remote end.
--   
--   After sending this request you should not use <a>send</a> anymore, but
--   you should still continue to call <a>recv</a> to process any pending
--   incomming messages. As soon as <a>recv</a> returns <a>Left</a>, you
--   can consider the WebSocket <a>Connection</a> closed and can proceed to
--   close the underlying transport.
--   
--   If there is an issue with the <a>Connection</a>, an exception
--   originating from the underlying <a>Stream</a> will be thrown.
close :: MonadIO m => Connection -> Word16 -> ByteString -> m ()

-- | Connect to the specified WebSockets server.
connect :: (MonadIO m, MonadMask m) => HostName -> ServiceName -> ByteString -> [(ByteString, ByteString)] -> ((Connection, SockAddr) -> m r) -> m r

-- | Like <a>connect</a>, but connects to the destination server through a
--   SOCKS5 proxy.
connectSOCKS5 :: (MonadIO m, MonadMask m) => HostName -> ServiceName -> HostName -> ServiceName -> ByteString -> [(ByteString, ByteString)] -> ((Connection, SockAddr, SockAddr) -> m r) -> m r

-- | Obtain a <a>Connection</a> to the specified URI over the given
--   <a>Stream</a>, connected to either a WebSockets server, or a Secure
--   WebSockets server.
clientConnectionFromStream :: MonadIO m => Stream -> HostName -> ServiceName -> ByteString -> [(ByteString, ByteString)] -> m Connection

-- | Obtain a <a>Stream</a> implemented using the network <a>Socket</a>.
--   You can use the <a>network-simple</a> library to get one of those.
streamFromSocket :: MonadIO m => Socket -> m Stream