ably-pubsub-core 0.0.1.pre

data/lib/ably/models/protocol_message.rb

@@ -0,0 +1,288 @@
+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://ably.com/docs/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] auth
+  #   @return [Ably::Models::AuthDetails] Authentication details used to perform authentication upgrades over an existing transport
+  # @!attribute [r] count
+  #   @return [Integer] The count field is used for ACK and NACK actions. See {http://ably.com/docs/client-lib-development-guide/protocol/#message-acknowledgement message acknowledgement protocol}
+  # @!attribute [r] error
+  #   @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 private connection key used to recover this connection
+  # @!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 [Array<Message>] A {ProtocolMessage} with a `:message` action contains one or more messages belonging to the channel
+  # @!attribute [r] presence
+  #   @return [Array<PresenceMessage>] A {ProtocolMessage} with a `:presence` action contains one or more presence updates belonging to the channel
+  # @!attribute [r] flags
+  #   @return [Integer] Flags indicating special ProtocolMessage states
+  # @!attribute [r] attributes
+  #   @return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys
+  #
+  class ProtocolMessage
+    include Ably::Modules::ModelCommon
+    include Ably::Modules::Encodeable
+    include Ably::Modules::SafeDeferrable 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,
+      auth:         17
+    )
+
+    ATTACH_FLAGS_MAPPING = {
+      resume: 32, # 2^5
+      presence: 65536, # 2^16
+      publish: 131072, # 2^17
+      subscribe: 262144, # 2^18
+      presence_subscribe: 524288, # 2^19
+    }
+
+    # Indicates this protocol message action will generate an ACK response such as :message or :presence
+    # @api private
+    def self.ack_required?(for_action)
+      ACTION(for_action).match_any?(ACTION.Presence, ACTION.Message)
+    end
+
+    # {ProtocolMessage} initializer
+    #
+    # @param  hash_object [Hash]            object with the underlying protocol message data
+    # @param  [Hash]      options           an options Hash for this initializer
+    # @option options     [Logger]          :logger            An optional Logger to be used by {Ably::Modules::SafeDeferrable} if an exception is caught in a callback
+    #
+    def initialize(hash_object, options = {})
+      @logger = options[:logger] # Logger expected for SafeDeferrable
+
+      @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).each do |attribute|
+      define_method attribute do
+        attributes[attribute.to_sym]
+      end
+    end
+
+    def id!
+      raise RuntimeError, 'ProtocolMessage #id is nil' unless id
+      id
+    end
+
+    def action
+      ACTION(attributes[:action])
+    rescue KeyError
+      raise KeyError, "Action '#{attributes[:action]}' is not supported by ProtocolMessage"
+    end
+
+    def error
+      @error ||= ErrorInfo.new(attributes[:error]) if attributes[:error]
+    end
+
+    def timestamp
+      as_time_from_epoch(attributes[:timestamp]) if attributes[:timestamp]
+    end
+
+    def message_serial
+      Integer(attributes[:msg_serial])
+    rescue TypeError
+      raise TypeError, "msg_serial '#{attributes[:msg_serial]}' is invalid, a positive Integer is expected for a ProtocolMessage"
+    end
+
+    def count
+      [1, attributes[:count].to_i].max
+    end
+
+    # @api private
+    def has_message_serial?
+      message_serial && true
+    rescue TypeError
+      false
+    end
+
+    def has_channel_serial?
+      channel_serial && true
+    rescue TypeError
+      false
+    end
+
+    def messages
+      @messages ||=
+        Array(attributes[:messages]).map do |message|
+          Ably::Models.Message(message, protocol_message: self)
+        end
+    end
+
+    # @api private
+    def add_message(message)
+      messages << message
+    end
+
+    def presence
+      @presence ||=
+        Array(attributes[:presence]).map do |message|
+          Ably::Models.PresenceMessage(message, protocol_message: self)
+        end
+    end
+
+    def message_size
+      presence.map(&:size).sum + messages.map(&:size).sum
+    end
+
+    def params
+      @params ||= attributes[:params].to_h
+    end
+
+    def flags
+      Integer(attributes[:flags])
+    rescue TypeError
+      0
+    end
+
+    # @api private
+    def has_presence_flag?
+      flags & 1 == 1
+    end
+
+    # @api private
+    def has_backlog_flag?
+      flags & 2 == 2 # 2^1
+    end
+
+    # @api private
+    def has_channel_resumed_flag?
+      flags & 4 == 4 # 2^2
+    end
+
+    # @api private
+    def has_local_presence_flag?
+      flags & 8 == 8 # 2^3
+    end
+
+    # @api private
+    def has_transient_flag?
+      flags & 16 == 16 # 2^4
+    end
+
+    # @api private
+    def has_attach_resume_flag?
+      flags & ATTACH_FLAGS_MAPPING[:resume] == ATTACH_FLAGS_MAPPING[:resume] # 2^5
+    end
+
+    # @api private
+    def has_attach_presence_flag?
+      flags & ATTACH_FLAGS_MAPPING[:presence] == ATTACH_FLAGS_MAPPING[:presence] # 2^16
+    end
+
+    # @api private
+    def has_attach_publish_flag?
+      flags & ATTACH_FLAGS_MAPPING[:publish] == ATTACH_FLAGS_MAPPING[:publish] # 2^17
+    end
+
+    # @api private
+    def has_attach_subscribe_flag?
+      flags & ATTACH_FLAGS_MAPPING[:subscribe] == ATTACH_FLAGS_MAPPING[:subscribe] # 2^18
+    end
+
+    # @api private
+    def has_attach_presence_subscribe_flag?
+      flags & ATTACH_FLAGS_MAPPING[:presence_subscribe] == ATTACH_FLAGS_MAPPING[:presence_subscribe] # 2^19
+    end
+
+    def connection_details
+      @connection_details ||= Ably::Models::ConnectionDetails(attributes[:connection_details])
+    end
+
+    def auth
+      @auth ||= Ably::Models::AuthDetails(attributes[:auth])
+    end
+
+    # Indicates this protocol message will generate an ACK response when sent
+    # Examples of protocol messages required ACK include :message and :presence
+    # @api private
+    def ack_required?
+      self.class.ack_required?(action)
+    end
+
+    def attributes
+      @hash_object
+    end
+
+    # Return a JSON ready object from the underlying #attributes using Ably naming conventions for keys
+    def as_json(*args)
+      raise TypeError, ':action is missing, cannot generate a valid Hash for ProtocolMessage' unless action
+
+      attributes.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
+      json_hash = as_json
+
+      # Decode any binary data to before converting to a JSON string representation
+      %w(messages presence).each do |message_type|
+        if json_hash[message_type] && !json_hash[message_type].empty?
+          json_hash[message_type].each do |message|
+            decode_binary_data_before_to_json message
+          end
+        end
+      end
+
+      json_hash.to_json
+    end
+
+    # True if the ProtocolMessage appears to be invalid, however this is not a guarantee
+    # Used for validating incoming protocol messages, so no need to add unnecessary checks
+    # @return [Boolean]
+    # @api private
+    def invalid?
+      action_enum = action rescue nil
+      !action_enum
+    end
+
+    # @!attribute [r] logger
+    # @api private
+    attr_reader :logger
+  end
+end

