ably-rest 0.7.1 → 0.7.3

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

@@ -0,0 +1,33 @@
+module Ably::Modules
+  # @api private
+  module StatesmanMonkeyPatch
+    # Override Statesman's #before_transition to support :from arrays
+    # This can be removed once https://github.com/gocardless/statesman/issues/95 is solved
+    def before_transition(options = nil, &block)
+      arrayify_transition(options) do |options_without_from_array|
+        super *options_without_from_array, &block
+      end
+    end
+
+    # Override Statesman's #after_transition to support :from arrays
+    # This can be removed once https://github.com/gocardless/statesman/issues/95 is solved
+    def after_transition(options = nil, &block)
+      arrayify_transition(options) do |options_without_from_array|
+        super *options_without_from_array, &block
+      end
+    end
+
+    private
+    def arrayify_transition(options, &block)
+      if options.nil?
+        yield []
+      elsif options.fetch(:from, nil).kind_of?(Array)
+        options[:from].each do |from_state|
+          yield [options.merge(from: from_state)]
+        end
+      else
+        yield [options]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+module Ably::Modules
+  # Mixing module that assists with {https://github.com/gocardless/statesman Statemans State Machine} state transitions
+  # and maintaining state of this object's #state.
+  #
+  # Expects:
+  #   - @state_machine is set to the StateMachine
+  #   - StateEmitter is included in the object
+  #
+  module UsesStateMachine
+    extend Forwardable
+
+    # Call #transition_to on the StateMachine
+    #
+    # @return [Boolean] true if new_state can be transitioned to by state machine
+    # @api private
+    def transition_state_machine(new_state, emit_object = nil)
+      state_machine.transition_state(new_state, emit_object)
+    end
+
+    # Call #transition_to! on the StateMachine
+    # An exception wil be raised if new_state cannot be transitioned to by state machine
+    #
+    # @return [void]
+    # @api private
+    def transition_state_machine!(new_state, emit_object = nil)
+      state_machine.transition_to!(new_state, emit_object)
+    end
+
+    # Provides an internal method for this object's state to match the StateMachine's current state.
+    # The current object's state will be changed to the StateMachine state and will emit an event
+    # @api private
+    def synchronize_state_with_statemachine(*args)
+      log_state_machine_state_change
+      change_state state_machine.current_state, state_machine.last_transition.metadata
+    end
+
+    # @!attribute [r] previous_state
+    # @return [STATE,nil] The previous state for this connection
+    # @api private
+    def previous_state
+      if state_machine.previous_state
+        STATE(state_machine.previous_state)
+      end
+    end
+
+    # @!attribute [r] state_history
+    # @return [Array<Hash>] All previous states including the current state in date ascending order with Hash properties :state, :metadata, :transitioned_at
+    # @api private
+    def state_history
+      state_machine.history.map do |transition|
+        {
+          state:           STATE(transition.to_state),
+          metadata:        transition.metadata,
+          transitioned_at: transition.created_at
+        }
+      end
+    end
+
+    def_delegators :state_machine, :can_transition_to?
+
+    private
+    attr_reader :state_machine
+
+    def_delegators :state_machine, :exception_for_state_change_to
+
+    def log_state_machine_state_change
+      if state_machine.previous_state
+        logger.debug "#{self.class.name}: Transitioned from #{state_machine.previous_state} => #{state_machine.current_state}"
+      else
+        logger.debug "#{self.class.name}: Transitioned to #{state_machine.current_state}"
+      end
+    end
+  end
+end

data/lib/submodules/ably-ruby/lib/ably/realtime.rb

