ably-rest 0.7.1 → 0.7.3

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

@@ -0,0 +1,74 @@
+module Ably::Models
+  # Authentication token issued by Ably in response to an token request
+  class Token
+    include Ably::Modules::ModelCommon
+
+    DEFAULTS = {
+      capability: { '*' => ['*'] },
+      ttl:        60 * 60 # 1 hour
+    }
+
+    # Buffer in seconds given to the use of a token prior to it being considered unusable
+    # For example, if buffer is 10s, the token can no longer be used for new requests 9s before it expires
+    TOKEN_EXPIRY_BUFFER = 5
+
+    def initialize(attributes)
+      @hash_object = IdiomaticRubyWrapper(attributes.clone.freeze)
+    end
+
+    # @!attribute [r] id
+    # @return [String] Unique token ID used to authenticate requests
+    def id
+      hash.fetch(:id)
+    end
+
+    # @!attribute [r] key_id
+    # @return [String] Key ID used to create this token
+    def key_id
+      hash.fetch(:key)
+    end
+
+    # @!attribute [r] issued_at
+    # @return [Time] Time the token was issued
+    def issued_at
+      as_time_from_epoch(hash.fetch(:issued_at), granularity: :s)
+    end
+
+    # @!attribute [r] expires_at
+    # @return [Time] Time the token expires
+    def expires_at
+      as_time_from_epoch(hash.fetch(:expires), granularity: :s)
+    end
+
+    # @!attribute [r] capability
+    # @return [Hash] Capabilities assigned to this token
+    def capability
+      hash.fetch(:capability)
+    end
+
+    # @!attribute [r] client_id
+    # @return [String] Optional client ID assigned to this token
+    def client_id
+      hash[:client_id]
+    end
+
+    # @!attribute [r] nonce
+    # @return [String] unique nonce used to generate Token and ensure token generation cannot be replayed
+    def nonce
+      hash.fetch(:nonce)
+    end
+
+    # Returns true if token is expired or about to expire
+    #
+    # @return [Boolean]
+    def expired?
+      expires_at < Time.now + TOKEN_EXPIRY_BUFFER
+    end
+
+    # @!attribute [r] hash
+    # @return [Hash] Access the token Hash object ruby'fied to use symbolized keys
+    def hash
+      @hash_object
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# Ably is the base namespace for the Ably {Ably::Realtime Realtime} & {Ably::Rest Rest} client libraries.
+#
+# Please refer to the {file:README.md Readme} on getting started.
+#
+# @see file:README.md README
+module Ably
+  # Fallback hosts to use when a connection to rest/realtime.ably.io is not possible due to
+  # network failures either at the client, between the client and Ably, within an Ably data center, or at the IO domain registrar
+  #
+  FALLBACK_HOSTS = %w(A.ably-realtime.com B.ably-realtime.com C.ably-realtime.com D.ably-realtime.com E.ably-realtime.com)
+  INTERNET_CHECK = {
+    url:     '//internet-up.ably-realtime.com/is-the-internet-up.txt',
+    ok_text: 'yes'
+  }
+end

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

