ably-rest 0.7.1 → 0.7.3

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

@@ -0,0 +1,69 @@
+module Ably
+  module Exceptions
+    # Base Ably exception class that contains status and code values used by Ably
+    # Refer to https://github.com/ably/ably-common/blob/master/protocol/errors.json
+    #
+    # @!attribute [r] message
+    #   @return [String] Error message from Ably
+    # @!attribute [r] status
+    #   @return [String] HTTP status code of error
+    # @!attribute [r] code
+    #   @return [String] Ably specific error code
+    class BaseAblyException < StandardError
+      attr_reader :status, :code
+      def initialize(message, status = nil, code = nil)
+        super message
+        @status = status
+        @code = code
+      end
+    end
+
+    # An invalid request was received by Ably
+    class InvalidRequest < BaseAblyException; end
+
+    # The token is invalid
+    class InvalidToken < BaseAblyException; end
+
+    # Ably Protocol message received that is invalid
+    class ProtocolError < BaseAblyException; end
+
+    # Encryption or Decryption failure
+    class CipherError < BaseAblyException; end
+
+    # Encoding or decoding failure
+    class EncoderError < BaseAblyException; end
+
+    # Connection error from Realtime or REST service
+    class ConnectionError < BaseAblyException
+      def initialize(message, status = nil, code = nil, base_error = nil)
+        super message, status, code
+        @base_error = base_error
+      end
+    end
+
+    # Connection Timeout accessing Realtime or REST service
+    class ConnectionTimeoutError < ConnectionError; end
+
+    # Invalid State Change error on a {https://github.com/gocardless/statesman Statesman State Machine}
+    class StateChangeError < BaseAblyException; end
+
+    # A generic Ably exception taht supports a status & code.
+    # See https://github.com/ably/ably-common/blob/master/protocol/errors.json for a list of Ably errors
+    class Standard < BaseAblyException; end
+
+    # The HTTP request has returned a 500 error
+    class ServerError < BaseAblyException; end
+
+    # PaginatedResource cannot retrieve the page
+    class InvalidPageError < BaseAblyException; end
+
+    # The expected response from the server was invalid
+    class InvalidResponseBody < BaseAblyException; end
+
+    # The request cannot be performed because it is insecure
+    class InsecureRequestError < BaseAblyException; end
+
+    # The token request could not be created
+    class TokenRequestError < BaseAblyException; end
+  end
+end

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

