ably 1.2.1 → 1.2.3

data/lib/ably/models/push_channel_subscription.rb

@@ -6,6 +6,7 @@ module Ably::Modules
     # @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
@@ -18,20 +19,14 @@ module Ably::Modules
 end
 
 module Ably::Models
-  # An object representing a devices details, used currently for push notifications
-  #
-  # @!attribute [r] channel
-  #   @return [String] The realtime pub/sub channel this subscription is registered to
-  # @!attribute [r] client_id
-  #   @return [String] Client ID that is assigned to one or more registered push devices
-  # @!attribute [r] device_id
-  #   @return [String] Unique device identifier assigned to the push device
+  # 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
-    #a
+    #
     def initialize(hash_object = {})
       @raw_hash_object = hash_object || {}
       @hash_object     = IdiomaticRubyWrapper(hash_object)
@@ -47,7 +42,9 @@ module Ably::Models
       end
     end
 
-    # Constructor for channel subscription by device ID
+    # 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
@@ -58,7 +55,9 @@ module Ably::Models
       PushChannelSubscription.new(channel: channel, device_id: device_id)
     end
 
-    # Constructor for channel subscription by client ID
+    # 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
@@ -69,11 +68,37 @@ module Ably::Models
       PushChannelSubscription.new(channel: channel, client_id: client_id)
     end
 
-    %w(channel client_id device_id).each do |attribute|
-      define_method attribute do
-        attributes[attribute.to_sym]
-      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"

data/lib/ably/models/stats.rb

@@ -17,27 +17,17 @@ module Ably::Models
 
   # A class representing an individual statistic for a specified {#interval_id}
   #
-  # @!attribute [r] all
-  #   @return [Stats::MessageTypes] Breakdown of summary stats for all message types
-  # @!attribute [r] inbound
-  #   @return [Stats::MessageTraffic] Breakdown of summary stats for traffic over various transport types for all inbound messages
-  # @!attribute [r] outbound
-  #   @return [Stats::MessageTraffic] Breakdown of summary stats for traffic over various transport types for all outbound messages
-  # @!attribute [r] persisted
-  #   @return [Stats::MessageTypes] Breakdown of summary stats for all persisted messages
-  # @!attribute [r] connections
-  #   @return [Stats::ConnectionTypes] A breakdown of summary stats data for different (TLS vs non-TLS) connection types.
-  # @!attribute [r] channels
-  #   @return [Stats::ResourceCount] Aggregate data for usage of Channels
-  # @!attribute [r] api_requests
-  #   @return [Stats::RequestCount] Aggregate data for numbers of API requests
-  # @!attribute [r] token_requests
-  #   @return [Stats::RequestCount] Aggregate data for numbers of Token requests
-  #
   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,
@@ -88,13 +78,13 @@ module Ably::Models
         Time.strptime("#{interval_id} +0000", "#{format} %z").utc
       end
 
-      # Returns the {GRANULARITY} determined from the interval_id
+      # Returns the {Symbol} determined from the interval_id
       # @example
       #   Stats.granularity_from_interval_id('2015-01-01:10') # => :hour
       #
       # @param interval_id [String]
       #
-      # @return [GRANULARITY] Granularity Enum for the interval_id
+      # @return [Symbol]
       #
       def granularity_from_interval_id(interval_id)
         raise ArgumentError, 'Interval ID must be a string' unless interval_id.kind_of?(String)
@@ -120,68 +110,114 @@ module Ably::Models
       set_attributes_object hash_object
     end
 
-    # Aggregates inbound and outbound messages
-    # @return {Stats::MessageTypes}
+    # 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
 
-    # All inbound messages i.e. received by Ably from clients
-    # @return {Stats::MessageTraffic}
+    # 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
 
-    # All outbound messages i.e. sent from Ably to clients
-    # @return {Stats::MessageTraffic}
+    # 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
 
-    # Messages persisted for later retrieval via the history API
-    # @return {Stats::MessageTypes}
+    # 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
 
-    # Breakdown of connection stats data for different (TLS vs non-TLS) connection types
-    # @return {Stats::ConnectionTypes}
+    # 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
 
