satori-rtm-sdk 0.0.1.rc1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e4b294a724bf1777e77a6694a414384215ea18d2
+  data.tar.gz: d505330ffc42ccd8d329b12b22405c1495792513
+SHA512:
+  metadata.gz: bfe76c7b4fc24dc0e6620321f53ed5c2b968058da80276bc8f6227d6ec9bc5702e4496ae7f31a4f6ac71e111223404e379103341ebbe149bb4c9eb5140060cce
+  data.tar.gz: 5d54ce8c2363f343960a86ad03223fceed82e65ee5fc5d04a851d6ebd7bce83b3d9662d57c0b19a7ce1a599bf8a6e68a00e0b6350cc21fe4dd84180b3bc3c7a1

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+v0.0.1 (?)
+-------------------
+* Initial release

data/README.md

@@ -0,0 +1,97 @@
+# Ruby SDK for Satori RTM
+
+RTM is the realtime messaging service at the core of the [Satori](https://www.satori.com).
+
+Ruby SDK makes it more convenient to use Satori RTM from [Ruby programming language](https://www.ruby-lang.org).
+
+## Installation
+
+Ruby SDK works on Ruby >= 2.0 and JRuby.
+
+Install it with [RubyGems](https://rubygems.org/)
+
+    gem install satori-rtm-sdk
+
+or add this to your Gemfile if you use [Bundler](http://gembundler.com/):
+
+    gem "satori-rtm-sdk"
+
+## Documentation
+
+* [Satori Ruby SDK API](...)
+* [RTM API](https://www.satori.com/docs/using-satori/rtm-api)
+
+## Getting started
+
+Here's an example how to use Satori RTM SDK to write publish / subscribe logic:
+
+```ruby
+require 'satori-rtm-sdk'
+
+endpoint = 'YOUR_ENDPOINT'
+appkey = 'YOUR_APPKEY'
+
+client = Satori::RTM::Client.new(endpoint, appkey)
+
+client.connect
+
+client.subscribe 'animals' do |_ctx, event|
+  case event.type
+  when :subscribed
+    puts "Subscribed to the channel: #{event.data[:subscription_id]}"
+  when :data
+    event.data[:messages].each { |msg| puts "Animal is received #{msg}" }
+  when :error
+    puts "Subscription error: #{event.data[:error]} -- #{event.data[:reason]}"
+  end
+end
+
+loop do
+  client.publish 'animals', who: 'zebra', where: [34.13, -118.32]
+  client.sock_read_repeatedly duration_in_secs: 2
+end
+```
+
+## EventMachine
+
+Ruby SDK for Satori RTM doesn't lock you into using threading or event loop frameworks, but it's ready to be used with any of those.
+
+The example of using Ruby SDK with EventMachine can be found [here](...)
+
+## Logging
+
+You can enable dumping of all PDUs either from your code
+
+```ruby
+Satori::RTM::Logger.use_std_logger(::Logger::DEBUG)
+```
+
+or by setting `DEBUG_SATORI_SDK` environment variable prior to running your application
+
+```ruby
+$ DEBUG_SATORI_SDK=true ruby myapp.rb
+```
+
+## Testing Your Changes
+
+Tests require an active RTM to be available. The tests require `credentials.json` to be populated with the RTM properties.
+
+The `credentials.json` file must include the following key-value pairs:
+
+```
+{
+  "endpoint": "YOUR_ENDPOINT",
+  "appkey": "YOUR_APPKEY",
+  "auth_role_name": "YOUR_ROLE",
+  "auth_role_secret_key": "YOUR_SECRET",
+  "auth_restricted_channel": "YOUR_RESTRICTED_CHANNEL"
+}
+```
+
+* `endpoint` is your customer-specific endpoint for RTM access.
+* `appkey` is your application key.
+* `auth_role_name` is a role name that permits to publish / subscribe to `auth_restricted_channel`. Must be not `default`.
+* `auth_role_secret_key` is a secret key for `auth_role_name`.
+* `auth_restricted_channel` is a channel with subscribe and publish access for `auth_role_name` role only.
+
+After setting up `credentials.json`, just type `rspec spec` at the command line.

data/lib/satori-rtm-sdk.rb

@@ -0,0 +1,13 @@
+require 'satori-rtm-sdk/codec'
+require 'satori-rtm-sdk/event_emitter'
+require 'satori-rtm-sdk/logger'
+require 'satori-rtm-sdk/websocket'
+require 'satori-rtm-sdk/model'
+require 'satori-rtm-sdk/client'
+require 'satori-rtm-sdk/version'
+
+module Satori
+  # Satori RTM classes.
+  module RTM
+  end
+end

data/lib/satori-rtm-sdk/client.rb

@@ -0,0 +1,477 @@
+require 'openssl'
+require 'uri'
+
+module Satori
+  module RTM
+    # The client that an application uses for accessing RTM.
+    #
+    # @!attribute [r] transport
+    #   @return [WebSocket] the WebSocket connection
+    class Client
+      include EventEmitter
+      include Logger
+
+      attr_reader :transport
+      private :on, :fire
+
+      # Returns a new instance of Client.
+      #
+      # @param endpoint [String] RTM endpoint
+      # @param appkey [String] appkey used to access RTM
+      # @param opts [Hash] options to create a client with.
+      # @option opts [WebSocket] :transport WebSocket connection implementation to use
+      def initialize(endpoint, appkey, opts = {})
+        @waiters = {}
+        @subscriptions = {}
+        @url = URI.join(endpoint, 'v2?appkey=' + appkey).to_s
+        @id = 0
+        @encoder = JsonCodec.new
+        @transport = init_transport(opts)
+        @state = :init
+      end
+
+      # @!group I/O
+
+      # Connects to Satori RTM.
+      #
+      # @raise [ConnectionError] network error occurred when connecting
+      # @return [void]
+      def connect
+        raise ConnectionError, "Client is a single-use object. You can't connect twice." if @state != :init
+        logger.info "connecting to #{@url}"
+        @transport.connect(@url)
+      rescue => e
+        # generate websocket close event
+        on_websocket_close(1006, "Connect exception: #{e.message}")
+        raise e
+      end
+
+      # Defines a callback to call when the client is successfully connected to Satori RTM.
+      #
+      # @yield Calls when client is connected
+      # @return [void]
+      def onopen(&fn)
+        on :open, &fn
+      end
+
+      # Defines a callback to call when the client is disconnected or not able to connect to Satori RTM.
+      #
+      # If a client is not able to connect, a +onclose+ yields too with a reason.
+      #
+      # @yield Calls when client is disconnected or not able to connect
+      # @yieldparam close_event [CloseEvent] reason why client was closed
+      # @return [void]
+      def onclose(&fn)
+        on :close, &fn
+      end
+
+      # Returns +true+ if the client is connected.
+      #
+      # @return [Boolean] +true+ if connected, +false+ otherwise
+      def connected?
+        @state == :open
+      end
+
+      # Closes gracefully the connection to Satori RTM.
+      # @return [void]
+      def close
+        @transport.close
+      end
+
+      # Reads from an WebSocket with an optional timeout.
+      #
+      # If timeout is greater than zero, it specifies a maximum interval (in seconds)
+      # to wait for any incoming WebSocket frames. If timeout is zero,
+      # then the method returns without blocking. If the timeout is less
+      # than zero, the method blocks indefinitely.
+      #
+      # @param opts [Hash] additional options
+      # @option opts [Integer] :timeout_in_secs (-1) timeout for a read operation
+      #
+      # @raise [ConnectionError] network error occurred when reading data
+      # @return [:ok] read successfully reads data from WebSocket
+      # @return [:timeout] a blocking operation times out
+      def sock_read(opts = {})
+        timeout_in_secs = opts.fetch(:timeout_in_secs, -1)
+        if timeout_in_secs >= 0
+          @transport.read_with_timeout(timeout_in_secs)
+        else
+          @transport.read
+        end
+      end
+
+      # Reads from an WebSocket in a non-blocking mode.
+      #
+      # @raise [ConnectionError] network error occurred when reading data
+      # @return [:ok] read successfully reads data from WebSocket
+      # @return [:would_block] read buffer is empty
+      def sock_read_nonblock
+        @transport.read_nonblock
+      end
+
+      # Reads repeatedly from an WebSocket.
+      #
+      # This method repeatedly reads from an WebSocket during a specified
+      # time (in seconds). If duration time is greater then zero, then the
+      # method blocks for the duration time and reads repeatedly all
+      # incoming WebSocket frames. If duration time is less than zero, the
+      # method blocks indefinitely.
+      #
+      # @param opts [Hash] additional options
+      # @option opts [Integer] :duration_in_secs (-1) duration interval
+      #
+      # @raise [ConnectionError] network error occurred when reading data
+      # @return [void]
+      def sock_read_repeatedly(opts = {})
+        duration_in_secs = opts.fetch(:duration_in_secs, -1)
+        start = Time.now
+        loop do
+          diff = (Time.now - start)
+          break if (duration_in_secs >= 0) && (duration_in_secs <= diff)
+          @transport.read_with_timeout(duration_in_secs - diff)
+        end
+      end
+
+      # Wait for all RTM replies for all pending requests.
+      #
+      # This method blocks until all RTM replies are received for all
+      # pending requests.
+      #
+      # If timeout is greater than zero, it specifies a maximum interval (in seconds)
+      # to wait for any incoming WebSocket frames.  If the timeout is less
+      # than zero, the method blocks indefinitely.
+      #
+      # @note if user's callback for a reply sends new RTM request
+      # then this method waits it too.
+      #
+      # @param opts [Hash] additional options
+      # @option opts [Integer] :timeout_in_secs (-1) timeout for an operation
+      #
+      # @raise [ConnectionError] network error occurred when reading data
+      #
+      # @return [:ok] all replies are received
+      # @return [:timeout] a blocking operation times out
+      def wait_all_replies(opts = {})
+        timeout_in_secs = opts.fetch(:timeout_in_secs, -1)
+        start = Time.now
+        rc = :ok
+        loop do
+          break if @waiters.empty?
+
+          if timeout_in_secs >= 0
+            diff = (Time.now - start)
+            if timeout_in_secs <= diff
+              rc = :timeout
+              break
+            end
+            @transport.read_with_timeout(timeout_in_secs - diff)
+          else
+            @transport.read_with_timeout(1)
+          end
+        end
+        rc
+      end
+
+      # @!endgroup
+
+      # @!group Satori RTM operations
+
+      # Publishes a message to a channel.
+      #
+      # @param channel [String] name of the channel
+      # @param message [Object] message to publish
+      # @yield Callback for an RTM reply. If the block is not given, then
+      #   no reply will be sent to a client, regardless of the outcome
+      # @yieldparam reply [BaseReply] RTM reply for delete request
+      # @return [void]
+      def publish(channel, message, &fn)
+        publish_opts = {
+          channel: channel,
+          message: message
+        }
+        send_r('rtm/publish', publish_opts, &fn)
+      end
+
+      # Reads a message in a channel.
+      #
+      # RTM returns the message at the position specified in the request.
+      # If there is no position specified, RTM defaults to the position of
+      # the latest message in the channel. A +null+ message in the reply
+      # PDU means that there were no messages at that position.
+      #
+      # @param channel [String] name of the channel
+      # @param opts [Hash] additional options for +rtm/read+ request
+      # @yield Callback for an RTM reply. If the block is not given, then
+      #   no reply will be sent to a client, regardless of the outcome
+      # @yieldparam reply [BaseReply] RTM reply for delete request
+      # @return [void]
+      def read(channel, opts = {}, &fn)
+        read_opts = opts.merge channel: channel
+        send_r('rtm/read', read_opts, &fn)
+      end
+
+      # Writes the value of the specified key from the key-value store.
+      #
+      # Key is represented by a channel. In current RTM implementation
+      # write operation is the same as publish operation.
+      #
+      # @param channel [String] name of the channel
+      # @param message [Object] message to write
+      # @yield Callback for an RTM reply. If the block is not given, then
+      #   no reply will be sent to a client, regardless of the outcome
+      # @yieldparam reply [BaseReply] RTM reply for delete request
+      # @return [void]
+      def write(channel, message, &fn)
+        write_opts = {
+          channel: channel,
+          message: message
+        }
+        send_r('rtm/write', write_opts, &fn)
+      end
+
+      # Deletes the value of the specified key from the key-value store.
+      #
+      # Key is represented by a channel, and only the last message in the
+      # channel is relevant (represents the value). Hence, publishing a +null+
+      # value, serves as deletion of the the previous value (if any). Delete request
+      # is the same as publishing or writing a null value to the channel.
+      #
+      # @param channel [String] name of the channel
+      # @yield Callback for an RTM reply. If the block is not given, then
+      #   no reply will be sent to a client, regardless of the outcome
+      # @yieldparam reply [BaseReply] RTM reply for delete request
+      # @return [void]
+      def delete(channel, &fn)
+        delete_opts = { channel: channel }
+        send_r('rtm/delete', delete_opts, &fn)
+      end
+
+      # Subscribes to a channel
+      #
+      # When you create a subscription, you can specify additional subscription options (e.g. history or view).
+      # Full list of subscription option you could find in RTM API specification.
+      #
+      # Satori SDK informs an user about any subscription state changes by calling block with proper event.
+      #
+      # @see SubscriptionEvent Information about subscription events
+      #
+      # @param sid [String] subscription id
+      # @param opts [Hash] additional options for +rtm/subscribe+ request
+      # @yield RTM subscription callback
+      # @yieldparam ctx [SubscriptionContext] current subscription context
+      # @yieldparam event [SubscriptionEvent] subscription event
+      # @return [void]
+      #
+      # @example
+      #   client.subscribe 'animals' do |_ctx, event|
+      #     case event.type
+      #     when :subscribed
+      #       puts "Subscribed to the channel: #{event.data[:subscription_id]}"
+      #     when :data
+      #       event.data[:messages].each { |msg| puts "Message is received #{msg}" }
+      #     when :error
+      #       puts "Subscription error: #{event.data[:error]} -- #{event.data[:reason]}"
+      #     end
+      #   end
+      def subscribe(sid, opts = {}, &fn)
+        request_opts = opts.merge subscription_id: sid
+        request_opts[:channel] = sid unless %i[filter view].any? { |k| opts.key?(k) }
+
+        context = SubscriptionContext.new(sid, opts, fn)
+
+        init_reply = SubscriptionEvent.new(:init, nil)
+        context.fn.call(context, init_reply)
+
+        send('rtm/subscribe', request_opts) do |status, data|
+          reply = context.handle_data(status, data)
+
+          if @subscriptions.key?(sid) && @subscriptions[sid] != context
+            prev_sub = @subscriptions[sid]
+            prev_sub.mark_as_resubscribed
+          end
+
+          @subscriptions[sid] = context if reply.type == :subscribed
+
+          context.fn.call(context, reply)
+        end
+      end
+
+      # Unsubscribes the subscription with the specific +subscription_id+
+      #
+      # @param sid [String] subscription id
+      # @yield Callback for an RTM reply
+      # @yieldparam reply [BaseReply] RTM reply for authenticate request
+      # @return [void]
+      def unsubscribe(sid)
+        request_opts = { subscription_id: sid }
+        send('rtm/unsubscribe', request_opts) do |status, data|
+          context = @subscriptions.delete(sid)
+          if context
+            reply = context.handle_data(status, data)
+            context.fn.call(context, reply)
+          end
+          # pass base reply to unsubscribe block
+          yield(BaseReply.new(status, data)) if block_given?
+        end
+      end
+
+      # Authenticates a user with specific role and secret.
+      #
+      # Authentication is based on the +HMAC+ algorithm with +MD5+ hashing routine:
+      # * The SDK obtains a nonce from the RTM in a handshake request
+      # * The SDK then sends an authorization request with its role secret
+      #   key hashed with the received nonce
+      #
+      # If authentication is failed then reason is passed to the yield block. In
+      # case of success the +rtm/authenticate+ reply is passed to the yield block.
+      #
+      # Use Dev Portal to obtain the role and secret key for your application.
+      #
+      # @param role [String] role name
+      # @param secret [String] role secret
+      # @yield Callback for an RTM reply
+      # @yieldparam reply [BaseReply] RTM reply for authenticate request
+      # @return [void]
+      #
+      # @example
+      #   client.authenticate role, role_secret do |reply|
+      #     raise "Failed to authenticate: #{reply.data[:error]} -- #{reply.data[:reason]}" unless reply.success?
+      #   end
+      #   client.wait_all_replies
+      def authenticate(role, secret)
+        handshake_opts = {
+          method: 'role_secret',
+          data: { role: role }
+        }
+        send_r('auth/handshake', handshake_opts) do |reply|
+          if reply.success?
+            hash = hmac_md5(reply.data[:data][:nonce], secret)
+            authenticate_opts = {
+              method: 'role_secret',
+              credentials: { hash: hash }
+            }
+            send_r('auth/authenticate', authenticate_opts) do |auth_reply|
+              yield(auth_reply)
+            end
+          else
+            yield(reply)
+          end
+        end
+      end
+
+      # @!endgroup
+
+      private
+
+      def pdu_to_reply_adapter(fn)
+        return if fn.nil?
+
+        proc do |status, data|
+          reply = BaseReply.new(status, data)
+          fn.call(reply)
+        end
+      end
+
+      def send_r(action, body, &fn)
+        send(action, body, &pdu_to_reply_adapter(fn))
+      end
+
+      def send(action, body, &block)
+        pdu = { action: action, body: body }
+        if block_given?
+          pdu[:id] = gen_next_id
+          @waiters[pdu[:id]] = block
+        end
+        logger.debug("-> #{pdu}")
+        data = @encoder.encode(pdu)
+        @transport.send(data, type: :text)
+      end
+
+      def gen_next_id
+        @id += 1
+      end
+
+      def on_websocket_open
+        logger.info('connection is opened')
+        @state = :open
+        fire(:open)
+      end
+
+      def on_websocket_close(code, reason)
+        return if @state == :close
+        @state = :close
+        is_normal = (code == 1000)
+        if is_normal
+          logger.info('connection is closed normally')
+        else
+          logger.warn("connection is closed with code: '#{code}' -- '#{reason}'")
+        end
+
+        pass_disconnect_to_all_callbacks
+
+        @waiters = {}
+        @subscriptions = {}
+
+        fire(:close, CloseEvent.new(code, reason))
+      end
+
+      def pass_disconnect_to_all_callbacks
+        err = { error: 'disconnect', reason: 'Connection is closed' }
+
+        @waiters.sort_by(&:first).map do |_, fn|
+          safe_call(fn, :disconnect, err)
+        end
+        @subscriptions.map do |_, context|
+          reply = context.handle_data(:disconnect, err)
+          safe_call(context.fn, context, reply)
+        end
+      end
+
+      def on_websocket_message(data, _type)
+        pdu = @encoder.decode(data)
+        logger.debug("<- #{pdu}")
+        id = pdu[:id]
+        if id.nil?
+          on_unsolicited_pdu(pdu)
+        else
+          fn = @waiters.delete(id)
+          fn.call(:pdu, pdu) unless fn.nil?
+        end
+      end
+
+      def on_unsolicited_pdu(pdu)
+        if pdu[:action] == '/error'
+          reason = "Unclassified RTM error is received: #{pdu[:body][:error]} -- #{pdu[:body][:reason]}"
+          @transport.close 1008, reason
+        elsif pdu[:action].start_with? 'rtm/subscription'
+          sid = pdu[:body][:subscription_id]
+          context = @subscriptions[sid]
+          if context
+            reply = context.handle_data(:pdu, pdu)
+            context.fn.call(context, reply)
+          end
+        end
+      end
+
+      def hmac_md5(nonce, secret)
+        algorithm = OpenSSL::Digest.new('md5')
+        digest = OpenSSL::HMAC.digest(algorithm, secret, nonce)
+        Base64.encode64(digest).chomp
+      end
+
+      def init_transport(opts)
+        transport = opts[:transport] || WebSocket.new
+        transport.on(:open, &method(:on_websocket_open))
+        transport.on(:message, &method(:on_websocket_message))
+        transport.on(:close, &method(:on_websocket_close))
+        transport
+      end
+
+      def safe_call(fn, *args)
+        fn.call(*args)
+      rescue => e
+        logger.error(e)
+      end
+    end
+  end
+end

data/lib/satori-rtm-sdk/codec.rb

@@ -0,0 +1,17 @@
+require 'json'
+
+module Satori
+  module RTM
+    # JSON message encoder / decoder.
+    # @!visibility private
+    class JsonCodec
+      def encode(pdu)
+        JSON.generate(pdu)
+      end
+
+      def decode(data)
+        JSON.parse(data, symbolize_names: true)
+      end
+    end
+  end
+end

data/lib/satori-rtm-sdk/event_emitter.rb

@@ -0,0 +1,39 @@
+module Satori
+  module RTM
+    # Event emitter pattern implementation.
+    # @!visibility private
+    module EventEmitter
+      def self.included(klass)
+        klass.__send__ :include, InstanceMethods
+      end
+
+      # @!visibility private
+      module InstanceMethods
+        def __handlers
+          @__handlers ||= {}
+        end
+
+        def on(name, &fn)
+          get_handler(name) << fn
+          fn
+        end
+
+        def fire(name, *args)
+          Array.new(get_handler(name)).each do |fn|
+            fn.call(*args)
+          end
+
+          Array.new(get_handler(:*)).each do |fn|
+            fn.call(name, *args)
+          end
+        end
+
+        private
+
+        def get_handler(name)
+          __handlers[name] ||= []
+        end
+      end
+    end
+  end
+end

data/lib/satori-rtm-sdk/logger.rb

@@ -0,0 +1,77 @@
+require 'logger'
+
+module Satori
+  module RTM
+    # Logger for Satori RTM SDK
+    module Logger
+      ENV_FLAG = 'DEBUG_SATORI_SDK'.freeze
+
+      class << self
+        def create_logger(level, output = $stderr)
+          logger = ::Logger.new(output)
+          logger.level = level
+          logger.progname = 'satori-rtm-sdk'
+          logger.formatter = lambda do |severity, datetime, progname, msg|
+            formatted_message = case msg
+                                when String
+                                  msg
+                                when Exception
+                                  format "%s (%s)\n%s",
+                                         msg.message, msg.class, (msg.backtrace || []).join("\n")
+                                else
+                                  msg.inspect
+                                end
+            format "%s [%5s] - %s: %s\n",
+                   datetime.strftime('%H:%M:%S.%L'),
+                   severity,
+                   progname,
+                   formatted_message
+          end
+          logger
+        end
+
+        # Sets a standard logger for all Satori RTM SDK classes.
+        #
+        # @param level [Keyword] logger log level
+        # @param output [IO] logger output
+        # @return [void]
+        def use_std_logger(level = default_level, output = $stderr)
+          use_logger create_logger(level, output)
+        end
+
+        # Sets a logger for all Satori RTM SDK classes.
+        #
+        # @param value [::Logger] logger
+        # @return [void]
+        def use_logger(value)
+          @global_logger = value
+        end
+
+        # Returns current logger
+        #
+        # @return [::Logger] logger
+        def logger
+          @global_logger ||= use_std_logger
+        end
+
+        # Returns the default logger level
+        #
+        # @return [Keyword] default logger level
+        def default_level
+          ENV.key?(ENV_FLAG) ? ::Logger::DEBUG : ::Logger::WARN
+        end
+
+        def included(klass)
+          klass.__send__ :include, InstanceMethods
+        end
+      end
+
+      # @!visibility private
+      module InstanceMethods
+        def logger
+          Satori::RTM::Logger.logger
+        end
+      end
+    end
+  end
+end

data/lib/satori-rtm-sdk/model.rb

@@ -0,0 +1,180 @@
+module Satori
+  module RTM
+    # Event about new subscription data or subscription status change.
+    #
+    # @!attribute [r] data
+    #   Returns an event data. In most cases it represent +body+ field from incoming
+    #   subscribe / subscription / unsubscribe PDUs. The type of PDU is accessible by
+    #   +type+ attribute. Information about fields in +data+ could be found in RTM API
+    #   specification.
+    #   @return [Hash] event data
+    #
+    # @!attribute [r] type
+    #   Returns a type of event.
+    #   @return [:init] event before +rtm/subscribe+ request is sent
+    #   @return [:subscribed] event when +rtm/subscribe/ok+ is received
+    #   @return [:unsubscribed] event when +rtm/unsubscribe/ok+ is received
+    #   @return [:error] event when +rtm/subscription/error+ / +rtm/subscribe/error+ are received
+    #   @return [:info] event when +rtm/subscription/info+ is received
+    #   @return [:disconnect] event when connection is lost
+    class SubscriptionEvent
+      attr_reader :data, :type
+
+      def initialize(type, data)
+        if type == :pdu
+          @type = resolve_type(data[:action])
+          @data = data[:body]
+        else
+          @type = type
+          @data = data
+        end
+      end
+
+      # Returns +true+ if event is an error PDU.
+      #
+      # @return [Boolean] +true+ if event is an error PDU, +false+ otherwise
+      def error?
+        type == :error
+      end
+
+      private
+
+      def resolve_type(action)
+        case action
+        when 'rtm/subscribe/ok'
+          :subscribed
+        when 'rtm/unsubscribe/ok'
+          :unsubscribed
+        when 'rtm/subscription/info'
+          :info
+        when 'rtm/subscription/data'
+          :data
+        when 'rtm/subscription/error', 'rtm/subscribe/error', 'rtm/unsubscribe/error'
+          :error
+        end
+      end
+    end
+
+    # Base RTM reply for a request.
+    #
+    # @!attribute [r] data
+    #   Returns a reply data. It represent +body+ field from reply PDUs from RTM.
+    #   Information about fields in data could be found in RTM API specification.
+    #   @return [Hash] event data
+    #
+    # @!attribute [r] type
+    #   Returns a type of reply.
+    #   @return [:ok] when RTM positive reply is received
+    #   @return [:error] when RTM error is received
+    #   @return [:disconnect] when connection is lost
+    class BaseReply
+      attr_reader :data, :type
+
+      def initialize(type, data)
+        if type == :pdu
+          @type = data[:action].end_with?('/ok') ? :ok : :error
+          @data = data[:body]
+        else
+          @type = type
+          @data = data
+        end
+      end
+
+      # Returns +true+ if a reply is positive
+      #
+      # @return [Boolean] +true+ if a reply is positive, +false+ otherwise
+      def success?
+        type == :ok
+      end
+
+      # Returns +true+ if a reply is not positive
+      #
+      # @return [Boolean] +true+ if a reply is not positive, +false+ otherwise
+      def error?
+        !success?
+      end
+    end
+
+    # Close event with information why connection is closed or can't be established.
+    #
+    # @!attribute [r] code
+    #   Returns a WebSocket close frame code
+    #   @see https://tools.ietf.org/html/rfc6455 WebSocket RFC
+    #   @return [Number] close code
+    #
+    # @!attribute [r] reason
+    #   Returns a human-readable reason why connection is closed or can't be established.
+    #   @return [String] close reason
+    class CloseEvent
+      attr_reader :code, :reason
+
+      def initialize(code, reason)
+        @code = code
+        @reason = reason
+      end
+
+      # Returns +true+ if connection was closed normally
+      # @return [Boolean] +true+ if connection was closed normally, +false+ otherwise
+      def normal?
+        @code == 1000
+      end
+    end
+
+    # Context with initial subscription settings and current subscription state.
+    #
+    # @!attribute [r] subscription_id
+    #   @return [String] subscription identifier
+    #
+    # @!attribute [r] req_opts
+    #   @return [Hash] additional options for +rtm/subscribe+ request used to create the subscription
+    #
+    # @!attribute [r] fn
+    #   @return [Proc] RTM subscription yield block used to create the subscription
+    #
+    # @!attribute [r] position
+    #   @return [String] current subscription position. Updated automatically after each RTM reply
+    #
+    # @!attribute [r] state
+    #   Subscription state
+    #   @return [:init] not established
+    #   @return [:subscribed] subscribed
+    #   @return [:unsubscribed] unsubscribed with +rtm/unsubscribe+ request
+    #   @return [:disconnect] unsubscribed because connection is lost
+    #   @return [:resubscribed] unsubscribed because new subscription replaces it with +force+ flag
+    class SubscriptionContext
+      attr_reader :subscription_id, :req_opts, :fn, :position, :state
+
+      def initialize(sid, opts, fn)
+        raise ArgumentError, 'subscription callback function should be specified' if fn.nil?
+
+        @subscription_id = sid
+        @fn = fn
+        @req_opts = opts
+        @position = nil
+        @state = :init
+      end
+
+      # @!visibility private
+      def handle_data(status, data)
+        data[:subscription_id] = @subscription_id if status == :disconnect
+        reply = SubscriptionEvent.new(status, data)
+        handle_reply(reply)
+        reply
+      end
+
+      # @!visibility private
+      def handle_reply(reply)
+        @position = reply.data[:position] if reply.data.key?(:position)
+        case reply.type
+        when :subscribed, :unsubscribed, :error, :disconnect
+          @state = reply.type
+        end
+      end
+
+      # @!visibility private
+      def mark_as_resubscribed
+        @state = :resubscribed
+      end
+    end
+  end
+end

data/lib/satori-rtm-sdk/version.rb

@@ -0,0 +1,5 @@
+module Satori
+  module RTM
+    VERSION = '0.0.1'.freeze
+  end
+end

data/lib/satori-rtm-sdk/websocket.rb

@@ -0,0 +1,189 @@
+require 'socket'
+require 'openssl'
+require 'websocket'
+
+module Satori
+  # Satori RTM classes.
+  module RTM
+    # Error class for any connection related error.
+    class ConnectionError < StandardError
+    end
+
+    # WebSocket implementation on top of standard TCP sockets.
+    class WebSocket
+      include EventEmitter
+      include Logger
+
+      attr_reader :socket
+
+      def initialize(opts = {})
+        @opts = opts
+        @state = :none
+      end
+
+      def connect(url)
+        uri = URI.parse(url)
+
+        @socket = create_socket(uri)
+        @socket = start_tls(@socket, uri.host) if uri.scheme == 'wss'
+
+        @hs = ::WebSocket::Handshake::Client.new(url: url)
+        @frame = incoming_frame.new(version: @hs.version)
+
+        @state = :open
+        do_ws_handshake
+        fire :open
+      rescue => ex
+        close 1006, ex.message
+        raise ConnectionError, ex.message, ex.backtrace
+      end
+
+      def read_nonblock
+        data = nil
+        begin
+          data = @socket.read_nonblock(1024)
+        rescue IO::WaitReadable, IO::WaitWritable
+          return :would_block
+        end
+
+        @frame << data
+        while (frame = @frame.next)
+          handle_incoming_frame(frame)
+        end
+        :ok
+      rescue => ex
+        close 1006, 'Socket is closed'
+        raise ConnectionError, ex.message, ex.backtrace
+      end
+
+      def read
+        while (rc = read_nonblock) == :would_block
+          IO.select([@socket])
+        end
+        rc
+      rescue => ex
+        close 1006, 'Socket is closed'
+        raise ConnectionError, ex.message, ex.backtrace
+      end
+
+      def read_with_timeout(timeout_in_secs)
+        now = Time.now
+        while (rc = read_nonblock) == :would_block
+          diff = Time.now - now
+          if timeout_in_secs <= diff
+            rc = :timeout
+            break
+          end
+          IO.select([@socket], nil, nil, timeout_in_secs - diff)
+        end
+        rc
+      rescue => ex
+        close 1006, 'Socket is closed'
+        raise ConnectionError, ex.message, ex.backtrace
+      end
+
+      def send(data, args)
+        type = args[:type] || :text
+        send_frame_unsafe(data, type, args[:code])
+      rescue => ex
+        close 1006, 'Socket is closed'
+        raise ConnectionError, ex.message, ex.backtrace
+      end
+
+      def close(code = 1000, reason = nil)
+        if @state == :open
+          send_frame_unsafe(reason, :close, code)
+        elsif @state == :server_close_frame_received
+          # server send close frame, replying back with default code
+          send_frame_unsafe(reason, :close)
+        end
+      rescue => ex
+        # ignore
+        logger.info("fail to close socket: #{ex.message}")
+      ensure
+        should_trigger_on_close = opened?
+        @state = :closed
+        @socket.close if @socket
+        fire :close, code, reason if should_trigger_on_close
+      end
+
+      private
+
+      def opened?
+        %i[open server_close_frame_received].include?(@state)
+      end
+
+      def incoming_frame
+        ::WebSocket::Frame::Incoming::Client
+      end
+
+      def outgoing_frame
+        ::WebSocket::Frame::Outgoing::Client
+      end
+
+      def send_frame_unsafe(data, type = :text, code = nil)
+        frame = create_out_frame(data, type, code)
+        return if frame.nil?
+        @socket.write frame
+        @socket.flush
+      end
+
+      def handle_incoming_frame(frame)
+        case frame.type
+        when :close
+          @state = :server_close_frame_received
+          close frame.code, frame.data
+        when :pong
+          fire :pong, frame.data
+        when :text
+          fire :message, frame.data, :text
+        end
+      end
+
+      def create_socket(uri)
+        host = uri.host
+        port = uri.port
+        port ||= uri.scheme == 'wss' ? 443 : 80
+        TCPSocket.new(host, port)
+      end
+
+      def start_tls(socket, hostname)
+        ctx = OpenSSL::SSL::SSLContext.new
+        ctx.verify_mode = OpenSSL::SSL::VERIFY_PEER | OpenSSL::SSL::VERIFY_FAIL_IF_NO_PEER_CERT
+
+        cert_store = OpenSSL::X509::Store.new
+        cert_store.set_default_paths
+        ctx.cert_store = cert_store
+
+        ssl_sock = OpenSSL::SSL::SSLSocket.new(socket, ctx)
+        # use undocumented method in SSLSocket to make it works with SNI
+        ssl_sock.hostname = hostname if ssl_sock.respond_to? :hostname=
+        ssl_sock.sync_close = true
+        ssl_sock.connect
+
+        ssl_sock
+      end
+
+      def do_ws_handshake
+        send(@hs.to_s, type: :plain)
+
+        while (line = @socket.gets)
+          @hs << line
+          break if @hs.finished?
+        end
+
+        unless @hs.valid?
+          raise ConnectionError, 'handshake error: ' + @hs.error.to_s
+        end
+      end
+
+      def create_out_frame(data, type, code)
+        if type == :plain
+          data
+        else
+          outgoing_frame.new(version: @hs.version, data: data, type: type, code: code).to_s
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,184 @@
+--- !ruby/object:Gem::Specification
+name: satori-rtm-sdk
+version: !ruby/object:Gem::Version
+  version: 0.0.1.rc1
+platform: ruby
+authors:
+- Andrey Vasenin
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-08-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: websocket
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: websocket-eventmachine-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: rspec_junit_formatter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.49.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.49.1
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.15.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.15.0
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.0
+description: 
+email: sdk@satori.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- CHANGELOG.md
+- README.md
+- lib/satori-rtm-sdk.rb
+- lib/satori-rtm-sdk/client.rb
+- lib/satori-rtm-sdk/codec.rb
+- lib/satori-rtm-sdk/event_emitter.rb
+- lib/satori-rtm-sdk/logger.rb
+- lib/satori-rtm-sdk/model.rb
+- lib/satori-rtm-sdk/version.rb
+- lib/satori-rtm-sdk/websocket.rb
+homepage: https://github.com/satori-com/satori-rtm-sdk-ruby
+licenses:
+- BSD-3-Clause
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--main"
+- README.md
+- "--markup"
+- markdown
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.11
+signing_key: 
+specification_version: 4
+summary: Ruby SDK for Satori RTM
+test_files: []