ably-rest 0.7.1 → 0.7.3

data/lib/submodules/ably-ruby/lib/ably/modules/event_emitter.rb

@@ -0,0 +1,128 @@
+module Ably
+  module Modules
+    # EventEmitter provides methods to attach to public events and trigger events on any class instance
+    #
+    # EventEmitter are typically used for public interfaces, and as such, may be overriden in
+    # the classes to enforce `event` names match expected values.
+    #
+    # @example
+    #   class Example
+    #     include Modules::EventEmitter
+    #   end
+    #
+    #   event_emitter = Example.new
+    #   event_emitter.on(:signal) { |name| puts "Signal #{name} received" }
+    #   event_emitter.trigger :signal, "Test"
+    #   #=> "Signal Test received"
+    #
+    module EventEmitter
+      module ClassMethods
+        attr_reader :event_emitter_coerce_proc
+
+        # Configure included EventEmitter
+        #
+        # @param [Hash] options the options for the {EventEmitter}
+        # @option options [Proc] :coerce_into A lambda/Proc that is used to coerce the event names for all events. This is useful to ensure the event names conform to a naming or type convention.
+        #
+        # @example
+        #   configure_event_emitter coerce_into: Proc.new { |event| event.to_sym }
+        #
+        def configure_event_emitter(options = {})
+          @event_emitter_coerce_proc = options[:coerce_into]
+        end
+
+        # Ensure @event_emitter_coerce_proc option is passed down to any classes that inherit the class with callbacks
+        def inherited(subclass)
+          subclass.instance_variable_set('@event_emitter_coerce_proc', @event_emitter_coerce_proc)
+          super
+        end
+      end
+
+      # On receiving an event matching the event_name, call the provided block
+      #
+      # @param [Array<String>] event_names event name
+      #
+      # @return [void]
+      def on(*event_names, &block)
+        event_names.each do |event_name|
+          callbacks[callbacks_event_coerced(event_name)] << proc_for_block(block)
+        end
+      end
+
+      # On receiving an event maching the event_name, call the provided block only once and remove the registered callback
+      #
+      # @param [Array<String>] event_names event name
+      #
+      # @return [void]
+      def once(*event_names, &block)
+        event_names.each do |event_name|
+          callbacks[callbacks_event_coerced(event_name)] << proc_for_block(block, delete_once_run: true)
+        end
+      end
+
+      # Trigger an event with event_name that will in turn call all matching callbacks setup with `on`
+      def trigger(event_name, *args)
+        callbacks[callbacks_event_coerced(event_name)].
+          clone.
+          select do |proc_hash|
+            proc_hash[:trigger_proc].call(*args)
+          end.each do |callback|
+            callbacks[callbacks_event_coerced(event_name)].delete callback
+          end
+      end
+
+      # Remove all callbacks for event_name.
+      #
+      # If a block is provided, only callbacks matching that block signature will be removed.
+      # If block is not provided, all callbacks matching the event_name will be removed.
+      #
+      # @param [Array<String>] event_names event name
+      #
+      # @return [void]
+      def off(*event_names, &block)
+        keys = if event_names.empty?
+          callbacks.keys
+        else
+          event_names
+        end
+
+        keys.each do |event_name|
+          if block_given?
+            callbacks[callbacks_event_coerced(event_name)].delete_if { |proc_hash| proc_hash[:block] == block }
+          else
+            callbacks[callbacks_event_coerced(event_name)].clear
+          end
+        end
+      end
+
+      private
+      def self.included(klass)
+        klass.extend ClassMethods
+      end
+
+      # Create a Hash with a proc that calls the provided block and returns true if option :delete_once_run is set to true.
+      # #trigger automatically deletes any blocks that return true thus allowing a block to be run once
+      def proc_for_block(block, options = {})
+        {
+          trigger_proc: Proc.new do |*args|
+            block.call *args
+            true if options[:delete_once_run]
+          end,
+          block: block
+        }
+      end
+
+      def callbacks
+        @callbacks ||= Hash.new { |hash, key| hash[key] = [] }
+      end
+
+      def callbacks_event_coerced(event_name)
+        if self.class.event_emitter_coerce_proc
+          self.class.event_emitter_coerce_proc.call(event_name)
+        else
+          event_name
+        end
+      end
+    end
+  end
+end

data/lib/submodules/ably-ruby/lib/ably/modules/event_machine_helpers.rb

