ably-pubsub-core 0.0.1.pre

data/lib/ably/models/message.rb

@@ -0,0 +1,223 @@
+require 'ably/models/message_encoders/base'
+
+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 [Hash] options (see Message#initialize)
+  #
+  # @return [Message]
+  #
+  def self.Message(message, options = {})
+    case message
+    when Message
+      message.tap do
+        message.assign_to_protocol_message options[:protocol_message] if options[:protocol_message]
+      end
+    else
+      Message.new(message, options)
+    end
+  end
+
+  # Contains an individual message that is sent to, or received from, Ably.
+  #
+  class Message
+    include Ably::Modules::Conversions
+    include Ably::Modules::Encodeable
+    include Ably::Modules::ModelCommon
+    include Ably::Modules::SafeDeferrable if defined?(Ably::Realtime)
+
+    # Statically register a default set of encoders for this class
+    Ably::Models::MessageEncoders.register_default_encoders self
+
+    # {Message} initializer
+    #
+    # @spec TM2, TM3
+    #
+    # @param  attributes [Hash]             object with the underlying message detail key value attributes
+    # @param  [Hash]      options           an options Hash for this initializer
+    # @option options     [ProtocolMessage] :protocol_message  An optional protocol message to assocate the presence message with
+    # @option options     [Logger]          :logger            An optional Logger to be used by {Ably::Modules::SafeDeferrable} if an exception is caught in a callback
+    #
+    def initialize(attributes, options = {})
+      @logger           = options[:logger] # Logger expected for SafeDeferrable
+      @protocol_message = options[:protocol_message]
+      @raw_hash_object  = attributes
+
+      set_attributes_object attributes
+
+      self.attributes[:name] = ensure_utf_8(:name, name, allow_nil: true) if name
+      self.attributes[:client_id] = ensure_utf_8(:client_id, client_id, allow_nil: true) if client_id
+      self.attributes[:encoding] = ensure_utf_8(:encoding,  encoding,  allow_nil: true) if encoding
+
+      self.attributes.freeze
+    end
+
+    # The client ID of the publisher of this message.
+    #
+    # @spec RSL1g1, TM2b
+    #
+    # @return [String]
+    #
+    def client_id
+      attributes[:client_id]
+    end
+
+    # This is typically empty, as all messages received from Ably are automatically decoded client-side using this value.
+    # However, if the message encoding cannot be processed, this attribute contains the remaining transformations
+    # not applied to the data payload.
+    #
+    # @spec TM2e
+    #
+    # @return [String]
+    #
+    def encoding
+      attributes[:encoding]
+    end
+
+    # The event name.
+    #
+    # @spec TM2g
+    #
+    # @return [String]
+    #
+    def name
+      attributes[:name]
+    end
+
+    # The message payload, if provided.
+    #
+    # @spec TM2d
+    #
+    # @return [Hash, nil]
+    #
+    def data
+      @data ||= attributes[:data].freeze
+    end
+
+    # A Unique ID assigned by Ably to this message.
+    #
+    # @spec TM2a
+    #
+    # @return [String]
+    #
+    def id
+      attributes.fetch(:id) { "#{protocol_message.id!}:#{protocol_message_index}" }
+    end
+
+    # The connection ID of the publisher of this message.
+    #
+    # @spec TM2c
+    #
+    # @return [String]
+    #
+    def connection_id
+      attributes.fetch(:connection_id) { protocol_message.connection_id if assigned_to_protocol_message? }
+    end
+
+    # Timestamp of when the message was received by Ably, as milliseconds since the Unix epoch.
+    #
+    # @spec TM2f
+    #
+    # @return [Integer]
+    #
+    def timestamp
+      if attributes[:timestamp]
+        as_time_from_epoch(attributes[:timestamp])
+      else
+        protocol_message.timestamp
+      end
+    end
+
+    def attributes
+      @attributes
+    end
+
+    def to_json(*args)
+      as_json(*args).tap do |message|
+        decode_binary_data_before_to_json message
+      end.to_json
+    end
+
+    # The size is the sum over name, data, clientId, and extras in bytes (TO3l8a)
+    #
+    def size
+      %w(name data client_id extras).map do |attr|
+        if (value = attributes[attr.to_sym]).is_a?(String)
+          value.bytesize
+        elsif value.nil?
+          0
+        else
+          value.to_json.bytesize
+        end
+      end.sum
+    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
+
+    # Contains any arbitrary key value pairs which may also contain other primitive JSON types, JSON-encodable objects or JSON-encodable arrays.
+    # The extras field is provided to contain message metadata and/or ancillary payloads in support of specific functionality, e.g. push
+    # 1.2 adds the delta extension which is of type DeltaExtras, and the headers extension, which contains arbitrary string->string key-value pairs,
+    # settable at publish time. Unless otherwise specified, the client library should not attempt to do any filtering or validation of the extras
+    # field itself, but should treat it opaquely, encoding it and passing it to realtime unaltered.
+    # @api private
+    def extras
+      attributes[:extras].tap do |val|
+        unless val.kind_of?(IdiomaticRubyWrapper) || val.kind_of?(Array) || val.kind_of?(Hash) || val.nil?
+          raise ArgumentError, "extras contains an unsupported type #{val.class}"
+        end
+      end
+    end
+
+    # Delta extras extension (TM2i)
+    #
+    # @return [DeltaExtras, nil]
+    #
+    # @api private
+    def delta_extras
+      return nil if attributes[:extras][:delta].nil?
+      @delta_extras ||= DeltaExtras.new(attributes[:extras][:delta]).freeze
+    end
+
+    def protocol_message_index
+      protocol_message.messages.map(&:object_id).index(self.object_id)
+    end
+
+    private
+    def raw_hash_object
+      @raw_hash_object
+    end
+
+    def set_attributes_object(new_attributes)
+      @attributes = IdiomaticRubyWrapper(new_attributes.clone, stop_at: [:data, :extras])
+    end
+
+    def logger
+      return @logger if @logger
+      protocol_message.logger if protocol_message
+    end
+  end
+end

data/lib/ably/models/message_encoders/base.rb

@@ -0,0 +1,135 @@
+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
+  module Models
+    module MessageEncoders
+      extend Ably::Modules::Conversions
+
+      # Base interface for an Ably Encoder
+      #
+      class Base
+        attr_reader :client, :options
+
+        def initialize(client, options = {})
+          @client = client
+          @options = options
+        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
+
+      # @api private
+      def self.register_default_encoders(client, options = {})
+        binary_protocol = !!options[:binary_protocol]
+        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, binary_protocol: binary_protocol
+      end
+
+      # @api private
+      def self.encoder_from(encoder, options)
+        encoder_klass = if encoder.kind_of?(String)
+          encoder.split('::').inject(Kernel) do |base, klass_name|
+            base.public_send(:const_get, klass_name)
+          end
+        else
+          encoder
+        end
+
+        raise "Encoder must inherit from `Ably::Models::MessageEncoders::Base`" unless encoder_klass.ancestors.include?(Ably::Models::MessageEncoders::Base)
+        encoder_klass.new(self, options)
+      end
+    end
+  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/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?
+      !options[:binary_protocol]
+    end
+  end
+end

data/lib/ably/models/message_encoders/cipher.rb

@@ -0,0 +1,84 @@
+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 the +:cipher+ channel option configured
+  #
+  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_params.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)
+      else
+        raise e
+      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_params.cipher_type == cipher_algorithm(message).upcase
+          raise Ably::Exceptions::CipherError.new("Cipher algorithm #{crypto.cipher_params.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.to_s] ||= Ably::Util::Crypto.new(channel_options.fetch(:cipher, {}))
+    end
+
+    def channel_configured_for_encryption?(channel_options)
+      channel_options[:cipher]
+    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/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/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/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