Network.WebSockets

How do you use this library? Here's how:

• Get an enumerator/iteratee pair from your favorite web server, or use runServer to set up a simple standalone server.
• Read the Request using receiveRequest. Inspect its path and the perform the initial handshake. This yields a Response which you can send back using sendResponse. The WebSocket is now ready.

There are (informally) three ways in which you can use the library:

• The most simple case: You don't care about the internal representation of the messages. In this case, use the WebSocketsData typeclass: receiveData, sendTextData and sendBinaryData will be useful.
• 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 receiveDataMessage and sendDataMessage methods.
• 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 receiveMessage and sendMessage methods.

In some cases, you want to escape from the WebSockets monad and send data to the websocket from different threads. To this end, the getSender method is provided.

For a full example, see:

http://github.com/jaspervdj/websockets/tree/master/example

WebSocket type

data WebSocketsOptions

Options for the WebSocket program

Constructors

WebSocketsOptions

Fields

onPong :: IO ()

pingInterval :: Maybe Int

defaultWebSocketsOptions :: WebSocketsOptions

Default options

data WebSockets a

The monad in which you can write WebSocket-capable applications

Instances

Monad WebSockets

Functor WebSockets

MonadIO WebSockets

runWebSockets :: WebSockets a -> Iteratee ByteString IO () -> Iteratee ByteString IO a

Run a WebSockets application on an 'Enumerator'/'Iteratee' pair.

runWebSocketsWith :: WebSocketsOptions -> WebSockets a -> Iteratee ByteString IO () -> Iteratee ByteString IO a

Version of runWebSockets which allows you to specify custom options

A simple standalone server

runServer

Arguments

:: String

Address to bind to

-> Int

Port to listen on

-> WebSockets ()

Application to serve

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

runWithSocket :: Socket -> WebSockets a -> IO a

This function wraps runWebSockets in order to provide a simple API for stand-alone servers.

Types

type Headers = [(CI ByteString, ByteString)]

Request headers

data Request

Simple request type

Constructors

Request

Fields

requestPath :: !ByteString

requestHeaders :: Headers

Instances

Show Request

data Response

Response to a Request

Constructors

Response

Fields

responseCode :: !Int

responseMessage :: !ByteString

responseHeaders :: Headers

Instances

Show Response

data FrameType

Type of a frame

Constructors

ContinuationFrame

TextFrame

BinaryFrame

CloseFrame

PingFrame

PongFrame

Instances

Eq FrameType

Show FrameType

data Frame

A frame

Constructors

Frame

Fields

frameFin :: !Bool

frameType :: !FrameType

framePayload :: !ByteString

Instances

Eq Frame

Show Frame

data Message

The kind of message a server application typically deals with

Constructors

ControlMessage ControlMessage

DataMessage DataMessage

Instances

Show Message

data ControlMessage

Different control messages

Constructors

Close ByteString

Ping ByteString

Pong ByteString

Instances

Show ControlMessage

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.

Constructors

Text ByteString

Binary ByteString

Instances

Show DataMessage

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

fromLazyByteString :: ByteString -> a

toLazyByteString :: a -> ByteString

Instances

WebSocketsData ByteString

WebSocketsData ByteString

WebSocketsData Text

WebSocketsData Text

Initial handshake

data HandshakeError

Error in case of failed handshake.

Constructors

HandshakeError String

Instances

Show HandshakeError

Error HandshakeError

receiveRequest :: WebSockets (Maybe Request)

Read a Request from the socket. Blocks until one is received and returns Nothing if the socket has been closed.

sendResponse :: Response -> WebSockets ()

Send a Response to the socket immediately.

handshake :: Request -> Either HandshakeError Response

Provides the logic for the initial handshake defined in the WebSocket protocol. This function will provide you with a Response which accepts and upgrades the received Request. Once this Response is sent, you can start sending and receiving actual application data.

In the case of a malformed request, a HandshakeError is returned.

Sending and receiving

receiveFrame :: WebSockets (Maybe Frame)

Read a Frame from the socket. Blocks until a frame is received and returns Nothing if the socket has been closed.

Note that a typical library user will want to use something like receiveByteStringData instead.

sendFrame :: Frame -> WebSockets ()

A low-level function to send an arbitrary frame over the wire.

receiveMessage :: WebSockets (Maybe Message)

Receive a message

sendMessage :: Message -> WebSockets ()

Send a message

receiveDataMessage :: WebSockets (Maybe DataMessage)

Receive an application message. Automatically respond to control messages.

sendDataMessage :: DataMessage -> WebSockets ()

Send an application-level message.

receiveData :: WebSocketsData a => WebSockets (Maybe a)

Receive a message, treating it as data transparently

sendTextData :: WebSocketsData a => a -> WebSockets ()

Send a text message

sendBinaryData :: WebSocketsData a => a -> WebSockets ()

Send some binary data

Advanced sending

type Encoder a = Mask -> a -> Builder

The inverse of a parser

type Sender a = Encoder a -> a -> IO ()

For asynchronous sending

send :: Encoder a -> a -> WebSockets ()

Low-level sending with an arbitrary Encoder

getSender :: WebSockets (Sender a)

In case the user of the library wants to do asynchronous sending to the socket, he can extract a Sender and pass this value around, for example, to other threads.

response :: Encoder Response

Encode an HTTP upgrade response

frame :: Encoder Frame

Encode a frame

message :: Encoder Message

Encode a message

controlMessage :: Encoder ControlMessage

Encode a control message

dataMessage :: Encoder DataMessage

Encode an application message

textData :: WebSocketsData a => Encoder a

binaryData :: WebSocketsData a => Encoder a