ably-rest 0.7.1 → 0.7.3

data/lib/submodules/ably-ruby/lib/ably/models/message_encoders/base.rb

@@ -0,0 +1,108 @@
+require 'ably/modules/conversions'
+
+# MessageEncoders are registered with the Ably client library and are responsible
+# for encoding & decoding messages.
+#
+# For example, if a message body is detected as JSON, it is encoded as a String and the encoding attribute
+# of the message is defined as 'json'.
+# Encrypted messages are encoded & decoded by the Cipher encoder.
+#
+module Ably::Models::MessageEncoders
+  extend Ably::Modules::Conversions
+
+  # Base interface for an Ably Encoder
+  #
+  class Base
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    # #encode is called once before a message is sent to Ably
+    #
+    # It is the responsibility of the #encode method to detect the intended encoding and modify the :data & :encoding properties of the message object.
+    #
+    # @param [Hash] message          the message as a Hash object received directly from Ably.
+    #                                The message contains properties :name, :data, :encoding, :timestamp, and optionally :id and :client_id.
+    #                                This #encode method should modify the message Hash if any encoding action is to be taken
+    # @param [Hash] channel_options  the options used to initialize the channel that this message was received on
+    #
+    # @return [void]
+    def encode(message, channel_options)
+      raise "Not yet implemented"
+    end
+
+    # #decode is called once for every encoding step
+    # i.e. if message encoding arrives with 'utf-8/cipher+aes-128-cbc/base64'
+    #      the decoder will call #decode once for each encoding part such as 'base64', then 'cipher+aes-128-cbc', and finally 'utf-8'
+    #
+    # It is the responsibility of the #decode method to detect the current encoding part and modify the :data & :encoding properties of the message object.
+    #
+    # @param [Hash] message          the message as a Hash object received directly from Ably.
+    #                                The message contains properties :name, :data, :encoding, :timestamp, and optionally :id and :client_id.
+    #                                This #encode method should modify the message Hash if any decoding action is to be taken
+    # @param [Hash] channel_options  the options used to initialize the channel that this message was received on
+    #
+    # @return [void]
+    def decode(message, channel_options)
+      raise "Not yet implemented"
+    end
+
+    # Add encoding to the message Hash.
+    # Ensures that encoding delimeter is used where required i.e utf-8/cipher+aes-128-cbc/base64
+    #
+    # @param [Hash]   message   the message as a Hash object received directly from Ably.
+    # @param [String] encoding  encoding to add to the current encoding
+    #
+    # @return [void]
+    def add_encoding_to_message(encoding, message)
+      message[:encoding] = [message[:encoding], encoding].compact.join('/')
+    end
+
+    # Returns the right most encoding form a meessage encoding, and nil if none exists
+    # i.e. current_encoding_part('utf-8/cipher+aes-128-cbc/base64') => 'base64'
+    #
+    # @return [String,nil]
+    def current_encoding_part(message)
+      if message[:encoding]
+        message[:encoding].split('/')[-1]
+      end
+    end
+
+    # Strip the current encoding part within the message Hash.
+    #
+    # For example, calling this method on an :encoding value of 'utf-8/cipher+aes-128-cbc/base64' would update the attribute
+    # :encoding to 'utf-8/cipher+aes-128-cbc'
+    #
+    # @param [Hash]   message   the message as a Hash object received directly from Ably.
+    #
+    # @return [void]
+    def strip_current_encoding_part(message)
+      raise "Cannot strip encoding when there is no encoding for this message" unless message[:encoding]
+      message[:encoding] = message[:encoding].split('/')[0...-1].join('/')
+      message[:encoding] = nil if message[:encoding].empty?
+    end
+
+    # True of the message data payload is empty
+    #
+    # @param [Hash]   message   the message as a Hash object received directly from Ably.
+    #
+    # @return [Boolean]
+    def is_empty?(message)
+      message[:data].nil? || message[:data] == ''
+    end
+  end
+
+  def self.register_default_encoders(client)
+    client.register_encoder Ably::Models::MessageEncoders::Utf8
+    client.register_encoder Ably::Models::MessageEncoders::Json
+    client.register_encoder Ably::Models::MessageEncoders::Cipher
+    client.register_encoder Ably::Models::MessageEncoders::Base64
+  end
+end
+
+require 'ably/models/message_encoders/base64'
+require 'ably/models/message_encoders/cipher'
+require 'ably/models/message_encoders/json'
+require 'ably/models/message_encoders/utf8'

