Copyright	(c) 2016 Michael Walker
License	MIT
Maintainer	Michael Walker <mike@barrucadu.co.uk>
Stability	experimental
Portability	portable
Safe Haskell	None
Language	Haskell2010

Network.Pusher.WebSockets

Contents

Pusher
- Connection
Re-exports

Description

Pusher has two APIs: the REST API and the websocket API. The websocket API, which is what this package implements, is used by clients primarily to subscribe to channels and receive events. This library encourages a callback-style approach to Pusher, where the pusherWithOptions function is used to subscribe to some channels and bind some event handlers, and then block until the connection is closed.

A small example, which simply prints all received events:

let key = "your-key"
let channels = ["your", "channels"]

-- Connect to Pusher with your key, SSL, and the us-east-1 region,
-- and do some stuff.
pusherWithOptions (defaultOptions key) $ do
  -- Subscribe to all the channels
  mapM_ subscribe channels

  -- Bind an event handler for all events on all channels which
  -- prints the received JSON.
  bindAll Nothing (liftIO . print)

  -- Wait for user input and then close the connection.
  liftIO (void getLine)
  disconnectBlocking

See https://pusher.com/docs/pusher_protocol for details of the protocol.

Synopsis

Pusher

data PusherClient a Source

A value of type PusherClient a is a computation with access to a connection to Pusher which, when executed, may perform Pusher-specific actions such as subscribing to channels and receiving events, as well as arbitrary I/O.

Instances

Monad PusherClient Source
Functor PusherClient Source
Applicative PusherClient Source
MonadIO PusherClient Source

data PusherClosed Source

Thrown if attempting to communicate with Pusher after the connection has been closed.

If the server closed the connection, the error code is included. See the 4000-4099 error codes on https://pusher.com/docs/pusher_protocol.

Constructors

PusherClosed (Maybe Word16)

Instances

Eq PusherClosed Source
Ord PusherClosed Source
Read PusherClosed Source
Show PusherClosed Source
Exception PusherClosed Source

newtype AppKey Source

Your application's API key.

Constructors

AppKey String

Instances

Eq AppKey Source
Ord AppKey Source
Read AppKey Source
Show AppKey Source
IsString AppKey Source
NFData AppKey Source

data Options Source

Constructors

Options

Fields

appKey :: AppKey: The application key.
encrypted :: Bool: If the connection should be made over an encrypted connection. Defaults to True.
authorisationURL :: Maybe String: The URL which will return the authentication signature needed for private and presence channels. If not given, private and presence channels cannot be used. Defaults to Nothing.
cluster :: Cluster: Allows connecting to a different cluster by setting up correct hostnames for the connection. This parameter is mandatory when the app is created in a different cluster to the default us-east-1. Defaults to MT1.
pusherURL :: Maybe (HostName, PortNumber, String): The host, port, and path to use instead of the standard Pusher servers. If set, the cluster is ignored. Defaults to Nothing.

Instances

Eq Options Source
Ord Options Source
Show Options Source
NFData Options Source

data Cluster Source

Clusters correspond to geographical regions where apps can be assigned to.

Constructors

MT1	The us-east-1 cluster.
EU	The eu-west-1 cluster.
AP1	The ap-southeast-1 cluster.

Instances

Bounded Cluster Source
Enum Cluster Source
Eq Cluster Source
Ord Cluster Source
Read Cluster Source
Show Cluster Source
NFData Cluster Source

pusherWithOptions :: Options -> PusherClient a -> IO a Source

Connect to Pusher.

This does NOT automatically disconnect from Pusher when the supplied action terminates, so either the action will need to call disconnect or disconnectBlocking as the last thing it does, or one of the event handlers will need to do so eventually.

defaultOptions :: AppKey -> Options Source

See Options field documentation for what is set here.

Connection

data ConnectionState Source

The state of the connection. Events are sent when the state is changed.

Constructors

Initialized	Initial state. No event is emitted.
Connecting	Trying to connect. This state will also be entered when trying to reconnect after a connection failure. Emits the `"connecting"` event.
Connected	The connection is established and authenticated with your app. Emits the `"connected"` event.
Unavailable	The connection is temporarily unavailable. The network connection is down, the server is down, or something is blocking the connection. Emits the `"unavailable"` event and then enters the `Connecting` state again.
Disconnected (Maybe Word16)	The connection has been closed by the client, or the server indicated an error which cannot be resolved by reconnecting with the same settings. If the server closed the connection, the error code is included. See the 4000-4099 error codes on https://pusher.com/docs/pusher_protocol. Emits the `"disconnected"` event and then kills all forked threads.

Instances

Eq ConnectionState Source
Ord ConnectionState Source
Read ConnectionState Source
Show ConnectionState Source

connectionState :: PusherClient ConnectionState Source

Get the connection state.

disconnect :: PusherClient () Source

Gracefully close the connection. The connection will remain open and events will continue to be processed until the server accepts the request.

disconnectBlocking :: PusherClient () Source

Like disconnect, but block until the connection is actually closed.

blockUntilDisconnected :: PusherClient () Source

Block until the connection is closed (but do not initiate a disconnect).

This is useful if you run pusherWithOptions in the main thread to prevent the program from terminating until one of your event handlers decides to disconnect.

Re-exports

module Network.Pusher.WebSockets.Channel

module Network.Pusher.WebSockets.Event

module Network.Pusher.WebSockets.Util