@@ -0,0 +1,64 @@
+require 'eventmachine'
+require 'websocket/driver'
+
+require 'ably/modules/event_emitter'
+
+require 'ably/realtime/channel'
+require 'ably/realtime/channels'
+require 'ably/realtime/channel/channel_manager'
+require 'ably/realtime/channel/channel_state_machine'
+require 'ably/realtime/client'
+require 'ably/realtime/connection'
+require 'ably/realtime/connection/connection_manager'
+require 'ably/realtime/connection/connection_state_machine'
+require 'ably/realtime/connection/websocket_transport'
+require 'ably/realtime/presence'
+
+Dir.glob(File.expand_path("models/*.rb", File.dirname(__FILE__))).each do |file|
+  require file
+end
+
+Dir.glob(File.expand_path("realtime/models/*.rb", File.dirname(__FILE__))).each do |file|
+  require file
+end
+
+require 'ably/models/message_encoders/base'
+
+require 'ably/realtime/client/incoming_message_dispatcher'
+require 'ably/realtime/client/outgoing_message_dispatcher'
+
+module Ably
+  # Realtime provides the top-level class to be instanced for the Ably Realtime library
+  #
+  # @example
+  #   client = Ably::Realtime.new("xxxxx")
+  #   channel = client.channel("test")
+  #   channel.subscribe do |message|
+  #     message[:name] #=> "greeting"
+  #   end
+  #   channel.publish "greeting", "data"
+  #
+  module Realtime
+    # Convenience method providing an alias to {Ably::Realtime::Client} constructor.
+    #
+    # @param (see Ably::Realtime::Client#initialize)
+    # @option options (see Ably::Realtime::Client#initialize)
+    #
+    # @yield (see Ably::Realtime::Client#initialize)
+    # @yieldparam (see Ably::Realtime::Client#initialize)
+    # @yieldreturn (see Ably::Realtime::Client#initialize)
+    #
+    # @return [Ably::Realtime::Client]
+    #
+    # @example
+    #    # create a new client authenticating with basic auth
+    #    client = Ably::Realtime.new('key.id:secret')
+    #
+    #    # create a new client authenticating with basic auth and a client_id
+    #    client = Ably::Realtime.new(api_key: 'key.id:secret', client_id: 'john')
+    #
+    def self.new(options, &token_request_block)
+      Ably::Realtime::Client.new(options, &token_request_block)
+    end
+  end
+end

data/lib/submodules/ably-ruby/lib/ably/realtime/channel.rb

