Network.Pusher

Exposes the functions necessary for interacting with the Pusher Channels HTTP API, as well as functions for generating auth signatures for private and presence channels.

First create a Settings. The easiest way of doing this is by using defaultSettings. From that you can use newPusher to create a Pusher instance and then call the functions defined in this module to make the HTTP requests.

If any of the requests fail, the return values of the functions will result in a Left PusherError when run.

An example of how you would use these functions:

  let
    settings =
      defaultSettings
        { pusherAddress = Cluster "mt1",
          pusherAppID = 123,
          pusherToken = Token "wrd12344rcd234" "124df34d545v"
        }
  pusher <- newPusher settings

  result <-
    trigger pusher ["my-channel"] "my-event" "my-data" Nothing

  case result of
    Left e -> putStrLn $ displayException e
    Right resp -> print resp

There are simple working examples in the example/ directory.

See https://pusher.com/docs/channels/server_api/http-api for more detail on the HTTP requests.

Data types

Settings

data Settings

All the required configuration needed to interact with the API.

Constructors

Settings

Fields

• pusherAddress :: Address
• pusherAppID :: Word32
• pusherToken :: Token
• pusherUseTLS :: Bool

Instances

FromJSON Settings

Defined in Network.Pusher.Data

Methods

parseJSON :: Value -> Parser Settings

parseJSONList :: Value -> Parser [Settings]

defaultSettings :: Settings

A convenient way of creating an instance of Settings. Another benefit is it prevents breaking changes when fields are added to Settings, see https://www.yesodweb.com/book/settings-types.You must set pusherAppID and pusherToken. Currently pusherAddress defaults to the mt1 cluster.

Example:

defaultSettings
  { pusherAppID = 123,
    pusherToken = Token { tokenKey = "key", tokenSecret "secret" }
  }

data Token

A Channels key and secret pair for a particular app.

Constructors

Token

Fields

• tokenKey :: ByteString
• tokenSecret :: ByteString

Instances

FromJSON Token

Defined in Network.Pusher.Data

Methods

parseJSON :: Value -> Parser Token

parseJSONList :: Value -> Parser [Token]

data Address

Typically you will want to connect directly to a standard Pusher Channels Cluster.

Constructors

Cluster ByteString

The cluster the current app resides on. Common clusters include: mt1, eu, ap1, ap2.

HostPort ByteString Word16

Used to connect to a raw address:port.

Main Pusher type

data Pusher

The core handle to the Pusher API.

newPusher :: MonadIO m => Settings -> m Pusher

Use this to get a Pusher instance.

newPusherWithConnManager :: Manager -> Settings -> Pusher

Get a Pusher instance with a given connection manager. This can be useful if you want to share a connection with your application code.

HTTP Requests

Trigger events

trigger

Arguments

:: MonadIO m

=> Pusher

-> [Text]

The list of channels to trigger to.

-> Text

Event name.

-> Text

Event data. Often encoded JSON.

-> Maybe Text

An optional socket ID of a connection you wish to exclude.

-> m (Either PusherError ())

Trigger an event to one or more channels.

triggerBatch

Arguments

:: MonadIO m

=> Pusher

-> [Event]

The list of events to trigger.

-> m (Either PusherError ())

Trigger multiple events.

Event type for triggerBatch

data Event

Constructors

Event

Fields

• eventChannel :: Text

  Channel to trigger on.

• eventName :: Text

  Event name.

• eventData :: Text

  Event data. Often encoded JSON.

• eventSocketId :: Maybe Text

  An optional socket ID of a connection you wish to exclude.

Instances

ToJSON Event

Defined in Network.Pusher.Data

Methods

toJSON :: Event -> Value

toEncoding :: Event -> Encoding

toJSONList :: [Event] -> Value

toEncodingList :: [Event] -> Encoding

Channel queries

channels

Arguments

:: MonadIO m

=> Pusher

-> Text

A channel prefix you wish to filter on.

-> ChannelsInfoQuery

Data you wish to query for, currently just the user count.

-> m (Either PusherError ChannelsInfo)

The returned data.

Query a list of channels for information.

channel

Arguments

:: MonadIO m

=> Pusher

-> ByteString

-> ChannelInfoQuery

Can query user count and also subscription count (if enabled).

-> m (Either PusherError FullChannelInfo)

Query for information on a single channel.

users :: MonadIO m => Pusher -> ByteString -> m (Either PusherError Users)

Get a list of users in a presence channel.

Authentication

authenticatePresence :: ToJSON a => Pusher -> Text -> Text -> a -> ByteString

Generate an auth signature of the form "app_key:auth_sig" for a user of a presence channel.

authenticatePrivate :: Pusher -> Text -> Text -> ByteString

Generate an auth signature of the form "app_key:auth_sig" for a user of a private channel.

Errors

data PusherError

Constructors

