space_elevator - The ActionCable Client for Ruby

space_elevator is a client for integrating a ruby application with a remote ActionCable-based backend provided by a Rails 7 (or recent) application or compatible framework. It allows for subscription and publication to multiple channels simultaneously, features automatic message routing to subscription-specific handlers, and supports eavesdropping on wire-level messages, allowing you to harness the power of WebSockets and receive push notifications in your own Ruby applications!

Installation

Add this line to your application's Gemfile:

gem 'space_elevator'

And then execute:

$ bundle

Or install it yourself as:

$ gem install space_elevator

Troubleshooting Event Machine Installation

gem may not find the OpenSSL include directory necessary to compile. For macOS users with brew install openssl already run can install eventmachine like so:

gem install eventmachine -- --with-cppflags=-I/opt/homebrew/opt/openssl/include

Usage

require 'space_elevator'
require 'eventmachine'
require 'em-websocket-client'

EventMachine.run do

    url = 'ws://example.com'

    # Create a SpaceElevator::Client with a disconnect handler.
    client = SpaceElevator::Client.new(url) do
        puts 'Disconnected. Exiting...'
        EventMachine.stop_event_loop
    end

    # Connect the client using the provided callback block.
    client.connect do |msg|
        case msg['type'] # The server will always set a 'type'.
        when 'welcome' # Sent after a successful connection.
            puts 'The server says "welcome".'

            # Subscribe to something..
            client.subscribe(channel: 'ChatChannel') do |chat|
                puts "Received Chat Event: #{chat}"
                if chat['type'] == 'confirm_subscription'
                    puts "Subscription to #{chat['identifier']['channel']} confirmed!"
                    # Broadcast to the channel! The actual channel identifier and message payload is specific to your backend's WebSocket API.
                    client.publish({channel: 'ChatChannel'}, {subject: 'Hi', text: "What's up, y'all!?!?"})
                end
            end

            # Subscribe to something else simultaneously. Note the additional parameters!
            client.subscribe(channel: 'PlatformChannel', platform_id: platform_id) do |m|
                puts "Received Platform #{platform_id} Event: #{m}"
                # Do whatever, here.
            end
        when 'ping'
            puts 'The server just pinged us.'
        else
            puts msg
        end
    end
end

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/preston/space_elevator. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

This work is published under the Apache 2.0 license. Copyright (c) 2017-2023 Preston Lee.