ably 1.2.2 → 1.2.4

data/lib/ably/models/channel_state_change.rb

@@ -1,15 +1,5 @@
 module Ably::Models
-  # ChannelStateChange is a class that is emitted by the {Ably::Realtime::Channel} object
-  # when a state change occurs
-  #
-  # @!attribute [r] current
-  #   @return [Connection::STATE] Current channel state
-  # @!attribute [r] previous
-  #   @return [Connection::STATE] Previous channel state
-  # @!attribute [r] reason
-  #   @return [Ably::Models::ErrorInfo] Object describing the reason for a state change when not initiated by the consumer of the client library
-  # @!attribute [r] resumed
-  #   @return [Boolean] True when a channel is resumed, false when continuity on the channel is no longer provided indicating that the developer is now responsible for recovering lost messages on this channel through other means, such as using the hisory API
+  # Contains state change information emitted by {Ably::Rest::Channel} and {Ably::Realtime::Channel} objects.
   #
   class ChannelStateChange
     include Ably::Modules::ModelCommon
@@ -31,12 +21,52 @@ module Ably::Models
       raise ArgumentError, e
     end
 
-    %w(current previous event reason).each do |attribute|
-      define_method attribute do
-        @hash_object[attribute.to_sym]
-      end
+    # The new current {Ably::Realtime::Channel::STATE}.
+    #
+    # @spec RTL2a, RTL2b
+    #
+    # @return [Ably::Realtime::Channel::STATE]
+    #
+    def current
+      @hash_object[:current]
+    end
+
+    # The previous state. For the {Ably::Realtime::Channel::EVENT}(:update) event, this is equal to the current {Ably::Realtime::Channel::STATE}.
+    #
+    # @spec RTL2a, RTL2b
+    #
+    # @return [Ably::Realtime::Channel::EVENT]
+    #
+    def previous
+      @hash_object[:previous]
+    end
+
+    # The event that triggered this {Ably::Realtime::Channel::STATE} change.
+    #
+    # @spec TH5
+    #
+    # @return [Ably::Realtime::Channel::STATE]
+    #
+    def event
+      @hash_object[:event]
+    end
+
+    # An {Ably::Models::ErrorInfo} object containing any information relating to the transition.
+    #
+    # @spec RTL2e, TH3
+    #
+    # @return [Ably::Models::ErrorInfo, nil]
+    #
+    def reason
+      @hash_object[:reason]
     end
 
+    # Indicates whether message continuity on this channel is preserved, see Nonfatal channel errors for more info.
+    #
+    # @spec RTL2f, TH4
+    #
+    # @return [Boolean]
+    #
     def resumed
       !!@hash_object[:resumed]
     end

data/lib/ably/models/channel_status.rb

@@ -4,6 +4,7 @@ module Ably::Models
   # @param attributes (see #initialize)
   #
   # @return [ChannelStatus]
+  #
   def self.ChannelStatus(attributes)
     case attributes
     when ChannelStatus
@@ -13,14 +14,19 @@ module Ably::Models
     end
   end
 
-  # ChannelStatus is a type that contains status and occupancy for a channel (CHS1)
+  # Contains the status of a {Ably::Models::Rest::Channel} or {Ably::Models::Realtime::Channel} object
+  # such as whether it is active and its {Ably::Models::ChannelOccupancy}.
+  #
+  # @spec CHS1
   #
   class ChannelStatus
     extend Ably::Modules::Enum
     extend Forwardable
     include Ably::Modules::ModelCommon
 
-    # The attributes of ChannelStatus (CHS2)
+    # The attributes of ChannelStatus
+    #
+    # @spec CHS2
     #
     attr_reader :attributes
 
@@ -32,7 +38,9 @@ module Ably::Models
       @attributes = IdiomaticRubyWrapper(attrs.clone)
     end
 
-    # Represents if the channel is active (CHS2a)
+    # If true, the channel is active, otherwise false.
+    #
+    # @spec CHS2a
     #
     # @return [Boolean]
     #
@@ -42,7 +50,9 @@ module Ably::Models
     alias_method :active?, :is_active
     alias_method :is_active?, :is_active
 
-    # Occupancy ChannelOccupancy – occupancy is an object containing the metrics for the channel (CHS2b)
+    # A {Ably::Models::ChannelOccupancy} object.
+    #
+    # @spec CHS2b
     #
     # @return [Ably::Models::ChannelOccupancy, nil]
     #

