Copyright	(c) Will Sewell 2016
License	MIT
Maintainer	[email protected]
Stability	stable
Safe Haskell	None
Language	Haskell2010

Network.Pusher

Contents

Data types
- Settings
- Main Pusher type
HTTP Requests
- Trigger events
  - Event type for triggerBatch
- Channel queries
Authentication
Errors
Webhooks

Description

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.

Synopsis

data Settings = Settings {
- pusherAddress :: Address
- pusherAppID :: Word32
- pusherToken :: Token
- pusherUseTLS :: Bool
}
defaultSettings :: Settings
data Token = Token {
- tokenKey :: ByteString
- tokenSecret :: ByteString
}
data Address
- = Cluster ByteString
- | HostPort ByteString Word16
data Pusher
newPusher :: MonadIO m => Settings -> m Pusher
newPusherWithConnManager :: Manager -> Settings -> Pusher
trigger :: MonadIO m => Pusher -> [Text] -> Text -> Text -> Maybe Text -> m (Either PusherError ())
triggerBatch :: MonadIO m => Pusher -> [Event] -> m (Either PusherError ())
data Event = Event {
- eventChannel :: Text
- eventName :: Text
- eventData :: Text
- eventSocketId :: Maybe Text
}
channels :: MonadIO m => Pusher -> Text -> ChannelsInfoQuery -> m (Either PusherError ChannelsInfo)
channel :: MonadIO m => Pusher -> ByteString -> ChannelInfoQuery -> m (Either PusherError FullChannelInfo)
users :: MonadIO m => Pusher -> ByteString -> m (Either PusherError Users)
authenticatePresence :: ToJSON a => Pusher -> Text -> Text -> a -> ByteString
authenticatePrivate :: Pusher -> Text -> Text -> ByteString
data PusherError
- = Non200Response {
  - non200ResponseStatusCode :: Word16
  - non200ResponseBody :: Text
  }
- | InvalidResponse Text
parseWebhookPayload :: Pusher -> [(ByteString, ByteString)] -> ByteString -> Maybe WebhookPayload
data WebhookEv
- = ChannelOccupiedEv {
  - onChannel :: Text
  }
- | ChannelVacatedEv {
  - onChannel :: Text
  }
- | MemberAddedEv {
  - onChannel :: Text
  - withUser :: User
  }
- | MemberRemovedEv {
  - onChannel :: Text
  - withUser :: User
  }
- | ClientEv {
  - onChannel :: Text
  - clientEvName :: Text
  - clientEvBody :: Maybe Value
  - withSocketId :: Text
  - withPossibleUser :: Maybe User
  }
data WebhookPayload = WebhookPayload {
- xPusherKey :: ByteString
- xPusherSignature :: ByteString
- webhooks :: Webhooks
}
data Webhooks = Webhooks {
- timeMs :: Word64
- webhookEvs :: [WebhookEv]
}
parseAppKeyHdr :: ByteString -> ByteString -> Maybe ByteString
parseAuthSignatureHdr :: ByteString -> ByteString -> Maybe ByteString
parseWebhooksBody :: ByteString -> Maybe Webhooks
verifyWebhooksBody :: ByteString -> ByteString -> ByteString -> Bool
parseWebhookPayloadWith :: (ByteString -> Maybe ByteString) -> [(ByteString, ByteString)] -> ByteString -> Maybe WebhookPayload

Data types

Settings

data Settings Source #

All the required configuration needed to interact with the API.

Constructors

Settings
Fields pusherAddress :: Address pusherAppID :: Word32 pusherToken :: Token pusherUseTLS :: Bool

Instances

Instances details

FromJSON Settings Source #
Instance details Defined in Network.Pusher.Data Methods parseJSON :: Value -> Parser Settings # parseJSONList :: Value -> Parser [Settings] # omittedField :: Maybe Settings #

defaultSettings :: Settings Source #

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 Source #

A Channels key and secret pair for a particular app.

Constructors