-    # Breakdown of channels stats
-    # @return {Stats::ResourceCount}
+    # 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
 
-    # Breakdown of API requests received via the REST API
-    # @return {Stats::RequestCount}
+    # 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
 
-    # Breakdown of Token requests received via the REST API
-    # @return {Stats::RequestCount}
+    # 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
 
-    # @!attribute [r] interval_id
-    # @return [String] The interval that this statistic applies to, see {GRANULARITY} and {INTERVAL_FORMAT_STRING}
+    # 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
 
-    # @!attribute [r] interval_time
-    # @return [Time] A Time object representing the start of the interval
+    # Represents the intervalId as a time object.
+    #
+    # @spec TS12b
+    #
+    # @return [Time]
+    #
     def interval_time
       self.class.from_interval_id(interval_id)
     end
 
-    # @!attribute [r] interval_granularity
+    # 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

data/lib/ably/models/stats_types.rb

@@ -59,71 +59,47 @@ module Ably::Models
     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
+    #
+    # @spec TS5a, TS5b
+    #
     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
+    #
+    # @spec TS8a, TS8b, TS8c
+    #
     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)
+    #
+    # @spec TS4a, TS4b, TS4c
+    #
     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)
+    #
+    # @spec TS6a, TS6b, TS6c
+    #
     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)
+    #
+    # @spec TS7a, TS7b, TS7c, TS7d
+    #
     class MessageTraffic < StatsStruct
       coerce_attributes :realtime, :rest, :webhook, :all, into: MessageTypes
     end

data/lib/ably/models/token_details.rb

@@ -4,6 +4,7 @@ module Ably::Models
   # @param attributes (see #initialize)
   #
   # @return [TokenDetails]
+  #
   def self.TokenDetails(attributes)
     case attributes
     when TokenDetails
@@ -13,11 +14,7 @@ module Ably::Models
     end
   end
 
-  # TokenDetails is a class providing details of the token string and the token's associated metadata,
-  # constructed from the response from Ably when request in a token via the REST API.
-  #
-  # Ruby {http://ruby-doc.org/core/Time.html Time} objects are supported in place of Ably ms since epoch time fields.  However, if a numeric is provided
-  # it must always be expressed in milliseconds as the Ably API always uses milliseconds for time fields.
+  # Contains an Ably Token and its associated metadata.
   #
   class TokenDetails
     include Ably::Modules::ModelCommon
@@ -46,31 +43,39 @@ module Ably::Models
       self.attributes.freeze
     end
 
-    # @!attribute [r] token
+    # The Ably Token itself. A typical Ably Token string appears with the form xVLyHw.A-pwh7wicf3afTfgiw4k2Ku33kcnSA7z6y8FjuYpe3QaNRTEo4.
+    #
+    # @spec TD2
+    #
     # @return [String] Token used to authenticate requests
+    #
     def token
       attributes[:token]
     end
 
-    # @!attribute [r] key_name
     # @return [String] API key name used to create this token.  An API key is made up of an API key name and secret delimited by a +:+
+    #
     def key_name
       attributes[:key_name]
     end
 
-    # @!attribute [r] issued
+    # The timestamp at which this token was issued as milliseconds since the Unix epoch.
+    # @spec TD4
     # @return [Time] Time the token was issued
     def issued
       as_time_from_epoch(attributes[:issued], granularity: :ms, allow_nil: :true)
     end
 
-    # @!attribute [r] expires
+    # The timestamp at which this token expires as milliseconds since the Unix epoch.
+    # @spec TD3
     # @return [Time] Time the token expires
     def expires
       as_time_from_epoch(attributes[:expires], granularity: :ms, allow_nil: :true)
     end
 
-    # @!attribute [r] capability
+    # The capabilities associated with this Ably Token. The capabilities value is a JSON-encoded representation of the
+    # resource paths and associated operations. Read more about capabilities in the capabilities docs.
+    # @spec TD5
     # @return [Hash] Capabilities assigned to this token
     def capability
       if attributes.has_key?(:capability)
@@ -86,7 +91,10 @@ module Ably::Models
       end
     end
 
