ably-pubsub-core 0.0.1.pre

data/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/ably/modules/exception_codes.rb

@@ -0,0 +1,128 @@
+# This file is generated by running `rake :generate_error_codes`
+# Do not manually modify this file
+# Generated at: 2018-09-18 18:28:58 UTC
+#
+module Ably
+  module Exceptions
+    module Codes
+      NO_ERROR                                                                         = 10000
+      BAD_REQUEST                                                                      = 40000
+      INVALID_REQUEST_BODY                                                             = 40001
+      INVALID_PARAMETER_NAME                                                           = 40002
+      INVALID_PARAMETER_VALUE                                                          = 40003
+      INVALID_HEADER                                                                   = 40004
+      INVALID_CREDENTIAL                                                               = 40005
+      INVALID_CONNECTION_ID                                                            = 40006
+      INVALID_MESSAGE_ID                                                               = 40007
+      INVALID_CONTENT_LENGTH                                                           = 40008
+      MAXIMUM_MESSAGE_LENGTH_EXCEEDED                                                  = 40009
+      INVALID_CHANNEL_NAME                                                             = 40010
+      STALE_RING_STATE                                                                 = 40011
+      INVALID_CLIENT_ID                                                                = 40012
+      INVALID_MESSAGE_DATA_OR_ENCODING                                                 = 40013
+      RESOURCE_DISPOSED                                                                = 40014
+      INVALID_DEVICE_ID                                                                = 40015
+      BATCH_ERROR                                                                      = 40020
+      INVALID_PUBLISH_REQUEST_UNSPECIFIED                                              = 40030
+      INVALID_PUBLISH_REQUEST_INVALID_CLIENTSPECIFIED_ID                               = 40031
+      UNAUTHORIZED                                                                     = 40100
+      INVALID_CREDENTIALS                                                              = 40101
+      INCOMPATIBLE_CREDENTIALS                                                         = 40102
+      INVALID_USE_OF_BASIC_AUTH_OVER_NONTLS_TRANSPORT                                  = 40103
+      TIMESTAMP_NOT_CURRENT                                                            = 40104
+      NONCE_VALUE_REPLAYED                                                             = 40105
+      UNABLE_TO_OBTAIN_CREDENTIALS_FROM_GIVEN_PARAMETERS                               = 40106
+      ACCOUNT_DISABLED                                                                 = 40110
+      ACCOUNT_RESTRICTED_CONNECTION_LIMITS_EXCEEDED                                    = 40111
+      ACCOUNT_BLOCKED_MESSAGE_LIMITS_EXCEEDED                                          = 40112
+      ACCOUNT_BLOCKED                                                                  = 40113
+      ACCOUNT_RESTRICTED_CHANNEL_LIMITS_EXCEEDED                                       = 40114
+      APPLICATION_DISABLED                                                             = 40120
+      KEY_ERROR_UNSPECIFIED                                                            = 40130
+      KEY_REVOKED                                                                      = 40131
+      KEY_EXPIRED                                                                      = 40132
+      KEY_DISABLED                                                                     = 40133
+      TOKEN_ERROR_UNSPECIFIED                                                          = 40140
+      TOKEN_REVOKED                                                                    = 40141
+      TOKEN_EXPIRED                                                                    = 40142
+      TOKEN_UNRECOGNISED                                                               = 40143
+      INVALID_JWT_FORMAT                                                               = 40144
+      INVALID_TOKEN_FORMAT                                                             = 40145
+      CONNECTION_BLOCKED_LIMITS_EXCEEDED                                               = 40150
+      OPERATION_NOT_PERMITTED_WITH_PROVIDED_CAPABILITY                                 = 40160
+      ERROR_FROM_CLIENT_TOKEN_CALLBACK                                                 = 40170
+      FORBIDDEN                                                                        = 40300
+      ACCOUNT_DOES_NOT_PERMIT_TLS_CONNECTION                                           = 40310
+      OPERATION_REQUIRES_TLS_CONNECTION                                                = 40311
+      APPLICATION_REQUIRES_AUTHENTICATION                                              = 40320
+      UNABLE_TO_ACTIVATE_ACCOUNT_DUE_TO_PLACEMENT_CONSTRAINT_UNSPECIFIED               = 40330
+      UNABLE_TO_ACTIVATE_ACCOUNT_DUE_TO_PLACEMENT_CONSTRAINT_INCOMPATIBLE_ENVIRONMENT  = 40331
+      UNABLE_TO_ACTIVATE_ACCOUNT_DUE_TO_PLACEMENT_CONSTRAINT_INCOMPATIBLE_SITE         = 40332
+      NOT_FOUND                                                                        = 40400
+      METHOD_NOT_ALLOWED                                                               = 40500
+      RATE_LIMIT_EXCEEDED_NONFATAL_REQUEST_REJECTED_UNSPECIFIED                        = 42910
+      MAX_PERCONNECTION_PUBLISH_RATE_LIMIT_EXCEEDED_NONFATAL_UNABLE_TO_PUBLISH_MESSAGE = 42911
+      RATE_LIMIT_EXCEEDED_FATAL                                                        = 42920
+      MAX_PERCONNECTION_PUBLISH_RATE_LIMIT_EXCEEDED_FATAL_CLOSING_CONNECTION           = 42921
+      INTERNAL_ERROR                                                                   = 50000
+      INTERNAL_CHANNEL_ERROR                                                           = 50001
+      INTERNAL_CONNECTION_ERROR                                                        = 50002
+      TIMEOUT_ERROR                                                                    = 50003
+      REQUEST_FAILED_DUE_TO_OVERLOADED_INSTANCE                                        = 50004
+      REACTOR_OPERATION_FAILED                                                         = 70000
+      REACTOR_OPERATION_FAILED_POST_OPERATION_FAILED                                   = 70001
+      REACTOR_OPERATION_FAILED_POST_OPERATION_RETURNED_UNEXPECTED_CODE                 = 70002
+      REACTOR_OPERATION_FAILED_MAXIMUM_NUMBER_OF_CONCURRENT_INFLIGHT_REQUESTS_EXCEEDED = 70003
+      EXCHANGE_ERROR_UNSPECIFIED                                                       = 71000
+      FORCED_REATTACHMENT_DUE_TO_PERMISSIONS_CHANGE                                    = 71001
+      EXCHANGE_PUBLISHER_ERROR_UNSPECIFIED                                             = 71100
+      NO_SUCH_PUBLISHER                                                                = 71101
+      PUBLISHER_NOT_ENABLED_AS_AN_EXCHANGE_PUBLISHER                                   = 71102
+      EXCHANGE_PRODUCT_ERROR_UNSPECIFIED                                               = 71200
+      NO_SUCH_PRODUCT                                                                  = 71201
+      PRODUCT_DISABLED                                                                 = 71202
+      NO_SUCH_CHANNEL_IN_THIS_PRODUCT                                                  = 71203
+      EXCHANGE_SUBSCRIPTION_ERROR_UNSPECIFIED                                          = 71300
+      SUBSCRIPTION_DISABLED                                                            = 71301
+      REQUESTER_HAS_NO_SUBSCRIPTION_TO_THIS_PRODUCT                                    = 71302
+      CONNECTION_FAILED                                                                = 80000
+      CONNECTION_FAILED_NO_COMPATIBLE_TRANSPORT                                        = 80001
+      CONNECTION_SUSPENDED                                                             = 80002
+      DISCONNECTED                                                                     = 80003
+      ALREADY_CONNECTED                                                                = 80004
+      INVALID_CONNECTION_ID_REMOTE_NOT_FOUND                                           = 80005
+      UNABLE_TO_RECOVER_CONNECTION_MESSAGES_EXPIRED                                    = 80006
+      UNABLE_TO_RECOVER_CONNECTION_MESSAGE_LIMIT_EXCEEDED                              = 80007
+      UNABLE_TO_RECOVER_CONNECTION_CONNECTION_EXPIRED                                  = 80008
+      CONNECTION_NOT_ESTABLISHED_NO_TRANSPORT_HANDLE                                   = 80009
+      INVALID_OPERATION_INVALID_TRANSPORT_HANDLE                                       = 80010
+      UNABLE_TO_RECOVER_CONNECTION_INCOMPATIBLE_AUTH_PARAMS                            = 80011
+      UNABLE_TO_RECOVER_CONNECTION_INVALID_OR_UNSPECIFIED_CONNECTION_SERIAL            = 80012
+      PROTOCOL_ERROR                                                                   = 80013
+      CONNECTION_TIMED_OUT                                                             = 80014
+      INCOMPATIBLE_CONNECTION_PARAMETERS                                               = 80015
+      OPERATION_ON_SUPERSEDED_TRANSPORT                                                = 80016
+      CONNECTION_CLOSED                                                                = 80017
+      INVALID_CONNECTION_ID_INVALID_FORMAT                                             = 80018
+      CLIENT_CONFIGURED_AUTHENTICATION_PROVIDER_REQUEST_FAILED                         = 80019
+      CONTINUITY_LOSS_DUE_TO_MAXIMUM_SUBSCRIBE_MESSAGE_RATE_EXCEEDED                   = 80020
+      CLIENT_RESTRICTION_NOT_SATISFIED                                                 = 80030
+      CHANNEL_OPERATION_FAILED                                                         = 90000
+      CHANNEL_OPERATION_FAILED_INVALID_CHANNEL_STATE                                   = 90001
+      CHANNEL_OPERATION_FAILED_EPOCH_EXPIRED_OR_NEVER_EXISTED                          = 90002
+      UNABLE_TO_RECOVER_CHANNEL_MESSAGES_EXPIRED                                       = 90003
+      UNABLE_TO_RECOVER_CHANNEL_MESSAGE_LIMIT_EXCEEDED                                 = 90004
+      UNABLE_TO_RECOVER_CHANNEL_NO_MATCHING_EPOCH                                      = 90005
+      UNABLE_TO_RECOVER_CHANNEL_UNBOUNDED_REQUEST                                      = 90006
+      CHANNEL_OPERATION_FAILED_NO_RESPONSE_FROM_SERVER                                 = 90007
+      MAXIMUM_NUMBER_OF_CHANNELS_PER_CONNECTION_EXCEEDED                               = 90010
+      UNABLE_TO_ENTER_PRESENCE_CHANNEL_NO_CLIENTID                                     = 91000
+      UNABLE_TO_ENTER_PRESENCE_CHANNEL_INVALID_CHANNEL_STATE                           = 91001
+      UNABLE_TO_LEAVE_PRESENCE_CHANNEL_THAT_IS_NOT_ENTERED                             = 91002
+      UNABLE_TO_ENTER_PRESENCE_CHANNEL_MAXIMUM_MEMBER_LIMIT_EXCEEDED                   = 91003
+      UNABLE_TO_AUTOMATICALLY_REENTER_PRESENCE_CHANNEL                                 = 91004
+      PRESENCE_STATE_IS_OUT_OF_SYNC                                                    = 91005
+      MEMBER_IMPLICITLY_LEFT_PRESENCE_CHANNEL_CONNECTION_CLOSED                        = 91100
+    end
+  end
+end

