ably-pubsub-core 0.0.1.pre

data/lib/ably/modules/conversions.rb

@@ -0,0 +1,153 @@
+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 = {})
+      return nil if options[:allow_nil] && !time
+
+      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 = {})
+      return nil if options[:allow_nil] && !time
+
+      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
+
+    # Ensures that the payload is a type supported by all Ably client libraries.
+    # Ably guarantees interoperability between client libraries and subsequently
+    # client libraries must reject unsupported types
+    #
+    # @return <void>
+    #
+    def ensure_supported_payload(payload)
+      return if payload.kind_of?(String) ||
+        payload.kind_of?(Hash) ||
+        payload.kind_of?(Array) ||
+        payload.nil?
+
+      raise Ably::Exceptions::UnsupportedDataType.new('Invalid data payload', 400, Ably::Exceptions::Codes::INVALID_MESSAGE_DATA_OR_ENCODING)
+    end
+
+    # Converts the name, data, attributes into the array of Message objects
+    #
+    # @return [Array<Ably::Models::Message>]
+    #
+    def build_messages(name, data = nil, attributes = {})
+      return [Ably::Models::Message(ensure_supported_name_and_payload(nil, data, attributes))] if name.nil?
+
+      Array(name).map do |item|
+        Ably::Models::Message(ensure_supported_name_and_payload(item, data, attributes))
+      end
+    end
+
+    # Ensures if the first argument (name) is a String, Hash or Ably::Models::Message object,
+    # second argument (data) should be a String, Hash, Array or nil (see ensure_supported_payload() method).
+    #
+    # @return [Hash]        Contains :name, :data and other attributes
+    #
+    # (RSL1a, RSL1b)
+    #
+    def ensure_supported_name_and_payload(name, data = nil, attributes = {})
+      return name.attributes.dup if name.kind_of?(Ably::Models::Message)
+
+      payload = data
+      if (hash = name).kind_of?(Hash)
+        name, payload = hash[:name], (hash[:data] || payload)
+        attributes.merge!(hash)
+      end
+
+      name = ensure_utf_8(:name, name, allow_nil: true)
+      ensure_supported_payload payload
+
+      attributes.merge({ name: name, data: payload })
+    end
+  end
+end

data/lib/ably/modules/encodeable.rb

@@ -0,0 +1,111 @@
+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 #attributes method that returns the underlying hash object
+  # - A #set_attributes_object(attributes) method that updates the underlying hash object
+  # - A #raw_hash_object attribute that returns the original hash object used to create this object
+  #
+  module Encodeable
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Return a Message or Presence object from the encoded JSON-like object, using the optional channel options
+      # @param message_object [Hash] JSON-like object representation of an encoded message
+      # @param channel_options [Hash] Channel options, currently reserved for Encryption options
+      # @yield [Ably::Exceptions::BaseAblyException] yields an Ably exception if decoding fails
+      # @return [Message,Presence]
+      def from_encoded(message_object, channel_options = {}, &error_block)
+        new(message_object).tap do |message|
+          message.decode(encoders, channel_options, &error_block)
+        end
+      end
+
+      # Return an Array of Message or Presence objects from the encoded Array of JSON-like objects, using the optional channel options
+      # @param message_object_array [Array<Hash>] Array of JSON-like objects with encoded messages
+      # @param channel_options [Hash] Channel options, currently reserved for Encryption options
+      # @return [Array<Message,Presence>]
+      def from_encoded_array(message_object_array, channel_options = {})
+        Array(message_object_array).map do |message_object|
+          from_encoded(message_object, channel_options)
+        end
+      end
+
+      # Register an encoder for this object
+      # @api private
+      def register_encoder(encoder, options = {})
+        encoders << Ably::Models::MessageEncoders.encoder_from(encoder, options)
+      end
+
+      private
+      def encoders
+        @encoders ||= []
+      end
+    end
+
+    # Encode a message using the channel options and register encoders for the client
+    # @param encoders [Array<Ably::Models::MessageEncoders::Base>] List of encoders to apply to the message
+    # @param channel_options [Hash] Channel options, currently reserved for Encryption options
+    # @return [void]
+    # @api private
+    def encode(encoders, channel_options, &error_block)
+      apply_encoders :encode, encoders, channel_options, &error_block
+    end
+
+    # Decode a message using the channel options and registered encoders for the client
+    # @param encoders [Array<Ably::Models::MessageEncoders::Base>] List of encoders to apply to the message
+    # @param channel_options [Hash] Channel options, currently reserved for Encryption options
+    # @return [void]
+    # @api private
+    def decode(encoders, channel_options, &error_block)
+      apply_encoders :decode, encoders, channel_options, &error_block
+    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)
+      data_key = message[:data] ? :data : 'data'
+      encoding_key = message[:encoding] ? :encoding : 'encoding'
+
+      if message[data_key].kind_of?(String) && message[data_key].encoding == ::Encoding::ASCII_8BIT
+        message[data_key] = ::Base64.encode64(message[data_key])
+        message[encoding_key] = [message[encoding_key], 'base64'].compact.join('/')
+      end
+    end
+
+    def apply_encoders(method, encoders, channel_options, &error_callback)
+      max_encoding_length = 512
+      message_attributes = attributes.dup
+
+      begin
+        if message_attributes[:encoding].to_s.length > max_encoding_length
+          raise Ably::Exceptions::EncoderError("Encoding error, encoding value is too long: '#{message_attributes[:encoding]}'", nil, 92100)
+        end
+
+        previous_encoding = message_attributes[:encoding]
+        encoders.each do |encoder|
+          encoder.public_send method, message_attributes, channel_options
+        end
+      end until previous_encoding == message_attributes[:encoding]
+
+      set_attributes_object message_attributes
+    rescue Ably::Exceptions::CipherError => cipher_error
+      if block_given?
+        yield cipher_error, "Encoder error #{cipher_error.code} trying to #{method} message: #{cipher_error.message}"
+      else
+        raise cipher_error
+      end
+    end
+  end
+end