@@ -0,0 +1,102 @@
+module Ably
+  # Logger unifies logging for #debug, #info, #warn, #error, and #fatal messages.
+  # A new Ably client uses this Logger and sets the appropriate log level.
+  # A custom Logger can be configured when instantiating the client, refer to the {Ably::Rest::Client} and {Ably::Realtime::Client} documentation
+  #
+  class Logger
+    extend Forwardable
+
+    # @param client        [Ably::Rest::Client,Ably::Realtime::Client] Rest or Realtime Ably client
+    # @param log_level     [Integer] {http://www.ruby-doc.org/stdlib-1.9.3/libdoc/logger/rdoc/Logger.html Ruby Logger} log level
+    # @param custom_logger [nil,Object] A custom logger can optionally be used instead of the,
+    #                      however it must provide a {http://www.ruby-doc.org/stdlib-1.9.3/libdoc/logger/rdoc/Logger.html Ruby Logger} compatible interface.
+    #
+    def initialize(client, log_level, custom_logger = nil)
+      @client        = client
+      @custom_logger = custom_logger
+      @logger        = custom_logger || default_logger
+      @log_level     = log_level
+
+      ensure_logger_interface_is_valid
+
+      @logger.level = log_level
+    end
+
+    # The logger used by this class, defaults to {http://www.ruby-doc.org/stdlib-1.9.3/libdoc/logger/rdoc/Logger.html Ruby Logger}
+    # @return {Object,Logger}
+    attr_reader :logger
+
+    # If a custom logger is being used with this Logger, this property is not nil
+    # @return {nil,Object}
+    attr_reader :custom_logger
+
+    # The log level ranging from DEBUG to FATAL, refer to http://www.ruby-doc.org/stdlib-1.9.3/libdoc/logger/rdoc/Logger.html
+    # @return {Integer}
+    attr_reader :log_level
+
+    def_delegators :logger, :fatal, :error, :warn, :info, :debug
+
+    private
+    attr_reader :client
+
+    def color(color_value, string)
+      "\033[#{color_value}m#{string}\033[0m"
+    end
+
+    def red(string)
+      color(31, string)
+    end
+
+    def magenta(string)
+      color(35, string)
+    end
+
+    def cyan(string)
+      color(36, string)
+    end
+
+    def connection_id
+      if realtime?
+        if client.connection.id
+          "[#{cyan(client.connection.id)}] "
+        else
+          "[ #{cyan('--')} ] "
+        end
+      end
+    end
+
+    def realtime?
+      defined?(Ably::Realtime::Client) && client.kind_of?(Ably::Realtime::Client)
+    end
+
+    def default_logger
+      ::Logger.new(STDOUT).tap do |logger|
+        logger.formatter = proc do |severity, datetime, progname, msg|
+          severity = ::Logger::SEV_LABEL.index(severity) if severity.kind_of?(String)
+
+          formatted_date = if severity == ::Logger::DEBUG
+            datetime.strftime("%H:%M:%S.%L")
+          else
+            datetime.strftime("%Y-%m-%d %H:%M:%S.%L")
+          end
+
+          severity_label = if severity <= ::Logger::INFO
+            magenta(::Logger::SEV_LABEL[severity])
+          else
+            red(::Logger::SEV_LABEL[severity])
+          end
+
+          "#{formatted_date} #{severity_label} #{connection_id}#{msg}\n"
+        end
+      end
+    end
+
+    def ensure_logger_interface_is_valid
+      %w(fatal error warn info debug level level=).each do |method|
+        unless logger.respond_to?(method)
+          raise ArgumentError, "The custom Logger's interface does not provide the method '#{method}'"
+        end
+      end
+    end
+  end
+end

data/lib/submodules/ably-ruby/lib/ably/models/error_info.rb

@@ -0,0 +1,37 @@
+module Ably::Models
+  # An exception type encapsulating error information containing
+  # an Ably-specific error code and generic status code.
+  #
+  # @!attribute [r] message
+  #   @return [String] Additional reason information, where available
+  # @!attribute [r] code
+  #   @return [Integer] Ably error code (see ably-common/protocol/errors.json)
+  # @!attribute [r] status
+  #   @return [Integer] HTTP Status Code corresponding to this error, where applicable
+  # @!attribute [r] hash
+  #   @return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys
+  #
+  class ErrorInfo
+    include Ably::Modules::ModelCommon
+
+    def initialize(hash_object)
+      @raw_hash_object = hash_object
+      @hash_object     = IdiomaticRubyWrapper(hash_object.clone.freeze)
+    end
+
+    %w(message code status_code).each do |attribute|
+      define_method attribute do
+        hash[attribute.to_sym]
+      end
+    end
+    alias_method :status, :status_code
+
+    def hash
+      @hash_object
+    end
+
+    def to_s
+      "Error: #{message} (code: #{code}, http status: #{status})"
+    end
+  end
+end

data/lib/submodules/ably-ruby/lib/ably/models/idiomatic_ruby_wrapper.rb

