ably 1.2.2 → 1.2.3

data/lib/ably/models/http_paginated_response.rb

@@ -11,6 +11,7 @@ module Ably::Models
     #   and allows an optional success callback block to be provided.
     #
     # @return [HttpPaginatedResponse,Ably::Util::SafeDeferrable]
+    #
     def first(&success_callback)
       async_wrap_if_realtime(success_callback) do
         return nil unless supports_pagination?
@@ -23,6 +24,7 @@ module Ably::Models
     #   and allows an optional success callback block to be provided.
     #
     # @return [HttpPaginatedResponse,Ably::Util::SafeDeferrable]
+    #
     def next(&success_callback)
       async_wrap_if_realtime(success_callback) do
         return nil unless has_next?
@@ -30,34 +32,54 @@ module Ably::Models
       end
     end
 
-    # HTTP status code for response
+    # The HTTP status code of the response.
+    #
+    # @spec HP4
+    #
     # @return [Integer]
+    #
     def status_code
       http_response.status.to_i
     end
 
-    # True if the response is considered successful due to the HTTP status code
+    # Whether statusCode indicates success. This is equivalent to 200 <= statusCode < 300.
+    #
+    # @spec HP5
+    #
     # @return [Boolean]
+    #
     def success?
       (200..299).include?(http_response.status.to_i)
     end
 
-    # Ably error code from +X-Ably-Errorcode+ header if available from response
+    # The error code if the X-Ably-Errorcode HTTP header is sent in the response.
+    #
+    # @spec HP6
+    #
     # @return [Integer]
+    #
     def error_code
       if http_response.headers['X-Ably-Errorcode']
         http_response.headers['X-Ably-Errorcode'].to_i
       end
     end
 
-    # Error message from +X-Ably-Errormessage+ header if available from response
+    # The error message if the X-Ably-Errormessage HTTP header is sent in the response.
+    #
+    # @spec HP7
+    #
     # @return [String]
+    #
     def error_message
       http_response.headers['X-Ably-Errormessage']
     end
 
-    # Headers for the HTTP response
+    # The headers of the response.
+    #
+    # @spec HP8
+    #
     # @return [Hash<String, String>]
+    #
     def headers
       http_response.headers || {}
     end

data/lib/ably/models/idiomatic_ruby_wrapper.rb

@@ -5,7 +5,8 @@ module Ably::Modules
     private
     # Creates or returns an {IdiomaticRubyWrapper} ensuring it never wraps itself
     #
-    # @return {IdiomaticRubyWrapper}
+    # @return [IdiomaticRubyWrapper]
+    #
     def IdiomaticRubyWrapper(object, options = {})
       case object
       when Ably::Models::IdiomaticRubyWrapper
@@ -143,7 +144,7 @@ module Ably::Models
     end
 
     # @!attribute [r] Hash
-    # @return [Hash] Access to the raw Hash object provided to the constructer of this wrapper
+    # @return [Hash] Access to the raw Hash object provided to the constructor of this wrapper
     def attributes
       @attributes
     end

data/lib/ably/models/message.rb

@@ -7,6 +7,7 @@ module Ably::Models
   # @param [Hash] options (see Message#initialize)
   #
   # @return [Message]
+  #
   def self.Message(message, options = {})
     case message
     when Message
@@ -18,26 +19,7 @@ module Ably::Models
     end
   end
 
-  # A class representing an individual message to be sent or received
-  # via the Ably Realtime service.
-  #
-  # @!attribute [r] name
-  #   @return [String] The event name, if available
-  # @!attribute [r] client_id
-  #   @return [String] The id of the publisher of this message
-  # @!attribute [r] data
-  #   @return [Object] The message payload. See the documentation for supported datatypes.
-  # @!attribute [r] encoding
-  #   @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 realtime service
-  # @!attribute [r] id
-  #   @return [String] A globally unique message ID
-  # @!attribute [r] connection_id
-  #   @return [String] The connection_id of the publisher of the message
-  # @!attribute [r] attributes
-  #   @return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys
+  # Contains an individual message that is sent to, or received from, Ably.
   #
   class Message
     include Ably::Modules::Conversions
@@ -50,6 +32,8 @@ module Ably::Models
 
     # {Message} initializer
     #
+    # @spec TM2, TM3
+    #
     # @param  attributes [Hash]             object with the underlying message detail key value attributes
     # @param  [Hash]      options           an options Hash for this initializer
     # @option options     [ProtocolMessage] :protocol_message  An optional protocol message to assocate the presence message with