data/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://www.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/ably/modules/message_emitter.rb

@@ -0,0 +1,78 @@
+require 'ably/util/pub_sub'
+
+module Ably::Modules
+  # Message emitter, subscriber and unsubscriber (Pub/Sub) functionality common to Channels and Presence
+  # In addition to standard Pub/Sub functionality, it allows subscribers to subscribe to :all.
+  module MessageEmitter
+
+    include Ably::Modules::SafeYield
+
+    # Subscribe to events on this object
+    #
+    # @param names [String,Symbol] Optional, the event name(s) to subscribe to. Defaults to `:all` events
+    # @yield [Object] For each event, the provided block is called with the event payload object
+    #
+    # @return [void]
+    #
+    def subscribe(*names, &callback)
+      raise ArgumentError, 'Block required to subscribe to events' unless block_given?
+      names = :all unless names && !names.empty?
+      Array(names).uniq.each do |name|
+        message_emitter_subscriptions[message_emitter_subscriptions_message_name_key(name)] << callback
+      end
+    end
+
+    # Unsubscribe the matching block for events on the this object.
+    # If a block is not provided, all subscriptions will be unsubscribed
+    #
+    # @param names [String,Symbol] Optional, the event name(s) to unsubscribe from. Defaults to `:all` events
+    #
+    # @return [void]
+    #
+    def unsubscribe(*names, &callback)
+      names = :all unless names && !names.empty?
+      Array(names).each do |name|
+        if name == :all
+          message_emitter_subscriptions.keys
+        else
+          Array(message_emitter_subscriptions_message_name_key(name))
+        end.each do |key|
+          message_emitter_subscriptions[key].delete_if do |block|
+            !block_given? || callback == block
+          end
+        end
+      end
+    end
+
+    # Emit a message to message subscribers
+    #
+    # param name [String,Symbol] the event name
+    # param payload [Object] the event object to emit
+    #
+    # @return [void]
+    #
+    # @api private
+    def emit_message(name, payload)
+      message_emitter_subscriptions[:all].each { |cb| safe_yield(cb, payload) }
+      message_emitter_subscriptions[name].each { |cb| safe_yield(cb, payload) } if name
+    end
+
+    private
+    def message_emitter_subscriptions
+      @message_emitter_subscriptions ||= Hash.new { |hash, key| hash[key] = [] }
+    end
+
+    def message_emitter_subscriptions_message_name_key(name)
+      if name == :all
+        :all
+      else
+        message_emitter_subscriptions_coerce_message_key(name)
+      end
+    end
+
+    # this method can be overwritten easily to enforce use of set key types§
+    def message_emitter_subscriptions_coerce_message_key(name)
+      name.to_s
+    end
+  end
+end

