Network.WebSockets.Client

A-little-bit-higher-level WebSocket client library.

Thanks to http-client and http-client-tls, functions in this module support HTTP_PROXY environment variable and TLS.

NOTE: Currently, non-TLS connection via an HTTP proxy server is NOT supported.

Documentation

withConnection

Arguments

:: String

Endpoint URL (e.g. wss://example.com/path).

-> (Connection -> IO a)

Action using the Connection

-> IO a

The main entrypoint to connect by the WebSocket protocol. This function automatically closes the created connection after exiting the action.

If HTTP_PROXY environment variable is set, The connection is automatically made via the HTTP proxy server specified by the variable.

NOTE: Currently, non-TLS connection via an HTTP proxy server is NOT supported.

Re-export from Network.WebSockets

data Connection

Sending and receiving messages

receive :: Connection -> IO Message

receiveDataMessage :: Connection -> IO DataMessage

Receive an application message. Automatically respond to control messages.

When the peer sends a close control message, an exception of type CloseRequest is thrown. The peer can send a close control message either to initiate a close or in response to a close message we have sent to the peer. In either case the CloseRequest exception will be thrown. The RFC specifies that the server is responsible for closing the TCP connection, which should happen after receiving the CloseRequest exception from this function.

This will throw ConnectionClosed if the TCP connection dies unexpectedly.

receiveData :: WebSocketsData a => Connection -> IO a

Receive a message, converting it to whatever format is needed.

send :: Connection -> Message -> IO ()

sendDataMessage :: Connection -> DataMessage -> IO ()

Send a Message. This allows you send both human-readable text and binary data. This is a slightly more low-level interface than sendTextData or sendBinaryData.

sendDataMessages :: Connection -> [DataMessage] -> IO ()

Send a collection of Messages. This is more efficient than calling sendDataMessage many times.

sendTextData :: WebSocketsData a => Connection -> a -> IO ()

Send a textual message. The message will be encoded as UTF-8. This should be the default choice for human-readable text-based protocols such as JSON.

sendTextDatas :: WebSocketsData a => Connection -> [a] -> IO ()

Send a number of textual messages. This is more efficient than calling sendTextData many times.

sendBinaryData :: WebSocketsData a => Connection -> a -> IO ()

Send a binary message. This is useful for sending binary blobs, e.g. images, data encoded with MessagePack, images...

sendBinaryDatas :: WebSocketsData a => Connection -> [a] -> IO ()

Send a number of binary messages. This is more efficient than calling sendBinaryData many times.

sendClose :: WebSocketsData a => Connection -> a -> IO ()

Send a friendly close message. Note that after sending this message, you should still continue calling receiveDataMessage to process any in-flight messages. The peer will eventually respond with a close control message of its own which will cause receiveDataMessage to throw the CloseRequest exception. This exception is when you can finally consider the connection closed.

sendCloseCode :: WebSocketsData a => Connection -> Word16 -> a -> IO ()

Send a friendly close message and close code. Similar to sendClose, you should continue calling receiveDataMessage until you receive a CloseRequest exception.

See http://tools.ietf.org/html/rfc6455#section-7.4 for a list of close codes.

sendPing :: WebSocketsData a => Connection -> a -> IO ()

Send a ping

WebSocket message types

data Message

The kind of message a server application typically deals with

Constructors

ControlMessage ControlMessage

DataMessage Bool Bool Bool DataMessage

Reserved bits, actual message

Instances

Eq Message

Defined in Network.WebSockets.Types

Methods

(==) :: Message -> Message -> Bool

(/=) :: Message -> Message -> Bool

Show Message

Defined in Network.WebSockets.Types

Methods

showsPrec :: Int -> Message -> ShowS

show :: Message -> String

showList :: [Message] -> ShowS

data ControlMessage

Different control messages

Constructors

Close Word16 ByteString

Ping ByteString

Pong ByteString

Instances

Eq ControlMessage

Defined in Network.WebSockets.Types

Methods

(==) :: ControlMessage -> ControlMessage -> Bool

(/=) :: ControlMessage -> ControlMessage -> Bool

Show ControlMessage

Defined in Network.WebSockets.Types

Methods

showsPrec :: Int -> ControlMessage -> ShowS

show :: ControlMessage -> String

showList :: [ControlMessage] -> ShowS

data DataMessage

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.

There are currently two kinds of data messages supported by the WebSockets protocol:

• Textual UTF-8 encoded data. This corresponds roughly to sending a String in JavaScript.
• Binary data. This corresponds roughly to send an ArrayBuffer in JavaScript.

Constructors

Text ByteString (Maybe Text)

A textual message. The second field might contain the decoded UTF-8 text for caching reasons. This field is computed lazily so if it's not accessed, it should have no performance impact.

Binary ByteString

A binary message.

Instances

Eq DataMessage

Defined in Network.WebSockets.Types

Methods

(==) :: DataMessage -> DataMessage -> Bool

(/=) :: DataMessage -> DataMessage -> Bool

Show DataMessage

Defined in Network.WebSockets.Types

Methods

showsPrec :: Int -> DataMessage -> ShowS

show :: DataMessage -> String

showList :: [DataMessage] -> ShowS

class WebSocketsData a where

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 Text or the Text instance when you are sure that the data is UTF-8 encoded (which is the case for Text messages).
• Messages can be very large. If this is the case, it might be inefficient to use the strict ByteString and Text instances.

Methods

fromDataMessage :: DataMessage -> a

fromLazyByteString :: ByteString -> a

toLazyByteString :: a -> ByteString

Instances

WebSocketsData ByteString

Defined in Network.WebSockets.Types

Methods

fromDataMessage :: DataMessage -> ByteString

fromLazyByteString :: ByteString0 -> ByteString

toLazyByteString :: ByteString -> ByteString0

WebSocketsData ByteString

Defined in Network.WebSockets.Types

Methods

fromDataMessage :: DataMessage -> ByteString

fromLazyByteString :: ByteString -> ByteString

toLazyByteString :: ByteString -> ByteString

WebSocketsData Text

Defined in Network.WebSockets.Types

Methods

fromDataMessage :: DataMessage -> Text

fromLazyByteString :: ByteString -> Text

toLazyByteString :: Text -> ByteString

WebSocketsData Text

Defined in Network.WebSockets.Types

Methods

fromDataMessage :: DataMessage -> Text

fromLazyByteString :: ByteString -> Text

toLazyByteString :: Text -> ByteString

Exceptions

data HandshakeException

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

Defined in Network.WebSockets.Http

Methods

showsPrec :: Int -> HandshakeException -> ShowS

show :: HandshakeException -> String

showList :: [HandshakeException] -> ShowS

Exception HandshakeException

Defined in Network.WebSockets.Http

Methods

toException :: HandshakeException -> SomeException

fromException :: SomeException -> Maybe HandshakeException

displayException :: HandshakeException -> String

data ConnectionException

Various exceptions that can occur while receiving or transmitting messages

Constructors

CloseRequest Word16 ByteString

The peer has requested that the connection be closed, and included a close code and a reason for closing. When receiving this exception, no more messages can be sent. Also, the server is responsible for closing the TCP connection once this exception is received.

See http://tools.ietf.org/html/rfc6455#section-7.4 for a list of close codes.

ConnectionClosed

The peer unexpectedly closed the connection while we were trying to receive some data. This is a violation of the websocket RFC since the TCP connection should only be closed after sending and receiving close control messages.

ParseException String

The client sent garbage, i.e. we could not parse the WebSockets stream.

UnicodeException String

The client sent invalid UTF-8. Note that this exception will only be thrown if strict decoding is set in the connection options.

Instances

Eq ConnectionException

Defined in Network.WebSockets.Types

Methods

(==) :: ConnectionException -> ConnectionException -> Bool

(/=) :: ConnectionException -> ConnectionException -> Bool

Show ConnectionException

Defined in Network.WebSockets.Types

Methods

showsPrec :: Int -> ConnectionException -> ShowS

show :: ConnectionException -> String

showList :: [ConnectionException] -> ShowS

Exception ConnectionException

Defined in Network.WebSockets.Types

Methods

toException :: ConnectionException -> SomeException

fromException :: SomeException -> Maybe ConnectionException

displayException :: ConnectionException -> String

Utilities

withPingThread

Arguments

:: Connection

-> Int

Second interval in which pings should be sent.

-> IO ()

Repeat this after sending a ping.

-> IO a

Application to wrap with a ping thread.

-> IO a

Executes application and kills ping thread when done.

Forks a ping thread, sending a ping message every n seconds over the connection. The thread is killed when the inner IO action is finished.

This is useful to keep idle connections open through proxies and whatnot. Many (but not all) proxies have a 60 second default timeout, so based on that sending a ping every 30 seconds is a good idea.