@@ -0,0 +1,62 @@
+require 'eventmachine'
+
+module Ably::Modules
+  # Provides methods to convert synchronous operations into async operations through the use of
+  # {EventMachine#defer http://www.rubydoc.info/github/eventmachine/eventmachine/EventMachine#defer-class_method}.
+  # The async_wrap method can only be called from within an EventMachine reactor, and must be thread safe.
+  #
+  # @note using this AsyncWrapper should only be used for methods that are used less frequently and typically
+  #       not run with levels of concurrency due to the limited number of threads available to EventMachine by default.
+  #
+  # @example
+  #   class BlockingOperation
+  #     include Aby::Modules::AsyncWrapper
+  #
+  #     def operation(&success_callback)
+  #       async_wrap(success_callback) do
+  #         sleep 1
+  #         'slept'
+  #       end
+  #     end
+  #   end
+  #
+  #   blocking_object = BlockingOperation.new
+  #   deferrable = blocking_object.operation do |result|
+  #     puts "Done with result: #{result}"
+  #   end
+  #   puts "Starting"
+  #
+  #   # => 'Starting'
+  #   # => 'Done with result: slept'
+  #
+  module AsyncWrapper
+    private
+
+    # Will yield the provided block in a new thread and return an {EventMachine::Deferrable http://www.rubydoc.info/github/eventmachine/eventmachine/EventMachine/Deferrable}
+    #
+    # @yield [Object] operation block that is run in a thread
+    # @return [EventMachine::Deferrable]
+    #
+    def async_wrap(success_callback = nil)
+      raise ArgumentError, 'Block required' unless block_given?
+
+      EventMachine::DefaultDeferrable.new.tap do |deferrable|
+        deferrable.callback &success_callback if success_callback
+
+        operation_with_exception_handling = proc do
+          begin
+            yield
+          rescue StandardError => e
+            deferrable.fail e
+          end
+        end
+
+        complete_callback = proc do |result|
+          deferrable.succeed result
+        end
+
+        EventMachine.defer operation_with_exception_handling, complete_callback
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+module Ably::Modules
+  # ChannelsCollection module provides common functionality to the Rest and Realtime Channels objects
+  # such as #get, #[], #fetch, and #release
+  module ChannelsCollection
+    include Enumerable
+
+    def initialize(client, channel_klass)
+      @client         = client
+      @channel_klass  = channel_klass
+      @channels       = {}
+    end
+
+    # Return a Channel for the given name
+    #
+    # @param name [String] The name of the channel
+    # @param channel_options [Hash] Channel options including the encryption options
+    #
+    # @return [Channel]
+    #
+    def get(name, channel_options = {})
+      channels[name] ||= channel_klass.new(client, name, channel_options)
+    end
+    alias_method :[], :get
+
+    # Return a Channel for the given name if it exists, else the block will be called.
+    # This method is intentionally similar to {http://ruby-doc.org/core-2.1.3/Hash.html#method-i-fetch Hash#fetch} providing a simple way to check if a channel exists or not without creating one
+    #
+    # @param name [String] The name of the channel
+    #
+    # @yield [options] (optional) if a missing_block is passed to this method and no channel exists matching the name, this block is called
+    # @yieldparam [String] name of the missing channel
+    #
+    # @return [Channel]
+    #
+    def fetch(name, &missing_block)
+      channels.fetch(name, &missing_block)
+    end
+
+    # Destroy the Channel and releases the associated resources.
+    #
+    # Releasing a Channel is not typically necessary as a channel consumes no resources other than the memory footprint of the
+    # Channel object. Explicitly release channels to free up resources if required
+    #
+    # @param name [String] The name of the channel
+    #
+    # @return [void]
+    #
+    def release(name)
+      channels.delete(name)
+    end
+
+    # @!attribute [r] length
+    # @return [Integer] number of channels created
+    def length
+      channels.length
+    end
+    alias_method :count, :length
+    alias_method :size,  :length
+
+    # Method to allow {ChannelsCollection} to be {http://ruby-doc.org/core-2.1.3/Enumerable.html Enumerable}
+    def each(&block)
+      return to_enum(:each) unless block_given?
+      channels.values.each(&block)
+    end
+
+    private
+    attr_reader :client, :channel_klass, :channels
+  end
+end

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