-    # @!attribute [r] client_id
+    # The client ID, if any, bound to this Ably Token. If a client ID is included, then the Ably Token authenticates its
+    # bearer as that client ID, and the Ably Token may only be used to perform operations on behalf of that client ID.
+    # The client is then considered to be an identified client.
+    # @spec TD6
     # @return [String] Optional client ID assigned to this token
     def client_id
       attributes[:client_id]
@@ -113,8 +121,8 @@ module Ably::Models
       attributes.keys == [:token]
     end
 
-    # @!attribute [r] attributes
     # @return [Hash] Access the token details Hash object ruby'fied to use symbolized keys
+    #
     def attributes
       @hash_object
     end
@@ -122,5 +130,19 @@ module Ably::Models
     def to_s
       "<TokenDetails token=#{token} client_id=#{client_id} key_name=#{key_name} issued=#{issued} expires=#{expires} capability=#{capability} expired?=#{expired?}>"
     end
+
+    # A static factory method to create a {Ably::Models::TokenDetails} object from a deserialized {Ably::Models::TokenDetails}-like
+    # object or a JSON stringified TokenDetails object. This method is provided to minimize bugs as a result of differing
+    # types by platform for fields such as timestamp or ttl. For example, in Ruby ttl in the {Ably::Models::TokenDetails}
+    # object is exposed in seconds as that is idiomatic for the language, yet when serialized to JSON using to_json it
+    # is automatically converted to the Ably standard which is milliseconds. By using the fromJson() method when constructing
+    # a {Ably::Models::TokenDetails} object, Ably ensures that all fields are consistently serialized and deserialized across platforms.
+    #
+    # @overload from_json(json_like_object)
+    # @spec TD7
+    # @param json_like_object [Hash, String] A deserialized TokenDetails-like object or a JSON stringified TokenDetails object.
+    #
+    # @return [Ably::Models::TokenDetails]  An Ably authentication token.
+    #
   end
 end

data/lib/ably/models/token_request.rb

@@ -4,6 +4,7 @@ module Ably::Models
   # @param attributes (see #initialize)
   #
   # @return [TokenRequest]
+  #
   def self.TokenRequest(attributes)
     case attributes
     when TokenRequest
@@ -14,7 +15,8 @@ module Ably::Models
   end
 
 
-  # TokenRequest is a class that stores the attributes of a token request
+  # Contains the properties of a request for a token to Ably.
+  # Tokens are generated using {Ably::Auth#requestToken}.
   #
   # Ruby {http://ruby-doc.org/core/Time.html Time} objects are supported in place of Ably ms since epoch time fields.  However, if a numeric is provided
   # it must always be expressed in milliseconds as the Ably API always uses milliseconds for time fields.
@@ -39,13 +41,26 @@ module Ably::Models
       self.attributes.freeze
     end
 
+    # The name of the key against which this request is made. The key name is public, whereas the key secret is private.
+    #
     # @!attribute [r] key_name
+    #
+    # @spec TE2
+    #
     # @return [String] API key name of the key against which this request is made.  An API key is made up of an API key name and secret delimited by a +:+
+    #
     def key_name
       attributes.fetch(:key_name) { raise Ably::Exceptions::InvalidTokenRequest, 'Key name is missing' }
     end
 
+    # Requested time to live for the Ably Token in milliseconds. If the Ably TokenRequest is successful, the TTL of the
+    # returned Ably Token is less than or equal to this value, depending on application settings and the attributes of
+    # the issuing key. The default is 60 minutes.
+    #
     # @!attribute [r] ttl
+    #
+    # @spec TE4
+    #
     # @return [Integer] requested time to live for the token in seconds. If the token request is successful,
     #                   the TTL of the returned token will be less than or equal to this value depending on application
     #                   settings and the attributes of the issuing key.
@@ -54,7 +69,15 @@ module Ably::Models
       attributes.fetch(:ttl) / 1000
     end
 
+    # Capability of the requested Ably Token. If the Ably TokenRequest is successful, the capability of the returned
+    # Ably Token will be the intersection of this capability with the capability of the issuing key. The capabilities
+    # value is a JSON-encoded representation of the resource paths and associated operations. Read more about
+    # capabilities in the capabilities docs.
+    #
     # @!attribute [r] capability
