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


-- | A sensible and clean way to write WebSocket-capable servers in Haskell.
--   
--   This library allows you to write WebSocket-capable servers.
--   
--   See an example:
--   <a>http://github.com/jaspervdj/websockets/tree/master/example</a>.
--   
--   The API of the <a>Network.WebSockets</a> module should also contain
--   enough information to get you started.
--   
--   This library currently works with Chromium <tt>&gt;= 14</tt>, and
--   Firefox <tt>&gt;= 6</tt>.
--   
--   See also:
--   
--   <ul>
--   <li>The specification of the WebSocket protocol:
--   <a>http://www.whatwg.org/specs/web-socket-protocol/</a></li>
--   <li>The JavaScript API for dealing with WebSockets:
--   <a>http://www.w3.org/TR/websockets/</a></li>
--   </ul>
@package websockets
@version 0.3.1.1


-- | How do you use this library? Here's how:
--   
--   <ul>
--   <li>Get an enumerator/iteratee pair from your favorite web server, or
--   use <a>runServer</a> to set up a simple standalone server.</li>
--   <li>Read the <a>Request</a> using <a>receiveRequest</a>. Inspect its
--   path and the perform the initial <a>handshake</a>. This yields a
--   <a>Response</a> which you can send back using <a>sendResponse</a>. The
--   WebSocket is now ready.</li>
--   </ul>
--   
--   There are (informally) three ways in which you can use the library:
--   
--   <ul>
--   <li>The most simple case: You don't care about the internal
--   representation of the messages. In this case, use the
--   <a>WebSocketsData</a> typeclass: <a>receiveData</a>,
--   <a>sendTextData</a> and <a>sendBinaryData</a> will be useful.</li>
--   <li>You have some protocol, and it is well-specified in which cases
--   the client should send text messages, and in which cases the client
--   should send binary messages. In this case, you can use the
--   <a>receiveDataMessage</a> and <a>sendDataMessage</a> methods.</li>
--   <li>You need to write a more low-level server in which you have
--   control over control frames (e.g. ping/pong). In this case, you can
--   use the <a>receiveMessage</a> and <a>sendMessage</a> methods.</li>
--   </ul>
--   
--   In some cases, you want to escape from the <a>WebSockets</a> monad and
--   send data to the websocket from different threads. To this end, the
--   <a>getSender</a> method is provided.
--   
--   For a full example, see:
--   
--   <a>http://github.com/jaspervdj/websockets/tree/master/example</a>
module Network.WebSockets

-- | Options for the WebSocket program
data WebSocketsOptions
WebSocketsOptions :: IO () -> Maybe Int -> WebSocketsOptions
onPong :: WebSocketsOptions -> IO ()
pingInterval :: WebSocketsOptions -> Maybe Int

-- | Default options
defaultWebSocketsOptions :: WebSocketsOptions

-- | The monad in which you can write WebSocket-capable applications
data WebSockets a

-- | Run a <a>WebSockets</a> application on an 'Enumerator'/'Iteratee'
--   pair.
runWebSockets :: WebSockets a -> Iteratee ByteString IO () -> Iteratee ByteString IO a

-- | Version of <a>runWebSockets</a> which allows you to specify custom
--   options
runWebSocketsWith :: WebSocketsOptions -> WebSockets a -> Iteratee ByteString IO () -> Iteratee ByteString IO a

-- | Provides a simple server. This function blocks forever. Note that this
--   is merely provided for quick-and-dirty standalone applications, for
--   real applications, you should use a real server.
runServer :: String -> Int -> WebSockets () -> IO ()

-- | This function wraps <a>runWebSockets</a> in order to provide a simple
--   API for stand-alone servers.
runWithSocket :: Socket -> WebSockets a -> IO a

-- | Request headers
type Headers = [(CI ByteString, ByteString)]

-- | Simple request type
data Request
Request :: !ByteString -> Headers -> Request
requestPath :: Request -> !ByteString
requestHeaders :: Request -> Headers

-- | Response to a <a>Request</a>
data Response
Response :: !Int -> !ByteString -> Headers -> Response
responseCode :: Response -> !Int
responseMessage :: Response -> !ByteString
responseHeaders :: Response -> Headers

-- | Type of a frame
data FrameType
ContinuationFrame :: FrameType
TextFrame :: FrameType
BinaryFrame :: FrameType
CloseFrame :: FrameType
PingFrame :: FrameType
PongFrame :: FrameType