data/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(pk = nil)
+      as_json.to_msgpack(pk)
+    end
+  end
+end

data/lib/ably/modules/model_common.rb

@@ -0,0 +1,84 @@
+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
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Provide a normal Hash accessor to the underlying raw message object
+    #
+    # @return [Object]
+    #
+    def [](key)
+      attributes[key]
+    end
+
+    def ==(other)
+      other.kind_of?(self.class) &&
+        attributes == other.attributes
+    end
+
+    # Return a JSON ready object from the underlying #attributes using Ably naming conventions for keys
+    #
+    # @return [Hash]
+    #
+    def as_json(*args)
+      attributes.as_json.reject { |key, val| val.nil? }
+    end
+
+    # Stringify the JSON representation of this object from the underlying #attributes
+    #
+    # @return [String]
+    #
+    def to_json(*args)
+      as_json.to_json(*args)
+    end
+
+    # @!attribute [r] hash
+    # @return [Integer] Compute a hash-code for this hash. Two hashes with the same content will have the same hash code
+    def hash
+      attributes.hash
+    end
+
+    def to_s
+      representation = attributes.map do |key, val|
+        if val.nil?
+          nil
+        else
+          val_str = val.to_s
+          val_str = "#{val_str[0...80]}..." if val_str.length > 80
+          "#{key}=#{val_str}"
+        end
+      end
+      "<#{self.class.name}: #{representation.compact.join(', ')}>"
+    end
+
+    module ClassMethods
+      # Return a new instance of this object using the provided JSON-like object or JSON string
+      # @param json_like_object  [Hash, String]  JSON-like object or JSON string
+      # @return a new instance to this object
+      def from_json(json_like_object)
+        if json_like_object.kind_of?(String)
+          new(JSON.parse(json_like_object))
+        else
+          new(json_like_object)
+        end
+      end
+    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/ably/modules/safe_deferrable.rb

