ably-rest 0.7.1 → 0.7.3

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

@@ -0,0 +1,147 @@
+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] connection_id
+  #   @return [String] A unique member identifier, disambiguating situations where a given client_id is present on multiple connections simultaneously
+  # @!attribute [r] member_key
+  #   @return [String] A unique connection and client_id identifier ensuring multiple connected clients with the same client_id are unique
+  # @!attribute [r] data
+  #   @return [Object] Optional client-defined status or other event payload associated with this state
+  # @!attribute [r] encoding
+  #   @return [Object] The encoding for the message data. Encoding and decoding of messages is handled automatically by the client library.
+  #                    Therefore, the `encoding` attribute should always be nil unless an Ably library decoding error has occurred.
+  # @!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::Conversions
+    include Ably::Modules::Encodeable
+    include Ably::Modules::ModelCommon
+    include EventMachine::Deferrable
+    extend Ably::Modules::Enum
+
+    ACTION = ruby_enum('ACTION',
+      :absent,
+      :present,
+      :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
+
+      set_hash_object hash_object
+
+      ensure_utf_8 :client_id,     client_id,     allow_nil: true
+      ensure_utf_8 :connection_id, connection_id, allow_nil: true
+      ensure_utf_8 :encoding,      encoding,      allow_nil: true
+    end
+
+    %w( client_id data encoding ).each do |attribute|
+      define_method attribute do
+        hash[attribute.to_sym]
+      end
+    end
+
+    def id
+      hash.fetch(:id) { "#{protocol_message.id!}:#{protocol_message_index}" }
+    end
+
+    def connection_id
+      hash.fetch(:connection_id) { protocol_message.connection_id if assigned_to_protocol_message? }
+    end
+
+    def member_key
+      "#{connection_id}:#{client_id}"
+    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 |presence_message|
+        presence_message['action'] = action.to_i
+        decode_binary_data_before_to_json presence_message
+      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
+    attr_reader :raw_hash_object
+
+    def protocol_message_index
+      protocol_message.presence.index(self)
+    end
+
+    def set_hash_object(hash)
+      @hash_object = IdiomaticRubyWrapper(hash.clone.freeze, stop_at: [:data])
+    end
+  end
+end

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

@@ -0,0 +1,210 @@
+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.
+  # ProtocolMessages are serially numbered on a connection.
+  # See the {http://docs.ably.io/client-lib-development-guide/protocol/ Ably client library developer documentation}
+  # for further details on the members of a ProtocolMessage
+  #
+  # @!attribute [r] action
+  #   @return [ACTION] Protocol Message action {Ably::Modules::Enum} from list of {ACTION}. Returns nil if action is unsupported by protocol
+  # @!attribute [r] count
+  #   @return [Integer] The count field is used for ACK and NACK actions. See {http://docs.ably.io/client-lib-development-guide/protocol/#message-acknowledgement message acknowledgement protocol}
+  # @!attribute [r] error_info
+  #   @return [ErrorInfo] Contains error information
+  # @!attribute [r] channel
+  #   @return [String] Channel name for messages
+  # @!attribute [r] channel_serial
+  #   @return [String] Contains a serial number for a message on the current channel
+  # @!attribute [r] connection_id
+  #   @return [String] Contains a string public identifier for the connection
+  # @!attribute [r] connection_key
+  #   @return [String] Contains a string private connection key used to recover this connection
+  # @!attribute [r] connection_serial
+  #   @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 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] flags
+  #   @return [Integer] Flags inidicating special ProtocolMessage states
+  # @!attribute [r] hash
+  #   @return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys
+  #
+  class ProtocolMessage
+    include Ably::Modules::ModelCommon
+    include EventMachine::Deferrable if defined?(Ably::Realtime)
+    extend Ably::Modules::Enum
+
+    # Actions which are sent by the Ably Realtime API
+    #
+    # The values correspond to the ints which the API
+    # understands.
+    ACTION = ruby_enum('ACTION',
+      heartbeat:    0,
+      ack:          1,
+      nack:         2,
+      connect:      3,
+      connected:    4,
+      disconnect:   5,
+      disconnected: 6,
+      close:        7,
+      closed:       8,
+      error:        9,
+      attach:       10,
+      attached:     11,
+      detach:       12,
+      detached:     13,
+      presence:     14,
+      message:      15,
+      sync:         16
+    )
+
+    # Indicates this protocol message action will generate an ACK response such as :message or :presence
+    def self.ack_required?(for_action)
+      [ACTION.Presence, ACTION.Message].include?(ACTION(for_action))
+    end
+
+    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(id channel channel_serial connection_id connection_key).each do |attribute|
+      define_method attribute do
+        hash[attribute.to_sym]
+      end
+    end
+
+    def id!
+      raise RuntimeError, 'ProtocolMessage #id is nil' unless id
+      id
+    end
+
+    def action
+      ACTION(hash[:action])
+    rescue KeyError
+      raise KeyError, "Action '#{hash[:action]}' is not supported by ProtocolMessage"
+    end
+
+    def error
+      @error_info ||= ErrorInfo.new(hash[:error]) if hash[:error]
+    end
+
+    def timestamp
+      as_time_from_epoch(hash[:timestamp]) if hash[:timestamp]
+    end
+
+    def message_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, "connection_serial '#{hash[:connection_serial]}' is invalid, a positive Integer is expected for a ProtocolMessage"
+    end
+
+    def count
+      [1, hash[:count].to_i].max
+    end
+
+    def has_message_serial?
+      message_serial && true
+    rescue TypeError
+      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(hash[:messages]).map do |message|
+          Ably::Models.Message(message, self)
+        end
+    end
+
+    def add_message(message)
+      messages << message
+    end
+
+    def presence
+      @presence ||=
+        Array(hash[:presence]).map do |message|
+          Ably::Models.PresenceMessage(message, self)
+        end
+    end
+
+    # Flags as bits
+    def flags
+      Integer(hash[:flags])
+    rescue TypeError
+      0
+    end
+
+    def has_presence_flag?
+      flags & 1 == 1
+    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 hash
+      @hash_object
+    end
+
+    # 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

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

@@ -0,0 +1,161 @@
+module Ably::Models
+  # Convert stat argument to a {Stat} object
+  #
+  # @param stat [Stat,Hash] A Stat object or Hash of stat properties
+  #
+  # @return [Stat]
+  def self.Stat(stat)
+    case stat
+    when Stat
+      stat
+    else
+      Stat.new(stat)
+    end
+  end
+
+  # A class representing an individual statistic for a specified {#interval_id}
+  #
+  # @!attribute [r] all
+  #   @return [Hash] Breakdown of summary stats for all message types
+  # @!attribute [r] inbound
+  #   @return [Hash] Breakdown of summary stats for traffic over various transport types for all inbound messages
+  # @!attribute [r] outbound
+  #   @return [Hash] Breakdown of summary stats for traffic over various transport types for all outbound messages
+  # @!attribute [r] persisted
+  #   @return [Hash] Breakdown of summary stats for all persisted messages
+  # @!attribute [r] connections
+  #   @return [Hash] A breakdown of summary stats data for different (TLS vs non-TLS) connection types.
+  # @!attribute [r] channels
+  #   @return [Hash] Aggregate data for usage of Channels
+  # @!attribute [r] api_requests
+  #   @return [Hash] Aggregate data for numbers of API requests
+  # @!attribute [r] token_requests
+  #   @return [Hash] Aggregate data for numbers of Token requests
+  #
+  class Stat
+    include Ably::Modules::ModelCommon
+    extend Ably::Modules::Enum
+
+    GRANULARITY = ruby_enum('GRANULARITY',
+      :minute,
+      :hour,
+      :day,
+      :month
+    )
+
+    INTERVAL_FORMAT_STRING = [
+      '%Y-%m-%d:%H:%M',
+      '%Y-%m-%d:%H',
+      '%Y-%m-%d',
+      '%Y-%m'
+    ]
+
+    class << self
+      # Convert a Time with the specified Granularity into an interval ID based on UTC 0 time
+      # @example
+      #   Stat.to_interval_id(Time.now, :hour) # => '2015-01-01:10'
+      #
+      # @param time [Time] Time used to determine the interval
+      # @param granularity [GRANULARITY] Granularity of the metrics such as :hour, :day
+      #
+      # @return [String] interval ID used for stats
+      #
+      def to_interval_id(time, granularity)
+        raise ArgumentError, 'Time object required as first argument' unless time.kind_of?(Time)
+
+        granularity = GRANULARITY(granularity)
+        format = INTERVAL_FORMAT_STRING[granularity.to_i]
+
+        time.utc.strftime(format)
+      end
+
+      # Returns the UTC 0 start Time of an interval_id
+      # @example
+      #   Stat.from_interval_id('2015-01-01:10') # => 2015-01-01 10:00:00 +0000
+      #
+      # @param interval_id [String]
+      #
+      # @return [Time] start time of the provided interval_id
+      #
+      def from_interval_id(interval_id)
+        raise ArgumentError, 'Interval ID must be a string' unless interval_id.kind_of?(String)
+
+        format = INTERVAL_FORMAT_STRING.find { |format| expected_length(format) == interval_id.length }
+        raise ArgumentError, 'Interval ID is an invalid length' unless format
+
+        Time.strptime("#{interval_id} +0000", "#{format} %z").utc
+      end
+
+      # Returns the {GRANULARITY} determined from the interval_id
+      # @example
+      #   Stat.granularity_from_interval_id('2015-01-01:10') # => :hour
+      #
+      # @param interval_id [String]
+      #
+      # @return [GRANULARITY] Granularity Enum for the interval_id
+      #
+      def granularity_from_interval_id(interval_id)
+        raise ArgumentError, 'Interval ID must be a string' unless interval_id.kind_of?(String)
+
+        format = INTERVAL_FORMAT_STRING.find { |format| expected_length(format) == interval_id.length }
+        raise ArgumentError, 'Interval ID is an invalid length' unless format
+
+        GRANULARITY[INTERVAL_FORMAT_STRING.index(format)]
+      end
+
+      private
+      def expected_length(format)
+        format.gsub('%Y', 'YYYY').length
+      end
+    end
+
+    # {Stat} initializer
+    #
+    # @param hash_object  [Hash]  object with the underlying stat details
+    #
+    def initialize(hash_object)
+      @raw_hash_object  = hash_object
+
+      set_hash_object hash_object
+    end
+
+    %w( all inbound outbound persisted connections channels api_requests token_requests ).each do |attribute|
+      define_method attribute do
+        hash[attribute.to_sym]
+      end
+    end
+
+    # @!attribute [r] interval_id
+    # @return [String] The interval that this statistic applies to, see {GRANULARITY} and {INTERVAL_FORMAT_STRING}
+    def interval_id
+      hash.fetch(:interval_id)
+    end
+
+    # @!attribute [r] interval_time
+    # @return [Time] A Time object representing the start of the interval
+    def interval_time
+      self.class.from_interval_id(interval_id)
+    end
+
+    # @!attribute [r] interval_granularity
+    # @return [GRANULARITY] The granularity of the interval for the stat such as :day, :hour, :minute, see {GRANULARITY}
+    def interval_granularity
+      self.class.granularity_from_interval_id(interval_id)
+    end
+
+    def hash
+      @hash_object
+    end
+
+    def as_json(*args)
+      hash.as_json(*args)
+    end
+
+    private
+    attr_reader :raw_hash_object
+
+    def set_hash_object(hash)
+      @hash_object = IdiomaticRubyWrapper(hash.clone.freeze)
+    end
+  end
+end