@@ -0,0 +1,100 @@
+module Ably::Modules
+  # Conversions module provides common timestamp and variable naming conversions to Ably classes.
+  # All methods are private
+  module Conversions
+    extend self
+
+    private
+    def as_since_epoch(time, options = {})
+      granularity = options.fetch(:granularity, :ms)
+
+      case time
+      when Time
+        time.to_f * multiplier_from_granularity(granularity)
+      when Numeric
+        time
+      else
+        raise ArgumentError, 'time argument must be a Numeric or Time object'
+      end.to_i
+    end
+
+    def as_time_from_epoch(time, options = {})
+      granularity = options.fetch(:granularity, :ms)
+
+      case time
+      when Numeric
+        Time.at(time / multiplier_from_granularity(granularity))
+      when Time
+        time
+      else
+        raise ArgumentError, 'time argument must be a Numeric or Time object'
+      end
+    end
+
+    def multiplier_from_granularity(granularity)
+      case granularity
+      when :ms # milliseconds
+        1_000.0
+      when :s # seconds
+        1.0
+      else
+        raise ArgumentError, 'invalid granularity'
+      end
+    end
+
+    # Convert key to mixedCase from mixed_case
+    def convert_to_mixed_case(key, options = {})
+      force_camel = options.fetch(:force_camel, false)
+
+      key.to_s.
+        split('_').
+        each_with_index.map do |str, index|
+          if index > 0 || force_camel
+            str.capitalize
+          else
+            str
+          end
+        end.
+        join
+    end
+
+    # Convert a Hash into a mixed case Hash objet
+    # i.e. { client_id: 1 } becomes { 'clientId' => 1 }
+    def convert_to_mixed_case_hash(hash, options = {})
+      raise ArgumentError, 'Hash expected' unless hash.kind_of?(Hash)
+      hash.each_with_object({}) do |pair, new_hash|
+        key, val = pair
+        new_hash[convert_to_mixed_case(key, options)] = val
+      end
+    end
+
+    # Convert key to :snake_case from snakeCase
+    def convert_to_snake_case_symbol(key)
+      key.to_s.gsub(/::/, '/').
+        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+        gsub(/([a-z\d])([A-Z])/,'\1_\2').
+        gsub(/([a-zA-Z])(\d)/,'\1_\2').
+        tr("-", "_").
+        downcase.
+        to_sym
+    end
+
+    def convert_to_lower_case(key)
+      key.to_s.gsub('_', '')
+    end
+
+    # Ensures that the string value is converted to UTF-8 encoding
+    # Unless option allow_nil: true, an {ArgumentError} is raised if the string_value is not a string
+    #
+    # @return <void>
+    #
+    def ensure_utf_8(field_name, string_value, options = {})
+      unless options[:allow_nil] && string_value.nil?
+        raise ArgumentError, "#{field_name} must be a String" unless string_value.kind_of?(String)
+      end
+      string_value.encode!(Encoding::UTF_8) if string_value
+    rescue Encoding::UndefinedConversionError, Encoding::InvalidByteSequenceError => e
+      raise ArgumentError, "#{field_name} could not be converted to UTF-8: #{e.message}"
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+require 'base64'
+require 'ably/exceptions'
+
+module Ably::Modules
+  # Provides methods to allow this model's `data` property to be encoded and decoded based on the `encoding` property.
+  #
+  # This module expects the following:
+  # - A #hash method that returns the underlying hash object
+  # - A #set_hash_object(hash) method that updates the underlying hash object
+  # - A #raw_hash_object attribute that returns the original hash used to create this object
+  #
+  module Encodeable
+    # Encode a message using the channel options and register encoders for the client
+    # @param channel [Ably::Realtime::Channel]
+    # @return [void]
+    # @api private
+    def encode(channel)
+      apply_encoders :encode, channel
+    end
+
+    # Decode a message using the channel options and registered encoders for the client
+    # @param channel [Ably::Realtime::Channel]
+    # @return [void]
+    # @api private
+    def decode(channel)
+      apply_encoders :decode, channel
+    end
+
+    # The original encoding of this message when it was received as a raw message from the Ably service
+    # @return [String,nil]
+    # @api private
+    def original_encoding
+      raw_hash_object['encoding']
+    end
+
+    private
+    def decode_binary_data_before_to_json(message)
+      if message[:data].kind_of?(String) && message[:data].encoding == ::Encoding::ASCII_8BIT
+        message[:data] = ::Base64.encode64(message[:data])
+        message[:encoding] = [message[:encoding], 'base64'].compact.join('/')
+      end
+    end
+
+    def apply_encoders(method, channel)
+      max_encoding_length = 512
+      message_hash = hash.dup
+
+      begin
+        if message_hash[:encoding].to_s.length > max_encoding_length
+          raise Ably::Exceptions::EncoderError("Encoding error, encoding value is too long: '#{message_hash[:encoding]}'", nil, 92100)
+        end
+
+        previous_encoding = message_hash[:encoding]
+        channel.client.encoders.each do |encoder|
+          encoder.send method, message_hash, channel.options
+        end
+      end until previous_encoding == message_hash[:encoding]
+
+      set_hash_object message_hash
+    rescue Ably::Exceptions::CipherError => cipher_error
+      if channel.respond_to?(:trigger)
+        channel.client.logger.error "Encoder error #{cipher_error.code} trying to #{method} message: #{cipher_error.message}"
+        channel.trigger :error, cipher_error
+      else
+        raise cipher_error
+      end
+    end
+  end
+end

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

