ably-rest 0.8.2 → 0.8.3

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

@@ -92,12 +92,10 @@ module Ably::Models
       @hash_object
     end
 
-    def as_json(*args)
-      raise RuntimeError, ':name is missing, cannot generate a valid Hash for Message' unless name
-
-      hash.dup.tap do |message|
+    def to_json(*args)
+      as_json(*args).tap do |message|
         decode_binary_data_before_to_json message
-      end.as_json
+      end.to_json
     end
 
     # Assign this message to a ProtocolMessage before delivery to the Ably system

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

@@ -1,6 +1,6 @@
 module Ably::Models
   # Wraps any Ably HTTP response that supports paging and provides methods to iterate through
-  # the pages using {#first}, {#next}, {#first?}, {#has_next?} and {#last?}
+  # the pages using {#first}, {#next}, {#has_next?} and {#last?}
   #
   # All items in the HTTP response are available in the Array returned from {#items}
   #
@@ -68,14 +68,6 @@ module Ably::Models
         pagination_header('next').nil?
     end
 
-    # True if this is the first page in the paged resource set
-    #
-    # @return [Boolean]
-    def first?
-      !supports_pagination? ||
-        pagination_header('first') == pagination_header('current')
-    end
-
     # True if there is a subsequent page in this paginated set available with {#next}
     #
     # @return [Boolean]
@@ -94,8 +86,7 @@ module Ably::Models
       <<-EOF.gsub(/^        /, '')
         #<#{self.class.name}:#{self.object_id}
          @base_url="#{base_url}",
-         @first?=#{!!first?},
-         @last?=#{!!first?},
+         @last?=#{!!last?},
          @has_next?=#{!!has_next?},
          @items=
            #{items.map { |item| item.inspect }.join(",\n           ") }
@@ -132,7 +123,7 @@ module Ably::Models
     end
 
     def pagination_url(id)
-      raise Ably::Exceptions::InvalidPageError, "Paging header link #{id} does not exist" unless pagination_header(id)
+      raise Ably::Exceptions::PageMissing, "Paging header link #{id} does not exist" unless pagination_header(id)
 
       if pagination_header(id).match(%r{^\./})
         "#{base_url}#{pagination_header(id)[2..-1]}"

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

@@ -109,12 +109,18 @@ module Ably::Models
     def as_json(*args)
       hash.dup.tap do |presence_message|
         presence_message['action'] = action.to_i
-        decode_binary_data_before_to_json presence_message
-      end.as_json
+      end.as_json.reject { |key, val| val.nil? }
     rescue KeyError
       raise KeyError, ':action is missing or invalid, cannot generate a valid Hash for ProtocolMessage'
     end
 
+    def to_json(*args)
+      as_json(*args).tap do |presence_message|
+        decode_binary_data_before_to_json presence_message
+      end.to_json
+    end
+
+
     # Assign this presence message to a ProtocolMessage before delivery to the Ably system
     # @api private
     def assign_to_protocol_message(protocol_message)

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

@@ -27,9 +27,9 @@ module Ably::Models
   # @!attribute [r] timestamp
   #   @return [Time] An optional timestamp, applied by the service in messages sent to the client, to indicate the system time at which the message was sent (milliseconds past epoch)
   # @!attribute [r] messages
-  #   @return [Message] A {ProtocolMessage} with a `:message` action contains one or more messages belonging to a channel
+  #   @return [Array<Message>] A {ProtocolMessage} with a `:message` action contains one or more messages belonging to the channel
   # @!attribute [r] presence
-  #   @return [PresenceMessage] A {ProtocolMessage} with a `:presence` action contains one or more presence updates belonging to a channel
+  #   @return [Array<PresenceMessage>] A {ProtocolMessage} with a `:presence` action contains one or more presence updates belonging to the channel
   # @!attribute [r] flags
   #   @return [Integer] Flags indicating special ProtocolMessage states
   # @!attribute [r] hash