data/lib/ably/models/push_channel_subscription.rb

@@ -0,0 +1,114 @@
+module Ably::Modules
+  module Conversions
+    private
+    # Convert push_channel_subscription argument to a {Ably::Models::PushChannelSubscription} object
+    #
+    # @param push_channel_subscription [Ably::Models::PushChannelSubscription,Hash,nil] A device details object
+    #
+    # @return [Ably::Models::PushChannelSubscription]
+    #
+    def PushChannelSubscription(push_channel_subscription)
+      case push_channel_subscription
+      when Ably::Models::PushChannelSubscription
+        push_channel_subscription
+      else
+        Ably::Models::PushChannelSubscription.new(push_channel_subscription)
+      end
+    end
+  end
+end
+
+module Ably::Models
+  # Contains the subscriptions of a device, or a group of devices sharing the same clientId,
+  # has to a channel in order to receive push notifications.
+  #
+  class PushChannelSubscription < Ably::Exceptions::BaseAblyException
+    include Ably::Modules::ModelCommon
+
+    # @param hash_object   [Hash,nil]  Device detail attributes
+    #
+    def initialize(hash_object = {})
+      @raw_hash_object = hash_object || {}
+      @hash_object     = IdiomaticRubyWrapper(hash_object)
+
+      if !attributes[:client_id] && !attributes[:device_id]
+        raise ArgumentError, 'Either client_id or device_id must be provided'
+      end
+      if attributes[:client_id] && attributes[:device_id]
+        raise ArgumentError, 'client_id and device_id cannot both be provided, they are mutually exclusive'
+      end
+      if !attributes[:channel]
+        raise ArgumentError, 'channel is required'
+      end
+    end
+
+    # A static factory method to create a PushChannelSubscription object for a channel and single device.
+    #
+    # @spec PSC5
+    #
+    # @param channel    [String]  the realtime pub/sub channel this subscription is registered to
+    # @param device_id  [String]  Unique device identifier assigned to the push device
+    #
+    # @return [PushChannelSubscription]
+    #
+    def self.for_device(channel, device_id)
+      PushChannelSubscription.new(channel: channel, device_id: device_id)
+    end
+
+    # A static factory method to create a PushChannelSubscription object for a channel and group of devices sharing the same clientId.
+    #
+    # @spec PSC5
+    #
+    # @param channel    [String]  the realtime pub/sub channel this subscription is registered to
+    # @param client_id  [String]  Client ID that is assigned to one or more registered push devices
+    #
+    # @return [PushChannelSubscription]
+    #
+    def self.for_client_id(channel, client_id)
+      PushChannelSubscription.new(channel: channel, client_id: client_id)
+    end
+
+    # The channel the push notification subscription is for.
+    #
+    # @spec PCS4
+    #
+    # @return [String]
+    #
+    def channel
+      attributes[:channel]
+    end
+
+    # The ID of the client the device, or devices are associated to.
+    #
+    # @spec PCS3, PCS6
+    #
+    # @return [String]
+    #
+    def client_id
+      attributes[:client_id]
+    end
+
+    # The unique ID of the device.
+    #
+    # @spec PCS2, PCS5, PCS6
+    #
+    # @return [String]
+    #
+    def device_id
+      attributes[:device_id]
+    end
+
+    %w(channel client_id device_id).each do |attribute|
+      define_method "#{attribute}=" do |val|
+        unless val.nil? || val.kind_of?(String)
+          raise ArgumentError, "#{attribute} must be nil or a string value"
+        end
+        attributes[attribute.to_sym] = val
+      end
+    end
+
+    def attributes
+      @hash_object
+    end
+  end
+end

