ably 0.1.5 → 0.1.6

data/lib/ably/{realtime/models → models}/message.rb

@@ -1,7 +1,13 @@
-module Ably::Realtime::Models
+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 Ably::Realtime::Models::Message
+    when Message
       message.tap do
         message.assign_to_protocol_message protocol_message
       end
@@ -19,80 +25,81 @@ module Ably::Realtime::Models
   #   @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] sender_timestamp
-  #   @return [Time] Timestamp when the message was sent according to the publisher client
-  # @!attribute [r] ably_timestamp
-  #   @return [Time] Timestamp when the message was received by the Ably the service for publishing
-  # @!attribute [r] message_id
+  # @!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] json
+  # @!attribute [r] hash
   #   @return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys
   #
   class Message
-    include Shared
-    include Ably::Modules::Conversions
+    include Ably::Modules::ModelCommon
     include EventMachine::Deferrable
 
     # {Message} initializer
     #
-    # @param json_object [Hash] JSON like object with the underlying message details
+    # @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(json_object, protocol_message = nil)
+    def initialize(hash_object, protocol_message = nil)
       @protocol_message = protocol_message
-      @raw_json_object  = json_object
-      @json_object      = IdiomaticRubyWrapper(json_object.clone.freeze, stop_at: [:data])
+      @raw_hash_object  = hash_object
+      @hash_object      = IdiomaticRubyWrapper(hash_object.clone.freeze, stop_at: [:data])
     end
 
     %w( name client_id ).each do |attribute|
       define_method attribute do
-        json[attribute.to_sym]
+        hash[attribute.to_sym]
       end
     end
 
     def data
-      @data ||= json[:data].freeze
-    end
-
-    def message_id
-      "#{connection_id}:#{message_serial}:#{protocol_message_index}"
-    end
-
-    def sender_timestamp
-      as_time_from_epoch(json[:timestamp]) if json[:timestamp]
+      @data ||= hash[:data].freeze
     end
 
-    def ably_timestamp
-      protocol_message.timestamp
+    def id
+      hash[:id] || "#{protocol_message.id!}:#{protocol_message_index}"
     end
 
-    def json
-      @json_object
+    def timestamp
+      if hash[:timestamp]
+        as_time_from_epoch(hash[:timestamp])
+      else
+        protocol_message.timestamp
+      end
     end
 
-    def to_json_object
-      raise RuntimeError, ":name is missing, cannot generate valid JSON for Message" unless name
-
-      json.dup.tap do |json_object|
-        json_object[:timestamp] = as_since_epoch(Time.now) unless sender_timestamp
-      end
+    def hash
+      @hash_object
     end
 
-    def to_json(*args)
-      to_json_object.to_json
+    def as_json(*args)
+      raise RuntimeError, ":name is missing, cannot generate a valid Hash for Message" unless name
+      super
     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
 
-    private
+    # 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?
+      raise RuntimeError, "Message is not yet published with a ProtocolMessage. ProtocolMessage is nil" if @protocol_message.nil?
       @protocol_message
     end
 
+    private
     def protocol_message_index
       protocol_message.messages.index(self)
     end

data/lib/ably/{realtime/models → models}/nil_channel.rb

@@ -1,10 +1,10 @@
-module Ably::Realtime::Models
+module Ably::Models
   # Nil object for Channels, this object is only used within the internal API of this client library
   class NilChannel
     include Ably::Modules::EventEmitter
     extend Ably::Modules::Enum
     STATE = ruby_enum('STATE', Ably::Realtime::Channel::STATE)
-    include Ably::Modules::State
+    include Ably::Modules::StateEmitter
 
     def initialize
       @state = STATE.Initialized
@@ -14,8 +14,8 @@ module Ably::Realtime::Models
       'Nil channel'
     end
 
-    def __incoming_protocol_msgbus__
-      @__incoming_protocol_msgbus__ ||= Ably::Util::PubSub.new
+    def __incoming_msgbus__
+      @__incoming_msgbus__ ||= Ably::Util::PubSub.new
     end
   end
 end

data/lib/ably/{rest/models/paged_resource.rb → models/paginated_resource.rb}

@@ -1,23 +1,24 @@
-module Ably::Rest::Models
+module Ably::Models
   # Wraps any Ably HTTP response that supports paging and automatically provides methdos to iterated through
   # the array of resources using {#first}, {#next}, {#last?} and {#first?}
   #
   # Paging information is provided by Ably in the LINK HTTP headers