Non200Response

Received non 200 response code from Pusher.

Fields

• non200ResponseStatusCode :: Word16
• non200ResponseBody :: Text

InvalidResponse Text

Received unexpected data from Pusher.

Instances

Exception PusherError

Defined in Network.Pusher.Error

Methods

toException :: PusherError -> SomeException

fromException :: SomeException -> Maybe PusherError

displayException :: PusherError -> String

Show PusherError

Defined in Network.Pusher.Error

Methods

showsPrec :: Int -> PusherError -> ShowS

show :: PusherError -> String

showList :: [PusherError] -> ShowS

Webhooks

parseWebhookPayload :: Pusher -> [(ByteString, ByteString)] -> ByteString -> Maybe WebhookPayload

Parse webhooks from a list of HTTP headers and a HTTP body given their app key matches the one in our Pusher Channels credentials and the webhook is correctly encrypted by the corresponding app secret.

data WebhookEv

A WebhookEv is one of several events Pusher may send to your server in response to events your users may trigger.

Constructors

ChannelOccupiedEv

A channel has become occupied. There is > 1 subscriber.

Fields

• onChannel :: Text

ChannelVacatedEv

A channel has become vacated. There are 0 subscribers.

Fields

• onChannel :: Text

MemberAddedEv

A new user has subscribed to a presence channel.

Fields

• onChannel :: Text
• withUser :: User

MemberRemovedEv

A user has unsubscribed from a presence channel.

Fields

• onChannel :: Text
• withUser :: User

ClientEv

A client has sent a named client event with some json body. They have a socket_id and a User if they were in a presence channel.

Fields

• onChannel :: Text
• clientEvName :: Text
• clientEvBody :: Maybe Value
• withSocketId :: Text
• withPossibleUser :: Maybe User

Instances

FromJSON WebhookEv

Defined in Network.Pusher.Webhook

Methods

parseJSON :: Value -> Parser WebhookEv

parseJSONList :: Value -> Parser [WebhookEv]

Show WebhookEv

Defined in Network.Pusher.Webhook

Methods

showsPrec :: Int -> WebhookEv -> ShowS

show :: WebhookEv -> String

showList :: [WebhookEv] -> ShowS

Eq WebhookEv

Defined in Network.Pusher.Webhook

Methods

(==) :: WebhookEv -> WebhookEv -> Bool

(/=) :: WebhookEv -> WebhookEv -> Bool

data WebhookPayload

Constructors

WebhookPayload

Fields

• xPusherKey :: ByteString

  Authentication header. The oldest active token is used, identified by this key.

• xPusherSignature :: ByteString

  A HMAC SHA256 formed by signing the payload with the tokens secret.

• webhooks :: Webhooks

Instances

Show WebhookPayload

Defined in Network.Pusher.Webhook

Methods

showsPrec :: Int -> WebhookPayload -> ShowS

show :: WebhookPayload -> String

showList :: [WebhookPayload] -> ShowS

Eq WebhookPayload

Defined in Network.Pusher.Webhook

Methods

(==) :: WebhookPayload -> WebhookPayload -> Bool

(/=) :: WebhookPayload -> WebhookPayload -> Bool

data Webhooks

A Webhook is received by POST request from Pusher to notify your server of a number of WebhookEvs. Multiple events are received under the same timestamp if batch events is enabled.

Constructors

Webhooks

Fields

• timeMs :: Word64
• webhookEvs :: [WebhookEv]

Instances

FromJSON Webhooks

Defined in Network.Pusher.Webhook

Methods

parseJSON :: Value -> Parser Webhooks

parseJSONList :: Value -> Parser [Webhooks]

Show Webhooks

Defined in Network.Pusher.Webhook

Methods

showsPrec :: Int -> Webhooks -> ShowS

show :: Webhooks -> String

showList :: [Webhooks] -> ShowS

Eq Webhooks

Defined in Network.Pusher.Webhook

Methods

(==) :: Webhooks -> Webhooks -> Bool

(/=) :: Webhooks -> Webhooks -> Bool

parseAppKeyHdr :: ByteString -> ByteString -> Maybe ByteString

Given a HTTP Header and its associated value, parse an app key.

parseAuthSignatureHdr :: ByteString -> ByteString -> Maybe ByteString

Given a HTTP Header and its associated value, parse an auth signature.

parseWebhooksBody :: ByteString -> Maybe Webhooks

Given a HTTP body, parse the contained webhooks.

verifyWebhooksBody :: ByteString -> ByteString -> ByteString -> Bool

Does a webhook body hash with our secret key to the given signature?

parseWebhookPayloadWith :: (ByteString -> Maybe ByteString) -> [(ByteString, ByteString)] -> ByteString -> Maybe WebhookPayload

Given a list of http header key:values, a http body and a lookup function for an apps secret, parse and validate a potential webhook payload.