ably-rest 1.0.6 → 1.1.0

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

@@ -157,7 +157,7 @@ module Ably::Realtime
           logger.debug { "WebsocketTransport: Prot msg recv <=: #{action_name} - #{event_data}" }
 
           if protocol_message.invalid?
-            error = Ably::Exceptions::ProtocolError.new("Invalid Protocol Message received: #{event_data}\nConnection moving to the failed state as the protocol is invalid and unsupported", 400, 80013)
+            error = Ably::Exceptions::ProtocolError.new("Invalid Protocol Message received: #{event_data}\nConnection moving to the failed state as the protocol is invalid and unsupported", 400, Ably::Exceptions::Codes::PROTOCOL_ERROR)
             logger.fatal { "WebsocketTransport: #{error.message}" }
             failed_protocol_message = Ably::Models::ProtocolMessage.new(
               action: Ably::Models::ProtocolMessage::ACTION.Error,

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

@@ -233,7 +233,7 @@ module Ably::Realtime
           deferrable.fail Ably::Exceptions::InvalidState.new(
             'Presence state is out of sync as channel is SUSPENDED. Presence#get on a SUSPENDED channel is only supported with option wait_for_sync: false',
             nil,
-            91005
+            Ably::Exceptions::Codes::PRESENCE_STATE_IS_OUT_OF_SYNC
           )
         end
         return deferrable
@@ -330,7 +330,7 @@ module Ably::Realtime
     def send_presence_protocol_message(presence_action, client_id, data)
       presence_message = create_presence_message(presence_action, client_id, data)
       unless presence_message.client_id
-        raise Ably::Exceptions::Standard.new('Unable to enter create presence message without a client_id', 400, 91000)
+        raise Ably::Exceptions::Standard.new('Unable to enter create presence message without a client_id', 400, Ably::Exceptions::Codes::UNABLE_TO_ENTER_PRESENCE_CHANNEL_NO_CLIENTID)
       end
 
       protocol_message = {
@@ -437,13 +437,13 @@ module Ably::Realtime
 
     def attach_channel_then(deferrable)
       if channel.detached? || channel.failed?
-        deferrable.fail Ably::Exceptions::InvalidState.new("Operation is not allowed when channel is in #{channel.state}", 400, 91001)
+        deferrable.fail Ably::Exceptions::InvalidState.new("Operation is not allowed when channel is in #{channel.state}", 400, Ably::Exceptions::Codes::UNABLE_TO_ENTER_PRESENCE_CHANNEL_INVALID_CHANNEL_STATE)
       else
         channel.unsafe_once(:attached, :detached, :failed) do |channel_state_change|
           if channel_state_change.current == :attached
             yield
           else
-            deferrable.fail Ably::Exceptions::InvalidState.new("Operation failed as channel transitioned to #{channel_state_change.current}", 400, 91001)
+            deferrable.fail Ably::Exceptions::InvalidState.new("Operation failed as channel transitioned to #{channel_state_change.current}", 400, Ably::Exceptions::Codes::UNABLE_TO_ENTER_PRESENCE_CHANNEL_INVALID_CHANNEL_STATE)
           end
         end
         channel.attach

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

@@ -275,7 +275,7 @@ module Ably::Realtime
             presence_message_client_id = presence_message.client_id || client.auth.client_id
             re_enter_error = Ably::Models::ErrorInfo.new(
               message: "unable to automatically re-enter presence channel for client_id '#{presence_message_client_id}'. Source error code #{error.code} and message '#{error.message}'",
-              code: 91004
+              code: Ably::Exceptions::Codes::UNABLE_TO_AUTOMATICALLY_REENTER_PRESENCE_CHANNEL
             )
             channel.emit :update, Ably::Models::ChannelStateChange.new(
               current: channel.state,
@@ -312,14 +312,14 @@ module Ably::Realtime
         when Ably::Models::PresenceMessage::ACTION.Leave
           remove_presence_member presence_message
         else
-          Ably::Exceptions::ProtocolError.new("Protocol error, unknown presence action #{presence_message.action}", 400, 80013)
+          Ably::Exceptions::ProtocolError.new("Protocol error, unknown presence action #{presence_message.action}", 400, Ably::Exceptions::Codes::PROTOCOL_ERROR)
         end
       end
 
       def ensure_presence_message_is_valid(presence_message)
         return true if presence_message.connection_id
 
-        error = Ably::Exceptions::ProtocolError.new("Protocol error, presence message is missing connectionId", 400, 80013)
+        error = Ably::Exceptions::ProtocolError.new("Protocol error, presence message is missing connectionId", 400, Ably::Exceptions::Codes::PROTOCOL_ERROR)
         logger.error { "PresenceMap: On channel '#{channel.name}' error: #{error}" }
       end
 

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

@@ -0,0 +1,40 @@
+require 'ably/realtime/push/admin'
+
+module Ably
+  module Realtime
+    # Class providing push notification functionality
+    class Push
+      # @private
+      attr_reader :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      # Admin features for push notifications like managing devices and channel subscriptions
+      # @return [Ably::Realtime::Push::Admin]
+      def admin
+        @admin ||= Admin.new(self)
+      end
+
+      # Activate this device for push notifications by registering with the push transport such as GCM/APNS
+      #
+      # @note This is unsupported in the Ruby library
+      def activate(*arg)
+        raise_unsupported
+      end
+
+      # Deactivate this device for push notifications by removing the registration with the push transport such as GCM/APNS
+      #
+      # @note This is unsupported in the Ruby library
+      def deactivate(*arg)
+        raise_unsupported
+      end
+
+      private
+      def raise_unsupported
+        raise Ably::Exceptions::PushNotificationsNotSupported, 'This device does not support receiving or subscribing to push notifications. All PushChannel methods are unavailable'
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+require 'ably/realtime/push/device_registrations'
+require 'ably/realtime/push/channel_subscriptions'
+
+module Ably::Realtime
+  class Push
+    # Class providing push notification administrative functionality
+    # for registering devices and attaching to channels etc.
+    class Admin
+      include Ably::Modules::AsyncWrapper
+      include Ably::Modules::Conversions
+
+      # @api private
+      attr_reader :client
+
+      # @api private
+      attr_reader :push
+
+      def initialize(push)
+        @push = push
+        @client = push.client
+      end
+
+      # (see Ably::Rest::Push#publish)
+      #
+      # @yield  Block is invoked upon successful publish of the message
+      # @return [Ably::Util::SafeDeferrable]
+      #
+      def publish(recipient, data, &callback)
+        raise ArgumentError, "Expecting a Hash object for recipient, got #{recipient.class}" unless recipient.kind_of?(Hash)
+        raise ArgumentError, "Recipient data is empty. You must provide recipient details" if recipient.empty?
+        raise ArgumentError, "Expecting a Hash object for data, got #{data.class}" unless data.kind_of?(Hash)
+        raise ArgumentError, "Push data field is empty. You must provide attributes for the push notification" if data.empty?
+
+        async_wrap(callback) do
+          rest_push_admin.publish(recipient, data)
+        end
+      end
+
+      # Manage device registrations
+      # @return [Ably::Realtime::Push::DeviceRegistrations]
+      def device_registrations
+        @device_registrations ||= DeviceRegistrations.new(self)
+      end
+
+      # Manage channel subscriptions for devices or clients
+      # @return [Ably::Realtime::Push::ChannelSubscriptions]
+      def channel_subscriptions
+        @channel_subscriptions ||= ChannelSubscriptions.new(self)
+      end
+
+      private
+      def rest_push_admin
+        client.rest_client.push.admin
+      end
+
+      def logger
+        client.logger
+      end
+    end
+  end
+end

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

@@ -0,0 +1,108 @@
+module Ably::Realtime
+  class Push
+    # Manage push notification channel subscriptions for devices or clients
+    class ChannelSubscriptions
+      include Ably::Modules::Conversions
+      include Ably::Modules::AsyncWrapper
+
+      # @api private
+      attr_reader :client
+
+      # @api private
+      attr_reader :admin
+
+      def initialize(admin)
+        @admin = admin
+        @client = admin.client
+      end
+
+      # (see Ably::Rest::Push::ChannelSubscriptions#list)
+      #
+      # @yield  Block is invoked when request succeeds
+      # @return [Ably::Util::SafeDeferrable]
+      #
+      def list(params, &callback)
+        raise ArgumentError, "params must be a Hash" unless params.kind_of?(Hash)
+
+        if (IdiomaticRubyWrapper(params).keys & [:channel, :client_id, :device_id]).length == 0
+          raise ArgumentError, "at least one channel, client_id or device_id filter param must be provided"
+        end
+
+        async_wrap(callback) do
+          rest_channel_subscriptions.list(params.merge(async_blocking_operations: true))
+        end
+      end
+
+      # (see Ably::Rest::Push::ChannelSubscriptions#list_channels)
+      #
+      # @yield  Block is invoked when request succeeds
+      # @return [Ably::Util::SafeDeferrable]
+      #
+      def list_channels(params = {}, &callback)
+        params = {} if params.nil?
+        raise ArgumentError, "params must be a Hash" unless params.kind_of?(Hash)
+
+        async_wrap(callback) do
+          rest_channel_subscriptions.list_channels(params.merge(async_blocking_operations: true))
+        end
+      end
+
+      # (see Ably::Rest::Push::ChannelSubscriptions#save)
+      #
+      # @yield  Block is invoked when request succeeds
+      # @return [Ably::Util::SafeDeferrable]
+      #
+      def save(push_channel_subscription, &callback)
+        push_channel_subscription_object = PushChannelSubscription(push_channel_subscription)
+        raise ArgumentError, "Channel is required yet is empty" if push_channel_subscription_object.channel.to_s.empty?
+
+        async_wrap(callback) do
+          rest_channel_subscriptions.save(push_channel_subscription)
+        end
+      end
+
+      # (see Ably::Rest::Push::ChannelSubscriptions#remove)
+      #
+      # @yield  Block is invoked when request succeeds
+      # @return [Ably::Util::SafeDeferrable]
+      #
+      def remove(push_channel_subscription, &callback)
+        push_channel_subscription_object = PushChannelSubscription(push_channel_subscription)
+        raise ArgumentError, "Channel is required yet is empty" if push_channel_subscription_object.channel.to_s.empty?
+        if push_channel_subscription_object.client_id.to_s.empty? && push_channel_subscription_object.device_id.to_s.empty?
+          raise ArgumentError, "Either client_id or device_id must be present"
+        end
+
+        async_wrap(callback) do
+          rest_channel_subscriptions.remove(push_channel_subscription)
+        end
+      end
+
+      # (see Ably::Rest::Push::ChannelSubscriptions#remove_where)
+      #
+      # @yield  Block is invoked when request succeeds
+      # @return [Ably::Util::SafeDeferrable]
+      #
+      def remove_where(params, &callback)
+        raise ArgumentError, "params must be a Hash" unless params.kind_of?(Hash)
+
+        if (IdiomaticRubyWrapper(params).keys & [:channel, :client_id, :device_id]).length == 0
+          raise ArgumentError, "at least one channel, client_id or device_id filter param must be provided"
+        end
+
+        async_wrap(callback) do
+          rest_channel_subscriptions.remove_where(params)
+        end
+      end
+
+      private
+      def rest_channel_subscriptions
+        client.rest_client.push.admin.channel_subscriptions
+      end
+
+      def logger
+        client.logger
+      end
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+module Ably::Realtime
+  class Push
+    # Manage device registrations for push notifications
+    class DeviceRegistrations
+      include Ably::Modules::Conversions
+      include Ably::Modules::AsyncWrapper
+
+      # @api private
+      attr_reader :client
+
+      # @api private
+      attr_reader :admin
+
+      def initialize(admin)
+        @admin = admin
+        @client = admin.client
+      end
+
+      # (see Ably::Rest::Push::DeviceRegistrations#get)
+      #
+      # @yield  Block is invoked when request succeeds
+      # @return [Ably::Util::SafeDeferrable]
+      #
+      def get(device_id, &callback)
+        device_id = device_id.id if device_id.kind_of?(Ably::Models::DeviceDetails)
+        raise ArgumentError, "device_id must be a string or DeviceDetails object" unless device_id.kind_of?(String)
+
+        async_wrap(callback) do
+          rest_device_registrations.get(device_id)
+        end
+      end
+
+      # (see Ably::Rest::Push::DeviceRegistrations#list)
+      #
+      # @yield  Block is invoked when request succeeds
+      # @return [Ably::Util::SafeDeferrable]
+      #
+      def list(params = {}, &callback)
+        params = {} if params.nil?
+        raise ArgumentError, "params must be a Hash" unless params.kind_of?(Hash)
+        raise ArgumentError, "device_id filter cannot be specified alongside a client_id filter. Use one or the other" if params[:client_id] && params[:device_id]
+
+        async_wrap(callback) do
+          rest_device_registrations.list(params.merge(async_blocking_operations: true))
+        end
+      end
+
+      # (see Ably::Rest::Push::DeviceRegistrations#save)
+      #
+      # @yield  Block is invoked when request succeeds
+      # @return [Ably::Util::SafeDeferrable]
+      #
+      def save(device, &callback)
+        device_details = DeviceDetails(device)
+        raise ArgumentError, "Device ID is required yet is empty" if device_details.id.nil? || device_details == ''
+
+        async_wrap(callback) do
+          rest_device_registrations.save(device_details)
+        end
+      end
+
+      # (see Ably::Rest::Push::DeviceRegistrations#remove)
+      #
+      # @yield  Block is invoked when request succeeds
+      # @return [Ably::Util::SafeDeferrable]
+      #
+      def remove(device_id, &callback)
+        device_id = device_id.id if device_id.kind_of?(Ably::Models::DeviceDetails)
+        raise ArgumentError, "device_id must be a string or DeviceDetails object" unless device_id.kind_of?(String)
+
+        async_wrap(callback) do
+          rest_device_registrations.remove(device_id)
+        end
+      end
+
+      # (see Ably::Rest::Push::DeviceRegistrations#remove_where)
+      #
+      # @yield  Block is invoked when request succeeds
+      # @return [Ably::Util::SafeDeferrable]
+      #
+      def remove_where(params = {}, &callback)
+        filter = if params.kind_of?(Ably::Models::DeviceDetails)
+          { 'deviceId' => params.id }
+        else
+          raise ArgumentError, "params must be a Hash" unless params.kind_of?(Hash)
+          raise ArgumentError, "device_id filter cannot be specified alongside a client_id filter. Use one or the other" if params[:client_id] && params[:device_id]
+          IdiomaticRubyWrapper(params).as_json
+        end
+
+        async_wrap(callback) do
+          rest_device_registrations.remove_where(filter)
+        end
+      end
+
+      private
+      def rest_device_registrations
+        client.rest_client.push.admin.device_registrations
+      end
+
+      def logger
+        client.logger
+      end
+    end
+  end
+end

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

@@ -1,6 +1,7 @@
 require 'ably/rest/channel'
 require 'ably/rest/channels'
 require 'ably/rest/client'
+require 'ably/rest/push'
 require 'ably/rest/presence'
 
 require 'ably/models/message_encoders/base'

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

@@ -3,8 +3,6 @@ module Ably
     # The Ably Realtime service organises the traffic within any application into named channels.
     # Channels are the "unit" of message distribution; clients attach to channels to subscribe to messages, and every message broadcast by the service is associated with a unique channel.
     #
-    # @!attribute [r] client
-    #   @return {Ably::Realtime::Client} Ably client associated with this channel
     # @!attribute [r] name
     #   @return {String} channel name
     # @!attribute [r] options
@@ -12,7 +10,19 @@ module Ably
     class Channel
       include Ably::Modules::Conversions
 
-      attr_reader :client, :name, :options
+      # Ably client associated with this channel
+      # @return [Ably::Realtime::Client]
+      # @api private
+      attr_reader :client
+
+      attr_reader :name, :options
+
+      # Push channel used for push notification (client-side)
+      # @return [Ably::Rest::Channel::PushChannel]
+      # @api private
+      attr_reader :push
+
+      IDEMPOTENT_LIBRARY_GENERATED_ID_LENGTH = 9 # See spec RSL1k1
 
       # Initialize a new Channel object
       #
@@ -27,13 +37,14 @@ module Ably
         update_options channel_options
         @client  = client
         @name    = name
+        @push    = PushChannel.new(self)
       end
 
       # Publish one or more messages to the channel.
       #
       # @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
-      # @param attributes [Hash, nil]   Optional additional message attributes such as :client_id or :connection_id, applied when name attribute is nil or a string
+      # @param attributes [Hash, nil]   Optional additional message attributes such as :extras, :id, :client_id or :connection_id, applied when name attribute is nil or a string
       # @return [Boolean]  true if the message was published, otherwise false
       #
       # @example
@@ -58,12 +69,16 @@ module Ably
         messages = if name.kind_of?(Enumerable)
           name
         else
+          if name.kind_of?(Ably::Models::Message)
+            raise ArgumentError, "name argument does not support single Message objects, only arrays of Message objects"
+          end
+
           name = ensure_utf_8(:name, name, allow_nil: true)
           ensure_supported_payload data
           [{ name: name, data: data }.merge(attributes)]
         end
 
-        payload = messages.map do |message|
+        payload = messages.each_with_index.map do |message, index|
           Ably::Models::Message(message.dup).tap do |msg|
             msg.encode client.encoders, options
 
@@ -75,6 +90,17 @@ module Ably
               raise Ably::Exceptions::IncompatibleClientId.new("Cannot publish with client_id '#{msg.client_id}' as it is incompatible with the current configured client_id '#{client.client_id}'")
             end
           end.as_json
+        end.tap do |payload|
+          if client.idempotent_rest_publishing
+            # We cannot mutate for idempotent publishing if one or more messages already has an ID
+            if payload.all? { |msg| !msg['id'] }
+              # Mutate the JSON to support idempotent publishing where a Message.id does not exist
+              idempotent_publish_id = SecureRandom.base64(IDEMPOTENT_LIBRARY_GENERATED_ID_LENGTH)
+              payload.each_with_index do |msg, idx|
+                msg['id'] = "#{idempotent_publish_id}:#{idx}"
+              end
+            end
+          end
         end
 
         response = client.post("#{base_path}/publish", payload.length == 1 ? payload.first : payload)
@@ -141,3 +167,5 @@ module Ably
     end
   end
 end
+
+require 'ably/rest/channel/push_channel'