Skip to content

A ruby client for interacting with Rails' ActionCable. -- Maintainers Wanted.

License

Notifications You must be signed in to change notification settings

NullVoxPopuli/action_cable_client

Repository files navigation

Action Cable Client

Gem Version Build Status Code Climate Test Coverage

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