ably 0.7.5 → 0.7.6

data/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/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/ably/realtime.rb

@@ -50,7 +50,7 @@ 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)

data/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
@@ -181,13 +186,24 @@ 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.
+      #
       # @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.
       #
-      # @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 cannot be specified if 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 +228,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/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/ably/realtime/client.rb

@@ -75,7 +75,7 @@ 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)
@@ -114,7 +114,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/ably/realtime/connection.rb

@@ -150,7 +150,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/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

data/lib/ably/rest.rb

@@ -34,7 +34,7 @@ module Ably
     #    client = Ably::Rest.new('key.id:secret')
     #
     #    # create a new client authenticating with basic auth and a client_id
-    #    client = Ably::Rest.new(api_key: 'key.id:secret', client_id: 'john')
+    #    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)

data/lib/ably/rest/channel.rb

@@ -20,7 +20,7 @@ module Ably
       # @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
@@ -52,16 +52,15 @@ module Ably
         [201, 204].include?(response.status)
       end
 
-      # Return the message history of the channel
+      # 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 [Symbol]       :direction  +:forwards+ or +:backwards+
       # @option options [Integer]      :limit      Maximum number of messages to retrieve up to 10,000
-      # @option options [Symbol]       :by         `:message`, `:bundle` or `:hour`. Defaults to `:message`
       #
-      # @return [Ably::Models::PaginatedResource<Ably::Models::Message>] An Array of {Ably::Models::Message} objects that supports paging (#next_page, #first_page)
+      # @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

data/lib/ably/rest/client.rb

@@ -70,7 +70,7 @@ 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]                  :api_key             API key comprising the key ID and key secret in a single string
+      # @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]                  :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
@@ -89,7 +89,7 @@ module Ably
       #    client = Ably::Rest::Client.new('key.id:secret')
       #
       #    # create a new client and configure a client ID used for presence
-      #    client = Ably::Rest::Client.new(api_key: 'key.id:secret', client_id: 'john')
+      #    client = Ably::Rest::Client.new(key: 'key.id:secret', client_id: 'john')
       #
       def initialize(options, &token_request_block)
         raise ArgumentError, 'Options Hash is expected' if options.nil?
@@ -97,7 +97,7 @@ module Ably
         options = options.clone
         if options.kind_of?(String)
           options = if options.match(/^[\w]{2,}\.[\w]{2,}:[\w]{2,}$/)
-            { api_key:  options }
+            { key: options }
           else
             { token_id: options }
           end
@@ -152,7 +152,7 @@ module Ably
       # @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`
       #