@@ -37,6 +37,7 @@ module Ably::Models
   #
   class ProtocolMessage
     include Ably::Modules::ModelCommon
+    include Ably::Modules::Encodeable
     include Ably::Modules::SafeDeferrable if defined?(Ably::Realtime)
     extend Ably::Modules::Enum
 
@@ -203,7 +204,18 @@ module Ably::Models
     end
 
     def to_s
-      to_json
+      json_hash = as_json
+
+      # Decode any binary data to before converting to a JSON string representation
+      %w(messages presence).each do |message_type|
+        if json_hash[message_type] && !json_hash[message_type].empty?
+          json_hash[message_type].each do |message|
+            decode_binary_data_before_to_json message
+          end
+        end
+      end
+
+      json_hash.to_json
     end
 
     # True if the ProtocolMessage appears to be invalid, however this is not a guarantee

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

@@ -191,7 +191,7 @@ module Ably::Models
     end
 
     def as_json(*args)
-      hash.as_json(*args)
+      hash.as_json(*args).reject { |key, val| val.nil? }
     end
 
     private

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

@@ -25,7 +25,7 @@ module Ably::Models
 
     # 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
+    TOKEN_EXPIRY_BUFFER = 15
 
     def initialize(attributes)
       @hash_object = IdiomaticRubyWrapper(attributes.clone.freeze)

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

@@ -18,7 +18,13 @@ module Ably::Modules
     # @return [Channel]
     #
     def get(name, channel_options = {})
-      channels[name] ||= channel_klass.new(client, name, channel_options)
+      if channels.has_key?(name)
+        channels[name].tap do |channel|
+          channel.update_options channel_options if channel_options && !channel_options.empty?
+        end
+      else
+        channels[name] ||= channel_klass.new(client, name, channel_options)
+      end
     end
     alias_method :[], :get
 

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

@@ -109,7 +109,7 @@ module Ably::Modules
         payload.kind_of?(Array) ||
         payload.nil?
 
-      raise Ably::Exceptions::UnsupportedDataTypeError.new('Invalid data payload', 400, 40011)
+      raise Ably::Exceptions::UnsupportedDataType.new('Invalid data payload', 400, 40011)
     end
   end
 end

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

@@ -35,9 +35,12 @@ module Ably::Modules
 
     private
     def decode_binary_data_before_to_json(message)
-      if message[:data].kind_of?(String) && message[:data].encoding == ::Encoding::ASCII_8BIT
-        message[:data] = ::Base64.encode64(message[:data])
-        message[:encoding] = [message[:encoding], 'base64'].compact.join('/')
+      data_key = message[:data] ? :data : 'data'
+      encoding_key = message[:encoding] ? :encoding : 'encoding'
+
+      if message[data_key].kind_of?(String) && message[data_key].encoding == ::Encoding::ASCII_8BIT
+        message[data_key] = ::Base64.encode64(message[data_key])
+        message[encoding_key] = [message[encoding_key], 'base64'].compact.join('/')
       end
     end
 

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

@@ -7,8 +7,8 @@ module Ably::Modules
   module MessagePack
     # Generate a packed MsgPack version of this object based on the JSON representation.
     # Keys thus use mixedCase syntax as expected by the Realtime API
-    def to_msgpack(*args)
-      as_json(*args).to_msgpack
+    def to_msgpack(pk = nil)
+      as_json.to_msgpack(pk)
     end
   end
 end

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

@@ -22,7 +22,7 @@ module Ably::Modules
 
     # Return a JSON ready object from the underlying #hash using Ably naming conventions for keys
     def as_json
-      hash.as_json.dup
+      hash.as_json.reject { |key, val| val.nil? }
     end
 
     # Stringify the JSON representation of this object from the underlying #hash

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

@@ -40,10 +40,10 @@ module Ably::Modules
       previous_transition.to_state if previous_transition
     end
 
