ably 0.7.5 → 0.7.6

data/ably.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.version       = Ably::VERSION
   spec.authors       = ['Lewis Marshall', "Matthew O'Riordan"]
   spec.email         = ['lewis@lmars.net', 'matt@ably.io']
-  spec.description   = %q{A Ruby client library for ably.io, the real-time messaging service}
-  spec.summary       = %q{A Ruby client library for ably.io, the real-time messaging service}
+  spec.description   = %q{A Ruby client library for ably.io, the realtime messaging service}
+  spec.summary       = %q{A Ruby client library for ably.io, the realtime messaging service}
   spec.homepage      = 'http://github.com/ably/ably-ruby'
   spec.license       = 'MIT'
 
@@ -33,4 +33,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rspec-retry'
   spec.add_development_dependency 'yard'
   spec.add_development_dependency 'webmock'
+
+  spec.add_development_dependency 'coveralls'
 end

data/lib/ably/auth.rb

@@ -15,7 +15,7 @@ module Ably
   #   @return [Ably::Models::Token] Current {Ably::Models::Token} issued by this library or one of the provided callbacks used to authenticate requests
   # @!attribute [r] token_id
   #   @return [String] Token ID provided to the {Ably::Client} constructor that is used to authenticate all requests
-  # @!attribute [r] api_key
+  # @!attribute [r] key
   #   @return [String] Complete API key containing both the key ID and key secret, if present
   # @!attribute [r] key_id
   #   @return [String] Key ID (public part of the API key), if present
@@ -49,14 +49,16 @@ module Ably
         raise ArgumentError, 'Expected auth_options to be a Hash'
       end
 
-      if auth_options[:api_key] && (auth_options[:key_secret] || auth_options[:key_id])
-        raise ArgumentError, 'api_key and key_id or key_secret are mutually exclusive. Provider either an api_key or key_id & key_secret'
+      api_key = auth_options[:key] || auth_options[:api_key] # backwards support for previously used :api_key
+
+      if api_key && (auth_options[:key_secret] || auth_options[:key_id])
+        raise ArgumentError, 'key and key_id or key_secret are mutually exclusive. Provider either a key or key_id & key_secret'
       end
 
-      split_api_key_into_key_and_secret! auth_options if auth_options[:api_key]
+      split_api_key_into_key_and_secret! auth_options if api_key
 
       if using_basic_auth? && !api_key_present?
-        raise ArgumentError, 'api_key is missing. Either an API key, token, or token auth method must be provided'
+        raise ArgumentError, 'key is missing. Either an API key, token, or token auth method must be provided'
       end
 
       if has_client_id?
@@ -73,7 +75,7 @@ module Ably
     #
     # @param [Hash] options the options for the token request
     # @option options (see #request_token)
-    # @option options [String]  :api_key API key comprising the key ID and key secret in a single string
+    # @option options [String]  :key     API key comprising the key ID and key secret in a single string
     # @option options [Boolean] :force   obtains a new token even if the current token is valid
     #
     # @yield (see #request_token)
@@ -84,7 +86,7 @@ module Ably
     #
     # @example
     #    # will issue a simple token request using basic auth
-    #    client = Ably::Rest::Client.new(api_key: 'key.id:secret')
+    #    client = Ably::Rest::Client.new(key: 'key.id:secret')
     #    token = client.auth.authorise
     #
     #    # will use token request from block to authorise if not already authorised
@@ -99,7 +101,9 @@ module Ably
       end
 
       options = options.clone
-      split_api_key_into_key_and_secret! options if options[:api_key]
+
+      api_key = options[:key] || options[:api_key] # backwards support for previously used :api_key
+      split_api_key_into_key_and_secret! options if api_key
 
       @options             = @options.merge(options)
       @default_token_block = token_request_block if block_given?
@@ -131,7 +135,7 @@ module Ably
     #
     # @example
     #    # simple token request using basic auth
-    #    client = Ably::Rest::Client.new(api_key: 'key.id:secret')
+    #    client = Ably::Rest::Client.new(key: 'key.id:secret')
     #    token = client.auth.request_token
     #
     #    # token request using auth block