@@ -69,24 +53,74 @@ module Ably::Models
       self.attributes.freeze
     end
 
-    %w( name client_id encoding ).each do |attribute|
-      define_method attribute do
-        attributes[attribute.to_sym]
-      end
+    # The client ID of the publisher of this message.
+    #
+    # @spec RSL1g1, TM2b
+    #
+    # @return [String]
+    #
+    def client_id
+      attributes[:client_id]
+    end
+
+    # This is typically empty, as all messages received from Ably are automatically decoded client-side using this value.
+    # However, if the message encoding cannot be processed, this attribute contains the remaining transformations
+    # not applied to the data payload.
+    #
+    # @spec TM2e
+    #
+    # @return [String]
+    #
+    def encoding
+      attributes[:encoding]
     end
 
+    # The event name.
+    #
+    # @spec TM2g
+    #
+    # @return [String]
+    #
+    def name
+      attributes[:name]
+    end
+
+    # The message payload, if provided.
+    #
+    # @spec TM2d
+    #
+    # @return [Hash, nil]
+    #
     def data
       @data ||= attributes[:data].freeze
     end
 
+    # A Unique ID assigned by Ably to this message.
+    #
+    # @spec TM2a
+    #
+    # @return [String]
+    #
     def id
       attributes.fetch(:id) { "#{protocol_message.id!}:#{protocol_message_index}" }
     end
 
+    # The connection ID of the publisher of this message.
+    #
+    # @spec TM2c
+    #
+    # @return [String]
+    #
     def connection_id
       attributes.fetch(:connection_id) { protocol_message.connection_id if assigned_to_protocol_message? }
     end
 
+    # Timestamp of when the message was received by Ably, as milliseconds since the Unix epoch.
+    #
+    # @spec TM2f
+    #
+    # @return [Integer]
+    #
     def timestamp
       if attributes[:timestamp]
         as_time_from_epoch(attributes[:timestamp])
@@ -126,14 +160,18 @@ module Ably::Models
     end
 
     # True if this message is assigned to a ProtocolMessage for delivery to Ably, or received from Ably
+    #
     # @return [Boolean]
+    #
     # @api private
     def assigned_to_protocol_message?
       !!@protocol_message
     end
 
     # The optional ProtocolMessage this message is assigned to.  If ProtocolMessage is nil, an error will be raised.
+    #
     # @return [Ably::Models::ProtocolMessage]
+    #
     # @api private
     def protocol_message
       raise RuntimeError, 'Message is not yet published with a ProtocolMessage. ProtocolMessage is nil' if @protocol_message.nil?
@@ -155,7 +193,9 @@ module Ably::Models
     end
 
     # Delta extras extension (TM2i)
+    #
     # @return [DeltaExtras, nil]
+    #
     # @api private
     def delta_extras
       return nil if attributes[:extras][:delta].nil?

data/lib/ably/models/message_encoders/base.rb

@@ -32,6 +32,7 @@ module Ably
         # @param [Hash] channel_options  the options used to initialize the channel that this message was received on
         #
         # @return [void]
+        #
         def encode(message, channel_options)
           raise "Not yet implemented"
         end
@@ -48,6 +49,7 @@ module Ably
         # @param [Hash] channel_options  the options used to initialize the channel that this message was received on
         #
         # @return [void]
+        #
         def decode(message, channel_options)
           raise "Not yet implemented"
         end
@@ -59,6 +61,7 @@ module Ably
         # @param [String] encoding  encoding to add to the current encoding
         #
         # @return [void]
+        #
         def add_encoding_to_message(encoding, message)
           message[:encoding] = [message[:encoding], encoding].compact.join('/')
         end
@@ -67,6 +70,7 @@ module Ably
         # i.e. current_encoding_part('utf-8/cipher+aes-128-cbc/base64') => 'base64'
         #
         # @return [String,nil]
+        #
         def current_encoding_part(message)
           if message[:encoding]
             message[:encoding].split('/')[-1]
@@ -81,6 +85,7 @@ module Ably
         # @param [Hash]   message   the message as a Hash object received directly from Ably.
         #
         # @return [void]
+        #
         def strip_current_encoding_part(message)
           raise "Cannot strip encoding when there is no encoding for this message" unless message[:encoding]
           message[:encoding] = message[:encoding].split('/')[0...-1].join('/')
@@ -92,6 +97,7 @@ module Ably
         # @param [Hash]   message   the message as a Hash object received directly from Ably.
         #
         # @return [Boolean]
