Network.WebSockets

A new client connected to the server. We haven't accepted the connection yet, though.

Useful for e.g. inspecting the request path.

Accept a pending connection, turning it into a Connection.

This datatype allows you to set options for acceptRequestWith. It is strongly recommended to use defaultAcceptRequest and then modify the various fields, that way new fields introduced in the library do not break your code.

This function is like acceptRequest but allows you to set custom options using the AcceptRequest datatype.

Requires calling pendingStream and close.

Parameters that allow you to tweak how a request is rejected. Please use defaultRejectRequest and modify fields using record syntax so your code will not break when new fields are added.

Set options for a Connection. Please do not use this constructor directly, but rather use defaultConnectionOptions and then set the fields you want, e.g.:

myOptions = defaultConnectionOptions {connectionStrictUnicode = True}

This way your code does not break if the library introduces new fields.

The default connection options:

• Nothing happens when a pong is received.

• Compression is disabled.

• Lenient unicode decoding.

• 30 second timeout for connection establishment.

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.

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

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

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

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.

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

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

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

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.

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.

Send a ping

Request headers

A request with a body

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

List of subprotocols specified by the client, in order of preference. If the client did not specify a list of subprotocols, this will be the empty list.

A response including a body

HTTP response, without body.

The kind of message a server application typically deals with

Different control messages

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.

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.

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.

Various exceptions that can occur while receiving or transmitting messages

WebSockets application that can be ran by a server. Once this IO action finishes, the underlying socket is closed automatically.

Provides a simple server. This function blocks forever. Note that this is merely provided for quick-and-dirty or internal applications, but for real applications, you should use a real server.

For example:

• Performance is reasonable under load, but:

• No protection against DoS attacks is provided.

• No logging is performed.

• ...

Glue for using this package with real servers is provided by:

• https://hackage.haskell.org/package/wai-websockets

• https://hackage.haskell.org/package/websockets-snap

A version of runServer which allows you to customize some options.

Customizable version of runServer. Never returns until killed.

Please use the defaultServerOptions combined with record updates to set the fields you want. This way your code is unlikely to break on future changes.

Create a standardized socket on which you can listen for incomming connections. Should only be used for a quick and dirty solution! Should be preceded by the call Network.Socket.withSocketsDo.

Turns a socket, connected to some client, into a PendingConnection. The PendingConnection should be closed using pendingStream and close later.

More general version of makePendingConnection for Stream instead of a Socket.

A client application interacting with a single server. Once this IO action finished, the underlying socket is closed automatically.

Build a new Connection from the client's point of view.

WARNING: Be sure to call close on the given Stream after you are done using the Connection in order to properly close the communication channel. runClientWithStream handles this for you, prefer to use it when possible.

Options for ping-pong

Make sure that the ping interval is less than the pong timeout, for example N/2.

Default options for ping-pong

Ping every 15 seconds, timeout after 30 seconds

Run an application with ping-pong enabled. Raises PongTimeout if a pong is not received.

Can used with Client and Server connections.

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.

Note that usually you want to use withPingPong to timeout the connection if a pong is not received.

DEPRECATED: Use withPingThread instead.

Forks a ping thread, sending a ping message every n seconds over the connection. The thread dies silently if the connection crashes or is closed.

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.