-  class PagedResource
+  class PaginatedResource
     include Enumerable
 
     # @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 PagedResource
+    # @option options [Symbol,String] :coerce_into symbol or string representing class that should be used to create each item in the PaginatedResource
     #
-    # @return [PagedResource]
+    # @return [PaginatedResource]
     def initialize(http_response, base_url, client, options = {})
       @http_response = http_response
       @client        = client
       @base_url      = "#{base_url.gsub(%r{/[^/]*$}, '')}/"
       @coerce_into   = options[:coerce_into]
+      @raw_body      = http_response.body
 
       @body = if @coerce_into
         http_response.body.map do |item|
@@ -30,17 +31,17 @@ module Ably::Rest::Models
 
     # Retrieve the first page of results
     #
-    # @return [PagedResource]
+    # @return [PaginatedResource]
     def first_page
-      PagedResource.new(client.get(pagination_url('first')), base_url, client, coerce_into: coerce_into)
+      PaginatedResource.new(client.get(pagination_url('first')), base_url, client, coerce_into: coerce_into)
     end
 
     # Retrieve the next page of results
     #
-    # @return [PagedResource]
+    # @return [PaginatedResource]
     def next_page
       raise Ably::Exceptions::InvalidPageError, "There are no more pages" if supports_pagination? && last_page?
-      PagedResource.new(client.get(pagination_url('next')), base_url, client, coerce_into: coerce_into)
+      PaginatedResource.new(client.get(pagination_url('next')), base_url, client, coerce_into: coerce_into)
     end
 
     # True if this is the last page in the paged resource set
@@ -78,7 +79,7 @@ module Ably::Rest::Models
     alias_method :count, :length
     alias_method :size,  :length
 
-    # Method ensuring this {PagedResource} is {http://ruby-doc.org/core-2.1.3/Enumerable.html Enumerable}
+    # Method ensuring this {PaginatedResource} is {http://ruby-doc.org/core-2.1.3/Enumerable.html Enumerable}
     def each(&block)
       body.each do |item|
         if block_given?
@@ -89,8 +90,18 @@ module Ably::Rest::Models
       end
     end
 
+    # Last item in this page
+    def first
+      body.first
+    end
+
+    # Last item in this page
+    def last
+      body.last
+    end
+
     private
-    attr_reader :body, :http_response, :base_url, :client, :coerce_into
+    attr_reader :body, :http_response, :base_url, :client, :coerce_into, :raw_body
 
     def pagination_headers
       link_regex = %r{<(?<url>[^>]+)>; rel="(?<rel>[^"]+)"}

data/lib/ably/models/presence_message.rb

@@ -0,0 +1,126 @@
+module Ably::Models
+  # Convert presence_messsage argument to a {PresenceMessage} object and associate with a protocol message if provided
+  #
+  # @param presence_message [PresenceMessage,Hash] A presence message object or Hash of presence message properties
+  # @param protocol_message [ProtocolMessage] An optional protocol message to assocate the presence message with
+  #
+  # @return [PresenceMessage]
+  def self.PresenceMessage(presence_message, protocol_message = nil)
+    case presence_message
+    when PresenceMessage
+      presence_message.tap do
+        presence_message.assign_to_protocol_message protocol_message
+      end
+    else
+      PresenceMessage.new(presence_message, protocol_message)
+    end
+  end
+
+  # A class representing an individual presence message to be sent or received
+  # via the Ably Realtime service.
+  #
+  # @!attribute [r] action
+  #   @return [STATE] the state change event signified by a PresenceMessage
+  # @!attribute [r] client_id
+  #   @return [String] The client_id associated with this presence state
+  # @!attribute [r] member_id
+  #   @return [String] A unique member identifier, disambiguating situations where a given client_id is present on multiple connections simultaneously
+  # @!attribute [r] client_data
+  #   @return [Object] Optional client-defined status or other event payload associated with this state
+  # @!attribute [r] timestamp
+  #   @return [Time] Timestamp when the message was received by the Ably the real-time service
+  # @!attribute [r] hash
+  #   @return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys
+  #
+  class PresenceMessage
+    include Ably::Modules::ModelCommon
+    include EventMachine::Deferrable
+    extend Ably::Modules::Enum
+
+    ACTION = ruby_enum('ACTION',
+      :enter,
+      :leave,
+      :update
+    )
+
+    # {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
+      @hash_object      = IdiomaticRubyWrapper(hash_object.clone.freeze, stop_at: [:data])
+    end
+
+    %w( client_id member_id client_data ).each do |attribute|
+      define_method attribute do
+        hash[attribute.to_sym]
+      end
+    end
+
+    def id
+      hash[:id] || "#{protocol_message.id!}:#{protocol_message_index}"
+    end
+
+    def timestamp
+      if hash[:timestamp]
+        as_time_from_epoch(hash[:timestamp])
+      else
+        protocol_message.timestamp
+      end
+    end
+
+    def action
+      ACTION(hash[:action])
+    end
+
+    def hash
+      @hash_object
+    end
+
+    # Return a JSON ready object from the underlying #hash using Ably naming conventions for keys
+    def as_json(*args)
+      hash.dup.tap do |hash|
+        hash['action'] = action.to_i
+      end.as_json
+    rescue KeyError
+      raise KeyError, ":action is missing or invalid, cannot generate a valid Hash for ProtocolMessage"
+    end
+
+    # Assign this presence 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 presence 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 presence message is assigned to.  If ProtocolMessage is nil, an error will be raised.
+    # @return [Ably::Models::ProtocolMessage]
+    # @api private
+    def protocol_message
+      raise RuntimeError, "Presence Message is not yet published with a ProtocolMessage. ProtocolMessage is nil" if @protocol_message.nil?
+      @protocol_message
+    end
+
+    private
+    def protocol_message_index
+      protocol_message.presence.index(self)
+    end
+
+    def connection_id
+      protocol_message.connection_id
+    end
+
+    def message_serial
+      protocol_message.message_serial
+    end
+  end
+end