data/lib/ably/models/stats.rb

@@ -0,0 +1,242 @@
+require 'ably/models/stats_types'
+
+module Ably::Models
+  # Convert stat argument to a {Stats} object
+  #
+  # @param stat [Stats,Hash] A Stats object or Hash of stat properties
+  #
+  # @return [Stats]
+  def self.Stats(stat)
+    case stat
+    when Stats
+      stat
+    else
+      Stats.new(stat)
+    end
+  end
+
+  # A class representing an individual statistic for a specified {#interval_id}
+  #
+  class Stats
+    include Ably::Modules::ModelCommon
+    extend Ably::Modules::Enum
+
+    # Describes the interval unit over which statistics are gathered.
+    #
+    # MINUTE		Interval unit over which statistics are gathered as minutes.
+    # HOUR		  Interval unit over which statistics are gathered as hours.
+    # DAY		    Interval unit over which statistics are gathered as days.
+    # MONTH		  Interval unit over which statistics are gathered as months.
+    #
+    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
+      #   Stats.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
+      #   Stats.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 { |fmt| expected_length(fmt) == interval_id.length }
+        raise ArgumentError, 'Interval ID is an invalid length' unless format
+
+        Time.strptime("#{interval_id} +0000", "#{format} %z").utc
+      end
+
+      # Returns the {Symbol} determined from the interval_id
+      # @example
+      #   Stats.granularity_from_interval_id('2015-01-01:10') # => :hour
+      #
+      # @param interval_id [String]
+      #
+      # @return [Symbol]
+      #
+      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 { |fmt| expected_length(fmt) == 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
+
+    # {Stats} initializer
+    #
+    # @param hash_object  [Hash]  object with the underlying stat details
+    #
+    def initialize(hash_object)
+      @raw_hash_object  = hash_object
+      set_attributes_object hash_object
+    end
+
+    # A {Ably::Models::Stats::MessageTypes} object containing the aggregate count of all message stats.
+    #
+    # @spec TS12e
+    #
+    # @return [Stats::MessageTypes]
+    #
+    def all
+      @all ||= Stats::MessageTypes.new(attributes[:all])
+    end
+
+    # A {Ably::Models::Stats::MessageTraffic} object containing the aggregate count of inbound message stats.
+    #
+    # @spec TS12f
+    #
+    # @return [Ably::Models::Stats::MessageTraffic]
+    #
+    def inbound
+      @inbound ||= Stats::MessageTraffic.new(attributes[:inbound])
+    end
+
+    # A {Ably::Models::Stats::MessageTraffic} object containing the aggregate count of outbound message stats.
+    #
+    # @spec TS12g
+    #
+    # @return [Ably::Models::Stats::MessageTraffic]
+    #
+    def outbound
+      @outbound ||= Stats::MessageTraffic.new(attributes[:outbound])
+    end
+
+    # A {Ably::Models::Stats::MessageTraffic} object containing the aggregate count of persisted message stats.
+    #
+    # @spec TS12h
+    #
+    # @return [Ably::Models::Stats::MessageTraffic]
+    #
+    def persisted
+      @persisted ||= Stats::MessageTypes.new(attributes[:persisted])
+    end
+
+    # A {Ably::Models::Stats::ConnectionTypes} object containing a breakdown of connection related stats, such as min, mean and peak connections.
+    #
+    # @spec TS12i
+    #
+    # @return [Ably::Models::Stats::ConnectionTypes]
+    #
+    def connections
+      @connections ||= Stats::ConnectionTypes.new(attributes[:connections])
+    end
+
+    # A {Ably::Models::Stats::ResourceCount} object containing a breakdown of connection related stats, such as min, mean and peak connections.
+    #
+    # @spec TS12j
+    #
+    # @return [Ably::Models::Stats::ResourceCount]
+    #
+    def channels
+      @channels ||= Stats::ResourceCount.new(attributes[:channels])
+    end
+
+    # A {Ably::Models::Stats::RequestCount} object containing a breakdown of API Requests.
+    #
+    # @spec TS12k
+    #
+    # @return [Ably::Models::Stats::RequestCount]
+    #
+    def api_requests
+      @api_requests ||= Stats::RequestCount.new(attributes[:api_requests])
+    end
+
+    # A {Ably::Models::Stats::RequestCount} object containing a breakdown of Ably Token requests.
+    #
+    # @spec TS12l
+    #
+    # @return [Ably::Models::Stats::RequestCount]
+    #
+    def token_requests
+      @token_requests ||= Stats::RequestCount.new(attributes[:token_requests])
+    end
+
+    # The UTC time at which the time period covered begins. If unit is set to minute this will be in
+    # the format YYYY-mm-dd:HH:MM, if hour it will be YYYY-mm-dd:HH, if day it will be YYYY-mm-dd:00
+    # and if month it will be YYYY-mm-01:00.
+    #
+    # @spec TS12a
+    #
+    # @return [String]
+    #
+    def interval_id
+      attributes.fetch(:interval_id)
+    end
+
+    # Represents the intervalId as a time object.
+    #
+    # @spec TS12b
+    #
+    # @return [Time]
+    #
+    def interval_time
+      self.class.from_interval_id(interval_id)
+    end
+
+    # The length of the interval the stats span. Values will be a [StatsIntervalGranularity]{@link StatsIntervalGranularity}.
+    #
+    # @spec TS12c
+    #
+    # @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 attributes
+      @attributes
+    end
+
+    def as_json(*args)
+      attributes.as_json(*args).reject { |key, val| val.nil? }
+    end
+
+    private
+    def raw_hash_object
+      @raw_hash_object
+    end
+
+    def set_attributes_object(new_attributes)
+      @attributes = IdiomaticRubyWrapper(new_attributes.clone.freeze)
+    end
+  end
+end