+    #
+    # @spec TE3
+    #
     # @return [Hash] capability of the token. If the token request is successful,
     #                the capability of the returned token will be the intersection of
     #                this capability with the capability of the issuing key.
@@ -71,14 +94,25 @@ module Ably::Models
       end
     end
 
+    # The client ID to associate with the requested Ably Token. When provided, the Ably Token may only be used to
+    # perform operations on behalf of that client ID.
+    #
     # @!attribute [r] client_id
+    #
+    # @spec TE2
+    #
     # @return [String] the client ID to associate with this token. The generated token
     #                  may be used to authenticate as this clientId.
     def client_id
       attributes[:client_id]
     end
 
+    # The timestamp of this request as milliseconds since the Unix epoch.
+    #
     # @!attribute [r] timestamp
+    #
+    # @spec TE5
+    #
     # @return [Time] the timestamp of this request.
     #                Timestamps, in conjunction with the nonce, are used to prevent
     #                token requests from being replayed.
@@ -88,7 +122,12 @@ module Ably::Models
       as_time_from_epoch(timestamp_val, granularity: :ms)
     end
 
+    # A cryptographically secure random string of at least 16 characters, used to ensure the TokenRequest cannot be reused.
+    #
     # @!attribute [r] nonce
+    #
+    # @spec TE2
+    #
     # @return [String]  an opaque nonce string of at least 16 characters to ensure
     #                   uniqueness of this request. Any subsequent request using the
     #                   same nonce will be rejected.
@@ -96,14 +135,20 @@ module Ably::Models
       attributes.fetch(:nonce) { raise Ably::Exceptions::InvalidTokenRequest, 'Nonce is missing' }
     end
 
+    # The Message Authentication Code for this request.
+    #
     # @!attribute [r] mac
+    #
+    # @spec TE2
+    #
     # @return [String]  the Message Authentication Code for this request. See the
-    #                   {https://www.ably.com/docs Ably Authentication documentation} for more details.
+    #
     def mac
       attributes.fetch(:mac) { raise Ably::Exceptions::InvalidTokenRequest, 'MAC is missing' }
     end
 
     # Requests that the token is always persisted
+    #
     # @api private
     #
     def persisted
@@ -111,9 +156,25 @@ module Ably::Models
     end
 
     # @!attribute [r] attributes
+    #
     # @return [Hash] the token request Hash object ruby'fied to use symbolized keys
+    #
     def attributes
       @hash_object
     end
+
+    # A static factory method to create a TokenRequest object from a deserialized TokenRequest-like object or a JSON
+    # stringified TokenRequest object. This method is provided to minimize bugs as a result of differing types by platform
+    # for fields such as timestamp or ttl. For example, in Ruby ttl in the TokenRequest object is exposed in seconds as
+    # that is idiomatic for the language, yet when serialized to JSON using to_json it is automatically converted to
+    # the Ably standard which is milliseconds. By using the fromJson() method when constructing a TokenRequest object,
+    # Ably ensures that all fields are consistently serialized and deserialized across platforms.
+    #
+    # @overload from_json(json_like_object)
+    # @spec TE6
+    # @param json_like_object [Hash, String] A deserialized TokenRequest-like object or a JSON stringified TokenRequest object to create a TokenRequest.
+    #
+    # @return [Ably::Models::TokenRequest] An Ably token request object.
+    #
   end
 end

data/lib/ably/modules/async_wrapper.rb

@@ -36,6 +36,7 @@ module Ably::Modules
     # Will yield the provided block in a new thread and return an {Ably::Util::SafeDeferrable}
     #
     # @yield [Object] operation block that is run in a thread
+    #
     # @return [Ably::Util::SafeDeferrable]
     #
     def async_wrap(success_callback = nil, custom_error_handling = nil)

data/lib/ably/modules/enum.rb

@@ -90,7 +90,9 @@ module Ably::Modules
           end
 
           # Array of Enum values as symbols
+          #
           # @return [Array<Symbol>]
+          #
           def to_sym_arr
             @by_symbol.keys
           end