| Safe Haskell | None |
|---|
Network.WebSockets
Contents
- data PendingConnection
- pendingRequest :: PendingConnection -> RequestHead
- acceptRequest :: PendingConnection -> IO Connection
- rejectRequest :: PendingConnection -> ByteString -> IO ()
- data Connection
- data ConnectionOptions = ConnectionOptions {
- connectionOnPong :: IO ()
- defaultConnectionOptions :: ConnectionOptions
- receive :: Connection -> IO Message
- receiveDataMessage :: Connection -> IO DataMessage
- receiveData :: WebSocketsData a => Connection -> IO a
- send :: Connection -> Message -> IO ()
- sendDataMessage :: Connection -> DataMessage -> IO ()
- sendTextData :: WebSocketsData a => Connection -> a -> IO ()
- sendBinaryData :: WebSocketsData a => Connection -> a -> IO ()
- sendClose :: WebSocketsData a => Connection -> a -> IO ()
- sendPing :: WebSocketsData a => Connection -> a -> IO ()
- type Headers = [(CI ByteString, ByteString)]
- data Request = Request RequestHead ByteString
- data RequestHead = RequestHead {}
- data Response = Response ResponseHead ByteString
- data ResponseHead = ResponseHead {}
- data Message
- data ControlMessage
- = Close ByteString
- | Ping ByteString
- | Pong ByteString
- data DataMessage
- class WebSocketsData a where
- fromLazyByteString :: ByteString -> a
- toLazyByteString :: a -> ByteString
- data HandshakeException
- data ConnectionException = ConnectionClosed
- type ServerApp = PendingConnection -> IO ()
- runServer :: String -> Int -> ServerApp -> IO ()
- runServerWith :: String -> Int -> ConnectionOptions -> ServerApp -> IO ()
- type ClientApp a = Connection -> IO a
- runClient :: String -> Int -> String -> ClientApp a -> IO a
- runClientWith :: String -> Int -> String -> ConnectionOptions -> Headers -> ClientApp a -> IO a
- runClientWithSocket :: Socket -> String -> String -> ConnectionOptions -> Headers -> ClientApp a -> IO a
- runClientWithStream :: (InputStream ByteString, OutputStream ByteString) -> String -> String -> ConnectionOptions -> Headers -> ClientApp a -> IO a
Incoming connections and handshaking
data PendingConnection Source
A new client connected to the server. We haven't accepted the connection yet, though.
pendingRequest :: PendingConnection -> RequestHeadSource
Useful for e.g. inspecting the request path.
rejectRequest :: PendingConnection -> ByteString -> IO ()Source
Main connection type
data Connection Source
Options for connections
data ConnectionOptions Source
Constructors
| ConnectionOptions | |
Fields
| |
Sending and receiving messages
receive :: Connection -> IO MessageSource
receiveDataMessage :: Connection -> IO DataMessageSource
Receive an application message. Automatically respond to control messages.
receiveData :: WebSocketsData a => Connection -> IO aSource
Receive a message, converting it to whatever format is needed.
send :: Connection -> Message -> IO ()Source
sendDataMessage :: Connection -> DataMessage -> IO ()Source
Send a DataMessage
sendTextData :: WebSocketsData a => Connection -> a -> IO ()Source
Send a message as text
sendBinaryData :: WebSocketsData a => Connection -> a -> IO ()Source
Send a message as binary data
sendClose :: WebSocketsData a => Connection -> a -> IO ()Source
Send a friendly close message
sendPing :: WebSocketsData a => Connection -> a -> IO ()Source
Send a ping
HTTP Types
type Headers = [(CI ByteString, ByteString)]Source
Request headers
A request with a body
Constructors
| Request RequestHead ByteString |
data RequestHead Source
An HTTP request. The request body is not yet read.
Constructors
| RequestHead | |
Fields
| |
Instances
A response including a body
Constructors
| Response ResponseHead ByteString |
data ResponseHead Source
HTTP response, without body.
Constructors
| ResponseHead | |
Fields
| |
Instances
WebSocket message types
The kind of message a server application typically deals with
Constructors
| ControlMessage ControlMessage | |
| DataMessage DataMessage |
data ControlMessage Source
Different control messages
Constructors
| Close ByteString | |
| Ping ByteString | |
| Pong ByteString |
Instances
data DataMessage Source
For an end-user of this library, dealing with Frames would be a bit
low-level. This is why define another type on top of it, which represents
data for the application layer.
Constructors
| Text ByteString | |
| Binary ByteString |
Instances
class WebSocketsData a whereSource
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:
- Natively, everything is represented as a
ByteString, so this is the fastest instance - You should only use the
Textor theTextinstance when you are sure that the data is UTF-8 encoded (which is the case forTextmessages). - Messages can be very large. If this is the case, it might be inefficient to
use the strict
ByteStringandTextinstances.
Exceptions
data HandshakeException Source
Error in case of failed handshake. Will be thrown as an Exception.
TODO: This should probably be in the Handshake module, and is solely here to prevent a cyclic dependency.
Constructors
| NotSupported | We don't have a match for the protocol requested by the client. todo: version parameter |
| MalformedRequest RequestHead String | The request was somehow invalid (missing headers or wrong security token) |
| MalformedResponse ResponseHead String | The servers response was somehow invalid (missing headers or wrong security token) |
| RequestRejected Request String | The request was well-formed, but the library user rejected it. (e.g. unknown path) |
| OtherHandshakeException String | for example EOF came too early (which is actually a parse error) or for your own errors. (like unknown path?) |
data ConnectionException Source
The connection couldn't be established or broke down unexpectedly. thrown as an iteratee exception.
Constructors
| ConnectionClosed | the client unexpectedly closed the connection while we were trying to receive some data. todo: Also want this for sending. |
Running a standalone server
type ServerApp = PendingConnection -> IO ()Source
WebSockets application that can be ran by a server. Once this IO action
finishes, the underlying socket is closed automatically.
Arguments
| :: String | Address to bind |
| -> Int | Port to listen on |
| -> ServerApp | Application |
| -> IO () | Never returns |
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.
runServerWith :: String -> Int -> ConnectionOptions -> ServerApp -> IO ()Source
A version of runServer which allows you to customize some options.
Running a client
type ClientApp a = Connection -> IO aSource
A client application interacting with a single server. Once this IO
action finished, the underlying socket is closed automatically.
Arguments
| :: (InputStream ByteString, OutputStream ByteString) | Stream |
| -> String | Host |
| -> String | Path |
| -> ConnectionOptions | Connection options |
| -> Headers | Custom headers to send |
| -> ClientApp a | Client application |
| -> IO a |