data/lib/ably/{realtime/models → models}/protocol_message.rb

@@ -1,4 +1,4 @@
-module Ably::Realtime::Models
+module Ably::Models
   # A message sent and received over the Realtime protocol.
   # A ProtocolMessage always relates to a single channel only, but
   # can contain multiple individual Messages or PresenceMessages.
@@ -15,26 +15,25 @@ module Ably::Realtime::Models
   # @!attribute [r] channel
   #   @return [String] Channel name for messages
   # @!attribute [r] channel_serial
-  #   @return [String] Contains a serial number for amessage on the current channel
+  #   @return [String] Contains a serial number for a message on the current channel
   # @!attribute [r] connection_id
   #   @return [String] Contains a string connection ID
   # @!attribute [r] connection_serial
-  #   @return [Bignum] Contains a serial number for a message on the current connection
+  #   @return [Bignum] Contains a serial number for a message sent from the server to the client
   # @!attribute [r] message_serial
-  #   @return [Bignum] Contains a serial number for a message sent from the client to the service.
+  #   @return [Bignum] Contains a serial number for a message sent from the client to the server
   # @!attribute [r] timestamp
   #   @return [Time] An optional timestamp, applied by the service in messages sent to the client, to indicate the system time at which the message was sent (milliseconds past epoch)
   # @!attribute [r] messages
   #   @return [Message] A {ProtocolMessage} with a `:message` action contains one or more messages belonging to a channel.
   # @!attribute [r] presence
   #   @return [PresenceMessage] A {ProtocolMessage} with a `:presence` action contains one or more presence updates belonging to a channel.
-  # @!attribute [r] json
+  # @!attribute [r] hash
   #   @return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys
   #
   class ProtocolMessage
-    include Shared
+    include Ably::Modules::ModelCommon
     extend Ably::Modules::Enum
-    include Ably::Modules::Conversions
 
     # Actions which are sent by the Ably Realtime API
     #
@@ -64,40 +63,55 @@ module Ably::Realtime::Models
       [ACTION.Presence, ACTION.Message].include?(ACTION(for_action))
     end
 
-    def initialize(json_object)
-      @raw_json_object = json_object
-      @json_object     = IdiomaticRubyWrapper(@raw_json_object.clone.freeze)
+    def initialize(hash_object)
+      @raw_hash_object = hash_object
+      @hash_object     = IdiomaticRubyWrapper(@raw_hash_object.clone)
+
+      raise ArgumentError, "Invalid ProtocolMessage, action cannot be nil" if @hash_object[:action].nil?
+      @hash_object[:action] = ACTION(@hash_object[:action]).to_i unless @hash_object[:action].kind_of?(Integer)
+
+      @hash_object.freeze
     end
 
-    %w( channel channel_serial
-        connection_id connection_serial ).each do |attribute|
+    %w( id channel channel_serial connection_id ).each do |attribute|
       define_method attribute do