@@ -0,0 +1,83 @@
+require 'eventmachine'
+
+module Ably::Modules
+  # SafeDeferrable module provides an EventMachine::Deferrable interface to the object it is included in
+  # and is safe to use for for public interfaces of this client library.
+  # Any exceptions raised in the success or failure callbacks are caught and logged to #logger
+  #
+  # An exception in a callback provided by a developer should not break this client library
+  # and stop further execution of code.
+  #
+  # @note this Module requires that the method #logger is available
+  #
+  # See http://www.rubydoc.info/gems/eventmachine/1.0.7/EventMachine/Deferrable
+  #
+  module SafeDeferrable
+    include EventMachine::Deferrable
+
+    # Specify a block to be executed if and when the Deferrable object receives
+    # a status of :succeeded.
+    # See http://www.rubydoc.info/gems/eventmachine/1.0.7/EventMachine/Deferrable#callback-instance_method
+    #
+    # @return [void]
+    #
+    def callback(&block)
+      super do |*args|
+        safe_deferrable_block(*args, &block)
+      end
+    end
+
+    # Specify a block to be executed if and when the Deferrable object receives
+    # a status of :failed.
+    # See http://www.rubydoc.info/gems/eventmachine/1.0.7/EventMachine/Deferrable#errback-instance_method
+    #
+    # @return [void]
+    #
+    def errback(&block)
+      super do |*args|
+        safe_deferrable_block(*args, &block)
+      end
+    end
+
+    # Mark the Deferrable as succeeded and trigger all success callbacks.
+    # See http://www.rubydoc.info/gems/eventmachine/1.0.7/EventMachine/Deferrable#succeed-instance_method
+    #
+    # @return [void]
+    #
+    def succeed(*args)
+      super(*args)
+    end
+
+    # Mark the Deferrable as failed and trigger all error callbacks.
+    # See http://www.rubydoc.info/gems/eventmachine/1.0.7/EventMachine/Deferrable#fail-instance_method
+    #
+    # @return [void]
+    #
+    def fail(*args)
+      super(*args)
+    end
+
+    private
+    def safe_deferrable_block(*args)
+      yield(*args)
+    rescue StandardError => e
+      message = "An exception in a Deferrable callback was caught. #{e.class}: #{e.message}\n#{e.backtrace.join("\n")}"
+      if defined?(:logger) && logger.respond_to?(:error)
+        logger.error message
+      else
+        fallback_logger.error message
+      end
+    end
+
+    def fallback_logger
+      @fallback_logger ||= ::Logger.new(STDOUT).tap do |logger|
+        logger.formatter = lambda do |severity, datetime, progname, msg|
+          [
+            "#{datetime.strftime("%Y-%m-%d %H:%M:%S.%L")} #{::Logger::SEV_LABEL[severity]} #{msg}",
+            "Warning: SafeDeferrable expects the method #logger to be defined in the class it is included in, the method was not found in #{self.class}"
+          ].join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/ably/modules/safe_yield.rb