@@ -0,0 +1,202 @@
+require 'ably/modules/conversions'
+
+module Ably::Modules
+  # Enum brings Enum like functionality used in other languages to Ruby
+  #
+  # @example
+  #   class House
+  #     extend Ably::Moduels::Enum
+  #     CONSTRUCTION = ruby_enum('CONSTRUCTION',
+  #       :brick,
+  #       :steel,
+  #       :wood
+  #     )
+  #   end
+  #
+  #   House::CONSTRUCTION(:brick).to_i # => 0
+  #   House::CONSTRUCTION('Wood').to_i # => 2
+  #   House::CONSTRUCTION.Wood == :wood # => true
+  #
+  module Enum
+    private
+
+    class Base; end
+
+    # ruby_enum returns an Enum-like class that should be assigned to a constant in your class
+    # The first `enum_name` argument must match the constant name so that the coercion method is available
+    #
+    # @example
+    #   class House
+    #     extend Ably::Moduels::Enum
+    #     CONSTRUCTION = ruby_enum('CONSTRUCTION', :brick)
+    #   end
+    #
+    #   # ensures the following coercion method is available
+    #   House::CONSTRUCTION(:brick) # => CONSTRUCTION.Brick
+    #
+    def ruby_enum(enum_name, *values)
+      enum_class = Class.new(Enum::Base) do
+        include Conversions
+        extend Conversions
+
+        @enum_name = enum_name
+        @by_index  = {}
+        @by_symbol = {}
+
+        class << self
+          include Enumerable
+
+          def get(identifier)
+            case identifier
+            when Symbol
+              by_symbol.fetch(identifier)
+            when String
+              by_symbol.fetch(convert_to_snake_case_symbol(identifier))
+            when Numeric
+              by_index.fetch(identifier)
+            when ancestors.first
+              identifier
+            else
+              if identifier.class.ancestors.include?(Enum::Base)
+                by_symbol.fetch(identifier.to_sym)
+              else
+                raise KeyError, "Cannot find Enum matching identifier '#{identifier}' argument as it is an unacceptable type: #{identifier.class}"
+              end
+            end
+          end
+
+          def [](*args)
+            get(*args)
+          end
+
+          def to_s
+            name
+          end
+
+          def size
+            by_symbol.keys.length
+          end
+          alias_method :length, :size
+
+          # Method ensuring this {Enum} is {http://ruby-doc.org/core-2.1.3/Enumerable.html Enumerable}
+          def each(&block)
+            return to_enum(:each) unless block_given?
+            by_symbol.values.each(&block)
+          end
+
+          # The name provided in the constructor for this Enum
+          def name
+            @enum_name
+          end
+
+          private
+          attr_reader :by_index, :by_symbol
+
+          # Define constants for each of the Enum values
+          # e.g. define_constants(:dog) creates Enum::Dog
+          def define_values(values)
+            raise RuntimeError, "#{name} Enum cannot be modified" if by_index.frozen?
+
+            # Allow another Enum to be used as a set of values
+            if values.length == 1 && klass = values.first
+              if klass.kind_of?(Class) && klass.ancestors.include?(Enum::Base)
+                values = values.first.map(&:to_sym)
+              end
+            end
+
+            values.map do |value|
+              # Convert any key => index_value pairs into array pairs
+              Array(value)
+            end.flatten(1).each_with_index do |name, index|
+              name, index = name if name.kind_of?(Array) # name is key => index_value pair
+              raise ArgumentError, "Index value '#{index}' is invalid" unless index.kind_of?(Numeric)
+
+              camel_name  = convert_to_mixed_case(name, force_camel: true)
+              name_symbol = convert_to_snake_case_symbol(name)
+              enum        = new(camel_name, name_symbol, index.to_i)
+
+              by_index[index.to_i]   = enum
+              by_symbol[name_symbol] = enum
+
+              define_singleton_method camel_name do
+                enum
+              end
+            end
+
+            by_index.freeze
+            by_symbol.freeze
+          end
+        end
+
+        def initialize(name, symbol, index)
+          @name   = name
+          @index  = index
+          @symbol = symbol
+        end
+
+        def to_s
+          "#{self.class}.#{name}"
+        end
+
+        def to_i
+          index
+        end
+
+        def to_sym
+          symbol
+        end
+
+        def to_json(*args)
+          %{"#{symbol}"}
+        end
+
+        # Allow comparison of Enum objects based on:
+        #
+        # * Other equivalent Enum objects
+        # * Symbol
+        # * String
+        # * Integer index of Enum
+        #
+        def ==(other)
+          case other
+          when Symbol
+            self.to_sym == convert_to_snake_case_symbol(other)
+          when String
+            self.to_sym == convert_to_snake_case_symbol(other)
+          when Numeric
+            self.to_i == other.to_i
+          when self.class
+            self.to_i == other.to_i
+          else
+            false
+          end
+        end
+
+        private
+        attr_reader :name, :index, :symbol
+
+        define_values values
+      end
+
+      # Convert any comparable object into this Enum
+      # @example
+      #   class Example
+      #     DOGS = ruby_enum('DOGS', :terrier, :labrador, :great_dane)
+      #   end
+      #
+      #   Example.DOGS(:great_dane) # => <DOGS.GreatDane>
+      #   Example.DOGS(0) # => <DOGS.Terrier>
+      #   Example.new.DOGS(0) # => <DOGS.Terrier>
+      #
+      define_singleton_method enum_name do |val|
+        enum_class.get(val)
+      end
+
+      define_method enum_name do |val|
+        enum_class.get(val)
+      end
+
+      enum_class
+    end
+  end
+end