@@ -179,7 +183,7 @@ module Ably
     # @return [Hash]
     #
     # @example
-    #    client.auth.create_request_token(id: 'asd.asd', ttl: 3600)
+    #    client.auth.create_token_request(id: 'asd.asd', ttl: 3600)
     #    # => {
     #    #   :id=>"asds.adsa",
     #    #   :client_id=>nil,
@@ -225,7 +229,7 @@ module Ably
       convert_to_mixed_case_hash(token_request)
     end
 
-    def api_key
+    def key
       "#{key_id}:#{key_secret}" if api_key_present?
     end
 
@@ -308,12 +312,12 @@ module Ably
     # Basic Auth HTTP Authorization header value
     def basic_auth_header
       ensure_api_key_sent_over_secure_connection
-      "Basic #{encode64("#{api_key}")}"
+      "Basic #{encode64("#{key}")}"
     end
 
     def split_api_key_into_key_and_secret!(options)
-      api_key_parts = options[:api_key].to_s.match(/(?<id>[\w_-]+\.[\w_-]+):(?<secret>[\w_-]+)/)
-      raise ArgumentError, 'api_key is invalid' unless api_key_parts
+      api_key_parts = (options[:key] || options[:api_key]).to_s.match(/(?<id>[\w_-]+\.[\w_-]+):(?<secret>[\w_-]+)/)
+      raise ArgumentError, 'key is invalid' unless api_key_parts
 
       options[:key_id]     = api_key_parts[:id].encode(Encoding::UTF_8)
       options[:key_secret] = api_key_parts[:secret].encode(Encoding::UTF_8)

data/lib/ably/models/message.rb

@@ -29,7 +29,7 @@ module Ably::Models
   #   @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
+  #   @return [Time] Timestamp when the message was received by the Ably the realtime service
   # @!attribute [r] id
   #   @return [String] A globally unique message ID
   # @!attribute [r] connection_id

data/lib/ably/models/paginated_resource.rb

@@ -1,12 +1,18 @@
 module Ably::Models
-  # Wraps any Ably HTTP response that supports paging and automatically provides methods to iterate through
-  # the array of resources using {#first_page}, {#next_page}, {#first_page?} and {#last_page?}
+  # Wraps any Ably HTTP response that supports paging and provides methods to iterate through
+  # the pages using {#first}, {#next}, {#first?}, {#has_next?} and {#last?}
+  #
+  # All items in the HTTP response are available in the Array returned from {#items}
   #
   # Paging information is provided by Ably in the LINK HTTP headers
+  #
   class PaginatedResource
-    include Enumerable
     include Ably::Modules::AsyncWrapper if defined?(Ably::Realtime)
 
+    # The items contained within this {PaginatedResource}
+    # @return [Array]
+    attr_reader :items
+
     # @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
@@ -25,9 +31,9 @@ module Ably::Models
       @each_block    = each_block
       @make_async    = options.fetch(:async_blocking_operations, false)
 
-      @body = http_response.body
-      @body = coerce_items_into(body, @coerce_into) if @coerce_into
-      @body = body.map { |item| yield item } if block_given?
+      @items = http_response.body
+      @items = coerce_items_into(items, @coerce_into) if @coerce_into
+      @items = items.map { |item| yield item } if block_given?
     end
 
     # Retrieve the first page of results.
@@ -35,8 +41,9 @@ module Ably::Models
     #   and allows an optional success callback block to be provided.
     #
     # @return [PaginatedResource,Ably::Util::SafeDeferrable]
-    def first_page(&success_callback)
+    def first(&success_callback)
       async_wrap_if_realtime(success_callback) do
+        return nil unless supports_pagination?
         PaginatedResource.new(client.get(pagination_url('first')), base_url, client, pagination_options, &each_block)
       end
     end
@@ -46,9 +53,9 @@ module Ably::Models
     #   and allows an optional success callback block to be provided.
     #
     # @return [PaginatedResource,Ably::Util::SafeDeferrable]