data/lib/ably/models/cipher_params.rb

@@ -7,6 +7,7 @@ module Ably::Models
   # @param attributes (see #initialize)
   #
   # @return [CipherParams]
+  #
   def self.CipherParams(attributes)
     case attributes
     when CipherParams
@@ -16,7 +17,7 @@ module Ably::Models
     end
   end
 
-  # CipherParams is used to configure a channel for encryption
+  # Sets the properties to configure encryption for a {Ably::Models::Rest::Channel} or {Ably::Models::Realtime::Channel} object.
   #
   class CipherParams
     include Ably::Modules::ModelCommon
@@ -57,49 +58,71 @@ module Ably::Models
     end
 
     # The Cipher algorithm string such as AES-128-CBC
+    #
     # @param [Hash]  params  Hash containing :algorithm, :key_length and :mode key values
     #
     # @return [String]
+    #
     def self.cipher_type(params)
       "#{params[:algorithm]}-#{params[:key_length]}-#{params[:mode]}".to_s.upcase
     end
 
-    # @!attribute [r] algorithm
-    # @return [String] The algorithm to use for encryption, currently only +AES+ is supported
+    # The algorithm to use for encryption. Only AES is supported and is the default value.
+    #
+    # @spec TZ2a
+    #
+    # @return [String]
+    #
     def algorithm
       attributes.fetch(:algorithm) do
         Ably::Util::Crypto::DEFAULTS.fetch(:algorithm)
       end.downcase
     end
 
-    # @!attribute [r] key
-    # @return [Binary] Private key used to encrypt and decrypt payloads
+    # The private key used to encrypt and decrypt payloads.
+    #
+    # @spec TZ2d
+    #
+    # @return [Binary]
+    #
     def key
       attributes[:key]
     end
 
-    # @!attribute [r] key_length
-    # @return [Integer] The length in bits of the +key+
+    # The length of the key in bits; for example 128 or 256.
+    #
+    # @spec TZ2b
+    #
+    # @return [Integer]
+    #
     def key_length
       key.unpack('b*').first.length
     end
 
-    # @!attribute [r] mode
-    # @return [String] The cipher mode, currently only +CBC+ is supported
+    # The cipher mode. Only CBC is supported and is the default value.
+    #
+    # @spec TZ2c
+    #
+    # @return [String]
+    #
     def mode
       attributes.fetch(:mode) do
         Ably::Util::Crypto::DEFAULTS.fetch(:mode)
       end.downcase
     end
 
-    # @!attribute [r] cipher_type
-    # @return [String] The complete Cipher algorithm string such as AES-128-CBC
+    # The complete Cipher algorithm string such as AES-128-CBC
+    #
+    # @return [String]
+    #
     def cipher_type
       self.class.cipher_type(algorithm: algorithm, key_length: key_length, mode: mode)
     end
 
-    # @!attribute [r] attributes
-    # @return [Hash] Access the token details Hash object ruby'fied to use symbolized keys
+    # Access the token details Hash object ruby'fied to use symbolized keys
+    #
+    # @return [Hash]
+    #
     def attributes
       @attributes
     end

data/lib/ably/models/connection_details.rb

@@ -4,6 +4,7 @@ module Ably::Models
   # @param attributes (see #initialize)
   #
   # @return [ConnectionDetails]
+  #
   def self.ConnectionDetails(attributes)
     case attributes
     when ConnectionDetails
@@ -13,10 +14,8 @@ module Ably::Models
     end
   end
 
-  # ConnectionDetails are optionally passed to the client library in the +CONNECTED+ {Ably::Models::ProtocolMessage#connectionDetails} attribute
-  # to inform the client about any constraints it should adhere to and provide additional metadata about the connection.
-  # For example, if a request is made to publish a message that exceeds the +maxMessageSize+, the client library can reject
-  # the message immediately, without communicating with the Ably service
+  # Contains any constraints a client should adhere to and provides additional metadata about a {Ably::Realtime::Connection},
+  # such as if a request to {Ably::Realtime::Client#publish} a message that exceeds the maximum message size should be rejected immediately without communicating with Ably.
   #
   class ConnectionDetails
     include Ably::Modules::ModelCommon
@@ -28,7 +27,7 @@ module Ably::Models
     MAX_FRAME_SIZE = 524288 # See spec TO3l9
 
     # @param attributes [Hash]