+        #
         def is_empty?(message)
           message[:data].nil? || message[:data] == ''
         end

data/lib/ably/models/paginated_result.rb

@@ -1,16 +1,18 @@
 module Ably::Models
-  # Wraps any Ably HTTP response that supports paging and provides methods to iterate through
-  # the pages using {#first}, {#next}, {#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
+  # Contains a page of results for message or presence history, stats, or REST presence requests.
+  # A PaginatedResult response from a REST API paginated query is also accompanied by metadata
+  # that indicates the relative queries available to the PaginatedResult object.
   #
   class PaginatedResult
     include Ably::Modules::AsyncWrapper if defined?(Ably::Realtime)
 
-    # The items contained within this {PaginatedResult}
+    # Contains the current page of results; for example, an array of {Ably::Models::Message} or {Ably::Models::PresenceMessage} objects
+    # for a channel history request.
+    #
+    # @spec TG3
+    #
     # @return [Array]
+    #
     attr_reader :items
 
     # @param [Faraday::Response] http_response Initial HTTP response from an Ably request to a paged resource
@@ -22,6 +24,7 @@ module Ably::Models
     # @yield [Object] block will be called for each resource object for the current page.  This is a useful way to apply a transformation to any page resources after they are retrieved
     #
     # @return [PaginatedResult]
+    #
     def initialize(http_response, base_url, client, options = {}, &each_block)
       @http_response = http_response
       @client        = client
@@ -41,11 +44,12 @@ module Ably::Models
       @items = items.map { |item| yield item } if block_given?
     end
 
-    # Retrieve the first page of results.
-    # When used as part of the {Ably::Realtime} library, it will return a {Ably::Util::SafeDeferrable} object,
-    #   and allows an optional success callback block to be provided.
+    # Returns a new PaginatedResult for the first page of results.
+    #
+    # @spec TG5
+    #
+    # @return [PaginatedResult, Ably::Util::SafeDeferrable]
     #
-    # @return [PaginatedResult,Ably::Util::SafeDeferrable]
     def first(&success_callback)
       async_wrap_if_realtime(success_callback) do
         return nil unless supports_pagination?
@@ -54,10 +58,14 @@ module Ably::Models
     end
 
     # Retrieve the next page of results.
+    #
     # When used as part of the {Ably::Realtime} library, it will return a {Ably::Util::SafeDeferrable} object,
-    #   and allows an optional success callback block to be provided.
+    # and allows an optional success callback block to be provided.
+    #
+    # @spec TG4
     #
     # @return [PaginatedResult,Ably::Util::SafeDeferrable]
+    #
     def next(&success_callback)
       async_wrap_if_realtime(success_callback) do
         return nil unless has_next?
@@ -65,17 +73,23 @@ module Ably::Models
       end
     end
 
-    # True if this is the last page in the paged resource set
+    # Returns true if this page is the last page and returns false if there are more pages available by calling next available.
+    #
+    # @spec TG7
     #
     # @return [Boolean]
+    #
     def last?
       !supports_pagination? ||
         pagination_header('next').nil?
     end
 
-    # True if there is a subsequent page in this paginated set available with {#next}
+    # Returns true if there are more pages available by calling next and returns false if this page is the last page available.
+    #
+    # @spec TG6
     #
     # @return [Boolean]
+    #
     def has_next?
       supports_pagination? && !last?
     end
@@ -83,6 +97,7 @@ module Ably::Models
     # True if the HTTP response supports paging with the expected LINK HTTP headers
     #
     # @return [Boolean]
+    #
     def supports_pagination?
       !pagination_headers.empty?
     end

data/lib/ably/models/presence_message.rb

@@ -5,6 +5,7 @@ module Ably::Models
   # @param [Hash] options (see PresenceMessage#initialize)
   #
   # @return [PresenceMessage]
+  #
   def self.PresenceMessage(presence_message, options = {})
     case presence_message
     when PresenceMessage
@@ -19,24 +20,6 @@ module Ably::Models
   # A class representing an individual presence message to be sent or received
   # via the Ably Realtime service.
   #