@@ -0,0 +1,298 @@
+module Ably
+  module Realtime
+    # The Channel class represents a Channel belonging to this application.
+    # The Channel instance allows messages to be published and
+    # received, and controls the lifecycle of this instance's
+    # attachment to the channel.
+    #
+    # Channels will always be in one of the following states:
+    #
+    #   initialized: 0
+    #   attaching:   1
+    #   attached:    2
+    #   detaching:   3
+    #   detached:    4
+    #   failed:      5
+    #
+    # Note that the states are available as Enum-like constants:
+    #
+    #   Channel::STATE.Initialized
+    #   Channel::STATE.Attaching
+    #   Channel::STATE.Attached
+    #   Channel::STATE.Detaching
+    #   Channel::STATE.Detached
+    #   Channel::STATE.Failed
+    #
+    # Channels emit errors - use `on(:error)` to subscribe to errors
+    #
+    # @!attribute [r] state
+    #   @return {Ably::Realtime::Connection::STATE} channel state
+    #
+    class Channel
+      include Ably::Modules::Conversions
+      include Ably::Modules::EventEmitter
+      include Ably::Modules::EventMachineHelpers
+      include Ably::Modules::AsyncWrapper
+      extend Ably::Modules::Enum
+
+      STATE = ruby_enum('STATE',
+        :initialized,
+        :attaching,
+        :attached,
+        :detaching,
+        :detached,
+        :failed
+      )
+      include Ably::Modules::StateEmitter
+      include Ably::Modules::UsesStateMachine
+
+      # Max number of messages to bundle in a single ProtocolMessage
+      MAX_PROTOCOL_MESSAGE_BATCH_SIZE = 50
+
+      # {Ably::Realtime::Client} associated with this channel
+      # @return [Ably::Realtime::Client]
+      attr_reader :client
+
+      # Channel name
+      # @return [String]
+      attr_reader :name
+
+      # Channel options configured for this channel, see {#initialize} for channel_options
+      # @return [Hash]
+      attr_reader :options
+
+      # When a channel failure occurs this attribute contains the Ably Exception
+      # @return [Ably::Models::ErrorInfo,Ably::Exceptions::BaseAblyException]
+      attr_reader :error_reason
+
+      # The Channel manager responsible for attaching, detaching and handling failures for this channel
+      # @return [Ably::Realtime::Channel::ChannelManager]
+      # @api private
+      attr_reader :manager
+
+      # Initialize a new Channel object
+      #
+      # @param  client [Ably::Rest::Client]
+      # @param  name [String] The name of the channel
+      # @param  channel_options [Hash]     Channel options, currently reserved for Encryption options
+      # @option channel_options [Boolean]  :encrypted       setting this to true for this channel will encrypt & decrypt all messages automatically
+      # @option channel_options [Hash]     :cipher_params   A hash of options to configure the encryption. *:key* is required, all other options are optional.  See {Ably::Util::Crypto#initialize} for a list of `cipher_params` options
+      #
+      def initialize(client, name, channel_options = {})
+        ensure_utf_8 :name, name
+
+        @client        = client
+        @name          = name
+        @options       = channel_options.clone.freeze
+        @subscriptions = Hash.new { |hash, key| hash[key] = [] }
+        @queue         = []
+
+        @state_machine = ChannelStateMachine.new(self)
+        @state         = STATE(state_machine.current_state)
+        @manager       = ChannelManager.new(self, client.connection)
+
+        setup_event_handlers
+      end
+
+      # Publish a message on the channel
+      #
+      # @param name [String] The event name of the message
+      # @param data [String,ByteArray] payload for the message
+      # @yield [Ably::Models::Message] On success, will call the block with the {Ably::Models::Message}
+      # @return [Ably::Models::Message] Deferrable {Ably::Models::Message} that supports both success (callback) and failure (errback) callbacks
+      #
+      # @example
+      #   channel.publish('click', 'body')
+      #
+      #   channel.publish('click', 'body') do |message|
+      #     puts "#{message.name} event received with #{message.data}"
+      #   end
+      #
+      #   channel.publish('click', 'body').errback do |message, error|
+      #     puts "#{message.name} was not received, error #{error.message}"
+      #   end
+      #
+      def publish(name, data, &success_block)
+        ensure_utf_8 :name, name
+
+        create_message(name, data).tap do |message|
+          message.callback(&success_block) if block_given?
+          queue_message message
+        end
+      end
+
+      # Subscribe to messages matching providing event name, or all messages if event name not provided
+      #
+      # @param name [String] The event name of the message to subscribe to if provided.  Defaults to all events.
+      # @yield [Ably::Models::Message] For each message received, the block is called
+      #
+      # @return [void]
+      #
+      def subscribe(name = :all, &callback)
+        attach unless attached? || attaching?
+        subscriptions[message_name_key(name)] << callback
+      end
+
+      # Unsubscribe the matching block for messages matching providing event name, or all messages if event name not provided.
+      # If a block is not provided, all subscriptions will be unsubscribed
+      #
+      # @param name [String] The event name of the message to subscribe to if provided.  Defaults to all events.
+      #
+      # @return [void]
+      #
+      def unsubscribe(name = :all, &callback)
+        if message_name_key(name) == :all
+          subscriptions.keys
+        else
+          Array(message_name_key(name))
+        end.each do |key|
+          subscriptions[key].delete_if do |block|
+            !block_given? || callback == block
+          end
+        end
+      end
+
+      # Attach to this channel, and call the block if provided when attached.
+      # Attaching to a channel is implicit in when a message is published or #subscribe is called, so it is uncommon
+      # to need to call attach explicitly.
+      #
+      # @yield [Ably::Realtime::Channel] Block is called as soon as this channel is in the Attached state
+      # @return [EventMachine::Deferrable] Deferrable that supports both success (callback) and failure (errback) callback
+      #
+      def attach(&success_block)
+        transition_state_machine :attaching if can_transition_to?(:attaching)
+        deferrable_for_state_change_to(STATE.Attached, &success_block)
+      end
+
+      # Detach this channel, and call the block if provided when in a Detached or Failed state
+      #
+      # @yield [Ably::Realtime::Channel] Block is called as soon as this channel is in the Detached or Failed state
+      # @return [void]
+      #
+      def detach(&success_block)
+        raise exception_for_state_change_to(:detaching) if failed? || initialized?
+        transition_state_machine :detaching if can_transition_to?(:detaching)
+        deferrable_for_state_change_to(STATE.Detached, &success_block)
+      end
+
+      # Presence object for this Channel.  This controls this client's
+      # presence on the channel and may also be used to obtain presence information
+      # and change events for other members of the channel.
+      #
+      # @return {Ably::Realtime::Presence}
+      #
+      def presence
+        attach if initialized?
+        @presence ||= Presence.new(self)
+      end
+
+      # Return the message history of the channel
+      #
+      # @param (see Ably::Rest::Channel#history)
+      # @option options (see Ably::Rest::Channel#history)
+      #
+      # @yield [Ably::Models::PaginatedResource<Ably::Models::Message>] An Array of {Ably::Models::Message} objects that supports paging (#next_page, #first_page)
+      #
+      # @return [EventMachine::Deferrable]
+      def history(options = {}, &callback)
+        async_wrap(callback) do
+          rest_channel.history(options.merge(async_blocking_operations: true))
+        end
+      end
+
+      # @!attribute [r] __incoming_msgbus__
+      # @return [Ably::Util::PubSub] Client library internal channel incoming message bus
+      # @api private
+      def __incoming_msgbus__
+        @__incoming_msgbus__ ||= Ably::Util::PubSub.new(
+          coerce_into: Proc.new { |event| Ably::Models::ProtocolMessage::ACTION(event) }
+        )
+      end
+
+      # @api private
+      def set_failed_channel_error_reason(error)
+        @error_reason = error
+      end
+
+      # Used by {Ably::Modules::StateEmitter} to debug state changes
+      # @api private
+      def logger
+        client.logger
+      end
+
+      private
+      attr_reader :queue, :subscriptions
+
+      def setup_event_handlers
+        __incoming_msgbus__.subscribe(:message) do |message|
+          message.decode self
+
+          subscriptions[:all].each         { |cb| cb.call(message) }
+          subscriptions[message.name].each { |cb| cb.call(message) }
+        end
+
+        on(STATE.Attached) do
+          process_queue
+        end
+      end
+
+      # Queue message and process queue if channel is attached.
+      # If channel is not yet attached, attempt to attach it before the message queue is processed.
+      def queue_message(message)
+        queue << message
+
+        if attached?
+          process_queue
+        else
+          attach
+        end
+      end
+
+      def messages_in_queue?
+        !queue.empty?
+      end
+
+      # Move messages from Channel Queue into Outgoing Connection Queue
+      def process_queue
+        condition = -> { attached? && messages_in_queue? }
+        non_blocking_loop_while(condition) do
+          send_messages_within_protocol_message queue.shift(MAX_PROTOCOL_MESSAGE_BATCH_SIZE)
+        end
+      end
+
+      def send_messages_within_protocol_message(messages)
+        client.connection.send_protocol_message(
+          action:   Ably::Models::ProtocolMessage::ACTION.Message.to_i,
+          channel:  name,
+          messages: messages
+        )
+      end
+
+      def create_message(name, data)
+        message = { name: name }
+        message.merge!(data: data) unless data.nil?
+        message.merge!(clientId: client.client_id) if client.client_id
+
+        Ably::Models::Message.new(message, nil).tap do |message|
+          message.encode self
+        end
+      end
+
+      def rest_channel
+        client.rest_client.channel(name)
+      end
+
+      def connection
+        client.connection
+      end
+
+      def message_name_key(name)
+        if name == :all
+          :all
+        else
+          name.to_s
+        end
+      end
+    end
+  end
+end