Skip to content
Branch: master
Go to file
Code

Latest commit

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

Action Cable Client

Gem Version Build Status Code Climate Test Coverage Dependency Status

This gem is a wrapper around websocket-eventmachine-client, and supports the Rails Action Cable protocol.

Usage

require 'action_cable_client'

EventMachine.run do

  uri = "ws://localhost:3000/cable/"
  client = ActionCableClient.new(uri, 'RoomChannel')
  # called whenever a welcome message is received from the server
  client.connected { puts 'successfully connected.' }

  # called whenever a message is received from the server
  client.received do | message |
    puts message
  end

  # Sends a message to the sever, with the 'action', 'speak'
  client.perform('speak', { message: 'hello from amc' })
end

This example is compatible with this version of a small Rails app with Action Cable

The available hooks to tie in to are:

  • disconnected {}
  • connected {}
  • subscribed {}
  • rejected {}
  • errored { |msg| }
  • received { |msg }
  • pinged { |msg| }

Connecting on initialization is also configurable.

client = ActionCableClient.new(uri, 'RoomChannel', false)
client.connect!(headers = {})
client.pinged do |_data|
  # you could track the time since you last received a ping, if you haven't
  # received one in a while, it could be that your client is disconnected.
end

To reconnect,

client.reconnect!

Sending additional params

params = { channel: 'RoomChannel', favorite_color: 'blue' }
client = ActionCableClient.new(uri, params)

then on the server end, in your Channel, params will give you:

{
       "channel" => "RoomChannel",
"favorite_color" => "blue"
}

Using Headers

params = { channel: 'RoomChannel', favorite_color: 'blue' }
client = ActionCableClient.new(uri, params, true, {
  'Authorization' => 'Bearer token'
})

Using TLS

Example given for client certificate authentication. See EventMachine::Connection#start_tls documentation for other options.

params = { channel: 'RoomChannel', favorite_color: 'blue' }
tls = {cert_chain_file: 'user.crt', private_key_file: 'user.key'}
client = ActionCableClient.new(uri, params, true, nil, tls)

Demo

Live Demo

Action Cable Client Demo on YouTube (1:41)

Here is a set of files in a gist that demonstrate how different action_cable_clients can communicate with eachother.

The Action Cable Protocol

There really isn't that much to this gem. :-)

  1. Connect to the Action Cable URL
  2. After the connection succeeds, send a subscribe message
  • The subscribe message JSON should look like this
    • {"command":"subscribe","identifier":"{\"channel\":\"MeshRelayChannel\"}"}
  • You should receive a message like this:
    • {"identifier"=>"{\"channel\":\"MeshRelayChannel\"}", "type"=>"confirm_subscription"}
  1. Once subscribed, you can send messages.
  • Make sure that the action string matches the data-handling method name on your ActionCable server.
  • Your message JSON should look like this:
    • {"command":"message","identifier":"{\"channel\":\"MeshRelayChannel\"}","data":"{\"to\":\"user1\",\"message\":\"hello from user2\",\"action\":\"chat\"}"}
    • Received messages should look about the same
  1. Notes:
  • Every message sent to the server has a command and identifier key.
  • The channel value must match the name of the channel class on the ActionCable server.
  • identifier and data are redundantly jsonified. So, for example (in ruby):
payload = {
  command: 'command text',
  identifier: { channel: 'MeshRelayChannel' }.to_json,
  data: { to: 'user', message: 'hi', action: 'chat' }.to_json
}.to_json

Contributing

  1. Fork it ( https://github.com/NullVoxPopuli/action_cable_client/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request
You can’t perform that action at this time.