-    # @option attributes [String]    :client_id             contains the client ID assigned to the connection
+    # @option attributes [String]    :client_id             Contains the client ID assigned to the token. If clientId is null or omitted, then the client is prohibited from assuming a clientId in any operations, however if clientId is a wildcard string *, then the client is permitted to assume any clientId. Any other string value for clientId implies that the clientId is both enforced and assumed for all operations from this client.
     # @option attributes [String]    :connection_key        the connection secret key string that is used to resume a connection and its state
     # @option attributes [Integer]   :max_message_size      maximum individual message size in bytes
     # @option attributes [Integer]   :max_frame_size        maximum size for a single frame of data sent to Ably. This restriction applies to a {Ably::Models::ProtocolMessage} sent over a realtime connection, or the total body size for a REST request
@@ -49,18 +48,100 @@ module Ably::Models
       self.attributes.freeze
     end
 
-    %w(client_id connection_key max_message_size max_frame_size max_inbound_rate connection_state_ttl max_idle_interval server_id).each do |attribute|
-      define_method attribute do
-        attributes[attribute.to_sym]
-      end
+    # Contains the client ID assigned to the token. If clientId is null or omitted, then the client is prohibited from
+    # assuming a clientId in any operations, however if clientId is a wildcard string *, then the client is permitted
+    # to assume any clientId. Any other string value for clientId implies that the clientId is both enforced and assumed
+    # for all operations from this client.
+    #
+    # @spec RSA12a, CD2a
+    #
+    # @return [String]
+    #
+    def client_id
+      attributes[:client_id]
+    end
+
+    # The connection secret key string that is used to resume a connection and its state.
+    #
+    # @spec RTN15e, CD2b
+    #
+    # @return [String]
+    #
+    def connection_key
+      attributes[:connection_key]
+    end
+
+    # The duration that Ably will persist the connection state for when a Realtime client is abruptly disconnected.
+    #
+    # @spec CD2f, RTN14e, DF1a
+    #
+    # @return [Integer]
+    #
+    def connection_state_ttl
+      attributes[:connection_state_ttl]
+    end
+
+    # Overrides the default maxFrameSize.
+    #
+    # @spec CD2d
+    #
+    # @return [Integer]
+    #
+    def max_frame_size
+      attributes[:max_frame_size]
+    end
+
+    # The maximum allowable number of requests per second from a client or Ably. In the case of a realtime connection,
+    # this restriction applies to the number of messages sent, whereas in the case of REST, it is the total number of REST requests per second.
+    #
+    # @spec CD2e
+    #
+    # @return [Integer]
+    #
+    def max_inbound_rate
+      attributes[:max_inbound_rate]
+    end
+
+    # The maximum message size is an attribute of an Ably account and enforced by Ably servers.
+    # maxMessageSize indicates the maximum message size allowed by the Ably account this connection is using.
+    # Overrides the default value of ClientOptions.maxMessageSize.
+    #
+    # @spec CD2c
+    #
+    # @return [Integer]
+    #
+    def max_message_size
+      attributes[:max_message_size]
+    end
+
+    # A unique identifier for the front-end server that the client has connected to. This server ID is only used for the purposes of debugging.
+    #
+    # @spec CD2g
+    #
+    # @return [String]
+    #
+    def server_id
+      attributes[:server_id]
+    end
+
+    # The maximum length of time in milliseconds that the server will allow no activity to occur in the server to client direction.
+    # After such a period of inactivity, the server will send a HEARTBEAT or transport-level ping to the client.
+    # If the value is 0, the server will allow arbitrarily-long levels of inactivity.
+    #
+    # @spec CD2h
+    #
+    # @return [Integer]
+    #
+    def max_idle_interval
+      attributes[:max_idle_interval]
     end
 
     def has_client_id?
       attributes.has_key?(:client_id)
     end
 
-    # @!attribute [r] attributes
     # @return [Hash] Access the token details Hash object ruby'fied to use symbolized keys
+    #
     def attributes
       @hash_object
     end

data/lib/ably/models/connection_state_change.rb

@@ -1,15 +1,5 @@
 module Ably::Models
