websockets-0.8.2.3: A sensible and clean way to write WebSocket-capable servers in Haskell.

Safe HaskellNone

Network.WebSockets

Contents

Synopsis

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.

Main connection type

Options for connections

Sending and receiving messages

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.

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

data Request Source

A request with a body

Instances

data RequestHead Source

An HTTP request. The request body is not yet read.

Instances

data Response Source

A response including a body

Instances

data ResponseHead Source

HTTP response, without body.

Instances

WebSocket message types

data Message Source

The kind of message a server application typically deals with

Instances

data ControlMessage Source

Different control messages

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.

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

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.

runServerSource

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.

runClientSource

Arguments

:: String

Host

-> Int

Port

-> String

Path

-> ClientApp a

Client application

-> IO a 

runClientWithSource

Arguments

:: String

Host

-> Int

Port

-> String

Path

-> ConnectionOptions

Options

-> Headers

Custom headers to send

-> ClientApp a

Client application

-> IO a 

runClientWithSocketSource

Arguments

:: Socket

Socket

-> String

Host

-> String

Path

-> ConnectionOptions

Options

-> Headers

Custom headers to send

-> ClientApp a

Client application

-> IO a 

runClientWithStreamSource

Arguments

:: (InputStream ByteString, OutputStream ByteString)

Stream

-> String

Host

-> String

Path

-> ConnectionOptions

Connection options

-> Headers

Custom headers to send

-> ClientApp a

Client application

-> IO a