ably 1.0.7 → 1.1.0

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

data/lib/ably/rest/channel/push_channel.rb

@@ -0,0 +1,62 @@
+module Ably::Rest
+  class Channel
+    # A push channel used for push notifications
+    # Each PushChannel maps to exactly one Rest Channel
+    #
+    # @!attribute [r] channel
+    #   @return [Ably::Rest::Channel] Underlying channel object
+    #
+    class PushChannel
+      attr_reader :channel
+
+      def initialize(channel)
+        raise ArgumentError, "Unsupported channel type '#{channel.class}'" unless channel.kind_of?(Ably::Rest::Channel)
+        @channel = channel
+      end
+
+      def to_s
+        "<PushChannel: name=#{channel.name}>"
+      end
+
+      # Subscribe local device for push notifications on this channel
+      #
+      # @note This is unsupported in the Ruby library
+      def subscribe_device(*args)
+        raise_unsupported
+      end
+
+      # Subscribe all devices registered to this client's authenticated client_id for push notifications on this channel
+      #
+      # @note This is unsupported in the Ruby library
+      def subscribe_client_id(*args)
+        raise_unsupported
+      end
+
+      # Unsubscribe local device for push notifications on this channel
+      #
+      # @note This is unsupported in the Ruby library
+      def unsubscribe_device(*args)
+        raise_unsupported
+      end
+
+      # Unsubscribe all devices registered to this client's authenticated client_id for push notifications on this channel
+      #
+      # @note This is unsupported in the Ruby library
+      def unsubscribe_client_id(*args)
+        raise_unsupported
+      end
+
+      # Get list of subscriptions on this channel for this device or authenticate client_id
+      #
+      # @note This is unsupported in the Ruby library
+      def get_subscriptions(*args)
+        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