-    def next_page(&success_callback)
+    def next(&success_callback)
       async_wrap_if_realtime(success_callback) do
-        raise Ably::Exceptions::InvalidPageError, 'There are no more pages' if supports_pagination? && last_page?
+        return nil unless has_next?
         PaginatedResource.new(client.get(pagination_url('next')), base_url, client, pagination_options, &each_block)
       end
     end
@@ -56,7 +63,7 @@ module Ably::Models
     # True if this is the last page in the paged resource set
     #
     # @return [Boolean]
-    def last_page?
+    def last?
       !supports_pagination? ||
         pagination_header('next').nil?
     end
@@ -64,11 +71,18 @@ module Ably::Models
     # True if this is the first page in the paged resource set
     #
     # @return [Boolean]
-    def first_page?
+    def first?
       !supports_pagination? ||
         pagination_header('first') == pagination_header('current')
     end
 
+    # True if there is a subsequent page in this paginated set available with {#next}
+    #
+    # @return [Boolean]
+    def has_next?
+      supports_pagination? && !last?
+    end
+
     # True if the HTTP response supports paging with the expected LINK HTTP headers
     #
     # @return [Boolean]
@@ -76,48 +90,21 @@ module Ably::Models
       !pagination_headers.empty?
     end
 
-    # Standard Array accessor method
-    def [](index)
-      body[index]
-    end
-
-    # Returns number of items within this page, not the total number of items in the entire paged resource set
-    def length
-      body.length
-    end
-    alias_method :count, :length
-    alias_method :size,  :length
-
-    # Method to allow {PaginatedResource} to be {http://ruby-doc.org/core-2.1.3/Enumerable.html Enumerable}
-    def each(&block)
-      return to_enum(:each) unless block_given?
-      body.each(&block)
-    end
-
-    # First item in this page
-    def first
-      body.first
-    end
-
-    # Last item in this page
-    def last
-      body.last
-    end
-
     def inspect
       <<-EOF.gsub(/^        /, '')
         #<#{self.class.name}:#{self.object_id}
          @base_url="#{base_url}",
-         @first_page?=#{!!first_page?},
-         @last_page?=#{!!first_page?},
-         @body=
-           #{body.map { |item| item.inspect }.join(",\n           ") }
+         @first?=#{!!first?},
+         @last?=#{!!first?},
+         @has_next?=#{!!has_next?},
+         @items=
+           #{items.map { |item| item.inspect }.join(",\n           ") }
         >
       EOF
     end
 
     private
-    attr_reader :body, :http_response, :base_url, :client, :coerce_into, :raw_body, :each_block, :make_async
+    attr_reader :http_response, :base_url, :client, :coerce_into, :raw_body, :each_block, :make_async
 
     def coerce_items_into(items, type_string)
       items.map do |item|

data/lib/ably/models/presence_message.rb

@@ -33,7 +33,7 @@ module Ably::Models
   #   @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
+  #   @return [Time] Timestamp when the message was received by the Ably the realtime service
   # @!attribute [r] hash
   #   @return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys
   #

data/lib/ably/models/stat.rb

@@ -1,38 +1,40 @@
+require 'ably/models/stats_types'
+
 module Ably::Models
-  # Convert stat argument to a {Stat} object
+  # Convert stat argument to a {Stats} object
   #
-  # @param stat [Stat,Hash] A Stat object or Hash of stat properties
+  # @param stat [Stats,Hash] A Stats object or Hash of stat properties
   #
-  # @return [Stat]
-  def self.Stat(stat)
+  # @return [Stats]
+  def self.Stats(stat)
     case stat
-    when Stat
+    when Stats
       stat
     else
-      Stat.new(stat)
+      Stats.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
+  #   @return [Stats::MessageTypes] 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
+  #   @return [Stats::MessageTraffic] 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
+  #   @return [Stats::MessageTraffic] 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
+  #   @return [Stats::MessageTypes] 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.
+  #   @return [Stats::ConnectionTypes] 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
+  #   @return [Stats::ResourceCount] Aggregate data for usage of Channels
   # @!attribute [r] api_requests