-      # @return [Ably::Models::PaginatedResource<Ably::Models::Stat>] An Array of Stats
+      # @return [Ably::Models::PaginatedResource<Ably::Models::Stats>] An Array of Stats
       #
       def stats(options = {})
         options = {
@@ -163,7 +163,7 @@ module Ably
         [:start, :end].each { |option| options[option] = as_since_epoch(options[option]) if options.has_key?(option) }
 
         paginated_options = {
-          coerce_into: 'Ably::Models::Stat'
+          coerce_into: 'Ably::Models::Stats'
         }
 
         url = '/stats'

data/lib/ably/rest/presence.rb

@@ -28,7 +28,7 @@ module Ably
       # @option options [Symbol]       :direction  `:forwards` or `:backwards`
       # @option options [Integer]      :limit      Maximum number of members to retrieve up to 10,000
       #
-      # @return [Ably::Models::PaginatedResource<Ably::Models::PresenceMessage>] An Array of {Ably::Models::PresenceMessage} objects that supports paging (#next_page, #first_page)
+      # @return [Ably::Models::PaginatedResource<Ably::Models::PresenceMessage>] First {Ably::Models::PaginatedResource page} of {Ably::Models::PresenceMessage} objects accessible with {Ably::Models::PaginatedResource#items #items}.
       #
       def get(options = {})
         options = options.dup
@@ -55,7 +55,7 @@ module Ably
       # @option options [Symbol]       :direction  `:forwards` or `:backwards`
       # @option options [Integer]      :limit      Maximum number of presence messages to retrieve up to 10,000
       #
-      # @return [Ably::Models::PaginatedResource<Ably::Models::PresenceMessage>] An Array of {Ably::Models::PresenceMessage} objects that supports paging (#next_page, #first_page)
+      # @return [Ably::Models::PaginatedResource<Ably::Models::PresenceMessage>] First {Ably::Models::PaginatedResource page} of {Ably::Models::PresenceMessage} objects accessible with {Ably::Models::PaginatedResource#items #items}.
       #
       def history(options = {})
         url = "#{base_path}/history"

data/lib/ably/version.rb

@@ -1,3 +1,3 @@
 module Ably
-  VERSION = '0.7.5'
+  VERSION = '0.7.6'
 end

data/spec/acceptance/realtime/channel_history_spec.rb

@@ -3,10 +3,11 @@ require 'spec_helper'
 
 describe Ably::Realtime::Channel, '#history', :event_machine do
   vary_by_protocol do
-    let(:default_options) { options.merge(api_key: api_key, environment: environment, protocol: protocol) }
+    let(:default_options) { options.merge(key: api_key, environment: environment, protocol: protocol) }
 
     let(:client)       { Ably::Realtime::Client.new(default_options) }
     let(:channel)      { client.channel(channel_name) }
+    let(:rest_channel) { client.rest_client.channel(channel_name) }
 
     let(:client2)      { Ably::Realtime::Client.new(default_options) }
     let(:channel2)     { client2.channel(channel_name) }
@@ -21,20 +22,20 @@ describe Ably::Realtime::Channel, '#history', :event_machine do
       channel.publish('event', payload) do |message|
         history = channel.history
         expect(history).to be_a(Ably::Util::SafeDeferrable)
-        history.callback do |messages|
-          expect(messages.count).to eql(1)
-          expect(messages).to be_a(Ably::Models::PaginatedResource)
+        history.callback do |page|
+          expect(page.items.count).to eql(1)
+          expect(page).to be_a(Ably::Models::PaginatedResource)
           stop_reactor
         end
       end
     end
 
     context 'with a single client publishing and receiving' do
-      it 'retrieves real-time history' do
+      it 'retrieves realtime history' do
         channel.publish('event', payload) do |message|
-          channel.history do |history|
-            expect(history.length).to eql(1)
-            expect(history[0].data).to eql(payload)
+          channel.history do |page|
+            expect(page.items.length).to eql(1)
+            expect(page.items[0].data).to eql(payload)
             stop_reactor
           end
         end
@@ -42,15 +43,15 @@ describe Ably::Realtime::Channel, '#history', :event_machine do
     end
 
     context 'with two clients publishing messages on the same channel' do
-      it 'retrieves real-time history on both channels' do
+      it 'retrieves realtime history on both channels' do
         channel.publish('event', payload) do |message|
           channel2.publish('event', payload) do |message|
-            channel.history do |history|
-              expect(history.length).to eql(2)
-              expect(history.map(&:data).uniq).to eql([payload])
+            channel.history do |page|
+              expect(page.items.length).to eql(2)
+              expect(page.items.map(&:data).uniq).to eql([payload])
 
-              channel2.history do |history_2|
-                expect(history_2.length).to eql(2)
+              channel2.history do |page_2|
+                expect(page_2.items.length).to eql(2)
                 stop_reactor
               end
             end
@@ -65,18 +66,18 @@ describe Ably::Realtime::Channel, '#history', :event_machine do
       let(:limit)           { 15 }
 
       def ensure_message_history_direction_and_paging_is_correct(direction)
-        channel.history(direction: direction, limit: limit) do |history|
-          expect(history.length).to eql(limit)
+        channel.history(direction: direction, limit: limit) do |history_page|
+          expect(history_page.items.length).to eql(limit)
           limit.times do |index|
-            expect(history[index].data).to eql("history#{index}")
+            expect(history_page.items[index].data).to eql("history#{index}")
           end
 
-          history.next_page do |history|
-            expect(history.length).to eql(limit)
+          history_page.next do |next_page|
+            expect(next_page.items.length).to eql(limit)
             limit.times do |index|
-              expect(history[index].data).to eql("history#{index + limit}")
+              expect(next_page.items[index].data).to eql("history#{index + limit}")
             end
-            expect(history.last_page?).to eql(true)
+            expect(next_page).to be_last
 
             stop_reactor
           end
@@ -141,8 +142,8 @@ describe Ably::Realtime::Channel, '#history', :event_machine do
           channel.subscribe('event') do |message|
             messages << message
             if messages.count == batches * messages_per_batch
-              channel.history do |history|
-                expect(history.map(&:id).sort).to eql(messages.map(&:id).sort)
+              channel.history do |page|
+                expect(page.items.map(&:id).sort).to eql(messages.map(&:id).sort)
                 stop_reactor
               end
             end
@@ -150,5 +151,55 @@ describe Ably::Realtime::Channel, '#history', :event_machine do
         end
       end
     end
+
+    context 'with option until_attach: true' do
+      let(:event) { random_str }
+      let(:message_before_attach) { random_str }
+      let(:message_after_attach) { random_str }
+
+      it 'retrieves all messages before channel was attached' do
+        rest_channel.publish event, message_before_attach
+
+        channel.attach do
+          channel.publish(event, message_after_attach) do
+            channel.history(until_attach: true) do |messages|
+              expect(messages.items.count).to eql(1)
+              expect(messages.items.first.data).to eql(message_before_attach)
+              stop_reactor
+            end
+          end
+        end
+      end
+
+      context 'and two pages of messages' do
+        it 'retrieves two pages of messages before channel was attached' do
+          10.times { rest_channel.publish event, message_before_attach }
+
+          channel.attach do
+            10.times { rest_channel.publish event, message_after_attach }
+
+            EventMachine.add_timer(0.5) do
+              channel.history(until_attach: true, limit: 5) do |messages|
+                expect(messages.items.count).to eql(5)
+                expect(messages.items.map(&:data).uniq.first).to eql(message_before_attach)
+
+                messages.next do |next_page_messages|
+                  expect(next_page_messages.items.count).to eql(5)
+                  expect(next_page_messages.items.map(&:data).uniq.first).to eql(message_before_attach)
+                  expect(next_page_messages).to be_last
+
+                  stop_reactor
+                end
+              end
+            end
+          end
+        end
+      end
+
+      it 'raises an exception unless state is attached' do
+        expect { channel.history(until_attach: true) }.to raise_error(ArgumentError, /not attached/)
+        stop_reactor
+      end
+    end
   end
 end

data/spec/acceptance/realtime/channel_spec.rb

@@ -3,7 +3,7 @@ require 'spec_helper'
 
 describe Ably::Realtime::Channel, :event_machine do
   vary_by_protocol do
-    let(:default_options) { { api_key: api_key, environment: environment, protocol: protocol } }
+    let(:default_options) { { key: api_key, environment: environment, protocol: protocol } }
     let(:client_options)  { default_options }
 
     let(:client)       { Ably::Realtime::Client.new(client_options) }
@@ -158,7 +158,7 @@ describe Ably::Realtime::Channel, :event_machine do
 
       context 'failure as a result of insufficient key permissions' do
         let(:restricted_client) do
-          Ably::Realtime::Client.new(default_options.merge(api_key: restricted_api_key, log_level: :fatal))
+          Ably::Realtime::Client.new(default_options.merge(key: restricted_api_key, log_level: :fatal))
         end
         let(:restricted_channel) { restricted_client.channel("cannot_subscribe") }
 
@@ -202,7 +202,7 @@ describe Ably::Realtime::Channel, :event_machine do
             restricted_channel.once(:failed) do
               restricted_client.close do
                 # A direct call to #authorise is synchronous
-                restricted_client.auth.authorise(api_key: api_key)
+                restricted_client.auth.authorise(key: api_key)
 
                 restricted_client.connect do
                   restricted_channel.once(:attached) do