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

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 <tt>ServerApp</tt>, 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]) -> (Builder -> m ()) -> (ByteString -> m ()) -> (forall a. Parser a -> m a) -> m ByteString -> (ServerApp -> m ()) -> (Int -> 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])

-- | Write a <a>Bulider</a> to the response.
srvWriteBuilder :: ServerAPI m -> Builder -> m ()

-- | Set the <tt>Content-Type</tt> header of the response.
srvSetContentType :: ServerAPI m -> ByteString -> m ()

-- | Run a <a>Parser</a> against the request body.
srvParseRequestBody :: ServerAPI m -> forall a. Parser a -> m 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 ()

-- | Set the response code of the response.
srvSetResponseCode :: ServerAPI m -> Int -> 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)

-- | 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 Bounded PacketType
instance Enum PacketType
instance Eq PacketType
instance Read PacketType
instance Show PacketType
instance Eq PacketContent
instance Show PacketContent
instance Eq Packet
instance Show Packet
instance Eq Payload
instance Show Payload
instance Eq TransportType
instance Show TransportType
instance Bounded EngineIOError
instance Enum EngineIOError
instance Eq EngineIOError
instance Show EngineIOError
instance ToJSON OpenMessage
instance Ord Socket
instance Eq Socket
instance ToJSON TransportType