data/lib/ably/modules/enum.rb

@@ -0,0 +1,230 @@
+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) { raise KeyError, "#{name} key not found: :#{identifier}" }
+            when String
+              by_symbol.fetch(convert_to_snake_case_symbol(identifier)) { raise KeyError, "#{name} key not found: '#{identifier}'" }
+            when Numeric
+              by_index.fetch(identifier) { raise KeyError, "#{name} key not found: #{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
+
+          # Array of Enum values as symbols
+          #
+          # @return [Array<Symbol>]
+          #
+          def to_sym_arr
+            @by_symbol.keys
+          end
+
+          private
+          def by_index
+            @by_index
+          end
+
+          def by_symbol
+            @by_symbol
+          end
+
+          # 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 compared by Symbol (not Integer value)
+        # * 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
+          else
+            if other.kind_of?(Ably::Modules::Enum::Base)
+              self.to_sym == other.to_sym
+            end
+          end
+        end
+
+        def match_any?(*enums)
+          enums.any? { |enum| self.==(enum) }
+        end
+
+        private
+        def name
+          @name
+        end
+
+        def index
+          @index
+        end
+
+        def symbol
+          @symbol
+        end
+
+        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

data/lib/ably/modules/event_emitter.rb

@@ -0,0 +1,200 @@
+require 'ably/modules/safe_yield'
+
+module Ably
+  module Modules
+    # EventEmitter provides methods to attach to public events and emit events on any class instance
+    #
+    # EventEmitter are typically used for public interfaces, and as such, may be overriden in
+    # the classes to enforce `event` names match expected values.
+    #
+    # @note This module requires that the method #logger is defined.
+    #
+    # @example
+    #   class Example
+    #     include Modules::EventEmitter
+    #   end
+    #
+    #   event_emitter = Example.new
+    #   event_emitter.on(:signal) { |name| puts "Signal #{name} received" }
+    #   event_emitter.emit :signal, "Test"
+    #   #=> "Signal Test received"
+    #
+    module EventEmitter
+      include Ably::Modules::SafeYield
+
+      module ClassMethods
+        attr_reader :event_emitter_coerce_proc
+
+        # Configure included EventEmitter
+        #
+        # @param [Hash] options the options for the {EventEmitter}
+        # @option options [Proc] :coerce_into A lambda/Proc that is used to coerce the event names for all events. This is useful to ensure the event names conform to a naming or type convention.
+        #
+        # @example
+        #   configure_event_emitter coerce_into: lambda { |event| event.to_sym }
+        #
+        def configure_event_emitter(options = {})
+          @event_emitter_coerce_proc = options[:coerce_into]
+        end
+
+        # Ensure @event_emitter_coerce_proc option is passed down to any classes that inherit the class with callbacks
+        def inherited(subclass)
+          subclass.instance_variable_set('@event_emitter_coerce_proc', @event_emitter_coerce_proc) if defined?(@event_emitter_coerce_proc)
+          super
+        end
+      end
+
+      # On receiving an event matching the event_name, call the provided block
+      #
+      # @spec RTE4
+      #
+      # @param [Array<String>] event_names event name
+      #
+      # @return [void]
+      #
+      def on(*event_names, &block)
+        add_callback event_names, proc_for_block(block)
+      end
+
+      # Equivalent of {#on} but any exception raised in a block will bubble up and cause this client library to fail.
+      # This method is designed to be used internally by the client library.
+      # @api private
+      def unsafe_on(*event_names, &block)
+        add_callback event_names, proc_for_block(block, unsafe: true)
+      end
+
+      # On receiving an event maching the event_name, call the provided block only once and remove the registered callback
+      #
+      # @spec RTE4
+      #
+      # @param [Array<String>] event_names event name
+      #
+      # @return [void]
+      #
+      def once(*event_names, &block)
+        add_callback event_names, proc_for_block(block, delete_once_run: true)
+      end
+
+      # Equivalent of {#once} but any exception raised in a block will bubble up and cause this client library to fail.
+      # This method is designed to be used internally by the client library.
+      # @api private
+      def unsafe_once(*event_names, &block)
+        add_callback event_names, proc_for_block(block, delete_once_run: true, unsafe: true)
+      end
+
+      # Emits an event, calling registered listeners with the given event name and any other given arguments.
+      # If an exception is raised in any of the listeners, the exception is caught by the EventEmitter and the exception is logged to the Ably logger.
+      #
+      # @spec RTE6
+      #
+      def emit(event_name, *args)
+        [callbacks_any, callbacks[callbacks_event_coerced(event_name)]].each do |callback_arr|
+          callback_arr.clone.
+          select do |proc_hash|
+            if proc_hash[:unsafe]
+              proc_hash[:emit_proc].call(*args)
+            else
+              safe_yield proc_hash[:emit_proc], *args
+            end
+          end.each do |callback|
+            callback_arr.delete callback
+          end
+        end
+      end
+
+      # Remove all callbacks for event_name.
+      #
+      # If a block is provided, only callbacks matching that block signature will be removed.
+      # If block is not provided, all callbacks matching the event_name will be removed.
+      #
+      # @spec RTE5
+      #
+      # @param [Array<String>] event_names event name
+      #
+      # @return [void]
+      #
+      def off(*event_names, &block)
+        off_internal(false, *event_names, &block)
+      end
+
+      # Equivalent of {#off} but only unsafe listeners are removed.
+      # This method is designed to be used internally by the client library.
+      # @api private
+      def unsafe_off(*event_names, &block)
+        off_internal(true, *event_names, &block)
+      end
+
+      private
+      def off_internal(unsafe, *event_names, &block)
+        keys = if event_names.empty?
+          callbacks.keys
+        else
+          event_names
+        end
+
+        if event_names.empty?
+          callbacks_any.delete_if do |proc_hash|
+            if block_given?
+              (proc_hash[:unsafe] == unsafe) && (proc_hash[:block] == block)
+            else
+              proc_hash[:unsafe] == unsafe
+            end
+          end
+        end
+
+        keys.each do |event_name|
+          callbacks[callbacks_event_coerced(event_name)].delete_if do |proc_hash|
+            if block_given?
+              (proc_hash[:unsafe] == unsafe) && (proc_hash[:block] == block)
+            else
+              proc_hash[:unsafe] == unsafe
+            end
+          end
+        end
+      end
+
+      def self.included(klass)
+        klass.extend ClassMethods
+      end
+
+      def add_callback(event_names, proc_block)
+        if event_names.empty?
+          callbacks_any << proc_block
+        else
+          event_names.each do |event_name|
+            callbacks[callbacks_event_coerced(event_name)] << proc_block
+          end
+        end
+      end
+
+      # Create a Hash with a proc that calls the provided block and returns true if option :delete_once_run is set to true.
+      # #emit automatically deletes any blocks that return true thus allowing a block to be run once
+      def proc_for_block(block, options = {})
+        {
+          emit_proc: lambda do |*args|
+            block.call(*args)
+            true if options[:delete_once_run]
+          end,
+          block: block,
+          unsafe: options[:unsafe] || false
+        }
+      end
+
+      def callbacks
+        @callbacks ||= Hash.new { |hash, key| hash[key] = [] }
+      end
+
+      def callbacks_any
+        @callbacks_any ||= []
+      end
+
+      def callbacks_event_coerced(event_name)
+        if self.class.event_emitter_coerce_proc
+          self.class.event_emitter_coerce_proc.call(event_name)
+        else
+          event_name
+        end
+      end
+    end
+  end
+end