Token
Fields tokenKey :: ByteString tokenSecret :: ByteString

Instances

Instances details

FromJSON Token Source #
Instance details Defined in Network.Pusher.Data Methods parseJSON :: Value -> Parser Token # parseJSONList :: Value -> Parser [Token] # omittedField :: Maybe Token #

data Address Source #

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 Source #

The core handle to the Pusher API.

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

Use this to get a Pusher instance.

newPusherWithConnManager :: Manager -> Settings -> Pusher Source #

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 Source #

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 Source #

Arguments

:: MonadIO m
=> Pusher
-> [Event]	The list of events to trigger.
-> m (Either PusherError ())

Trigger multiple events.

Event type for `triggerBatch`

data Event Source #

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

Instances details

ToJSON Event Source #
Instance details Defined in Network.Pusher.Data Methods toJSON :: Event -> Value # toEncoding :: Event -> Encoding # toJSONList :: [Event] -> Value # toEncodingList :: [Event] -> Encoding # omitField :: Event -> Bool #

Channel queries

channels Source #

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 Source #

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) Source #

Get a list of users in a presence channel.

Authentication

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

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

authenticatePrivate :: Pusher -> Text -> Text -> ByteString Source #

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

Errors

data PusherError Source #

Constructors

Non200Response	Received non 200 response code from Pusher.
Fields non200ResponseStatusCode :: Word16 non200ResponseBody :: Text
InvalidResponse Text	Received unexpected data from Pusher.

Instances

Instances details

Exception PusherError Source #
Instance details Defined in Network.Pusher.Error Methods toException :: PusherError -> SomeException # fromException :: SomeException -> Maybe PusherError # displayException :: PusherError -> String # backtraceDesired :: PusherError -> Bool #
Show PusherError Source #
Instance details Defined in Network.Pusher.Error Methods showsPrec :: Int -> PusherError -> ShowS # show :: PusherError -> String # showList :: [PusherError] -> ShowS #

Webhooks

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

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 Source #

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

Instances details

FromJSON WebhookEv Source #
Instance details Defined in Network.Pusher.Webhook Methods parseJSON :: Value -> Parser WebhookEv # parseJSONList :: Value -> Parser [WebhookEv] # omittedField :: Maybe WebhookEv #
Show WebhookEv Source #
Instance details Defined in Network.Pusher.Webhook Methods showsPrec :: Int -> WebhookEv -> ShowS # show :: WebhookEv -> String # showList :: [WebhookEv] -> ShowS #
Eq WebhookEv Source #
Instance details Defined in Network.Pusher.Webhook Methods (==) :: WebhookEv -> WebhookEv -> Bool # (/=) :: WebhookEv -> WebhookEv -> Bool #

data WebhookPayload Source #

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

Instances details

Show WebhookPayload Source #
Instance details Defined in Network.Pusher.Webhook Methods showsPrec :: Int -> WebhookPayload -> ShowS # show :: WebhookPayload -> String # showList :: [WebhookPayload] -> ShowS #
Eq WebhookPayload Source #
Instance details Defined in Network.Pusher.Webhook Methods (==) :: WebhookPayload -> WebhookPayload -> Bool # (/=) :: WebhookPayload -> WebhookPayload -> Bool #

data Webhooks Source #

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

Instances details

FromJSON Webhooks Source #
Instance details Defined in Network.Pusher.Webhook Methods parseJSON :: Value -> Parser Webhooks # parseJSONList :: Value -> Parser [Webhooks] # omittedField :: Maybe Webhooks #
Show Webhooks Source #
Instance details Defined in Network.Pusher.Webhook Methods showsPrec :: Int -> Webhooks -> ShowS # show :: Webhooks -> String # showList :: [Webhooks] -> ShowS #
Eq Webhooks Source #
Instance details Defined in Network.Pusher.Webhook Methods (==) :: Webhooks -> Webhooks -> Bool # (/=) :: Webhooks -> Webhooks -> Bool #