ably 1.2.2 → 1.2.3

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

data/lib/ably/models/error_info.rb

@@ -6,6 +6,7 @@ module Ably::Modules
     # @param error_details [ErrorInfo,Hash] Error info attributes
     #
     # @return [ErrorInfo]
+    #
     def ErrorInfo(error_details)
       case error_details
       when Ably::Models::ErrorInfo
@@ -21,19 +22,6 @@ module Ably::Models
   # An exception type encapsulating error information containing
   # an Ably-specific error code and generic status code.
   #
-  # @!attribute [r] message
-  #   @return [String] Additional reason information, where available
-  # @!attribute [r] code
-  #   @return [Integer] Ably error code (see ably-common/protocol/errors.json)
-  # @!attribute [r] status
-  #   @return [Integer] HTTP Status Code corresponding to this error, where applicable
-  # @!attribute [r] request_id
-  #   @return [Integer] HTTP RequestId corresponding to this error, where applicable (#RSC7c)
-  # @!attribute [r] cause
-  #   @return [Integer] HTTP Status Code corresponding to this error, where applicable (#TI1)
-  # @!attribute [r] attributes
-  #   @return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys
-  #
   class ErrorInfo < Ably::Exceptions::BaseAblyException
     include Ably::Modules::ModelCommon
 
@@ -42,10 +30,64 @@ module Ably::Models
       @hash_object     = IdiomaticRubyWrapper(hash_object.clone.freeze)
     end
 
-    %w(message code href status_code request_id cause).each do |attribute|
-      define_method attribute do
-        attributes[attribute.to_sym]
-      end
+    # Ably error code.
+    #
+    # @spec TI1
+    #
+    # @return [Integer]
+    #
+    def code
+      attributes[:code]
+    end
+
+    # This is included for REST responses to provide a URL for additional help on the error code.
+    #
+    # @spec TI4
+    #
+    # @return [String]
+    #
+    def href
+      attributes[:href]
+    end
+
+    # Additional message information, where available.
+    #
+    # @spec TI1
+    #
+    # @return [String]
+    #
+    def message
+      attributes[:message]
+    end
+
+    # Information pertaining to what caused the error where available.
+    #
+    # @spec TI1
+    #
+    # @return [Ably::Models::ErrorInfo]
+    #
+    def cause
+      attributes[:cause]
+    end
+
+    # HTTP Status Code corresponding to this error, where applicable.
+    #
+    # @spec TI1
+    #
+    # @return [Integer]
+    #
+    def status_code
+      attributes[:status_code]
+    end
+
+    # If a request fails, the request ID must be included in the ErrorInfo returned to the user.
+    #
+    # @spec RSC7c
+    #
+    # @return [String]
+    #
+    def request_id
+      attributes[:request_id]
     end
     alias_method :status, :status_code