ably 0.7.6 → 0.8.0

data/lib/ably/models/presence_message.rb

@@ -30,7 +30,7 @@ module Ably::Models
   # @!attribute [r] data
   #   @return [Object] Optional client-defined status or other event payload associated with this state
   # @!attribute [r] encoding
-  #   @return [Object] The encoding for the message data. Encoding and decoding of messages is handled automatically by the client library.
+  #   @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

data/lib/ably/models/protocol_message.rb

@@ -31,7 +31,7 @@ module Ably::Models
   # @!attribute [r] presence
   #   @return [PresenceMessage] A {ProtocolMessage} with a `:presence` action contains one or more presence updates belonging to a channel
   # @!attribute [r] flags
-  #   @return [Integer] Flags inidicating special ProtocolMessage states
+  #   @return [Integer] Flags indicating special ProtocolMessage states
   # @!attribute [r] hash
   #   @return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys
   #
@@ -170,7 +170,6 @@ module Ably::Models
         end
     end
 
-    # Flags as bits
     def flags
       Integer(hash[:flags])
     rescue TypeError

data/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/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/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/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
@@ -52,8 +48,8 @@ module Ably
     #    # create a new client authenticating with basic auth and a client_id
     #    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/ably/realtime/channel.rb

@@ -100,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
@@ -127,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
@@ -177,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
@@ -186,21 +192,21 @@ module Ably
 
       # Return the message history of the channel
       #
-      # Once attached to a channel, you can retrieve messages published 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 subscribe to new realtime messages yet also display historical messages with
-      # the guarantee that no messages have been missed.
+      # 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, request for history will be limited only to messages published before this channel was attached. Channel must be attached.
+      # @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>] 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 cannot be specified if the channel is not attached' unless attached?
+          raise ArgumentError, 'option :until_attach is invalid as the channel is not attached' unless attached?
           options[:from_serial] = attached_serial
         end
 

data/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
@@ -77,8 +73,8 @@ module Ably
       #    # create a new client and configure a client ID used for presence
       #    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

data/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
     #

data/lib/ably/rest.rb

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

data/lib/ably/rest/channel.rb

@@ -54,16 +54,20 @@ module Ably
 
       # Return the message   of the channel
       #
-      # @param [Hash] options the options for the message history request
-      # @option options [Integer,Time] :start      Time or millisecond since epoch
-      # @option options [Integer,Time] :end        Time or millisecond since epoch
-      # @option options [Symbol]       :direction  +:forwards+ or +:backwards+
-      # @option options [Integer]      :limit      Maximum number of messages to retrieve up to 10,000
+      # @param [Hash] options   the options for the message history request
+      # @option options [Integer,Time] :start      Ensure earliest time or millisecond since epoch for any messages retrieved is +:start+
+      # @option options [Integer,Time] :end        Ensure latest time or millisecond since epoch for any messages retrieved is +:end+
+      # @option options [Symbol]       :direction  +:forwards+ or +:backwards+, defaults to +:backwards+
+      # @option options [Integer]      :limit      Maximum number of messages to retrieve up to 1,000, defaults to 100
       #
       # @return [Ably::Models::PaginatedResource<Ably::Models::Message>] First {Ably::Models::PaginatedResource page} of {Ably::Models::Message} objects accessible with {Ably::Models::PaginatedResource#items #items}.
+      #
       def history(options = {})
         url = "#{base_path}/messages"
-        options = options.dup
+        options = {
+          :direction => :backwards,
+          :limit     => 100
+        }.merge(options)
 
         [:start, :end].each { |option| options[option] = as_since_epoch(options[option]) if options.has_key?(option) }
 

data/lib/ably/rest/client.rb

@@ -70,18 +70,16 @@ module Ably
       # @param [Hash,String] options an options Hash used to configure the client and the authentication, or String with an API key or Token ID
       # @option options (see Ably::Auth#authorise)
       # @option options [Boolean]                 :tls                 TLS is used by default, providing a value of false disables TLS.  Please note Basic Auth is disallowed without TLS as secrets cannot be transmitted over unsecured connections.