@@ -0,0 +1,41 @@
+module Ably::Modules
+  # SafeYield provides the method safe_yield that will yield to the consumer
+  # who provided a block, however any exceptions will be caught, logged, and
+  # operation of the client library will continue.
+  #
+  # An exception in a callback provided by a developer should not break this client library
+  # and stop further execution of code.
+  #
+  # @note this Module requires that the method #logger is available
+  #
+  # @api private
+  module SafeYield
+    private
+
+    def safe_yield(block, *args)
+      block.call(*args)
+    rescue StandardError => e
+      message = "An exception in an external block was caught. #{e.class}: #{e.message}\n#{e.backtrace.join("\n")}"
+      safe_yield_log_error message
+    end
+
+    def safe_yield_log_error(message)
+      if defined?(:logger) && logger.respond_to?(:error)
+        return logger.error message
+      end
+    rescue StandardError
+      fallback_logger.error message
+    end
+
+    def fallback_logger
+      @fallback_logger ||= ::Logger.new(STDOUT).tap do |logger|
+        logger.formatter = lambda do |severity, datetime, progname, msg|
+          [
+            "#{datetime.strftime("%Y-%m-%d %H:%M:%S.%L")} #{::Logger::SEV_LABEL[severity]} #{msg}",
+            "Warning: SafeYield expects the method #logger to be defined in the class it is included in, the method was not found in #{self.class}"
+          ].join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/ably/modules/state_emitter.rb