-  # ConnectionStateChange is a class that is emitted by the {Ably::Realtime::Connection} object
-  # when a state change occurs
-  #
-  # @!attribute [r] current
-  #   @return [Connection::STATE] Current connection state
-  # @!attribute [r] previous
-  #   @return [Connection::STATE] Previous connection state
-  # @!attribute [r] retry_in
-  #   @return [Integer] Time in seconds until the connection will reattempt to connect when in the +:disconnected+ or +:suspended+ state
-  # @!attribute [r] reason
-  #   @return [Ably::Models::ErrorInfo] Object describing the reason for a state change when not initiated by the consumer of the client library
+  # Contains {Ably::Models::ConnectionState} change information emitted by the {Ably::Realtime::Connection} object.
   #
   class ConnectionStateChange
     include Ably::Modules::ModelCommon
@@ -31,10 +21,59 @@ module Ably::Models
       raise ArgumentError, e
     end
 
-    %w(current previous event retry_in reason protocol_message).each do |attribute|
-      define_method attribute do
-        @hash_object[attribute.to_sym]
-      end
+    # The new {Ably::Realtime::Connection::STATE}.
+    #
+    # @spec TA2
+    #
+    # @return [Ably::Realtime::Connection::STATE]
+    #
+    def current
+      @hash_object[:current]
+    end
+
+    # The event that triggered this {Ably::Realtime::Connection::EVENT} change.
+    #
+    # @spec TA5
+    #
+    # @return [Ably::Realtime::Connection::STATE]
+    #
+    def event
+      @hash_object[:event]
+    end
+
+    # The previous {Ably::Models::Connection::STATE}. For the {Ably::Models::Connection::EVENT} UPDATE event,
+    # this is equal to the current {Ably::Models::Connection::STATE}.
+    #
+    # @spec TA2
+    #
+    # @return [Ably::Realtime::Connection::STATE]
+    #
+    def previous
+      @hash_object[:previous]
+    end
+
+    # An {Ably::Models::ErrorInfo} object containing any information relating to the transition.
+    #
+    # @spec RTN4f, TA3
+    #
+    # @return [Ably::Models::ErrorInfo, nil]
+    #
+    def reason
+      @hash_object[:reason]
+    end
+
+    # Duration in milliseconds, after which the client retries a connection where applicable.
+    #
+    # @spec RTN14d, TA2
+    #
+    # @return [Integer]
+    #
+    def retry_in
+      @hash_object[:retry_in]
+    end
+
+    def protocol_message
+      @hash_object[:protocol_message]
     end
 
     def to_s

data/lib/ably/models/delta_extras.rb

@@ -1,19 +1,18 @@
 module Ably::Models
-  #
-  # @!attribute [r] from
-  #   @return [String] The id of the message the delta was generated from
-  # @!attribute [r] format
-  #   @return [String] The delta format. Only vcdiff is supported as at API version 1.2
+  # Contains any arbitrary key-value pairs, which may also contain other primitive JSON types, JSON-encodable objects,
+  # or JSON-encodable arrays from delta compression.
   #
   class DeltaExtras
     include Ably::Modules::ModelCommon
 
-    # The id of the message the delta was generated from.
+    # The ID of the message the delta was generated from.
+    #
     # @return [String, nil]
     #
     attr_reader :from
 
-    # The delta format.
+    # The delta compression format. Only vcdiff is supported.
+    #
     # @return [String, nil]
     #
     attr_reader :format

data/lib/ably/models/device_details.rb

@@ -6,6 +6,7 @@ module Ably::Modules
     # @param device_details [Ably::Models::DeviceDetails,Hash,nil] A device details object
     #
     # @return [Ably::Models::DeviceDetails]
+    #
     def DeviceDetails(device_details)
       case device_details
       when Ably::Models::DeviceDetails
@@ -18,38 +19,63 @@ module Ably::Modules
 end
 
 module Ably::Models
-  # An object representing a devices details, used currently for push notifications
-  #
-  # @!attribute [r] id
-  #   @return [String] Unique device identifier assigned randomly by the device
-  # @!attribute [r] platform
-  #   @return [String] Device platform such as android, ios or browser
-  # @!attribute [r] form_factor
-  #   @return [String] Device form factor such as phone, tablet, watch
-  # @!attribute [r] client_id
-  #   @return [String] The authenticated client identifier for this device. See {https://www.ably.com/docs/general/authentication#identified-clients auth documentation}.
-  # @!attribute [r] metadata
-  #   @return [Hash] Arbitrary metadata that can be associated with a device
-  # @!attribute [r] device_secret
-  #   @return [String] This secret is used internally by Ably client libraries to authenticate with Ably when push registration updates are required such as when the GCM token expires and needs renewing
-  # @!attribute [r] push
-  #   @return [DevicePushDetails] The push notification specific properties for this device allowing push notifications to be delivered to the device
+  # Contains the properties of a device registered for push notifications.
   #
   class DeviceDetails < 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)
     end
 