-  #   @return [Hash] Aggregate data for numbers of API requests
+  #   @return [Stats::RequestCount] Aggregate data for numbers of API requests
   # @!attribute [r] token_requests
-  #   @return [Hash] Aggregate data for numbers of Token requests
+  #   @return [Stats::RequestCount] Aggregate data for numbers of Token requests
   #
-  class Stat
+  class Stats
     include Ably::Modules::ModelCommon
     extend Ably::Modules::Enum
 
@@ -53,7 +55,7 @@ module Ably::Models
     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'
+      #   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
@@ -71,7 +73,7 @@ module Ably::Models
 
       # 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
+      #   Stats.from_interval_id('2015-01-01:10') # => 2015-01-01 10:00:00 +0000
       #
       # @param interval_id [String]
       #
@@ -88,7 +90,7 @@ module Ably::Models
 
       # Returns the {GRANULARITY} determined from the interval_id
       # @example
-      #   Stat.granularity_from_interval_id('2015-01-01:10') # => :hour
+      #   Stats.granularity_from_interval_id('2015-01-01:10') # => :hour
       #
       # @param interval_id [String]
       #
@@ -109,20 +111,61 @@ module Ably::Models
       end
     end
 
-    # {Stat} initializer
+    # {Stats} 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
+    # Aggregates inbound and outbound messages
+    # return {@Stats::MessageTypes}
+    def all
+      @all ||= Stats::MessageTypes.new(hash[:all])
+    end
+
+    # All inbound messages i.e. received by Ably from clients
+    # @return {Stats::MessageTraffic}
+    def inbound
+      @inbound ||= Stats::MessageTraffic.new(hash[:inbound])
+    end
+
+    # All outbound messages i.e. sent from Ably to clients
+    # @return {Stats::MessageTraffic}
+    def outbound
+      @outbound ||= Stats::MessageTraffic.new(hash[:outbound])
+    end
+
+    # Messages persisted for later retrieval via the history API
+    # @return {Stats::MessageTypes}
+    def persisted
+      @persisted ||= Stats::MessageTypes.new(hash[:persisted])
+    end
+
+    # Breakdown of connection stats data for different (TLS vs non-TLS) connection types
+    # @return {Stats::ConnectionTypes}
+    def connections
+      @connections ||= Stats::ConnectionTypes.new(hash[:connections])
+    end
+
+    # Breakdown of channels stats
+    # @return {Stats::ResourceCount}
+    def channels
+      @channels ||= Stats::ResourceCount.new(hash[:channels])
+    end
+
+    # Breakdown of API requests received via the REST API
+    # @return {Stats::RequestCount}
+    def api_requests
+      @api_requests ||= Stats::RequestCount.new(hash[:api_requests])
+    end
+
+    # Breakdown of Token requests received via the REST API
+    # @return {Stats::RequestCount}
+    def token_requests
+      @token_requests ||= Stats::RequestCount.new(hash[:token_requests])
     end
 
     # @!attribute [r] interval_id

data/lib/ably/models/stats_types.rb