@@ -0,0 +1,26 @@
+require 'eventmachine'
+
+module Ably::Modules
+  # EventMachineHelpers module provides common private methods to classes simplifying interaction with EventMachine
+  module EventMachineHelpers
+    private
+
+    # This method allows looped blocks to be run at the next EventMachine tick
+    # @example
+    #   x = 0
+    #   less_than_3 = -> { x < 3 }
+    #   non_blocking_loop_while(less_than_3) do
+    #     x += 1
+    #   end
+    def non_blocking_loop_while(lambda_condition, &execution_block)
+      if lambda_condition.call
+        EventMachine.next_tick do
+          if lambda_condition.call # ensure condition is still met following #next_tick
+            yield
+            non_blocking_loop_while(lambda_condition, &execution_block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/submodules/ably-ruby/lib/ably/modules/http_helpers.rb

@@ -0,0 +1,41 @@
+require 'base64'
+
+require 'ably/version'
+
+require 'ably/rest/middleware/encoder'
+require 'ably/rest/middleware/external_exceptions'
+require 'ably/rest/middleware/fail_if_unsupported_mime_type'
+require 'ably/rest/middleware/logger'
+require 'ably/rest/middleware/parse_json'
+require 'ably/rest/middleware/parse_message_pack'
+
+module Ably::Modules
+  # HttpHelpers provides common private methods to classes to simplify HTTP interactions with Ably
+  module HttpHelpers
+    protected
+    def encode64(text)
+      Base64.encode64(text).gsub("\n", '')
+    end
+
+    def user_agent
+      "Ably Ruby client #{Ably::VERSION} (https://ably.io)"
+    end
+
+    def setup_outgoing_middleware(builder)
+      # Convert request params to "www-form-urlencoded"
+      builder.use Ably::Rest::Middleware::Encoder
+    end
+
+    def setup_incoming_middleware(builder, logger, options = {})
+      builder.use Ably::Rest::Middleware::Logger, logger
+
+      # Parse JSON / MsgPack response bodies. ParseJson must be first (default) parsing middleware
+      if options[:fail_if_unsupported_mime_type] == true
+        builder.use Ably::Rest::Middleware::FailIfUnsupportedMimeType
+      end
+
+      builder.use Ably::Rest::Middleware::ParseJson
+      builder.use Ably::Rest::Middleware::ParseMessagePack
+    end
+  end
+end

data/lib/submodules/ably-ruby/lib/ably/modules/message_pack.rb

@@ -0,0 +1,14 @@
+require 'msgpack'
+
+module Ably::Modules
+  # MessagePack module adds #to_msgpack to the class on the assumption that the class
+  # supports the method #as_json
+  #
+  module MessagePack
+    # Generate a packed MsgPack version of this object based on the JSON representation.
+    # Keys thus use mixedCase syntax as expected by the Realtime API
+    def to_msgpack(*args)
+      as_json(*args).to_msgpack
+    end
+  end
+end

data/lib/submodules/ably-ruby/lib/ably/modules/model_common.rb

@@ -0,0 +1,41 @@
+require 'base64'
+require 'ably/modules/conversions'
+require 'ably/modules/message_pack'
+
+module Ably::Modules
+  # Common model functionality shared across many {Ably::Models}
+  module ModelCommon
+    include Conversions
+    include MessagePack
+
+    # Provide a normal Hash accessor to the underlying raw message object
+    #
+    # @return [Object]
+    def [](key)
+      hash[key]
+    end
+
+    def ==(other)
+      other.kind_of?(self.class) &&
+        hash == other.hash
+    end
+
+    # Return a JSON ready object from the underlying #hash using Ably naming conventions for keys
+    def as_json
+      hash.as_json.dup
+    end
+
+    # Stringify the JSON representation of this object from the underlying #hash
+    def to_json(*args)
+      as_json.to_json(*args)
+    end
+
+    private
+    def ensure_utf8_string_for(attribute, value)
+      if value
+        raise ArgumentError, "#{attribute} must be a String" unless value.kind_of?(String)
+        raise ArgumentError, "#{attribute} cannot use ASCII_8BIT encoding, please use UTF_8 encoding" unless value.encoding == Encoding::UTF_8
+      end
+    end
+  end
+end

data/lib/submodules/ably-ruby/lib/ably/modules/state_emitter.rb

@@ -0,0 +1,153 @@
+module Ably::Modules
+  # StateEmitter module adds a set of generic state related methods to a class on the assumption that
+  # the instance variable @state is used exclusively, the {Enum} STATE is defined prior to inclusion of this
+  # module, and the class is an {EventEmitter}.  It then emits state changes.
+  #
+  # It also ensures the EventEmitter is configured to retrict permitted events to the
+  # the available STATEs and :error.
+  #
+  # @example
+  #   class Connection
+  #     include Ably::Modules::EventEmitter
+  #     extend  Ably::Modules::Enum
+  #     STATE = ruby_enum('STATE',
+  #       :initialized,
+  #       :connecting,
+  #       :connected
+  #     )
+  #     include Ably::Modules::StateEmitter
+  #   end
+  #
+  #   connection = Connection.new
+  #   connection.state = :connecting     # emits :connecting event via EventEmitter, returns STATE.Connecting
+  #   connection.state?(:connected)      # => false
+  #   connection.connecting?             # => true
+  #   connection.state                   # => STATE.Connecting
+  #   connection.state = :invalid        # raises an Exception as only a valid state can be defined
+  #   connection.trigger :invalid        # raises an Exception as only a valid state can be used for EventEmitter
+  #   connection.change_state :connected # emits :connected event via EventEmitter, returns STATE.Connected
+  #   connection.once_or_if(:connected) { puts 'block called once when state is connected or becomes connected' }
+  #
+  module StateEmitter
+    # Current state {Ably::Modules::Enum}
+    #
+    # @return [Symbol] state
+    def state
+      STATE(@state)
+    end
+
+    # Evaluates if check_state matches current state
+    #
+    # @return [Boolean]
+    def state?(check_state)
+      state == check_state
+    end
+
+    # Set the current state {Ably::Modules::Enum}
+    #
+    # @return [Symbol] new state
+    # @api private
+    def state=(new_state, *args)
+      if state != new_state
+        logger.debug("#{self.class}: StateEmitter changed from #{state} => #{new_state}") if respond_to?(:logger, true)
+        @state = STATE(new_state)
+        trigger @state, *args
+      end
+    end
+    alias_method :change_state, :state=
+
+    # If the current state matches the target_state argument the block is called immediately.
+    # Else the block is called once when the target_state is reached.
+    #
+    # If the option block :else is provided then if any state other than target_state is reached, the :else block is called,
+    # however only one of the blocks will ever be called
+    #
+    # @param [Symbol,Ably::Modules::Enum,Array] target_states a single state or array of states that once met, will fire the success block only once
+    # @param [Hash] options
+    # @option options [Proc] :else block called once the state has changed to anything but target_state
+    #
+    # @yield block is called if the state is matched immediately or once when the state is reached
+    #
+    # @return [void]
+    def once_or_if(target_states, options = {})
+      raise ArgumentError, 'Block required' unless block_given?
+
+      if Array(target_states).any? { |target_state| state == target_state }
+        yield
+      else
+        failure_block   = options.fetch(:else, nil)
+        failure_wrapper = nil
+
+        success_wrapper = Proc.new do
+          yield
+          off &success_wrapper
+          off &failure_wrapper if failure_wrapper
+        end
+
+        failure_wrapper = proc do |*args|
+          failure_block.call *args
+          off &success_wrapper
+          off &failure_wrapper
+        end if failure_block
+
+        Array(target_states).each do |target_state|
+          once target_state, &success_wrapper
+
+          once_state_changed do |*args|
+            failure_wrapper.call *args unless state == target_state
+          end if failure_block
+        end
+      end
+    end
+
+    # Calls the block once when the state changes
+    #
+    # @yield block is called once the state changes
+    # @return [void]
+    #
+    # @api private
+    def once_state_changed(&block)
+      raise ArgumentError, 'Block required' unless block_given?
+
+      once_block = proc do |*args|
+        off *self.class::STATE.map, &once_block
+        yield *args
+      end
+
+      once *self.class::STATE.map, &once_block
+    end
+
+    private
+
+    # Returns an {EventMachine::Deferrable} and once the target state is reached, the
+    # success block if provided and {EventMachine::Deferrable#callback} is called.
+    # If the state changes to any other state, the {EventMachine::Deferrable#errback} is called.
+    #
+    def deferrable_for_state_change_to(target_state)
+      EventMachine::DefaultDeferrable.new.tap do |deferrable|
+        once_or_if(target_state, else: proc { |*args| deferrable.fail self, *args }) do
+          yield self if block_given?
+          deferrable.succeed self
+        end
+      end
+    end
+
+    def self.included(klass)
+      klass.configure_event_emitter coerce_into: Proc.new { |event|
+        if event == :error
+          :error
+        else
+          klass::STATE(event)
+        end
+      }
+
+      klass::STATE.each do |state_predicate|
+        klass.instance_eval do
+          define_method("#{state_predicate.to_sym}?") do
+            state?(state_predicate)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/submodules/ably-ruby/lib/ably/modules/state_machine.rb

@@ -0,0 +1,57 @@
+require 'statesman'
+require 'ably/modules/statesman_monkey_patch'
+
+module Ably::Modules
+  # Module providing Statesman StateMachine functionality
+  #
+  # Expects method #logger to be defined
+  #
+  # @api private
+  module StateMachine
+    def self.included(klass)
+      klass.class_eval do
+        include Statesman::Machine
+      end
+      klass.extend Ably::Modules::StatesmanMonkeyPatch
+      klass.extend ClassMethods
+    end
+
+    # Alternative to Statesman's #transition_to that:
+    # * log state change failures to {Logger}
+    # * raise an exception on the {Ably::Realtime::Channel}
+    #
+    # @return [void]
+    def transition_state(state, *args)
+      unless result = transition_to(state, *args)
+        exception = exception_for_state_change_to(state)
+        object.trigger :error, exception
+        logger.fatal "#{self.class}: #{exception.message}"
+      end
+      result
+    end
+
+    # @return [Statesman History Object]
+    def previous_transition
+      history[-2]
+    end
+
+    # @return [Symbol]
+    def previous_state
+      previous_transition.to_state if previous_transition
+    end
+
+    # @return [Ably::Exceptions::StateChangeError]
+    def exception_for_state_change_to(state)
+      error_message = "#{self.class}: Unable to transition from #{current_state} => #{state}"
+      Ably::Exceptions::StateChangeError.new(error_message, nil, 80020)
+    end
+
+    module ClassMethods
+      private
+
+      def is_error_type?(error)
+        error.kind_of?(Ably::Models::ErrorInfo) || error.kind_of?(StandardError)
+      end
+    end
+  end
+end