-    # @return [Ably::Exceptions::StateChangeError]
+    # @return [Ably::Exceptions::InvalidStateChange]
     def exception_for_state_change_to(state)
       error_message = "#{self.class}: Unable to transition from #{current_state} => #{state}"
-      Ably::Exceptions::StateChangeError.new(error_message, nil, 80020)
+      Ably::Exceptions::InvalidStateChange.new(error_message, nil, 80020)
     end
 
     module ClassMethods

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

@@ -3,6 +3,7 @@ require 'websocket/driver'
 
 require 'ably/modules/event_emitter'
 
+require 'ably/realtime/auth'
 require 'ably/realtime/channel'
 require 'ably/realtime/channels'
 require 'ably/realtime/client'

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

@@ -0,0 +1,191 @@
+require 'ably/auth'
+
+module Ably
+  module Realtime
+    # Auth is responsible for authentication with {https://www.ably.io Ably} using basic or token authentication
+    # This {Ably::Realtime::Auth Realtime::Auth} class wraps the {Ably::Auth Synchronous Ably::Auth} class in an EventMachine friendly way using Deferrables for all IO.  See {Ably::Auth Ably::Auth} for more information
+    #
+    # Find out more about Ably authentication at: https://www.ably.io/documentation/general/authentication/
+    #
+    # @!attribute [r] client_id
+    #   (see Ably::Auth#client_id)
+    # @!attribute [r] current_token_details
+    #   (see Ably::Auth#current_token_details)
+    # @!attribute [r] token
+    #   (see Ably::Auth#token)
+    # @!attribute [r] key
+    #   (see Ably::Auth#key)
+    # @!attribute [r] key_name
+    #   (see Ably::Auth#key_name)
+    # @!attribute [r] key_secret
+    #   (see Ably::Auth#key_secret)
+    # @!attribute [r] options
+    #   (see Ably::Auth#options)
+    # @!attribute [r] token_params
+    #   (see Ably::Auth#options)
+    # @!attribute [r] using_basic_auth?
+    #   (see Ably::Auth#using_basic_auth?)
+    # @!attribute [r] using_token_auth?
+    #   (see Ably::Auth#using_token_auth?)
+    # @!attribute [r] token_renewable?
+    #   (see Ably::Auth#token_renewable?)
+    # @!attribute [r] authentication_security_requirements_met?
+    #   (see Ably::Auth#authentication_security_requirements_met?)
+    #
+    class Auth
+      extend Forwardable
+      include Ably::Modules::AsyncWrapper
+
+      def_delegators :auth_sync, :client_id
+      def_delegators :auth_sync, :current_token_details, :token
+      def_delegators :auth_sync, :key, :key_name, :key_secret, :options, :auth_options, :token_params
+      def_delegators :auth_sync, :using_basic_auth?, :using_token_auth?
+      def_delegators :auth_sync, :token_renewable?, :authentication_security_requirements_met?
+      def_delegators :client, :logger
+
+      def initialize(client)
+        @client = client
+        @auth_sync = client.rest_client.auth
+      end
+
+      # Ensures valid auth credentials are present for the library instance. This may rely on an already-known and valid token, and will obtain a new token if necessary.
+      #
+      # In the event that a new token request is made, the provided options are used
+      #
+      # @param (see Ably::Auth#authorise)
+      # @option (see Ably::Auth#authorise)
+      #
+      # @return [Ably::Util::SafeDeferrable]
+      # @yield [Ably::Models::TokenDetails]
+      #
+      # @example
+      #    # will issue a simple token request using basic auth
+      #    client = Ably::Rest::Client.new(key: 'key.id:secret')
+      #    client.auth.authorise do |token_details|
+      #      token_details #=> Ably::Models::TokenDetails
+      #    end
+      #
+      def authorise(auth_options = {}, token_params = {}, &success_callback)
+        async_wrap(success_callback) do
+          auth_sync.authorise(auth_options, token_params)
+        end
+      end
+
+      # Synchronous version of {#authorise}. See {Ably::Auth#authorise} for method definition
+      # @param (see Ably::Auth#authorise)
+      # @option (see Ably::Auth#authorise)
+      # @return [Ably::Models::TokenDetails]
+      #
+      def authorise_sync(auth_options = {}, token_params = {})
+        auth_sync.authorise(auth_options, token_params)
+      end
+
+      # def_delegator :auth_sync, :request_token, :request_token_sync
+      # def_delegator :auth_sync, :create_token_request, :create_token_request_sync
+      # def_delegator :auth_sync, :auth_header, :auth_header_sync
+      # def_delegator :auth_sync, :auth_params, :auth_params_sync
+
+      # Request a {Ably::Models::TokenDetails} which can be used to make authenticated token based requests
+      #
+      # @param (see Ably::Auth#request_token)
+      # @option (see Ably::Auth#request_token)
+      #
+      # @return [Ably::Util::SafeDeferrable]
+      # @yield [Ably::Models::TokenDetails]
+      #
+      # @example
+      #    # simple token request using basic auth
+      #    client = Ably::Rest::Client.new(key: 'key.id:secret')
+      #    client.auth.request_token do |token_details|
+      #      token_details #=> Ably::Models::TokenDetails
+      #    end
+      #
+      def request_token(auth_options = {}, token_params = {}, &success_callback)
+        async_wrap(success_callback) do
+          request_token_sync(auth_options, token_params)
+        end
+      end
+
+      # Synchronous version of {#request_token}. See {Ably::Auth#request_token} for method definition
+      # @param (see Ably::Auth#authorise)
+      # @option (see Ably::Auth#authorise)
+      # @return [Ably::Models::TokenDetails]
+      #
+      def request_token_sync(auth_options = {}, token_params = {})
+        auth_sync.request_token(auth_options, token_params)
+      end
+
+      # Creates and signs a token request that can then subsequently be used by any client to request a token
+      #
+      # @param (see Ably::Auth#create_token_request)
+      # @option (see Ably::Auth#create_token_request)
+      #
+      # @return [Ably::Util::SafeDeferrable]
+      # @yield [Models::TokenRequest]
+      #
+      # @example
+      #   client.auth.create_token_request(id: 'asd.asd', ttl: 3600) do |token_request|
+      #     token_request #=> Ably::Models::TokenRequest
+      #   end
+      def create_token_request(auth_options = {}, token_params = {}, &success_callback)
+        async_wrap(success_callback) do
+          create_token_request_sync(auth_options, token_params)
+        end
+      end
+
+      # Synchronous version of {#create_token_request}. See {Ably::Auth#create_token_request} for method definition
+      # @param (see Ably::Auth#authorise)
+      # @option (see Ably::Auth#authorise)
+      # @return [Ably::Models::TokenRequest]
+      #
+      def create_token_request_sync(auth_options = {}, token_params = {})
+        auth_sync.create_token_request(auth_options, token_params)
+      end
+
+      # Auth header string used in HTTP requests to Ably
+      # Will reauthorise implicitly if required and capable
+      #
+      # @return [Ably::Util::SafeDeferrable]
+      # @yield [String] HTTP authentication value used in HTTP_AUTHORIZATION header
+      #
+      def auth_header(&success_callback)
+        async_wrap(success_callback) do
+          auth_header_sync
+        end
+      end
+
+      # Synchronous version of {#auth_header}. See {Ably::Auth#auth_header} for method definition
+      # @return [String] HTTP authentication value used in HTTP_AUTHORIZATION header
+      #
+      def auth_header_sync
+        auth_sync.auth_header
+      end
+
+      # Auth params used in URI endpoint for Realtime connections
+      # Will reauthorise implicitly if required and capable
+      #
+      # @return [Ably::Util::SafeDeferrable]
+      # @yield [Hash] Auth params for a new Realtime connection
+      #
+      def auth_params(&success_callback)
+        async_wrap(success_callback) do
+          auth_params_sync
+        end
+      end
+
+      # Synchronous version of {#auth_params}. See {Ably::Auth#auth_params} for method definition
+      # @return [Hash] Auth params for a new Realtime connection
+      #
+      def auth_params_sync
+        auth_sync.auth_params
+      end
+
+      private
+      # The synchronous Auth class instanced by the Rest client
+      # @return [Ably::Auth]
+      attr_reader :auth_sync
+
+      attr_reader :client
+    end
+  end
+end

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

