Action Cable Client

There are quite a few WebSocket Servers out there. The popular ones seem to be: faye-websocket-ruby, em-websockets. The client-only websocket gems are kinda hard to find, and are only raw websocket support. Rails has a thin layer on top of web sockets to help manage subscribing to channels and send/receive on channels.

This gem is a wrapper around em-websocket-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')
  # the connected callback is required, as it triggers
  # the actual subscribing to the channel but it can just be
  # client.connected {}
  client.connected { puts 'successfully connected.' }

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

  # adds to a queue that is purged upon receiving of
  # a ping from the server
  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 {}
• errored { |msg| }
• received { |msg }

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"}

3. 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

4. Notes:

   • Every message sent to the server has a command and identifier key.
   • Ping messages from the action cable server look like:
   • { "type" => "ping", "message" => 1461845503 }
   • 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): 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