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

Safe Haskell | None
Language | Haskell98

Network.WebSockets.Connection

Description

This module exposes connection internals and should only be used if you really know what you are doing.

Synopsis

- data PendingConnection = PendingConnection {
  - pendingOptions :: !ConnectionOptions
  - pendingRequest :: !RequestHead
  - pendingOnAccept :: !(Connection -> IO ())
  - pendingStream :: !Stream
  }
- acceptRequest :: PendingConnection -> IO Connection
- data AcceptRequest = AcceptRequest {
  - acceptSubprotocol :: !(Maybe ByteString)
  - acceptHeaders :: !Headers
  }
- defaultAcceptRequest :: AcceptRequest
- acceptRequestWith :: PendingConnection -> AcceptRequest -> IO Connection
- rejectRequest :: PendingConnection -> ByteString -> IO ()
- data Connection = Connection {
  - connectionOptions :: !ConnectionOptions
  - connectionType :: !ConnectionType
  - connectionProtocol :: !Protocol
  - connectionParse :: !(IO (Maybe Message))
  - connectionWrite :: !([Message] -> IO ())
  - connectionSentClose :: !(IORef Bool)
  }
- data ConnectionOptions = ConnectionOptions {
  - connectionOnPong :: !(IO ())
  }
- defaultConnectionOptions :: ConnectionOptions
- receive :: Connection -> IO Message
- receiveDataMessage :: Connection -> IO DataMessage
- receiveData :: WebSocketsData a => Connection -> IO a
- send :: Connection -> Message -> IO ()
- sendDataMessage :: Connection -> DataMessage -> IO ()
- sendDataMessages :: Connection -> [DataMessage] -> IO ()
- sendTextData :: WebSocketsData a => Connection -> a -> IO ()
- sendTextDatas :: WebSocketsData a => Connection -> [a] -> IO ()
- sendBinaryData :: WebSocketsData a => Connection -> a -> IO ()
- sendBinaryDatas :: WebSocketsData a => Connection -> [a] -> IO ()
- sendClose :: WebSocketsData a => Connection -> a -> IO ()
- sendCloseCode :: WebSocketsData a => Connection -> Word16 -> a -> IO ()
- sendPing :: WebSocketsData a => Connection -> a -> IO ()
- forkPingThread :: Connection -> Int -> IO ()

# Documentation

data PendingConnection #

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

Constructors

PendingConnection |
Fields pendingOptions :: !ConnectionOptions Options, passed as-is to the `Connection` pendingRequest :: !RequestHead Useful for e.g. inspecting the request path. pendingOnAccept :: !(Connection -> IO ()) One-shot callback fired when a connection is accepted, i.e., *after* the accepting response is sent to the client. pendingStream :: !Stream Input/output stream

acceptRequest :: PendingConnection -> IO Connection #

Accept a pending connection, turning it into a `Connection`.

data AcceptRequest #

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.

Constructors

AcceptRequest |
Fields acceptSubprotocol :: !(Maybe ByteString) The subprotocol to speak with the client. If `pendingSubprotcols` is non-empty, `acceptSubprotocol` must be one of the subprotocols from the list. acceptHeaders :: !Headers Extra headers to send with the response.

defaultAcceptRequest :: AcceptRequest #

acceptRequestWith :: PendingConnection -> AcceptRequest -> IO Connection #

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

rejectRequest :: PendingConnection -> ByteString -> IO () #

data Connection #

Constructors

Connection |
Fields connectionOptions :: !ConnectionOptions connectionType :: !ConnectionType connectionProtocol :: !Protocol connectionParse :: !(IO (Maybe Message)) connectionWrite :: !([Message] -> IO ()) connectionSentClose :: !(IORef Bool) According to the RFC, both the client and the server MUST send a close control message to each other. Either party can initiate the first close message but then the other party must respond. Finally, the server is in charge of closing the TCP connection. This IORef tracks if we have sent a close message and are waiting for the peer to respond.

data ConnectionOptions #

Set options for a `Connection`.

Constructors

ConnectionOptions |
Fields connectionOnPong :: !(IO ()) Whenever a `pong` is received, this IO action is executed. It can be used to tickle connections or fire missiles.

defaultConnectionOptions :: ConnectionOptions #

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 `DataMessage`

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

Send a collection of `DataMessage`s

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

Send a message as text

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

Send a collection of messages as text

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

Send a message as binary data

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

Send a collection of messages as binary data

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

forkPingThread :: Connection -> Int -> IO () #

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.