@@ -0,0 +1,223 @@
+require 'logger'
+
+module Ably::Modules
+  module Conversions
+    private
+    # Creates or returns an {IdiomaticRubyWrapper} ensuring it never wraps itself
+    #
+    # @return {IdiomaticRubyWrapper}
+    def IdiomaticRubyWrapper(object, options = {})
+      case object
+      when Ably::Models::IdiomaticRubyWrapper
+        object
+      else
+        Ably::Models::IdiomaticRubyWrapper.new(object, options)
+      end
+    end
+  end
+end
+
+module Ably::Models
+  # Wraps Hash objects returned by Ably service to appear as Idiomatic Ruby Hashes with symbol keys
+  # It recursively wraps containing Hashes, but will stop wrapping at arrays, any other non Hash object, or any key matching the `:stops_at` options
+  # It also provides methods matching the symbolic keys for convenience
+  #
+  # @example
+  #   ruby_hash = IdiomaticRubyWrapper.new({ 'keyValue' => 'true' })
+  #   # or recommended to avoid wrapping wrapped objects
+  #   ruby_hash = IdiomaticRubyWrapper({ 'keyValue' => 'true' })
+  #
+  #   ruby_hash[:key_value] # => 'true'
+  #   ruby_hash.key_value # => 'true'
+  #   ruby_hash[:key_value] = 'new_value'
+  #   ruby_hash.key_value # => 'new_value'
+  #
+  #   ruby_hash[:none] # => nil
+  #   ruby_hash.none # => nil
+  #
+  # @!attribute [r] stop_at
+  #   @return [Array<Symbol,String>] array of keys that this wrapper should stop wrapping at to preserve the underlying Hash as is
+  #
+  class IdiomaticRubyWrapper
+    include Enumerable
+    include Ably::Modules::Conversions
+    include Ably::Modules::MessagePack
+
+    attr_reader :stop_at
+
+    # Creates an IdiomaticRubyWrapper around the mixed case Hash object
+    #
+    # @attribute [Hash] mixedCaseHashObject mixed case Hash object
+    # @attribute [Array<Symbol,String>] stop_at array of keys that this wrapper should stop wrapping at to preserve the underlying Hash as is
+    #
+    def initialize(mixedCaseHashObject, options = {})
+      stop_at = options.fetch(:stop_at, [])
+
+      if mixedCaseHashObject.kind_of?(IdiomaticRubyWrapper)
+        $stderr.puts "<IdiomaticRubyWrapper#initialize> WARNING: Wrapping a IdiomaticRubyWrapper with another IdiomaticRubyWrapper"
+      end
+
+      @hash = mixedCaseHashObject
+      @stop_at = Array(stop_at).each_with_object({}) do |key, hash|
+        hash[convert_to_snake_case_symbol(key)] = true
+      end.freeze
+    end
+
+    def [](key)
+      value = hash[source_key_for(key)]
+      if stop_at?(key) || !value.kind_of?(Hash)
+        value
+      else
+        IdiomaticRubyWrapper.new(value, stop_at: stop_at)
+      end
+    end
+
+    def []=(key, value)
+      hash[source_key_for(key)] = value
+    end
+
+    def fetch(key, default = nil)
+      if has_key?(key)
+        self[key]
+      else
+        if default
+          default
+        elsif block_given?
+          yield key
+        else
+          raise KeyError, "key not found: #{key}"
+        end
+      end
+    end
+
+    def size
+      hash.size
+    end
+
+    def keys
+      map { |key, value| key }
+    end
+
+    def values
+      map { |key, value| value }
+    end
+
+    def has_key?(key)
+      hash.has_key?(source_key_for(key))
+    end
+
+    # Method ensuring this {IdiomaticRubyWrapper} is {http://ruby-doc.org/core-2.1.3/Enumerable.html Enumerable}
+    def each
+      return to_enum(:each) unless block_given?
+
+      hash.each do |key, value|
+        key = convert_to_snake_case_symbol(key)
+        value = self[key]
+        yield key, value
+      end
+    end
+
+    # Compare object based on Hash equivalent
+    def ==(other)
+      return false unless other.kind_of?(self.class) || other.kind_of?(Hash)
+
+      other = other.to_hash if other.kind_of?(self.class)
+      to_hash == other
+    end
+
+    def method_missing(method_sym, *arguments)
+      key = method_sym.to_s.gsub(%r{=$}, '')
+      return super if !has_key?(key)
+
+      if method_sym.to_s.match(%r{=$})
+        raise ArgumentError, "Cannot set #{method_sym} with more than one argument" unless arguments.length == 1
+        self[key] = arguments.first
+      else
+        raise ArgumentError, "Cannot pass an argument to #{method_sym} when retrieving its value" unless arguments.empty?
+        self[method_sym]
+      end
+    end
+
+    # Access to the raw Hash object provided to the constructer of this wrapper
+    def hash
+      @hash
+    end
+
+    # Takes the underlying Hash object and returns it in as a JSON ready Hash object using snakeCase for compability with the Ably service.
+    # Note name clashes are ignored and will result in loss of one or more values
+    # @example
+    #   wrapper = IdiomaticRubyWrapper({ 'mixedCase': true, mixed_case: false, 'snake_case': 1 })
+    #   wrapper.as_json({ 'mixedCase': true, 'snakeCase': 1 })
+    def as_json(*args)
+      hash.each_with_object({}) do |key_val, new_hash|
+        key, val                 = key_val
+        mixed_case_key           = convert_to_mixed_case(key)
+        wrapped_val              = self[key]
+        wrapped_val              = wrapped_val.as_json(args) if wrapped_val.kind_of?(IdiomaticRubyWrapper)
+
+        new_hash[mixed_case_key] = wrapped_val
+      end
+    end
+
+    # Converts the current wrapped mixedCase object to JSON
+    # using mixedCase syntax as expected by the Realtime API
+    def to_json(*args)
+      as_json(args).to_json
+    end
+
+    # Generate a symbolized Hash object representing the underlying Hash in a Ruby friendly format.
+    # Note name clashes are ignored and will result in loss of one or more values
+    # @example
+    #   wrapper = IdiomaticRubyWrapper({ 'mixedCase': true, mixed_case: false, 'snake_case': 1 })
+    #   wrapper.to_hash({ mixed_case: true, snake_case: 1 })
+    def to_hash(*args)
+      each_with_object({}) do |key_val, hash|
+        key, val  = key_val
+        val       = val.to_hash(args) if val.kind_of?(IdiomaticRubyWrapper)
+        hash[key] = val
+      end
+    end
+
+    # Method to create a duplicate of the underlying Hash object
+    # Useful when underlying Hash is frozen
+    def dup
+      Ably::Models::IdiomaticRubyWrapper.new(hash.dup)
+    end
+
+    # Freeze the underlying data
+    def freeze
+      hash.freeze
+    end
+
+    def to_s
+      hash.to_s
+    end
+
+    private
+    def stop_at?(key)
+      @stop_at.has_key?(key)
+    end
+
+    # We assume by default all keys are interchangeable between :this_format and 'thisFormat'
+    # However, this method will find other fallback formats such as CamelCase or :symbols if a matching
+    # key is not found in mixedCase.
+    def source_key_for(symbolized_key)
+      format_preferences = [
+        proc { |key_sym| convert_to_mixed_case(key_sym) },
+        proc { |key_sym| key_sym.to_sym },
+        proc { |key_sym| key_sym.to_s },
+        proc { |key_sym| convert_to_mixed_case(key_sym).to_sym },
+        proc { |key_sym| convert_to_lower_case(key_sym) },
+        proc { |key_sym| convert_to_lower_case(key_sym).to_sym },
+        proc { |key_sym| convert_to_mixed_case(key_sym, force_camel: true) },
+        proc { |key_sym| convert_to_mixed_case(key_sym, force_camel: true).to_sym }
+      ]
+
+      preferred_format = format_preferences.detect do |format|
+        hash.has_key?(format.call(symbolized_key))
+      end || format_preferences.first
+
+      preferred_format.call(symbolized_key)
+    end
+  end
+end