@@ -0,0 +1,131 @@
+module Ably::Models
+  class Stats
+    # StatsStruct is a basic Struct like class that allows methods to be defined
+    # on the class that will be retuned co-erced objects from the underlying hash used to
+    # initialize the object.
+    #
+    # This class provides a concise way to create classes that have fixed attributes and types
+    #
+    # @example
+    #   class MessageCount < StatsStruct
+    #     coerce_attributes :count, :data, into: Integer
+    #   end
+    #
+    # @api private
+    #
+    class StatsStruct
+      class << self
+        def coerce_attributes(*attributes)
+          options = attributes.pop
+          raise ArgumentError, 'Expected attribute into: within options hash' unless options.kind_of?(Hash) && options[:into]
+
+          @type_klass = options[:into]
+          setup_attribute_methods attributes
+        end
+
+        def type_klass
+          @type_klass
+        end
+
+        private
+        def setup_attribute_methods(attributes)
+          attributes.each do |attr|
+            define_method(attr) do
+              # Lazy load the co-erced value only when accessed
+              unless instance_variable_defined?("@#{attr}")
+                instance_variable_set "@#{attr}", self.class.type_klass.new(hash[attr.to_sym])
+              end
+              instance_variable_get("@#{attr}")
+            end
+          end
+        end
+      end
+
+      attr_reader :hash
+
+      def initialize(hash)
+        @hash = hash || {}
+      end
+    end
+
+    # IntegerDefaultZero will always return an Integer object and will default to value 0 unless truthy
+    #
+    # @api private
+    #
+    class IntegerDefaultZero
+      def self.new(value)
+        (value && value.to_i) || 0
+      end
+    end
+
+    # MessageCount contains aggregate counts for messages and data transferred
+    # @!attribute [r] count
+    #   @return [Integer] count of all messages
+    # @!attribute [r] data
+    #   @return [Integer] total data transferred for all messages in bytes
+    class MessageCount < StatsStruct
+      coerce_attributes :count, :data, into: IntegerDefaultZero
+    end
+
+    # RequestCount contains aggregate counts for requests made
+    # @!attribute [r] succeeded
+    #   @return [Integer] requests succeeded
+    # @!attribute [r] failed
+    #   @return [Integer] requests failed
+    # @!attribute [r] refused
+    #   @return [Integer] requests refused typically as a result of permissions or a limit being exceeded
+    class RequestCount < StatsStruct
+      coerce_attributes :succeeded, :failed, :refused, into: IntegerDefaultZero
+    end
+
+    # ResourceCount contains aggregate data for usage of a resource in a specific scope
+    # @!attribute [r] opened
+    #   @return [Integer] total resources of this type opened
+    # @!attribute [r] peak
+    #   @return [Integer] peak resources of this type used for this period
+    # @!attribute [r] mean
+    #   @return [Integer] average resources of this type used for this period
+    # @!attribute [r] min
+    #   @return [Integer] minimum total resources of this type used for this period
+    # @!attribute [r] refused
+    #   @return [Integer] resource requests refused within this period
+    class ResourceCount < StatsStruct
+      coerce_attributes :opened, :peak, :mean, :min, :refused, into: IntegerDefaultZero
+    end
+
+    # ConnectionTypes contains a breakdown of summary stats data for different (TLS vs non-TLS) connection types
+    # @!attribute [r] tls
+    #   @return [ResourceCount] TLS connection count
+    # @!attribute [r] plain
+    #   @return [ResourceCount] non-TLS connection count (unencrypted)
+    # @!attribute [r] all
+    #   @return [ResourceCount] all connection count (includes both TLS & non-TLS connections)
+    class ConnectionTypes < StatsStruct
+      coerce_attributes :tls, :plain, :all, into: ResourceCount
+    end
+
+    # MessageTypes contains a breakdown of summary stats data for different (message vs presence) message types
+    # @!attribute [r] messages
+    #   @return [MessageCount] count of channel messages
+    # @!attribute [r] presence
+    #   @return [MessageCount] count of presence messages
+    # @!attribute [r] all
+    #   @return [MessageCount] all messages count (includes both presence & messages)
+    class MessageTypes < StatsStruct
+      coerce_attributes :messages, :presence, :all, into: MessageCount
+    end
+
+    # MessageTraffic contains a breakdown of summary stats data for traffic over various transport types
+    # @!attribute [r] realtime
+    #   @return [MessageTypes] count of messages transferred over a realtime transport such as WebSockets
+    # @!attribute [r] rest
+    #   @return [MessageTypes] count of messages transferred using REST
+    # @!attribute [r] webhook
+    #   @return [MessageTypes] count of messages delivered using WebHooks
+    # @!attribute [r] all
+    #   @return [MessageTypes] all messages count (includes realtime, rest and webhook messages)
+    class MessageTraffic < StatsStruct
+      coerce_attributes :realtime, :rest, :webhook, :all, into: MessageTypes
+    end
+  end
+end