-- | A frame
data Frame
Frame :: !Bool -> !FrameType -> !ByteString -> Frame
frameFin :: Frame -> !Bool
frameType :: Frame -> !FrameType
framePayload :: Frame -> !ByteString

-- | The kind of message a server application typically deals with
data Message
ControlMessage :: ControlMessage -> Message
DataMessage :: DataMessage -> Message

-- | Different control messages
data ControlMessage
Close :: ByteString -> ControlMessage
Ping :: ByteString -> ControlMessage
Pong :: ByteString -> ControlMessage

-- | For an end-user of this library, dealing with <a>Frame</a>s would be a
--   bit low-level. This is why define another type on top of it, which
--   represents data for the application layer.
data DataMessage
Text :: ByteString -> DataMessage
Binary :: ByteString -> DataMessage

-- | In order to have an even more high-level API, we define a typeclass
--   for values the user can receive from and send to the socket. A few
--   warnings apply:
--   
--   <ul>
--   <li>Natively, everything is represented as a <a>ByteString</a>, so
--   this is the fastest instance</li>
--   <li>You should only use the <a>Text</a> or the <a>Text</a> instance
--   when you are sure that the data is UTF-8 encoded (which is the case
--   for <a>Text</a> messages).</li>
--   <li>Messages can be very large. If this is the case, it might be
--   inefficient to use the strict <a>ByteString</a> and <a>Text</a>
--   instances.</li>
--   </ul>
class WebSocketsData a
fromLazyByteString :: WebSocketsData a => ByteString -> a
toLazyByteString :: WebSocketsData a => a -> ByteString

-- | Error in case of failed handshake.
data HandshakeError
HandshakeError :: String -> HandshakeError

-- | Read a <a>Request</a> from the socket. Blocks until one is received
--   and returns <a>Nothing</a> if the socket has been closed.
receiveRequest :: WebSockets (Maybe Request)

-- | Send a <a>Response</a> to the socket immediately.
sendResponse :: Response -> WebSockets ()

-- | Provides the logic for the initial handshake defined in the WebSocket
--   protocol. This function will provide you with a <a>Response</a> which
--   accepts and upgrades the received <a>Request</a>. Once this
--   <a>Response</a> is sent, you can start sending and receiving actual
--   application data.
--   
--   In the case of a malformed request, a <a>HandshakeError</a> is
--   returned.
handshake :: Request -> Either HandshakeError Response

-- | Read a <a>Frame</a> from the socket. Blocks until a frame is received
--   and returns <a>Nothing</a> if the socket has been closed.
--   
--   Note that a typical library user will want to use something like
--   <tt>receiveByteStringData</tt> instead.
receiveFrame :: WebSockets (Maybe Frame)

-- | A low-level function to send an arbitrary frame over the wire.
sendFrame :: Frame -> WebSockets ()

-- | Receive a message
receiveMessage :: WebSockets (Maybe Message)

-- | Send a message
sendMessage :: Message -> WebSockets ()

-- | Receive an application message. Automatically respond to control
--   messages.
receiveDataMessage :: WebSockets (Maybe DataMessage)

-- | Send an application-level message.
sendDataMessage :: DataMessage -> WebSockets ()

-- | Receive a message, treating it as data transparently
receiveData :: WebSocketsData a => WebSockets (Maybe a)

-- | Send a text message
sendTextData :: WebSocketsData a => a -> WebSockets ()

-- | Send some binary data
sendBinaryData :: WebSocketsData a => a -> WebSockets ()

-- | The inverse of a parser
type Encoder a = Mask -> a -> Builder

-- | For asynchronous sending
type Sender a = Encoder a -> a -> IO ()

-- | Low-level sending with an arbitrary <a>Encoder</a>
send :: Encoder a -> a -> WebSockets ()

-- | In case the user of the library wants to do asynchronous sending to
--   the socket, he can extract a <a>Sender</a> and pass this value around,
--   for example, to other threads.
getSender :: WebSockets (Sender a)

-- | Encode an HTTP upgrade response
response :: Encoder Response

-- | Encode a frame
frame :: Encoder Frame

-- | Encode a message
message :: Encoder Message

-- | Encode a control message
controlMessage :: Encoder ControlMessage

-- | Encode an application message
dataMessage :: Encoder DataMessage
textData :: WebSocketsData a => Encoder a
binaryData :: WebSocketsData a => Encoder a