@@ -87,9 +87,9 @@ module Ably
       def initialize(client, name, channel_options = {})
         ensure_utf_8 :name, name
 
+        update_options channel_options
         @client        = client
         @name          = name
-        @options       = channel_options.clone.freeze
         @queue         = []
 
         @state_machine = ChannelStateMachine.new(self)
@@ -100,17 +100,33 @@ module Ably
         setup_presence
       end
 
-      # Publish a message on the channel.
+      # Publish one or more messages to 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
+      # @param name [String, Array<Ably::Models::Message|Hash>, nil]   The event name of the message to publish, or an Array of [Ably::Model::Message] objects or [Hash] objects with +:name+ and +:data+ pairs
+      # @param data [String, ByteArray, nil]   The message payload unless an Array of [Ably::Model::Message] objects passed in the first argument
+      #
+      # @yield [Ably::Models::Message,Array<Ably::Models::Message>] On success, will call the block with the {Ably::Models::Message} if a single message is publishde, or an Array of {Ably::Models::Message} when multiple messages are published
+      # @return [Ably::Util::SafeDeferrable] Deferrable that supports both success (callback) and failure (errback) callbacks
       #
       # @example
-      #   channel.publish('click', 'body')
+      #   # Publish a single message
+      #   channel.publish 'click', { x: 1, y: 2 }
+      #
+      #   # Publish an array of message Hashes
+      #   messages = [
+      #     { name: 'click', { x: 1, y: 2 } },
+      #     { name: 'click', { x: 2, y: 3 } }
+      #   ]
+      #   channel.publish messages
+      #
+      #   # Publish an array of Ably::Models::Message objects
+      #   messages = [
+      #     Ably::Models::Message(name: 'click', { x: 1, y: 2 })
+      #     Ably::Models::Message(name: 'click', { x: 2, y: 3 })
+      #   ]
+      #   channel.publish messages
       #
       #   channel.publish('click', 'body') do |message|
       #     puts "#{message.name} event received with #{message.data}"