-    %w(id platform form_factor client_id device_secret).each do |attribute|
-      define_method attribute do
-        attributes[attribute.to_sym]
-      end
+    # A unique ID generated by the device.
+    #
+    # @spec PCD2
+    #
+    def id
+      attributes[:id]
+    end
+
+    # The DevicePlatform associated with the device.
+    # Describes the platform the device uses, such as android or ios.
+    #
+    # @spec PCD6
+    #
+    # @return [String]
+    #
+    def platform
+      attributes[:platform]
+    end
+
+    # The client ID the device is connected to Ably with.
+    #
+    # @spec PCD3
+    #
+    # @return [String]
+    #
+    def client_id
+      attributes[:client_id]
+    end
+
+    # The DeviceFormFactor object associated with the device.
+    # Describes the type of the device, such as phone or tablet.
+    #
+    # @spec PCD4
+    #
+    # @return [String]
+    #
+    def form_factor
+      attributes[:form_factor]
+    end
+
+    def device_secret
+      attributes[:device_secret]
+    end
 
+    %w(id platform form_factor client_id device_secret).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"
@@ -58,6 +84,12 @@ module Ably::Models
       end
     end
 
+    # A JSON object of key-value pairs that contains metadata for the device.
+    #
+    # @spec PCD5
+    #
+    # @return [Hash, nil]
+    #
     def metadata
       attributes[:metadata] || {}
     end
@@ -69,6 +101,13 @@ module Ably::Models
       attributes[:metadata] = val
     end
 
+    # The {Ably::Models::DevicePushDetails} object associated with the device.
+    # Describes the details of the push registration of the device.
+    #
+    # @spec PCD7
+    #
+    # @return [Ably::Models::DevicePushDetails]
+    #
     def push
       DevicePushDetails(attributes[:push] || {})
     end

data/lib/ably/models/device_push_details.rb

@@ -6,6 +6,7 @@ module Ably::Modules
     # @param device_push_details [Ably::Models::DevicePushDetails,Hash,nil] A device push notification details object
     #
     # @return [Ably::Models::DevicePushDetails]
+    #
     def DevicePushDetails(device_push_details)
       case device_push_details
       when Ably::Models::DevicePushDetails
@@ -20,38 +21,39 @@ end
 module Ably::Models
   # An object with the push notification details for {DeviceDetails} object
   #
-  # @!attribute [r] transport_type
-  #   @return [String] Transport type for push notifications such as gcm, apns, web
-  # @!attribute [r] state
-  #   @return [String] The current state of this push target such as Active, Failing or Failed
-  # @!attribute [r] error_reason
-  #   @return [ErrorInfo] If the state is Failing of Failed, this field may optionally contain a reason
-  # @!attribute [r] metadata
-  #   @return [Hash] Arbitrary metadata that can be associated with this object
-  #
   class DevicePushDetails < Ably::Exceptions::BaseAblyException
     include Ably::Modules::ModelCommon
 
     # @param hash_object   [Hash,nil]  Device push detail attributes
-    #a
+    #
     def initialize(hash_object = {})
       @raw_hash_object = hash_object || {}
       @hash_object     = IdiomaticRubyWrapper(@raw_hash_object)
     end
 
-    %w(state).each do |attribute|
-      define_method attribute do
-        attributes[attribute.to_sym]
-      end
+    # The current state of the push registration.
+    #
+    # @spec PCP4
+    #
+    # @return [Symbol]
+    #
+    def state
+      attributes[:state]
+    end
 
-      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
+    def state=(val)
+      unless val.nil? || val.kind_of?(String)
+        raise ArgumentError, "state must be nil or a string value"
       end
+      attributes[:state] = val
     end
 
+    # A JSON object of key-value pairs that contains of the push transport and address.
+    #
+    # @spec PCP3
+    #
+    # @return [Hash, nil]
+    #
     def recipient
       attributes[:recipient] || {}
     end
@@ -63,6 +65,12 @@ module Ably::Models
       attributes[:recipient] = val
     end
 
+    # An {Ably::Models::ErrorInfo} object describing the most recent error when the state is Failing or Failed.
+    #
+    # @spec PCP2
+    #
+    # @return [Ably::Models::ErrorInfo]
+    #
     def error_reason
       attributes[:error_reason]
     end