ably-rest 0.7.5 → 0.8.1

data/lib/submodules/ably-ruby/lib/ably/models/token_details.rb

@@ -0,0 +1,101 @@
+module Ably::Models
+  # Convert token details argument to a {TokenDetails} object
+  #
+  # @param attributes [TokenDetails,Hash] A {TokenDetails} object or Hash of token and meta data attributes
+  # @option attributes (see TokenDetails#initialize)
+  #
+  # @return [TokenDetails]
+  def self.TokenDetails(attributes)
+    case attributes
+    when TokenDetails
+      return attributes
+    else
+      TokenDetails.new(attributes)
+    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 {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 TokenDetails
+    include Ably::Modules::ModelCommon
+
+    # Buffer in seconds before a token is considered unusable
+    # For example, if buffer is 10s, the token can no longer be used for new requests 9s before it expires
+    TOKEN_EXPIRY_BUFFER = 5
+
+    def initialize(attributes)
+      @hash_object = IdiomaticRubyWrapper(attributes.clone.freeze)
+    end
+
+    # @param attributes
+    # @option attributes [String]       :token      token used to authenticate requests
+    # @option attributes [String]       :key_name   API key name used to create this token
+    # @option attributes [Time,Integer] :issued  Time the token was issued as Time or Integer in milliseconds
+    # @option attributes [Time,Integer] :expires    Time the token expires as Time or Integer in milliseconds
+    # @option attributes [String]       :capability JSON stringified capabilities assigned to this token
+    # @option attributes [String]       :client_id  client ID assigned to this token
+    #
+    def initialize(attributes = {})
+      @hash_object = IdiomaticRubyWrapper(attributes.clone)
+
+      %w(issued expires).map(&:to_sym).each do |time_attribute|
+        hash[time_attribute] = (hash[time_attribute].to_f * 1000).round if hash[time_attribute].kind_of?(Time)
+      end
+
+      hash.freeze
+    end
+
+    # @!attribute [r] token
+    # @return [String] Token used to authenticate requests
+    def token
+      hash.fetch(: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
+      hash.fetch(:key_name)
+    end
+
+    # @!attribute [r] issued
+    # @return [Time] Time the token was issued
+    def issued
+      as_time_from_epoch(hash.fetch(:issued), granularity: :ms)
+    end
+
+    # @!attribute [r] expires
+    # @return [Time] Time the token expires
+    def expires
+      as_time_from_epoch(hash.fetch(:expires), granularity: :ms)
+    end
+
+    # @!attribute [r] capability
+    # @return [Hash] Capabilities assigned to this token
+    def capability
+      JSON.parse(hash.fetch(:capability))
+    end
+
+    # @!attribute [r] client_id
+    # @return [String] Optional client ID assigned to this token
+    def client_id
+      hash[:client_id]
+    end
+
+    # Returns true if token is expired or about to expire
+    #
+    # @return [Boolean]
+    def expired?
+      expires < Time.now + TOKEN_EXPIRY_BUFFER
+    end
+
+    # @!attribute [r] hash
+    # @return [Hash] Access the token details Hash object ruby'fied to use symbolized keys
+    def hash
+      @hash_object
+    end
+  end
+end

data/lib/submodules/ably-ruby/lib/ably/models/token_request.rb

@@ -0,0 +1,108 @@
+module Ably::Models
+  # Convert token request argument to a {TokenRequest} object
+  #
+  # @param attributes [TokenRequest,Hash] A {TokenRequest} object or Hash of attributes to create a new token request
+  # @option attributes (see TokenRequest#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
+  #
+  # Ruby {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
+    include Ably::Modules::ModelCommon
+
+    # @param attributes
+    # @option attributes [Integer]      :ttl        requested time to live for the token in milliseconds
+    # @option attributes [Time,Integer] :timestamp  the timestamp of this request in milliseconds or as a {Time}
+    # @option attributes [String]       :key_name   API key name of the key against which this request is made
+    # @option attributes [String]       :capability JSON stringified capability of the token
+    # @option attributes [String]       :client_id  client ID to associate with this token
+    # @option attributes [String]       :nonce      an opaque nonce string of at least 16 characters
+    # @option attributes [String]       :mac        the Message Authentication Code for this request
+    #
+    def initialize(attributes = {})
+      @hash_object = IdiomaticRubyWrapper(attributes.clone)
+      hash[:timestamp] = (hash[:timestamp].to_f * 1000).round if hash[:timestamp].kind_of?(Time)
+      hash.freeze
+    end
+
+    # @!attribute [r] key_name
+    # @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
+      hash.fetch(:key_name)
+    end
+
+    # @!attribute [r] ttl
+    # @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
+      hash.fetch(:ttl) / 1000
+    end
+
+    # @!attribute [r] capability
+    # @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
+      JSON.parse(hash.fetch(:capability))
+    end
+
+    # @!attribute [r] client_id
+    # @return [String] the client ID to associate with this token. The generated token
+    #                  may be used to authenticate as this clientId.
+    def client_id
+      hash[:client_id]
+    end
+
+    # @!attribute [r] timestamp
+    # @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
+      as_time_from_epoch(hash.fetch(:timestamp), granularity: :ms)
+    end
+
+    # @!attribute [r] nonce
+    # @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
+      hash.fetch(:nonce)
+    end
+
+    # @!attribute [r] mac
+    # @return [String]  the Message Authentication Code for this request. See the
+    #                   {https://www.ably.io/documentation Ably Authentication documentation} for more details.
+    def mac
+      hash.fetch(:mac)
+    end
+
+    # Requests that the token is always persisted
+    # @api private
+    #
+    def persisted
+      hash.fetch(:persisted)
+    end
+
+    # @!attribute [r] hash
+    # @return [Hash] the token request Hash object ruby'fied to use symbolized keys
+    def hash
+      @hash_object
+    end
+  end
+end

data/lib/submodules/ably-ruby/lib/ably/modules/async_wrapper.rb

@@ -47,8 +47,9 @@ module Ably::Modules
         operation_with_exception_handling = proc do
           begin
             yield
-          rescue StandardError => e
-            deferrable.fail e
+          rescue StandardError => err
+            logger.error "An exception in an AsyncWrapper block was caught. #{err.class}: #{err.message}\n#{err.backtrace.join("\n")}"
+            deferrable.fail err
           end
         end
 

data/lib/submodules/ably-ruby/lib/ably/modules/http_helpers.rb

@@ -18,7 +18,7 @@ module Ably::Modules
     end
 
     def user_agent
-      "Ably Ruby client #{Ably::VERSION} (https://ably.io)"
+      "Ably Ruby client #{Ably::VERSION} (https://www.ably.io)"
     end
 
     def setup_outgoing_middleware(builder)

data/lib/submodules/ably-ruby/lib/ably/modules/message_emitter.rb

@@ -6,7 +6,7 @@ module Ably::Modules
   module MessageEmitter
     # Subscribe to events on this object
     #
-    # @param name [String,Symbol] Optional, the event name to subscribe to. Defaults to `:all` events
+    # @param names [String,Symbol] Optional, the event name(s) to subscribe to. Defaults to `:all` events
     # @yield [Object] For each event, the provided block is called with the event payload object
     #
     # @return [void]
@@ -22,7 +22,7 @@ module Ably::Modules
     # Unsubscribe the matching block for events on the this object.
     # If a block is not provided, all subscriptions will be unsubscribed
     #
-    # @param name [String,Symbol] Optional, the event name to unsubscribe from. Defaults to `:all` events
+    # @param names [String,Symbol] Optional, the event name(s) to unsubscribe from. Defaults to `:all` events
     #
     # @return [void]
     #

data/lib/submodules/ably-ruby/lib/ably/realtime.rb

@@ -39,10 +39,6 @@ module Ably
     # @param (see Ably::Realtime::Client#initialize)
     # @option options (see Ably::Realtime::Client#initialize)
     #
-    # @yield (see Ably::Realtime::Client#initialize)
-    # @yieldparam (see Ably::Realtime::Client#initialize)
-    # @yieldreturn (see Ably::Realtime::Client#initialize)
-    #
     # @return [Ably::Realtime::Client]
     #
     # @example
@@ -50,10 +46,10 @@ module Ably
     #    client = Ably::Realtime.new('key.id:secret')
     #
     #    # create a new client authenticating with basic auth and a client_id
-    #    client = Ably::Realtime.new(api_key: 'key.id:secret', client_id: 'john')
+    #    client = Ably::Realtime.new(key: 'key.id:secret', client_id: 'john')
     #
-    def self.new(options, &token_request_block)
-      Ably::Realtime::Client.new(options, &token_request_block)
+    def self.new(options)
+      Ably::Realtime::Client.new(options)
     end
   end
 end

data/lib/submodules/ably-ruby/lib/ably/realtime/channel.rb

@@ -23,7 +23,7 @@ module Ably
     #   Channel::STATE.Detached
     #   Channel::STATE.Failed
     #
-    # Channels emit errors - use `on(:error)` to subscribe to errors
+    # Channels emit errors - use +on(:error)+ to subscribe to errors
     #
     # @!attribute [r] state
     #   @return {Ably::Realtime::Connection::STATE} channel state
@@ -71,13 +71,18 @@ module Ably
       # @api private
       attr_reader :manager
 
+      # Serial number assigned to this channel when it was attached
+      # @return [Integer]
+      # @api private
+      attr_reader :attached_serial
+
       # Initialize a new Channel object
       #
       # @param  client [Ably::Rest::Client]
       # @param  name [String] The name of the channel
       # @param  channel_options [Hash]     Channel options, currently reserved for Encryption options
       # @option channel_options [Boolean]  :encrypted       setting this to true for this channel will encrypt & decrypt all messages automatically
-      # @option channel_options [Hash]     :cipher_params   A hash of options to configure the encryption. *:key* is required, all other options are optional.  See {Ably::Util::Crypto#initialize} for a list of `cipher_params` options
+      # @option channel_options [Hash]     :cipher_params   A hash of options to configure the encryption. *:key* is required, all other options are optional.  See {Ably::Util::Crypto#initialize} for a list of +cipher_params+ options
       #
       def initialize(client, name, channel_options = {})
         ensure_utf_8 :name, name
@@ -95,7 +100,9 @@ module Ably
         setup_presence
       end
 
-      # Publish a message on the channel
+      # Publish a message on the channel.
+      #
+      # When publishing a message, if the channel is not attached, the channel is implicitly attached
       #
       # @param name [String] The event name of the message
       # @param data [String,ByteArray] payload for the message
@@ -122,7 +129,9 @@ module Ably
         end
       end
 
-      # Subscribe to messages matching providing event name, or all messages if event name not provided
+      # Subscribe to messages matching providing event name, or all messages if event name not provided.
+      #
+      # When subscribing to messages, if the channel is not attached, the channel is implicitly attached
       #
       # @param names [String] The event name of the message to subscribe to if provided.  Defaults to all events.
       # @yield [Ably::Models::Message] For each message received, the block is called
@@ -172,6 +181,8 @@ module Ably
       # presence on the channel and may also be used to obtain presence information
       # and change events for other members of the channel.
       #
+      # When accessing presence, if the channel is not attached, the channel is implicitly attached
+      #
       # @return {Ably::Realtime::Presence}
       #
       def presence
@@ -181,13 +192,24 @@ module Ably
 
       # Return the message history of the channel
       #
+      # If the channel is attached, you can retrieve messages published on the channel before the
+      # channel was attached with the option <tt>until_attach: true</tt>.  This is useful when a developer
+      # wishes to display historical messages with the guarantee that no messages have been missed since attach.
+      #
       # @param (see Ably::Rest::Channel#history)
       # @option options (see Ably::Rest::Channel#history)
+      # @option options [Boolean]  :until_attach  When true, the history request will be limited only to messages published before this channel was attached. Channel must be attached
       #
-      # @yield [Ably::Models::PaginatedResource<Ably::Models::Message>] An Array of {Ably::Models::Message} objects that supports paging (#next_page, #first_page)
+      # @yield [Ably::Models::PaginatedResource<Ably::Models::Message>] First {Ably::Models::PaginatedResource page} of {Ably::Models::Message} objects accessible with {Ably::Models::PaginatedResource#items #items}.
       #
       # @return [Ably::Util::SafeDeferrable]
+      #
       def history(options = {}, &callback)
+        if options.delete(:until_attach)
+          raise ArgumentError, 'option :until_attach is invalid as the channel is not attached' unless attached?
+          options[:from_serial] = attached_serial
+        end
+
         async_wrap(callback) do
           rest_channel.history(options.merge(async_blocking_operations: true))
         end
@@ -212,6 +234,11 @@ module Ably
         @error_reason = nil
       end
 
+      # @api private
+      def set_attached_serial(serial)
+        @attached_serial = serial
+      end
+
       # Used by {Ably::Modules::StateEmitter} to debug state changes
       # @api private
       def logger

data/lib/submodules/ably-ruby/lib/ably/realtime/channel/channel_manager.rb

@@ -40,6 +40,7 @@ module Ably::Realtime
         else
           channel.presence.manager.sync_not_expected
         end
+        channel.set_attached_serial attached_protocol_message.channel_serial
       end
 
       # An error has occurred on the channel

data/lib/submodules/ably-ruby/lib/ably/realtime/client.rb

@@ -64,10 +64,6 @@ module Ably
       # @option options [String]  :recover        When a recover option is specified a connection inherits the state of a previous connection that may have existed under a different instance of the Realtime library, please refer to the API documentation for further information on connection state recovery
       # @option options [Boolean] :connect_automatically  By default as soon as the client library is instantiated it will connect to Ably. You can optionally set this to false and explicitly connect.
       #
-      # @yield (see Ably::Rest::Client#initialize)
-      # @yieldparam (see Ably::Rest::Client#initialize)
-      # @yieldreturn (see Ably::Rest::Client#initialize)
-      #
       # @return [Ably::Realtime::Client]
       #
       # @example
@@ -75,10 +71,10 @@ module Ably
       #    client = Ably::Realtime::Client.new('key.id:secret')
       #
       #    # create a new client and configure a client ID used for presence
-      #    client = Ably::Realtime::Client.new(api_key: 'key.id:secret', client_id: 'john')
+      #    client = Ably::Realtime::Client.new(key: 'key.id:secret', client_id: 'john')
       #
-      def initialize(options, &token_request_block)
-        @rest_client           = Ably::Rest::Client.new(options, &token_request_block)
+      def initialize(options)
+        @rest_client           = Ably::Rest::Client.new(options)
         @auth                  = @rest_client.auth
         @channels              = Ably::Realtime::Channels.new(self)
         @echo_messages         = @rest_client.options.fetch(:echo_messages, true) == false ? false : true
@@ -114,7 +110,7 @@ module Ably
       # @param (see Ably::Rest::Client#stats)
       # @option options (see Ably::Rest::Client#stats)
       #
-      # @yield [Ably::Models::PaginatedResource<Ably::Models::Stat>] An Array of Stats
+      # @yield [Ably::Models::PaginatedResource<Ably::Models::Stats>] An Array of Stats
       #
       # @return [Ably::Util::SafeDeferrable]
       #

data/lib/submodules/ably-ruby/lib/ably/realtime/connection.rb

@@ -10,8 +10,9 @@ module Ably
     #   connected:    2
     #   disconnected: 3
     #   suspended:    4
-    #   closed:       5
-    #   failed:       6
+    #   closing:      5
+    #   closed:       6
+    #   failed:       7
     #
     # Note that the states are available as Enum-like constants:
     #
@@ -20,6 +21,7 @@ module Ably
     #   Connection::STATE.Connected
     #   Connection::STATE.Disconnected
     #   Connection::STATE.Suspended
+    #   Connection::STATE.Closing
     #   Connection::STATE.Closed
     #   Connection::STATE.Failed
     #
@@ -150,7 +152,7 @@ module Ably
       # @yield [Integer] if a block is passed to this method, then this block will be called once the ping heartbeat is received with the time elapsed in milliseconds
       #
       # @example
-      #    client = Ably::Rest::Client.new(api_key: 'key.id:secret')
+      #    client = Ably::Rest::Client.new(key: 'key.id:secret')
       #    client.connection.ping do |ms_elapsed|
       #      puts "Ping took #{ms_elapsed}ms"
       #    end

data/lib/submodules/ably-ruby/lib/ably/realtime/presence.rb

@@ -265,14 +265,25 @@ module Ably::Realtime
 
     # Return the presence messages history for the channel
     #
+    # Once attached to a channel, you can retrieve presence message history on the channel before the
+    # channel was attached with the option <tt>until_attach: true</tt>.  This is very useful for
+    # developers who wish to capture new presence events as well as retrieve historical presence state with
+    # the guarantee that no presence history has been missed.
+    #
     # @param (see Ably::Rest::Presence#history)
     # @option options (see Ably::Rest::Presence#history)
+    # @option options [Boolean]  :until_attach  When true, request for history will be limited only to messages published before the associated channel was attached. The associated channel must be attached.
     #
-    # @yield [Ably::Models::PaginatedResource<Ably::Models::PresenceMessage>] An Array of {Ably::Models::PresenceMessage} objects that supports paging (#next_page, #first_page)
+    # @yield [Ably::Models::PaginatedResource<Ably::Models::PresenceMessage>] First {Ably::Models::PaginatedResource page} of {Ably::Models::PresenceMessage} objects accessible with {Ably::Models::PaginatedResource#items #items}.
     #
     # @return [Ably::Util::SafeDeferrable]
     #
     def history(options = {}, &callback)
+      if options.delete(:until_attach)
+        raise ArgumentError, 'option :until_attach cannot be specified if the channel is not attached' unless channel.attached?
+        options[:from_serial] = channel.attached_serial
+      end
+
       async_wrap(callback) do
         rest_presence.history(options.merge(async_blocking_operations: true))
       end