| 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 {
- requestPath :: !ByteString
- requestHeaders :: Headers
- requestSecure :: Bool
- data Response = Response ResponseHead ByteString
- data ResponseHead = ResponseHead {
- responseCode :: !Int
- responseMessage :: !ByteString
- responseHeaders :: Headers
- data Message
- data ControlMessage
- data DataMessage
- class WebSocketsData a where
- fromLazyByteString :: ByteString -> a
- toLazyByteString :: a -> ByteString
- data HandshakeException
- = NotSupported
- | MalformedRequest RequestHead String
- | MalformedResponse ResponseHead String
- | RequestRejected Request String
- | OtherHandshakeException String
- 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
data RequestHead Source
An HTTP request. The request body is not yet read.
Constructors
| RequestHead | |
Fields
| |
Instances
| Show RequestHead |
data ResponseHead Source
HTTP response, without body.
Constructors
| ResponseHead | |
Fields
| |
Instances
| Show ResponseHead |
WebSocket message types
The kind of message a server application typically deals with
Constructors
| ControlMessage ControlMessage | |
| DataMessage DataMessage |
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.
Instances
| Eq DataMessage | |
| Show DataMessage |
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.
Instances
| WebSocketsData ByteString | |
| WebSocketsData ByteString | |
| WebSocketsData Text | |
| WebSocketsData Text |
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?) |
Instances
| Show HandshakeException | |
| Typeable HandshakeException | |
| Exception HandshakeException | |
| Error HandshakeException |
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. |
Instances
| Show ConnectionException | |
| Typeable ConnectionException | |
| Exception ConnectionException |
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
| :: String | Host |
| -> Int | Port |
| -> String | Path |
| -> ClientApp a | Client application |
| -> IO a |
Arguments
| :: String | Host |
| -> Int | Port |
| -> String | Path |
| -> ConnectionOptions | Options |
| -> Headers | Custom headers to send |
| -> ClientApp a | Client application |
| -> IO a |
Arguments
| :: Socket | Socket |
| -> String | Host |
| -> String | Path |
| -> ConnectionOptions | Options |
| -> Headers | Custom headers to send |
| -> ClientApp a | Client application |
| -> IO a |
Arguments
| :: (InputStream ByteString, OutputStream ByteString) | Stream |
| -> String | Host |
| -> String | Path |
| -> ConnectionOptions | Connection options |
| -> Headers | Custom headers to send |
| -> ClientApp a | Client application |
| -> IO a |