@@ -120,13 +136,24 @@ module Ably
       #     puts "#{message.name} was not received, error #{error.message}"
       #   end
       #
-      def publish(name, data, &success_block)
-        ensure_utf_8 :name, name
-        ensure_supported_payload data
+      def publish(name, data = nil, &success_block)
+        raise Ably::Exceptions::ChannelInactive.new('Cannot publish messages on a detached channel') if detached? || detaching?
+        raise Ably::Exceptions::ChannelInactive.new('Cannot publish messages on a failed channel') if failed?
 
-        create_message(name, data).tap do |message|
-          message.callback(&success_block) if block_given?
-          queue_message message
+        if !connection.can_publish_messages?
+          raise Ably::Exceptions::MessageQueueingDisabled.new("Message cannot be published. Client is configured to disallow queueing of messages and connection is currently #{connection.state}")
+        end
+
+        messages = if name.kind_of?(Enumerable)
+          name
+        else
+          ensure_utf_8 :name, name, allow_nil: true
+          ensure_supported_payload data
+          [{ name: name, data: data }]
+        end
+
+        queue_messages(messages).tap do |deferrable|
+          deferrable.callback &success_block if block_given?
         end
       end
 
@@ -163,6 +190,8 @@ module Ably
       # @return [Ably::Util::SafeDeferrable] Deferrable that supports both success (callback) and failure (errback) callback
       #
       def attach(&success_block)