data/lib/submodules/ably-ruby/lib/ably/models/message.rb

@@ -0,0 +1,132 @@
+module Ably::Models
+  # Convert messsage argument to a {Message} object and associate with a protocol message if provided
+  #
+  # @param message [Message,Hash] A message object or Hash of message properties
+  # @param protocol_message [ProtocolMessage] An optional protocol message to assocate the message with
+  #
+  # @return [Message]
+  def self.Message(message, protocol_message = nil)
+    case message
+    when Message
+      message.tap do
+        message.assign_to_protocol_message protocol_message
+      end
+    else
+      Message.new(message, protocol_message)
+    end
+  end
+
+  # A class representing an individual message to be sent or received
+  # via the Ably Realtime service.
+  #
+  # @!attribute [r] name
+  #   @return [String] The event name, if available
+  # @!attribute [r] client_id
+  #   @return [String] The id of the publisher of this message
+  # @!attribute [r] data
+  #   @return [Object] The message payload. See the documentation for supported datatypes.
+  # @!attribute [r] encoding
+  #   @return [Object] The encoding for the message data. Encoding and decoding of messages is handled automatically by the client library.
+  #                    Therefore, the `encoding` attribute should always be nil unless an Ably library decoding error has occurred.
+  # @!attribute [r] timestamp
+  #   @return [Time] Timestamp when the message was received by the Ably the real-time service
+  # @!attribute [r] id
+  #   @return [String] A globally unique message ID
+  # @!attribute [r] connection_id
+  #   @return [String] The connection_id of the publisher of the message
+  # @!attribute [r] hash
+  #   @return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys
+  #
+  class Message
+    include Ably::Modules::Conversions
+    include Ably::Modules::Encodeable
+    include Ably::Modules::ModelCommon
+    include EventMachine::Deferrable
+
+    # {Message} initializer
+    #
+    # @param hash_object      [Hash]            object with the underlying message details
+    # @param protocol_message [ProtocolMessage] if this message has been published, then it is associated with a {ProtocolMessage}
+    #
+    def initialize(hash_object, protocol_message = nil)
+      @protocol_message = protocol_message
+      @raw_hash_object  = hash_object
+
+      set_hash_object hash_object
+
+      ensure_utf_8 :name,      name,      allow_nil: true
+      ensure_utf_8 :client_id, client_id, allow_nil: true
+      ensure_utf_8 :encoding,  encoding,  allow_nil: true
+    end
+
+    %w( name client_id encoding connection_id ).each do |attribute|
+      define_method attribute do
+        hash[attribute.to_sym]
+      end
+    end
+
+    def data
+      @data ||= hash[:data].freeze
+    end
+
+    def id
+      hash.fetch(:id) { "#{protocol_message.id!}:#{protocol_message_index}" }
+    end
+
+    def connection_id
+      hash.fetch(:connection_id) { protocol_message.connection_id if assigned_to_protocol_message? }
+    end
+
+    def timestamp
+      if hash[:timestamp]
+        as_time_from_epoch(hash[:timestamp])
+      else
+        protocol_message.timestamp
+      end
+    end
+
+    def hash
+      @hash_object
+    end
+
+    def as_json(*args)
+      raise RuntimeError, ':name is missing, cannot generate a valid Hash for Message' unless name
+
+      hash.dup.tap do |message|
+        decode_binary_data_before_to_json message
+      end.as_json
+    end
+
+    # Assign this message to a ProtocolMessage before delivery to the Ably system
+    # @api private
+    def assign_to_protocol_message(protocol_message)
+      @protocol_message = protocol_message
+    end
+
+    # True if this message is assigned to a ProtocolMessage for delivery to Ably, or received from Ably
+    # @return [Boolean]
+    # @api private
+    def assigned_to_protocol_message?
+      !!@protocol_message
+    end
+
+    # The optional ProtocolMessage this message is assigned to.  If ProtocolMessage is nil, an error will be raised.
+    # @return [Ably::Models::ProtocolMessage]
+    # @api private
+    def protocol_message
+      raise RuntimeError, 'Message is not yet published with a ProtocolMessage. ProtocolMessage is nil' if @protocol_message.nil?
+      @protocol_message
+    end
+
+    private
+    attr_reader :raw_hash_object
+
+    def protocol_message_index
+      protocol_message.messages.map(&:object_id).index(self.object_id)
+    end
+
+    def set_hash_object(hash)
+      @hash_object = IdiomaticRubyWrapper(hash.clone.freeze, stop_at: [:data])
+    end
+  end
+end