-        json[attribute.to_sym]
+        hash[attribute.to_sym]
       end
     end
 
+    def id!
+      raise RuntimeError, "ProtocolMessage #id is nil" unless id
+      id
+    end
+
     def action
-      ACTION(json[:action])
+      ACTION(hash[:action])
     rescue KeyError
-      raise KeyError, "Action '#{json[:action]}' is not supported by ProtocolMessage"
+      raise KeyError, "Action '#{hash[:action]}' is not supported by ProtocolMessage"
     end
 
     def error
-      @error_info ||= ErrorInfo.new(json[:error]) if json[:error]
+      @error_info ||= ErrorInfo.new(hash[:error]) if hash[:error]
     end
 
     def timestamp
-      as_time_from_epoch(json[:timestamp]) if json[:timestamp]
+      as_time_from_epoch(hash[:timestamp]) if hash[:timestamp]
     end
 
     def message_serial
-      Integer(json[:msg_serial])
+      Integer(hash[:msg_serial])
+    rescue TypeError
+      raise TypeError, "msg_serial '#{hash[:msg_serial]}' is invalid, a positive Integer is expected for a ProtocolMessage"
+    end
+
+    def connection_serial
+      Integer(hash[:connection_serial])
     rescue TypeError
-      raise TypeError, "msg_serial '#{json[:msg_serial]}' is invalid, a positive Integer is expected for a ProtocolMessage"
+      raise TypeError, "connection_serial '#{hash[:connection_serial]}' is invalid, a positive Integer is expected for a ProtocolMessage"
     end
 
     def count
-      [1, json[:count].to_i].max
+      [1, hash[:count].to_i].max
     end
 
     def has_message_serial?
@@ -106,10 +120,28 @@ module Ably::Realtime::Models
       false
     end
 
+    def has_connection_serial?
+      connection_serial && true
+    rescue TypeError
+      false
+    end
+
+    def serial
+      if has_connection_serial?
+        connection_serial
+      else
+        message_serial
+      end
+    end
+
+    def has_serial?
+      has_connection_serial? || has_message_serial?
+    end
+
     def messages
       @messages ||=
-        Array(json[:messages]).map do |message|
-          Ably::Realtime::Models.Message(message, self)
+        Array(hash[:messages]).map do |message|
+          Ably::Models.Message(message, self)
         end
     end
 
@@ -119,37 +151,43 @@ module Ably::Realtime::Models
 
     def presence
       @presence ||=
-        Array(json[:presence]).map do |message|
-          PresenceMessage(message, self)
+        Array(hash[:presence]).map do |message|
+          Ably::Models.PresenceMessage(message, self)
         end
     end
 
-    def json
-      @json_object
-    end
-
     # Indicates this protocol message will generate an ACK response when sent
     # Examples of protocol messages required ACK include :message and :presence
     def ack_required?
       self.class.ack_required?(action)
     end
 
-    def to_json_object
-      raise TypeError, ":action is missing, cannot generate valid JSON for ProtocolMessage" unless action
-      raise TypeError, ":msg_serial is missing, cannot generate valid JSON for ProtocolMessage" if ack_required? && !has_message_serial?
-
-      json.dup.tap do |json_object|
-        json_object[:messages] = messages.map(&:to_json_object) unless messages.empty?
-        json_object[:presence] = presence.map(&:to_json_object) unless presence.empty?
-      end
+    def hash
+      @hash_object
     end
 
-    def to_json(*args)
-      to_json_object.to_json
+    # Return a JSON ready object from the underlying #hash using Ably naming conventions for keys
+    def as_json(*args)
+      raise TypeError, ":action is missing, cannot generate a valid Hash for ProtocolMessage" unless action
+      raise TypeError, ":msg_serial or :connection_serial is missing, cannot generate a valid Hash for ProtocolMessage" if ack_required? && !has_serial?
+
+      hash.dup.tap do |hash_object|
+        hash_object['action']   = action.to_i
+        hash_object['messages'] = messages.map(&:as_json) unless messages.empty?
+        hash_object['presence'] = presence.map(&:as_json) unless presence.empty?
+      end.as_json
     end
 
     def to_s
       to_json
     end
+
+    # True if the ProtocolMessage appears to be invalid, however this is not a guarantee
+    # @return [Boolean]
+    # @api private
+    def invalid?
+      action_enum = action rescue nil
+      !action_enum || (ack_required? && !has_serial?)
+    end
   end
 end