data/lib/submodules/ably-ruby/lib/ably/models/message_encoders/base64.rb

@@ -0,0 +1,40 @@
+require 'base64'
+require 'ably/models/message_encoders/base'
+
+module Ably::Models::MessageEncoders
+  # Base64 binary Encoder and Decoder
+  # Uses encoding identifier 'base64'
+  #
+  class Base64 < Base
+    ENCODING_ID = 'base64'
+
+    def encode(message, channel_options)
+      return if is_empty?(message)
+
+      if is_binary?(message) && transport_protocol_text?
+        message[:data] = ::Base64.encode64(message[:data])
+        add_encoding_to_message ENCODING_ID, message
+      end
+    end
+
+    def decode(message, channel_options)
+      if is_base64_encoded?(message)
+        message[:data] = ::Base64.decode64(message[:data])
+        strip_current_encoding_part message
+      end
+    end
+
+    private
+    def is_binary?(message)
+      message[:data].kind_of?(String) && message[:data].encoding == Encoding::ASCII_8BIT
+    end
+
+    def is_base64_encoded?(message)
+      current_encoding_part(message).to_s.match(/^#{ENCODING_ID}$/i)
+    end
+
+    def transport_protocol_text?
+      !client.protocol_binary?
+    end
+  end
+end

data/lib/submodules/ably-ruby/lib/ably/models/message_encoders/cipher.rb

@@ -0,0 +1,83 @@
+require 'ably/exceptions'
+require 'ably/models/message_encoders/base'
+require 'ably/util/crypto'
+
+module Ably::Models::MessageEncoders
+  # Cipher Encoder & Decoder that automatically encrypts & decrypts messages using Ably::Util::Crypto
+  # when a channel has option encrypted: true.
+  #
+  class Cipher < Base
+    ENCODING_ID = 'cipher'
+
+    def initialize(*args)
+      super
+      @cryptos = Hash.new
+    end
+
+    def encode(message, channel_options)
+      return if is_empty?(message)
+      return if already_encrypted?(message)
+
+      if channel_configured_for_encryption?(channel_options)
+        add_encoding_to_message 'utf-8', message unless is_binary?(message) || is_utf8_encoded?(message)
+
+        crypto = crypto_for(channel_options)
+        message[:data] = crypto.encrypt(message[:data])
+        add_encoding_to_message "#{ENCODING_ID}+#{crypto.cipher_type.downcase}", message
+      end
+    rescue ArgumentError => e
+      raise Ably::Exceptions::CipherError.new(e.message, nil, 92005)
+    rescue RuntimeError => e
+      if e.message.match(/unsupported cipher algorithm/i)
+        raise Ably::Exceptions::CipherError.new(e.message, nil, 92004)
+      end
+    end
+
+    def decode(message, channel_options)
+      if is_cipher_encoded?(message)
+        unless channel_configured_for_encryption?(channel_options)
+          raise Ably::Exceptions::CipherError.new('Message cannot be decrypted as the channel is not set up for encryption & decryption', nil, 92001)
+        end
+
+        crypto = crypto_for(channel_options)
+        unless crypto.cipher_type == cipher_algorithm(message).upcase
+          raise Ably::Exceptions::CipherError.new("Cipher algorithm #{crypto.cipher_type} does not match message cipher algorithm of #{cipher_algorithm(message).upcase}", nil, 92002)
+        end
+
+        message[:data] = crypto.decrypt(message[:data])
+        strip_current_encoding_part message
+      end
+    rescue OpenSSL::Cipher::CipherError => e
+      raise Ably::Exceptions::CipherError.new("CipherError decrypting data, the private key may not be correct", nil, 92003)
+    end
+
+    private
+    def is_binary?(message)
+      message.fetch(:data, '').encoding == Encoding::ASCII_8BIT
+    end
+
+    def is_utf8_encoded?(message)
+      current_encoding_part(message).to_s.match(/^utf-8$/i)
+    end
+
+    def crypto_for(channel_options)
+      @cryptos[channel_options.fetch(:cipher_params, :default)] ||= Ably::Util::Crypto.new(channel_options.fetch(:cipher_params, {}))
+    end
+
+    def channel_configured_for_encryption?(channel_options)
+      channel_options.fetch(:encrypted, false)
+    end
+
+    def is_cipher_encoded?(message)
+      !cipher_algorithm(message).nil?
+    end
+
+    def cipher_algorithm(message)
+      current_encoding_part(message).to_s[/^#{ENCODING_ID}\+([\w_-]+)$/, 1]
+    end
+
+    def already_encrypted?(message)
+      message.fetch(:encoding, '').to_s.match(%r{(^|/)#{ENCODING_ID}\+([\w_-]+)($|/)})
+    end
+  end
+end

data/lib/submodules/ably-ruby/lib/ably/models/message_encoders/json.rb

@@ -0,0 +1,34 @@
+require 'json'
+require 'ably/models/message_encoders/base'
+
+module Ably::Models::MessageEncoders
+  # JSON Encoder and Decoder
+  # Uses encoding identifier 'json' and encodes all objects that are not strings or byte arrays
+  #
+  class Json < Base
+    ENCODING_ID = 'json'
+
+    def encode(message, channel_options)
+      if needs_json_encoding?(message)
+        message[:data] = ::JSON.dump(message[:data])
+        add_encoding_to_message ENCODING_ID, message
+      end
+    end
+
+    def decode(message, channel_options)
+      if is_json_encoded?(message)
+        message[:data] = ::JSON.parse(message[:data])
+        strip_current_encoding_part message
+      end
+    end
+
+    private
+    def needs_json_encoding?(message)
+      !message[:data].kind_of?(String) && !message[:data].nil?
+    end
+
+    def is_json_encoded?(message)
+      current_encoding_part(message).to_s.match(/^#{ENCODING_ID}$/i)
+    end
+  end
+end

data/lib/submodules/ably-ruby/lib/ably/models/message_encoders/utf8.rb

@@ -0,0 +1,26 @@
+require 'ably/models/message_encoders/base'
+
+module Ably::Models::MessageEncoders
+  # Utf8 Encoder and Decoder
+  # Uses encoding identifier 'utf-8' and encodes all JSON objects as UTF-8, and sets the encoding when decoding
+  #
+  class Utf8 < Base
+    ENCODING_ID = 'utf-8'
+
+    def encode(message, channel_options)
+      # no encoding of UTF-8 required
+    end
+
+    def decode(message, channel_options)
+      if is_utf8_encoded?(message)
+        message[:data] = message[:data].force_encoding(Encoding::UTF_8)
+        strip_current_encoding_part message
+      end
+    end
+
+    private
+    def is_utf8_encoded?(message)
+      current_encoding_part(message).to_s.match(/^#{ENCODING_ID}$/i)
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+module Ably::Models
+  # When Log Level set to none, this NilLogger is used to silence all logging
+  # NilLogger provides a Ruby Logger compatible interface
+  class NilLogger
+    def null_method(*args)
+    end
+
+    def level
+      :none
+    end
+
+    def level=(value)
+      level
+    end
+
+    [:fatal, :error, :warn, :info, :debug].each do |method|
+      alias_method method, :null_method
+    end
+  end
+end

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

@@ -0,0 +1,173 @@
+module Ably::Models
+  # Wraps any Ably HTTP response that supports paging and automatically provides methods to iterate through
+  # the array of resources using {#first_page}, {#next_page}, {#first_page?} and {#last_page?}
+  #
+  # Paging information is provided by Ably in the LINK HTTP headers
+  class PaginatedResource
+    include Enumerable
+    include Ably::Modules::AsyncWrapper if defined?(Ably::Realtime)
+
+    # @param [Faraday::Response] http_response Initial HTTP response from an Ably request to a paged resource
+    # @param [String] base_url Base URL for request that generated the http_response so that subsequent paged requests can be made
+    # @param [Client] client {Ably::Client} used to make the request to Ably
+    # @param [Hash] options Options for this paged resource
+    # @option options [Symbol,String] :coerce_into symbol or string representing class that should be used to create each item in the PaginatedResource
+    #
+    # @yield [Object] block will be called for each resource object for the current page.  This is a useful way to apply a transformation to any page resources after they are retrieved
+    #
+    # @return [PaginatedResource]
+    def initialize(http_response, base_url, client, options = {}, &each_block)
+      @http_response = http_response
+      @client        = client
+      @base_url      = "#{base_url.gsub(%r{/[^/]*$}, '')}/"
+      @coerce_into   = options[:coerce_into]
+      @raw_body      = http_response.body
+      @each_block    = each_block
+      @make_async    = options.fetch(:async_blocking_operations, false)
+
+      @body = http_response.body
+      @body = coerce_items_into(body, @coerce_into) if @coerce_into
+      @body = body.map { |item| yield item } if block_given?
+    end
+
+    # Retrieve the first page of results.
+    # When used as part of the {Ably::Realtime} library, it will return a {EventMachine::Deferrable} object,
+    #   and allows an optional success callback block to be provided.
+    #
+    # @return [PaginatedResource,EventMachine::Deferrable]
+    def first_page(&success_callback)
+      async_wrap_if(make_async, success_callback) do
+        PaginatedResource.new(client.get(pagination_url('first')), base_url, client, pagination_options, &each_block)
+      end
+    end
+
+    # Retrieve the next page of results.
+    # When used as part of the {Ably::Realtime} library, it will return a {EventMachine::Deferrable} object,
+    #   and allows an optional success callback block to be provided.
+    #
+    # @return [PaginatedResource,EventMachine::Deferrable]
+    def next_page(&success_callback)
+      async_wrap_if(make_async, success_callback) do
+        raise Ably::Exceptions::InvalidPageError, 'There are no more pages' if supports_pagination? && last_page?
+        PaginatedResource.new(client.get(pagination_url('next')), base_url, client, pagination_options, &each_block)
+      end
+    end
+
+    # True if this is the last page in the paged resource set
+    #
+    # @return [Boolean]
+    def last_page?
+      !supports_pagination? ||
+        pagination_header('next').nil?
+    end
+
+    # True if this is the first page in the paged resource set
+    #
+    # @return [Boolean]
+    def first_page?
+      !supports_pagination? ||
+        pagination_header('first') == pagination_header('current')
+    end
+
+    # True if the HTTP response supports paging with the expected LINK HTTP headers
+    #
+    # @return [Boolean]
+    def supports_pagination?
+      !pagination_headers.empty?
+    end
+
+    # Standard Array accessor method
+    def [](index)
+      body[index]
+    end
+
+    # Returns number of items within this page, not the total number of items in the entire paged resource set
+    def length
+      body.length
+    end
+    alias_method :count, :length
+    alias_method :size,  :length
+
+    # Method to allow {PaginatedResource} to be {http://ruby-doc.org/core-2.1.3/Enumerable.html Enumerable}
+    def each(&block)
+      return to_enum(:each) unless block_given?
+      body.each(&block)
+    end
+
+    # First item in this page
+    def first
+      body.first
+    end
+
+    # Last item in this page
+    def last
+      body.last
+    end
+
+    def inspect
+      <<-EOF.gsub(/^        /, '')
+        #<#{self.class.name}:#{self.object_id}
+         @base_url="#{base_url}",
+         @first_page?=#{!!first_page?},
+         @last_page?=#{!!first_page?},
+         @body=
+           #{body.map { |item| item.inspect }.join(",\n           ") }
+        >
+      EOF
+    end
+
+    private
+    attr_reader :body, :http_response, :base_url, :client, :coerce_into, :raw_body, :each_block, :make_async
+
+    def coerce_items_into(items, type_string)
+      items.map do |item|
+        @coerce_into.split('::').inject(Kernel) do |base, klass_name|
+          base.public_send(:const_get, klass_name)
+        end.new(item)
+      end
+    end
+
+    def pagination_headers
+      link_regex = %r{<(?<url>[^>]+)>; rel="(?<rel>[^"]+)"}
+      @pagination_headers ||= begin
+        # All `Link:` headers are concatenated by Faraday into a comma separated list
+        # Finding matching `<url>; rel="rel"` pairs
+        link_headers = http_response.headers['link'] || ''
+        link_headers.scan(link_regex).each_with_object({}) do |val_array, hash|
+          url, rel = val_array
+          hash[rel] = url
+        end
+      end
+    end
+
+    def pagination_header(id)
+      pagination_headers[id]
+    end
+
+    def pagination_url(id)
+      raise Ably::Exceptions::InvalidPageError, "Paging header link #{id} does not exist" unless pagination_header(id)
+
+      if pagination_header(id).match(%r{^\./})
+        "#{base_url}#{pagination_header(id)[2..-1]}"
+      else
+        pagination_header[id]
+      end
+    end
+
+    def pagination_options
+      {
+        coerce_into: coerce_into,
+        async_blocking_operations: make_async
+      }
+    end
+
+    def async_wrap_if(is_realtime, success_callback, &operation)
+      if is_realtime
+        raise 'EventMachine is required for asynchronous operations' unless defined?(EventMachine)
+        async_wrap success_callback, &operation
+      else
+        yield
+      end
+    end
+  end
+end