channel.rb in ably-rest-0.8.1

- old
+ new

@@ -21,11 +21,11 @@
     #   Channel::STATE.Attached
     #   Channel::STATE.Detaching
     #   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
     #
     class Channel
@@ -69,17 +69,22 @@
       # The Channel manager responsible for attaching, detaching and handling failures for this channel
       # @return [Ably::Realtime::Channel::ChannelManager]
       # @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
 
         @client        = client
@@ -93,12 +98,14 @@
 
         setup_event_handlers
         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
       # @yield [Ably::Models::Message] On success, will call the block with the {Ably::Models::Message}
       # @return [Ably::Models::Message] Deferrable {Ably::Models::Message} that supports both success (callback) and failure (errback) callbacks
       #
@@ -120,12 +127,14 @@
           message.callback(&success_block) if block_given?
           queue_message message
         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
       #
       # @return [void]
       #
@@ -170,26 +179,39 @@
 
       # Presence object for this Channel.  This controls this client's
       # 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
         attach if initialized?
         @presence
       end
 
       # 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
       end
 
@@ -208,9 +230,14 @@
       end
 
       # @api private
       def clear_error_reason
         @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