socketcluster-client-ruby

A Ruby client for socketcluster.io

In lib/socketclusterclient, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file . To experiment with that code, run bin/console for an interactive prompt.

Refer below examples for more details.

Overview

This client provides following functionality

• Easy to setup and use
• Support for emitting and listening to remote events
• Automatic reconnection
• Pub/sub
• Authentication (JWT)
• Can be used for extensive unit-testing of all server side functions
• Support for ruby >= 2.2.0

Installation

Add this line to your application's Gemfile:

gem'socketclusterclient'

And then execute:

$ bundle

Or install it yourself as:

$ gem install socketclusterclient

Usage

Create instance of Socket class by passing url of socketcluster-server end-point

# Create a socket instancesocket=ScClient.new('ws://localhost:8000/socketcluster/')

Important Note : Default url to socketcluster end-point is always ws://somedomainname.com/socketcluster/.

Registering basic listeners

• Different functions are given as an argument to register listeners

require'socketclusterclient'require'logger'logger=Logger.new(STDOUT)logger.level=Logger::WARNon_connect=->{logger.info('on connect got called')}on_disconnect=->{logger.info('on disconnect got called')}on_connect_error=->{logger.info('on connect error got called')}on_set_authentication=lambdado |socket,token|
logger.info("Token received #{token}")socket.set_auth_token(token)endon_authentication=lambdado |socket,is_authenticated|
logger.info("Authenticated is #{is_authenticated}")endsocket=ScClient.new('ws://localhost:8000/socketcluster/')socket.set_basic_listener(on_connect,on_disconnect,on_connect_error)socket.set_authentication_listener(on_set_authentication,on_authentication)socket.connect

Connecting to server

• For connecting to server

# This will send websocket handshake request to socketcluster-serversocket.connect

• By default reconnection to server is disabled, so to enable automatic reconnection

# This will set automatic-reconnection to socketcluster-server repeat it infinitelysocket.set_reconnection(true)

• To set delay of reconnecting to server

# This will set automatic-reconnection to socketcluster-server with delay of 2 seconds and repeat it infinitelysocket.set_delay(2)socket.connect

• To disable automatic reconnection to server

# This will disable reconnection to socketcluster-serversocket.set_reconnection(false)

• For reconnection to the server you need to set reconnection strategy

# This will set the reconnection strategysocket.set_reconnection_listener(reconnect_interval,max_reconnect_interval,max_attempts)# default reconnection strategysocket.set_reconnection_listener(2000,30_000,nil)

For example,

socket.set_reconnection_listener(3000,30_000,10)# (reconnect_inverval, max_reconnect_interval, max_attempts)socket.set_reconnection_listener(3000,30_000)# (reconnect_inverval, max_reconnect_interval)

• You can set reconnect_interval, max_reconnect_interval and max_attempts directly as well

socket.reconnect_interval=2000socket.max_reconnect_interval=20_000socket.max_attempts=10

• To allow reconnection to server, you need to reconnect

# This will set automatic-reconnection to socketcluster-server with delay of 2 seconds and repeat it till the maximum attempts are finishedsocket.connect

Emitting and listening to events

Event emitter

• To emit a specified event on the corresponding socketcluster-server. The object sent can be String, Boolean, Long or JSONObject.

# Emit an eventsocket.emit(event_name,message);socket.emit("chat","Hi")

• To emit a specified event with acknowledgement on the corresponding socketcluster-server. The object sent can be String, Boolean, Long or JSONObject.

# Emit an event with acknowledgmentsocket.emitack(event_name,message,ack_emit)socket.emitack('chat','Hello',ack_emit)ack_emit=lambdado |key,error,object|
puts"Got ack data => #{object} and error => #{error} and key => #{key}"end

Event Listener

• To listen an event from the corresponding socketcluster-server. The object received can be String, Boolean, Long or JSONObject.

# Receive an eventsocket.on(event,message)socket.on('ping',message)message=lambdado |key,object|
puts"Got data => #{object} from key => #{key}"end

• To listen an event from the corresponding socketcluster-server and send the acknowledgment back. The object received can be String, Boolean, Long or JSONObject.

# Receive an event and send the acknowledgement backsocket.onack(event,message_with_acknowledgment)socket.onack('ping',ack_message)ack_message=lambdado |key,object,block_ack_message|
puts"Got ack data => #{object} from key => #{key}"block_ack_message.call('error lorem','data ipsum')end

Implementing Pub-Sub via channels

Creating a channel

• For creating and subscribing to channels

# Subscribe to channelsocket.subscribe('yell')# Subscribe to channel with acknowledgementsocket.subscribeack('yell',ack_subscribe)ack_subscribe=lambdado |channel,error,_object|
puts"Subscribed successfully to channel => #{channel}"iferror == ''end

• For getting list of created channels

# Get all subscribed channelchannels=socket.subscribed_channels

Publishing an event on channel

• For publishing an event

# Publish to a channelsocket.publish('yell','Hi')# Publish to a channel with acknowledgmentsocket.publishack('yell','Hi',ack_publish)ack_publish=lambdado |channel,error,_object|
puts"Publish sent successfully to channel => #{channel}"iferror == ''end

Listening to channel

• For listening to a channel event

# Listen to a channelsocket.onchannel('yell',channel_message)channel_message=lambdado |key,object|
puts"Got data => #{object} from key => #{key}"end

Un-subscribing to channel

• For unsubscribing to a channel

# Unsubscribe to a channelsocket.unsubscribe('yell')# Unsubscribe to a channel with acknowledgementsocket.unsubscribeack('yell',ack_unsubscribe)ack_unsubscribe=lambdado |channel,error,_object|
puts"Unsubscribed to channel => #{channel}"iferror == ''end

Logger

Disabling logger

• To get logger for logging of events

socket.logger.info("Some information")socket.logger.warn("Some warning")

• To disable logging of events

socket.disable_logging

• To enable logging of events

socket.enable_logging

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/opensocket/socketcluster-client-ruby. 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

The gem is available as open source under the terms of the MIT License.