A scala library to interact with the Pusher HTTP API.
This package lets you trigger events to your client and query the state of your Pusher channels. When used with a server, you can validate Pusher webhooks and authenticate private- or presence-channels.
In order to use this library, you need to have a free account on http://pusher.com. After registering, you will need the application credentials for your app.
libraryDependencies += "com.pusher" %% "pusher-http-scala" % <version>
where <version> is the version of the library you'd like to use.
Check out PusherExample.scala inside the example folder. It has some basic code to get started quickly.
There easiest way to configure the library is by creating a new Pusher instance:
val pusher = new Pusher("YOUR_APP_ID", "YOUR_KEY", "YOUR_SECRET")
val result = pusher.trigger(List("test_channel"), "test_event", "test_event")
result match {
case Left(error) => println(error)
case Right(res) => println(res)
}Note that this library does not throw any exceptions. A more functional approach is used by preferring the use of
Either[Left, Right] type. Return values are wrapped in a PusherResponse type which might contain either an error
on the left or the result on the right. It is then a case of using pattern matching to act on the result.
It is possible to trigger an event on one or more channels. Channel names can contain only characters which are alphanumeric, _ or `-`` and have to be at most 200 characters long. Event name can be at most 200 characters long too.
| Argument | Description |
|---|---|
channels String |
The name of the channel you wish to trigger on. |
event String |
The name of the event you wish to trigger |
data String |
The payload you wish to send. |
socketId Option[String] |
Optional socket id to event the recipient |
pusher.trigger(List("greeting_channel"), "say_hello", "{"hello": "world"}")You can also exclude a recipient whose connection has that socket_id from receiving the event. You can read more here.
pusher.trigger(List("a_channel"), "event", "hola", Some("123.12"))Application security is very important so Pusher provides a mechanism for authenticating a user’s access to a channel at the point of subscription.
This can be used both to restrict access to private channels, and in the case of presence channels notify subscribers of who else is also subscribed via presence events.
This library provides a mechanism for generating an authentication signature to send back to the client and authorize them.
For more information see our docs.
| Argument | Description |
|---|---|
channel String |
The channel to authenticate |
socketId String |
The assigned socket id |
customDataOpt Option[PresenceUser] |
Presence user data (only for presence channels) |
Returns a JSON string like so {"auth":"somekey:81a249f5aae14a7ffdef6574bc7aceeac10472f79e1b74283d3306d4a513bb89"}
pusher.authenticate("private-test-channel", "123.12", None)pusher.authenticate("presence-channel-2", "123.12", Some(PresenceUser("123", Map("key" -> "value"))))This library allows you to query our API to retrieve information about your application's channels, their individual properties, and, for presence-channels, the users currently subscribed to them.
| Argument | Description |
|---|---|
prefixFilterOpt Option[String] |
A map with query options. A key with "filter_by_prefix" will filter the returned channels. To get number of users subscribed to a presence-channel, specify an "info" key with value "user_count". |
attributesOpt: Option[List[String]] |
A list of attributes that you want returned for that channel |
Returns a PusherResponse[ChannelsInfoResponse](Either[PusherError, ChannelsInfoResponse]).
val result = pusher.channelsInfo(Some("presence-"), Some("user_count"))
result match {
case Left(error) => println(s"Yikes, there was an error: ${error.message}")
case Right(res) => println(res) // Right(ChannelsInfoResponse(Map("presence-foobar" -> ChannelDetails(user_count: 1))))
}| Argument | Description |
|---|---|
channel String |
The name of the channel |
attributes Option[List[String]] |
A list of attributes you'd like to request |
Returns a PusherResponse[ChannelInfoResponse](Either[PusherError, ChannelInfoResponse]).
val result = pusher.channelInfo(channel: "some-channel", None)
result match {
case Left(error) => println(s"Yikes, there was an error: ${error.message}")
case Right(res) => println(res) // Right(ChannelInfoResponse(occupied = true, None, None))
}| Argument | Description |
|---|---|
channel String |
The channel name |
Returns a PusherResponse[UserssInfoResponse](Either[PusherError, UsersInfoResponse]).
val result = pusher.usersInfo(channel: "some-channel")
result match {
case Left(error) => println(s"Yikes, there was an error: ${error.message}")
case Right(res) => println(res) // Right(UsersInfoResponse(List(UserDetails("1"))))
}On your dashboard, you can set up webhooks to POST a payload to your server after certain events. Such events include channels being occupied or vacated, members being added or removed in presence-channels, or after client-originated events. For more information see https://pusher.com/docs/webhooks.
This library provides a mechanism for checking that these POST requests are indeed from Pusher, by checking the token and authentication signature in the header of the request.
| Argument | Description |
|---|---|
key String |
Key from the X-Pusher-Key header |
signature String |
Signature from the X-Pusher-Signature header |
body String |
Body of the webhook (JSON string) |
Returns a PusherResponse[WebhookResponse](Either[PusherError, WebhookResponse])
There are a number of custom types used and can be found in the Types.scala file here
| Feature | Supported |
|---|---|
| Trigger event on single channel | ✔ |
| Trigger event on multiple channels | ✔ |
| Excluding recipients from events | ✔ |
| Authenticating private channels | ✔ |
| Authenticating presence channels | ✔ |
| Get the list of channels in an application | ✔ |
| Get the state of a single channel | ✔ |
| Get a list of users in a presence channel | ✔ |
| WebHook validation | ✔ |
| Heroku add-on support | ✘ |
| Debugging & Logging | ✘ |
| Cluster configuration | ✔ |
| Timeouts | ✘ |
| HTTPS | ✔ |
| HTTP Proxy configuration | ✘ |
| HTTP KeepAlive | ✘ |
These are helpers that have been implemented to to ensure interactions with the HTTP API only occur if they will not be rejected e.g. channel naming conventions.
| Helper Functionality | Supported |
|---|---|
| Channel name validation | ✔ |
| Limit to 10 channels per trigger | ✔ |
| Limit event name length to 200 chars | ✔ |
Feel more than free to fork this repo, improve it in any way you'd prefer, and send us a pull request :)
Run tests using sbt Simply type:
$ sbt test
This code is free to use under the terms of the MIT license.