shove

HTTP and WebSocket clients for shove.io

Installation

gem install shove

Using Shove

To use shove, you must first create a Shove::App object.

app = Shove::App.new(
  app_id: "myappid",
  app_key: "myappkey"
)

Get your app_id, and app_key at shove.io

Using the HTTP Client

The HTTP client gives publishing and access control capabilities without a persistent WebSocket connection. The HTTP client cannot act as a subscriber.

Publish to a channel

app.channel("notifications").publish("Hello World!")

Publish Direct

app.channel("direct:buddy").publish("Hey buddy")

Publish and handle the HTTP response

app.channel("notifications").publish("...") do |response|
  if reponse.error?
    puts "#{response.status} - #{response.error}"
  end
end

You can control access to your apps and channels, allowing for granular security.

Grant subscription on the notifications channel

app.channel("notifications").grant_subscribe("dan@shove.io")

Grant subscription on all channels to client dan

app.channel("*").grant_subscribe("dan@shove.io")

Grant publishing on chat:client_22733 channel to client dan

app.channel("chat:client_22733").grant_publish("dan")

Deny publishing on chat:client_22733 channel to dan

app.channel("chat:client_22733").deny_publish("dan")

Sometimes it's easier to give out an access key to a specific channel, which is also an option.

Channel Keys

You can generate channel keys which allow clients of your shove network to subscribe or publish to specific channels.

Example: Create a key for the channel groups:788

key = app.channel_key "group:788"

Subscribe only

key = app.subscribe_key "group:788"

This functionality becomes useful when you want to give you site users access. In your view:

var channel = "<%= @channel %>";
var key = "<%= @app.channel_key(@channel) %>";

Note: Channel keys are based off the app key (master key). So, in order for them to work, you must specify the app key in your app.

app = Shove::App.new(
  app_id: "myappid",
  app_key: "myappkey"
)

Using the WebSocket Client

You can also use the gem to run a persistent client. This requires that you are running an EventMachine reactor.

EM.run do
  app = Shove::App.new(
    app_id "myapp",
    app_key: "myappkey"
  )

  client = app.connect
end

Client events

Connect event:

client.on("connect") do
  # Connected!
end

Disconnect event:

client.on("disconnect") do
  # disconnect code
end

Error event:

client.on("error") do |error|
  log.error "Shove error: #{error}"
end

Connect denied event: (don't forget to authorize)

client.on("connect_denied") do |id|
  client.authorize
end

Channels & Publish and Subscribe

Subscribe to a channel or get a subscribed channel

channel = client.channel("channel")

Handle a message published on a channel

channel.on("message") do |msg|
  widget.append msg
end

Handle the subscribe callback for a given channel

channel.on("subscribe") do
  # channel is subscribed
end

If the app denies subscriptions by default, you should handle the subscribe_denied event

channel.on("subscribe_denied") do
  channel.authorize "key"
  channel.subscribe
end

You can get the binding for a callback and cancel it

binding = channel.on("message") do |msg|
  # important stuff here
end

binding.cancel

Handle a direct message

client.channel("direct").on("message") do |msg|
  # handle direct message
end

Unsubscribe from a channel, optionally handle the event

channel.on("unsubscribe_complete") do
end

channel.unsubscribe

Publish a message from the WebSocket client

channel.publish("hi!")

# publish json
channel.publish(obj.to_json)

WebSocket Client without App Key

If you are connecting to someone elses app and have limited scope and access, you can get by.

EM.run do
  app = Shove::App.new(
    app_id "myapp"
  )

  client = app.connect "connect-key"

  channel = client.channel("channel")
  channel.auth "channelkey"

  channel.on("message") do |message|
    puts message
  end
end