-      # @option options [String]                  :key                 API key comprising the key ID and key secret in a single string
-      # @option options [Boolean]                 :use_token_auth      Will force Basic Auth if set to false, and TOken auth if set to true
+      # @option options [String]                  :key                 API key comprising the key name and key secret in a single string
+      # @option options [String]                  :token               Token string or {Models::TokenDetails} used to authenticate requests
+      # @option options [String]                  :token_details       {Models::TokenDetails} used to authenticate requests
+      # @option options [Boolean]                 :use_token_auth      Will force Basic Auth if set to false, and Token auth if set to true
       # @option options [String]                  :environment         Specify 'sandbox' when testing the client library against an alternate Ably environment
       # @option options [Symbol]                  :protocol            Protocol used to communicate with Ably, :json and :msgpack currently supported. Defaults to :msgpack
       # @option options [Boolean]                 :use_binary_protocol Protocol used to communicate with Ably, defaults to true and uses MessagePack protocol.  This option will overide :protocol option
       # @option options [Logger::Severity,Symbol] :log_level           Log level for the standard Logger that outputs to STDOUT.  Defaults to Logger::ERROR, can be set to :fatal (Logger::FATAL), :error (Logger::ERROR), :warn (Logger::WARN), :info (Logger::INFO), :debug (Logger::DEBUG) or :none
       # @option options [Logger]                  :logger              A custom logger can be used however it must adhere to the Ruby Logger interface, see http://www.ruby-doc.org/stdlib-1.9.3/libdoc/logger/rdoc/Logger.html
       #
-      # @yield (see Ably::Auth#authorise)
-      # @yieldparam (see Ably::Auth#authorise)
-      # @yieldreturn (see Ably::Auth#authorise)
-      #
       # @return [Ably::Rest::Client]
       #
       # @example
@@ -91,7 +89,7 @@ module Ably
       #    # create a new client and configure a client ID used for presence
       #    client = Ably::Rest::Client.new(key: 'key.id:secret', client_id: 'john')
       #
-      def initialize(options, &token_request_block)
+      def initialize(options)
         raise ArgumentError, 'Options Hash is expected' if options.nil?
 
         options = options.clone
@@ -99,7 +97,7 @@ module Ably
           options = if options.match(/^[\w]{2,}\.[\w]{2,}:[\w]{2,}$/)
             { key: options }
           else
-            { token_id: options }
+            { token: options }
           end
         end
 
@@ -127,7 +125,7 @@ module Ably
         raise ArgumentError, 'Protocol is invalid.  Must be either :msgpack or :json' unless [:msgpack, :json].include?(@protocol)
 
         @options  = options.freeze
-        @auth     = Auth.new(self, options, &token_request_block)
+        @auth     = Auth.new(self, options)
         @channels = Ably::Rest::Channels.new(self)
         @encoders = []
 
@@ -146,18 +144,19 @@ module Ably
       # Retrieve the Stats for the application
       #
       # @param [Hash] options the options for the stats request
-      # @option options [Integer,Time] :start      Time or millisecond since epoch
-      # @option options [Integer,Time] :end        Time or millisecond since epoch
-      # @option options [Symbol]       :direction  `:forwards` or `:backwards`
-      # @option options [Integer]      :limit      Maximum number of stats to retrieve up to 10,000
-      # @option options [Symbol]       :by         `:minute`, `:hour`, `:day` or `:month`. Defaults to `:minute`
+      # @option options [Integer,Time] :start      Ensure earliest time or millisecond since epoch for any stats retrieved is +:start+
+      # @option options [Integer,Time] :end        Ensure latest time or millisecond since epoch for any stats retrieved is +:end+
+      # @option options [Symbol]       :direction  +:forwards+ or +:backwards+, defaults to +:backwards+
+      # @option options [Integer]      :limit      Maximum number of messages to retrieve up to 1,000, defaults to 100
+      # @option options [Symbol]       :unit       `:minute`, `:hour`, `:day` or `:month`. Defaults to `:minute`
       #
       # @return [Ably::Models::PaginatedResource<Ably::Models::Stats>] An Array of Stats
       #
       def stats(options = {})
         options = {
-          :direction => :forwards,
-          :by        => :minute
+          :direction => :backwards,
+          :unit      => :minute,
+          :limit     => 100
         }.merge(options)
 
         [:start, :end].each { |option| options[option] = as_since_epoch(options[option]) if options.has_key?(option) }