Network.EngineIO

Documentation

Network.EngineIO is a Haskell of implementation of Engine.IO, a realtime framework for the web. Engine.IO provides you with an abstraction for doing real-time communication between a server and a client. Engine.IO abstracts the framing and transport away, so that you can have real-time communication over long-polling HTTP requests, which are later upgraded to web sockets, if available.

Network.EngineIO needs to be provided with a ServerAPI in order to be ran. ServerAPI informs us how to fetch request headers, write HTTP responses to the client, and run web socket applications. Hackage contains implementations of ServerAPI as:

• engine-io-snap for Snap.
• engine-io-yesod for Yesod.

If you write your own implementation of ServerAPI, please share it on Hackage and I will link to it from here.

Example Usage

A simple echo server is easy to write with Engine.IO. The following imports will be required:

import Control.Concurrent.STM
import Control.Monad (forever)
import Network.EngineIO
import Network.EngineIO.Snap
import Snap.Http.Server

Next, we write the implementation of our per-socket processing logic. For this application we simply receive from the socket, and then send the result back to the socket. We wrap this all in forever as this connection should never terminate.

handleSocket :: Socket -> IO ()
handleSocket s = forever $ atomically $
  receive s >>= send s

Finally, we add a main function to our application to launch it. I'll use engine-io-snap as my server implementation:

main :: IO ()
main = do
  eio <- initialize
  quickHttpServe $ handler eio handleSocket

This means that any URL works as the Engine.IO server, which is sufficient for our example. In a real production application, you will probably want to nest the handler under /engine.io.

Running Engine.IO applications

initialize :: IO EngineIO

initialize initializes a new Engine.IO server. You can later serve this session by using handler.

handler :: MonadIO m => EngineIO -> (Socket -> m SocketApp) -> ServerAPI m -> m ()

Build the necessary handler for Engine.IO. The result of this function is a computation that you should serve under the engine.io path.

handler takes a function as an argument that is called every time a new session is created. This function runs in the m monad, so you have access to initial web request, which may be useful for performing authentication or collecting cookies. This function then returns a ServerApp, describing the main loop and an action to perform on socket disconnection.

data EngineIO

An opaque data type representing an open Engine.IO server.

data ServerAPI m

A dictionary of functions that Engine.IO needs in order to provide communication channels.

Constructors

ServerAPI

Fields

srvGetQueryParams :: m (HashMap ByteString [ByteString])

Retrieve the HashMap of query parameters in the request path to their zero-or-more values.

srvTerminateWithResponse :: Int -> ByteString -> Builder -> forall a. m a

Send a response with the given status code, content type and body. This should also terminate the web request entirely, such that further actions in m have no effect.

srvParseRequestBody :: forall a. Parser a -> m (Either String a)

Run a Parser against the request body.

srvGetRequestMethod :: m ByteString

Get the request method of the current request. The request method should be in uppercase for standard methods (e.g., GET).

srvRunWebSocket :: ServerApp -> m ()

Upgrade the current connection to run a WebSocket action.

data SocketApp

The application to run for the duration of a connected socket.

Constructors

SocketApp

Fields

saApp :: IO ()

An IO action to run for the duration of the socket's lifetime. If this action terminates, the connection will be closed. You will likely want to loop forever and block as appropriate with receive.

saOnDisconnect :: IO ()

An action to execute when the connection is closed, either by saApp terminating, or the client disconnecting.

Interacting with Sockets

send :: Socket -> PacketContent -> STM ()

Send a packet to the client. This is a non-blocking write.

receive :: Socket -> STM PacketContent

Receive data from the client, blocking if the input queue is empty.

data Socket

A connected Engine.IO session.

Instances

Eq Socket

Ord Socket

type SocketId = ByteString

The type of unique Engine.IO sessions. This is currently a base64-encoded random identifier.

socketId :: Socket -> SocketId

getOpenSockets :: EngineIO -> STM (HashMap SocketId Socket)

Retrieve a list of all currently open Engine.IO sessions.

dupRawReader :: Socket -> IO (STM Packet)

Create a new IO action to read the socket's raw incoming communications. The result of this call is iteslf an STM action, which will called will return the next unread incoming packet (or block). This provides you with a separate channel to monitor incoming communications. This may useful to monitor to determine if the socket has activity.

This is a fairly low level operation, so you will receive *all* packets - including pings and other control codes.

The Engine.IO Protocol

Packets

data Packet

A single Engine.IO packet.

Constructors

Packet !PacketType !PacketContent

Instances

Eq Packet

Show Packet

parsePacket :: Parser Packet

Parse bytes as an Packet assuming the packet contents extends to the end-of-input.

encodePacket

Arguments

:: Bool

If true, all bytes can be used. Otherwise, the packet will be base 64 encoded.

-> Packet

-> Builder

Encode a Packet to a Builder. The first argument determines whether or not binary is supported - if not, binary data will be base 64 encoded.

data PacketType

The possible packet types, as mentioned in the Engine.IO protocol documentation

Instances

Bounded PacketType

Enum PacketType

Eq PacketType

Read PacketType

Show PacketType

Packet Contents

data PacketContent

The contents attached to a packet. Engine.IO makes a clear distinction between binary data and text data. Clients will receive binary data as a Javascript ArrayBuffer, where as TextPackets will be received as UTF-8 strings.

Constructors

BinaryPacket !ByteString

TextPacket !Text

Instances

Eq PacketContent

Show PacketContent

Payloads

newtype Payload

A Payload is a stream of 0-or-more Packets.

Constructors

Payload (Vector Packet)

Instances

Eq Payload

Show Payload

parsePayload :: Parser Payload

Parse a stream of bytes into a Payload.

encodePayload

Arguments

:: Bool

If true, all bytes can be used. Otherwise, the packet will be base 64 encoded.

-> Payload

-> Builder

Encode a Payload to a Builder. As with encodePacket, the first argument determines whether or not binary transmission is supported.

Transport types

data TransportType

The possible types of transports Engine.IO supports.

Constructors

Polling

XHR long polling.

Websocket

HTML 5 websockets.

Instances

Eq TransportType

Show TransportType

ToJSON TransportType

parseTransportType :: Text -> Maybe TransportType

Attempt to parse a TransportType from its textual representation.