token_request.rb in ably-rest-1.2.3

- old
+ new

@@ -2,21 +2,23 @@
   # Convert token request argument to a {TokenRequest} object
   #
   # @param attributes (see #initialize)
   #
   # @return [TokenRequest]
+  #
   def self.TokenRequest(attributes)
     case attributes
     when TokenRequest
       return attributes
     else
       TokenRequest.new(attributes)
     end
   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.
   #
   class TokenRequest
@@ -37,26 +39,47 @@
         self.attributes[:timestamp] = (self.attributes[:timestamp].to_f * 1000).round
       end
       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.
     #                   TTL when sent to Ably is in milliseconds.
     def ttl
       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.
     def capability
       capability_val = attributes.fetch(:capability) { raise Ably::Exceptions::InvalidTokenRequest, 'Capability is missing' }
@@ -69,51 +92,89 @@
       else
         JSON.parse(attributes.fetch(:capability))
       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.
     #                Timestamp when sent to Ably is in milliseconds.
     def timestamp
       timestamp_val = attributes.fetch(:timestamp) { raise Ably::Exceptions::InvalidTokenRequest, 'Timestamp is missing' }
       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.
     def nonce
       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
       attributes[:persisted]
     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