+        raise Ably::Exceptions::InvalidStateChange.new("Cannot ATTACH channel when the connection is in a closed, suspended or failed state. Connection state: #{connection.state}") if connection.closing? || connection.closed? || connection.suspended? || connection.failed?
+
         transition_state_machine :attaching if can_transition_to?(:attaching)
         deferrable_for_state_change_to(STATE.Attached, &success_block)
       end
@@ -170,10 +199,18 @@ module Ably
       # Detach this channel, and call the block if provided when in a Detached or Failed state
       #
       # @yield [Ably::Realtime::Channel] Block is called as soon as this channel is in the Detached or Failed state
-      # @return [void]
+      # @return [Ably::Util::SafeDeferrable] Deferrable that supports both success (callback) and failure (errback) callback
       #
       def detach(&success_block)
-        raise exception_for_state_change_to(:detaching) if failed? || initialized?
+        if initialized?
+          success_block.call if block_given?
+          return Ably::Util::SafeDeferrable.new(logger).tap do |deferrable|
+            EventMachine.next_tick { deferrable.succeed }
+          end
+        end
+
+        raise exception_for_state_change_to(:detaching) if failed?
+
         transition_state_machine :detaching if can_transition_to?(:detaching)
         deferrable_for_state_change_to(STATE.Detached, &success_block)
       end
@@ -237,6 +274,11 @@ module Ably
         @attached_serial = serial
       end
 
+      # @api private
+      def update_options(channel_options)
+        @options = channel_options.clone.freeze
+      end
+
       # Used by {Ably::Modules::StateEmitter} to debug state changes
       # @api private
       def logger
@@ -257,16 +299,50 @@ module Ably
         end
       end
 
-      # Queue message and process queue if channel is attached.
+      # Queue messages and process queue if channel is attached.
       # If channel is not yet attached, attempt to attach it before the message queue is processed.
-      def queue_message(message)
-        queue << message
+      # @returns [Ably::Util::SafeDeferrable]
+      def queue_messages(raw_messages)
+        messages = Array(raw_messages).map { |msg| create_message(msg) }
+        queue.push *messages
 
         if attached?
           process_queue
         else
           attach
         end
+
+        if messages.count == 1
+          # A message is a Deferrable so, if publishing only one message, simply return that Deferrable
+          messages.first
+        else
+          deferrable_for_multiple_messages(messages)
+        end
+      end
+
+      # A deferrable object that calls the success callback once all messages are delivered
+      # If any message fails, the errback is called immediately
+      # Only one callback or errback is ever called i.e. if a group of messages all fail, only once
+      # errback will be invoked
+      def deferrable_for_multiple_messages(messages)
+        expected_deliveries = messages.count
+        actual_deliveries = 0
+        failed = false
+
+        Ably::Util::SafeDeferrable.new(logger).tap do |deferrable|
+          messages.each do |message|
+            message.callback do
+              return if failed
+              actual_deliveries += 1
+              deferrable.succeed messages if actual_deliveries == expected_deliveries
+            end
+            message.errback do |error|
+              return if failed
+              failed = true
+              deferrable.fail error, message
+            end
+          end
+        end
       end
 
       def messages_in_queue?
@@ -282,19 +358,15 @@ module Ably
       end
 
       def send_messages_within_protocol_message(messages)
-        client.connection.send_protocol_message(
+        connection.send_protocol_message(
           action:   Ably::Models::ProtocolMessage::ACTION.Message.to_i,
           channel:  name,
           messages: messages
         )
       end
 
-      def create_message(name, data)
-        message = { name: name }
-        message.merge!(data: data) unless data.nil?
-        message.merge!(clientId: client.client_id) if client.client_id
-
-        Ably::Models::Message.new(message, logger: logger).tap do |message|
+      def create_message(message)
+        Ably::Models::Message(message.dup).tap do |message|
           message.encode self
         end
       end