-  # @!attribute [r] action
-  #   @return [ACTION] the state change event signified by a PresenceMessage
-  # @!attribute [r] client_id
-  #   @return [String] The client_id associated with this presence state
-  # @!attribute [r] connection_id
-  #   @return [String] A unique member identifier, disambiguating situations where a given client_id is present on multiple connections simultaneously
-  # @!attribute [r] member_key
-  #   @return [String] A unique connection and client_id identifier ensuring multiple connected clients with the same client_id are unique
-  # @!attribute [r] data
-  #   @return [Object] Optional client-defined status or other event payload associated with this state
-  # @!attribute [r] encoding
-  #   @return [String] 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 realtime service
-  # @!attribute [r] attributes
-  #   @return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys
-  #
   class PresenceMessage
     include Ably::Modules::Conversions
     include Ably::Modules::Encodeable
@@ -44,6 +27,16 @@ module Ably::Models
     include Ably::Modules::SafeDeferrable if defined?(Ably::Realtime)
     extend Ably::Modules::Enum
 
+    # Describes the possible actions members in the presence set can emit.
+    #
+    #   ABSENT	    TP2	A member is not present in the channel.
+    #   PRESENT	    TP2	When subscribing to presence events on a channel that already has members present, this event is emitted for every member already present on the channel before the subscribe listener was registered.
+    #   ENTER	      TP2	A new member has entered the channel.
+    #   LEAVE	      TP2	A member who was present has now left the channel. This may be a result of an explicit request to leave or implicitly when detaching from the channel. Alternatively, if a member's connection is abruptly disconnected and they do not resume their connection within a minute, Ably treats this as a leave event as the client is no longer present.
+    #   UPDATE	    TP2	An already present member has updated their member data. Being notified of member data updates can be very useful, for example, it can be used to update the status of a user when they are typing a message.
+    #
+    # @spec TP2
+    #
     ACTION = ruby_enum('ACTION',
       :absent,
       :present,
@@ -76,24 +69,75 @@ module Ably::Models
       self.attributes.freeze
     end
 
-    %w( client_id data encoding ).each do |attribute|
-      define_method attribute do
-        attributes[attribute.to_sym]
-      end
+    # The ID of the client that published the PresenceMessage.
+    #
+    # @spec TP3c
+    #
+    # @return [String]
+    #
+    def client_id
+      attributes[:client_id]
+    end
+
+    # The payload of the {Ably::Models::PresenceMessage}.
+    #
+    # @spec TP3e
+    #
+    # @return [Hash, nil]
+    #
+    def data
+      attributes[:data]
+    end
+
+    # This will typically be empty as all presence messages received from Ably are automatically decoded client-side
+    # using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining
+    # transformations not applied to the data payload.
+    #
+    # @spec TP3f
+    #
+    # @return [String]
+    #
+    def encoding
+      attributes[:encoding]
     end
 
+    # A unique ID assigned to each {Ably::Models::PresenceMessage} by Ably.
+    #
+    # @spec TP3a
+    #
+    # @return [String]
+    #
     def id
       attributes.fetch(:id) { "#{protocol_message.id!}:#{protocol_message_index}" }
     end
 
+    # The ID of the connection associated with the client that published the {Ably::Models::PresenceMessage}.
+    #
+    # @spec TP3d
+    #
+    # @return [String]
+    #
     def connection_id
       attributes.fetch(:connection_id) { protocol_message.connection_id if assigned_to_protocol_message? }
     end
 
+    # Combines clientId and connectionId to ensure that multiple connected clients with an identical clientId are uniquely
+    # identifiable. A string function that returns the combined clientId and connectionId.
+    #
+    # @spec TP3h
+    #
+    # @return [String]
+    #
     def member_key
       "#{connection_id}:#{client_id}"
     end
 
+    # The time the {Ably::Models::PresenceMessage} was received by Ably, as milliseconds since the Unix epoch.
+    #
+    # @spec TP3g
+    #
+    # @return [Integer]
+    #
     def timestamp
       if attributes[:timestamp]
         as_time_from_epoch(attributes[:timestamp])
@@ -102,6 +146,12 @@ module Ably::Models
       end
     end
 
+    # The type of {Ably::Models::PresenceMessage::ACTION} the PresenceMessage is for.
+    #
+    # @spec TP3b
+    #
+    # @return [Ably::Models::PresenceMessage::ACTION]
+    #
     def action
       ACTION(attributes[:action])
     end

data/lib/ably/models/protocol_message.rb

@@ -189,10 +189,6 @@ module Ably::Models
       presence.map(&:size).sum + messages.map(&:size).sum
     end
 
-    def has_correct_message_size?
-      message_size <= connection_details.max_message_size
-    end
-
     def params
       @params ||= attributes[:params].to_h
     end

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"