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


-- | A Haskell implementation of Engine.IO
--   
--   This library provides a Haskell implementation of <a>Engine.IO</a>, a
--   library for real-time client-server communication on the web.
--   Engine.IO works with old browsers via XHR long-polling, and seamlessy
--   upgrades to web sockets. This implementation supports the majority of
--   the Engine.IO protocol, including text and binary packets and the
--   upgrading protocol.
@package engine-io
@version 1.2.21

module Network.EngineIO

-- | <a>initialize</a> initializes a new Engine.IO server. You can later
--   serve this session by using <a>handler</a>.
initialize :: IO EngineIO

-- | Build the necessary handler for Engine.IO. The result of this function
--   is a computation that you should serve under the
--   <tt><i>engine.io</i></tt> path.
--   
--   <a>handler</a> takes a function as an argument that is called every
--   time a new session is created. This function runs in the <tt>m</tt>
--   monad, so you have access to initial web request, which may be useful
--   for performing authentication or collecting cookies. This function
--   then returns a <a>SocketApp</a>, describing the main loop and an
--   action to perform on socket disconnection.
handler :: MonadIO m => EngineIO -> (Socket -> m SocketApp) -> ServerAPI m -> m ()

-- | An opaque data type representing an open Engine.IO server.
data EngineIO

-- | A dictionary of functions that Engine.IO needs in order to provide
--   communication channels.
data ServerAPI m
ServerAPI :: m (HashMap ByteString [ByteString]) -> Int -> ByteString -> Builder -> forall a. m a -> forall a. Parser a -> m (Either String a) -> m ByteString -> ServerApp -> m () -> ServerAPI m

-- | Retrieve the <a>HashMap</a> of query parameters in the request path to
--   their zero-or-more values.
[srvGetQueryParams] :: ServerAPI m -> m (HashMap ByteString [ByteString])

-- | Send a response with the given status code, content type and body.
--   This should also terminate the web request entirely, such that further
--   actions in <tt>m</tt> have no effect.
[srvTerminateWithResponse] :: ServerAPI m -> Int -> ByteString -> Builder -> forall a. m a

-- | Run a <a>Parser</a> against the request body.
[srvParseRequestBody] :: ServerAPI m -> forall a. Parser a -> m (Either String a)

-- | Get the request method of the current request. The request method
--   should be in uppercase for standard methods (e.g., <tt>GET</tt>).
[srvGetRequestMethod] :: ServerAPI m -> m ByteString

-- | Upgrade the current connection to run a WebSocket action.
[srvRunWebSocket] :: ServerAPI m -> ServerApp -> m ()

-- | The application to run for the duration of a connected socket.
data SocketApp
SocketApp :: IO () -> IO () -> SocketApp

-- | An IO action to run for the duration of the socket's lifetime. If this
--   action terminates, the connection will be closed. You will likely want
--   to loop <a>forever</a> and block as appropriate with <a>receive</a>.
[saApp] :: SocketApp -> IO ()

-- | An action to execute when the connection is closed, either by
--   <a>saApp</a> terminating, or the client disconnecting.
[saOnDisconnect] :: SocketApp -> IO ()

-- | Send a packet to the client. This is a non-blocking write.
send :: Socket -> PacketContent -> STM ()

-- | Receive data from the client, blocking if the input queue is empty.
receive :: Socket -> STM PacketContent

-- | A connected Engine.IO session.
data Socket

-- | The type of unique Engine.IO sessions. This is currently a
--   base64-encoded random identifier.
type SocketId = ByteString
socketId :: Socket -> SocketId

-- | Retrieve a list of <i>all</i> currently open Engine.IO sessions.
getOpenSockets :: EngineIO -> STM (HashMap SocketId Socket)

-- | Create a new <a>IO</a> action to read the socket's raw incoming
--   communications. The result of this call is iteslf an STM action, which
--   when called will return the next unread incoming packet (or block).
--   This provides you with a separate channel to monitor incoming
--   communications. It may be useful to monitor this to determine if the
--   socket has activity.
--   
--   This is a fairly low level operation, so you will receive *all*
--   packets - including pings and other control codes.
dupRawReader :: Socket -> IO (STM Packet)

-- | A single Engine.IO packet.
data Packet
Packet :: !PacketType -> !PacketContent -> Packet

-- | Parse bytes as an <a>Packet</a> assuming the packet contents extends
--   to the end-of-input.
parsePacket :: Parser Packet

-- | Encode a <a>Packet</a> to a <a>Builder</a>. The first argument
--   determines whether or not binary is supported - if not, binary data
--   will be base 64 encoded.
encodePacket :: Bool -> Packet -> Builder

-- | The possible packet types, as mentioned in the <a>Engine.IO protocol
--   documentation</a>
data PacketType

-- | The contents attached to a packet. Engine.IO makes a clear distinction
--   between binary data and text data. Clients will receive binary data as
--   a Javascript <tt>ArrayBuffer</tt>, where as <a>TextPacket</a>s will be
--   received as UTF-8 strings.
data PacketContent
BinaryPacket :: !ByteString -> PacketContent
TextPacket :: !Text -> PacketContent

-- | A <a>Payload</a> is a stream of 0-or-more <a>Packet</a>s.
newtype Payload
Payload :: (Vector Packet) -> Payload

-- | Parse a stream of bytes into a <a>Payload</a>.
parsePayload :: Parser Payload

-- | Encode a <a>Payload</a> to a <a>Builder</a>. As with
--   <a>encodePacket</a>, the first argument determines whether or not
--   binary transmission is supported.
encodePayload :: Bool -> Payload -> Builder

-- | The possible types of transports Engine.IO supports.
data TransportType

-- | XHR long polling.
Polling :: TransportType

-- | HTML 5 websockets.
Websocket :: TransportType

-- | Attempt to parse a <a>TransportType</a> from its textual
--   representation.
parseTransportType :: Text -> Maybe TransportType
instance GHC.Show.Show Network.EngineIO.EngineIOError
instance GHC.Classes.Eq Network.EngineIO.EngineIOError
instance GHC.Enum.Enum Network.EngineIO.EngineIOError
instance GHC.Enum.Bounded Network.EngineIO.EngineIOError
instance GHC.Show.Show Network.EngineIO.TransportType
instance GHC.Classes.Eq Network.EngineIO.TransportType
instance GHC.Show.Show Network.EngineIO.Payload
instance GHC.Classes.Eq Network.EngineIO.Payload
instance GHC.Show.Show Network.EngineIO.Packet
instance GHC.Classes.Eq Network.EngineIO.Packet
instance GHC.Show.Show Network.EngineIO.PacketContent
instance GHC.Classes.Eq Network.EngineIO.PacketContent
instance GHC.Show.Show Network.EngineIO.PacketType
instance GHC.Read.Read Network.EngineIO.PacketType
instance GHC.Classes.Eq Network.EngineIO.PacketType
instance GHC.Enum.Enum Network.EngineIO.PacketType
instance GHC.Enum.Bounded Network.EngineIO.PacketType
instance Data.Aeson.Types.ToJSON.ToJSON Network.EngineIO.OpenMessage
instance GHC.Classes.Eq Network.EngineIO.Socket
instance GHC.Classes.Ord Network.EngineIO.Socket
instance Data.Aeson.Types.ToJSON.ToJSON Network.EngineIO.TransportType