@@ -0,0 +1,181 @@
+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 restrict permitted events to the
+  # the available STATEs or EVENTs if defined i.e. if EVENTs includes an additional type such as
+  # :update, then it will support all EVENTs being emitted. EVENTs must be a superset of STATEs
+  #
+  # @note This module requires that the method #logger is defined.
+  #
+  # @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.emit :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)
+        emit @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 = {}, &block)
+      raise ArgumentError, 'Block required' unless block_given?
+
+      if Array(target_states).any? { |target_state| state == target_state }
+        safe_yield block
+      else
+        failure_block   = options.fetch(:else, nil)
+        failure_wrapper = nil
+
+        success_wrapper = lambda do |*args|
+          yield
+          off(&success_wrapper)
+          off(&failure_wrapper) if failure_wrapper
+        end
+
+        failure_wrapper = lambda do |*args|
+          failure_block.call(*args)
+          off(&success_wrapper)
+          off(&failure_wrapper)
+        end if failure_block
+
+        Array(target_states).each do |target_state|
+          safe_unsafe_method options[:unsafe], :once, target_state, &success_wrapper
+
+          safe_unsafe_method options[:unsafe], :once_state_changed do |*args|
+            failure_wrapper.call(*args) unless state == target_state
+          end if failure_block
+        end
+      end
+    end
+
+    # Equivalent of {#once_or_if} but any exception raised in a block will bubble up and cause this client library to fail.
+    # This method should only be used internally by the client library.
+    # @api private
+    def unsafe_once_or_if(target_states, options = {}, &block)
+      once_or_if(target_states, options.merge(unsafe: true), &block)
+    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(options = {}, &block)
+      raise ArgumentError, 'Block required' unless block_given?
+
+      once_block = lambda do |*args|
+        off(*self.class::STATE.map, &once_block)
+        yield(*args)
+      end
+
+      safe_unsafe_method options[:unsafe], :once, *self.class::STATE.map, &once_block
+    end
+
+    # Equivalent of {#once_state_changed} but any exception raised in a block will bubble up and cause this client library to fail.
+    # This method should only be used internally by the client library.
+    # @api private
+    def unsafe_once_state_changed(&block)
+      once_state_changed(unsafe: true, &block)
+    end
+
+    private
+
+    # Returns an {Ably::Util::SafeDeferrable} and once the target state is reached, the
+    # success block if provided and {Ably::Util::SafeDeferrable#callback} is called.
+    # If the state changes to any other state, the {Ably::Util::SafeDeferrable#errback} is called.
+    #
+    def deferrable_for_state_change_to(target_state)
+      Ably::Util::SafeDeferrable.new(logger).tap do |deferrable|
+        fail_proc = lambda do |state_change|
+          deferrable.fail state_change.reason
+        end
+        once_or_if(target_state, else: fail_proc) do
+          yield self if block_given?
+          deferrable.succeed self
+        end
+      end
+    end
+
+    def self.included(klass)
+      klass.configure_event_emitter coerce_into: lambda { |event|
+        # Special case allows EVENT instead of STATE to be emitted
+        # Relies on the assumption that EVENT is a superset of STATE
+        if klass.const_defined?(:EVENT)
+          klass::EVENT(event)
+        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
+
+    def safe_unsafe_method(unsafe, method_name, *args, &block)
+      public_send("#{'unsafe_' if unsafe}#{method_name}", *args, &block)
+    end
+  end
+end