ably-pubsub-core 0.0.1.pre

data/lib/ably/rest/push/device_registrations.rb

@@ -0,0 +1,114 @@
+module Ably::Rest
+  class Push
+    # Manage device registrations for push notifications
+    class DeviceRegistrations
+      include Ably::Modules::Conversions
+
+      # @api private
+      attr_reader :client
+
+      # @api private
+      attr_reader :admin
+
+      def initialize(admin)
+        @admin = admin
+        @client = admin.client
+      end
+
+      # Get registered device by device ID
+      #
+      # @spec RSH1b1
+      #
+      # @param [String, Ably::Models::DeviceDetails] device_id   the device to retrieve
+      #
+      # @return [Ably::Models::DeviceDetails]  Returns {Ably::Models::DeviceDetails} if a match is found else a {Ably::Exceptions::ResourceMissing} is raised
+      #
+      def get(device_id)
+        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)
+
+        DeviceDetails(client.get("/push/deviceRegistrations/#{device_id}").body)
+      end
+
+      # List registered devices filtered by optional params
+      #
+      # @spec RSH1b2
+      #
+      # @param [Hash] params   the filter options for the list registered device request
+      # @option params [String]   :client_id  filter by devices registered to a client identifier. Cannot be used with +device_id+ param
+      # @option params [String]   :device_id  filter by unique device ID. Cannot be used with +client_id+ param
+      # @option params [Integer]  :limit      maximum number of devices to retrieve up to 1,000, defaults to 100
+      #
+      # @return [Ably::Models::PaginatedResult<Ably::Models::DeviceDetails>]  Paginated list of matching {Ably::Models::DeviceDetails}
+      #
+      def list(params = {})
+        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]
+
+        params = params.clone
+
+        paginated_options = {
+          coerce_into: 'Ably::Models::DeviceDetails',
+          async_blocking_operations: params.delete(:async_blocking_operations),
+        }
+
+        response = client.get('/push/deviceRegistrations', IdiomaticRubyWrapper(params).as_json)
+
+        Ably::Models::PaginatedResult.new(response, '', client, paginated_options)
+      end
+
+      # Registers or updates a {Ably::Models::DeviceDetails} object with Ably.
+      # Returns the new, or updated {Ably::Models::DeviceDetails} object.
+      #
+      # @spec RSH1b3
+      #
+      # @param [Ably::Models::DeviceDetails, Hash]  device   the device details to save
+      #
+      # @return [void]
+      #
+      def save(device)
+        device_details = DeviceDetails(device)
+        raise ArgumentError, "Device ID is required yet is empty" if device_details.id.nil? || device_details == ''
+
+        client.put("/push/deviceRegistrations/#{device_details.id}", device_details.as_json)
+      end
+
+      # Remove device
+      #
+      # @spec RSH1b4
+      #
+      # @param [String, Ably::Models::DeviceDetails]  device_id  the device to remove
+      #
+      # @return [void]
+      #
+      def remove(device_id)
+        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)
+
+        client.delete("/push/deviceRegistrations/#{device_id}", {})
+      end
+
+      # Removes all devices registered to receive push notifications from Ably matching the filter params provided.
+      #
+      # @spec RSH1b5
+      #
+      # @param [Hash] params   the filter params for the remove request
+      # @option params [String]   :client_id  remove devices registered to a client identifier. Cannot be used with +device_id+ param
+      # @option params [String]   :device_id  remove device with this unique device ID. Cannot be used with +client_id+ param
+      #
+      # @return [void]
+      #
+      def remove_where(params = {})
+        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
+        client.delete("/push/deviceRegistrations", filter)
+      end
+    end
+  end
+end

data/lib/ably/rest/push.rb

@@ -0,0 +1,25 @@
+require 'ably/rest/push/admin'
+
+module Ably
+  module Rest
+    # Class providing push notification functionality
+    class Push
+      include Ably::Modules::Conversions
+
+      # @private
+      attr_reader :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      # Admin features for push notifications like managing devices and channel subscriptions
+      #
+      # @return [Ably::Rest::Push::Admin]
+      #
+      def admin
+        @admin ||= Admin.new(self)
+      end
+    end
+  end
+end

data/lib/ably/rest.rb

@@ -0,0 +1,40 @@
+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'
+
+Dir.glob(File.expand_path("models/*.rb", File.dirname(__FILE__))).each do |file|
+  require file
+end
+
+module Ably
+  # Rest provides the top-level class to be instanced for the Ably Rest library
+  #
+  # @example
+  #   client = Ably::Rest.new("xxxxx")
+  #   channel = client.channel("test")
+  #   channel.publish "greeting", "data"
+  #
+  module Rest
+    # Convenience method providing an alias to {Ably::Rest::Client} constructor.
+    #
+    # @param (see Ably::Rest::Client#initialize)
+    # @option options (see Ably::Rest::Client#initialize)
+    #
+    # @return [Ably::Rest::Client]
+    #
+    # @example
+    #    # create a new client authenticating with basic auth
+    #    client = Ably::Rest.new('key.id:secret')
+    #
+    #    # create a new client authenticating with basic auth and a client_id
+    #    client = Ably::Rest.new(key: 'key.id:secret', client_id: 'john')
+    #
+    def self.new(options)
+      Ably::Rest::Client.new(options)
+    end
+  end
+end

data/lib/ably/util/ably_extensions.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Ably::Util
+  module AblyExtensions
+    refine Object do
+      def nil_or_empty?
+        self.nil? || self.empty?
+      end
+    end
+
+    refine Hash do
+      def fetch_with_default(key, default)
+        value = self.fetch(key, default)
+        if value.nil?
+          return default
+        end
+        return value
+      end
+
+      def delete_with_default(key, default)
+        value = self.delete(key)
+        if value.nil?
+          return default
+        end
+        return value
+      end
+    end
+  end
+end

data/lib/ably/util/crypto.rb

@@ -0,0 +1,134 @@
+require 'msgpack'
+require 'openssl'
+
+module Ably::Util
+  # Contains the properties required to configure the encryption of {Ably::Models::Message} payloads.
+  #
+  class Crypto
+    DEFAULTS = {
+      algorithm: 'aes',
+      mode: 'cbc',
+      key_length: 256,
+    }
+
+    BLOCK_LENGTH = 16
+
+    # Configured {Ably::Models::CipherParams} for this Crypto object, see {#initialize} for a list of configureable options
+    #
+    # @return [Ably::Models::CipherParams]
+    #
+    attr_reader :cipher_params
+
+    # Creates a {Ably::Util::Crypto} object
+    #
+    # @param [Hash] params a Hash used to configure the Crypto library's {Ably::Models::CipherParams}
+    # @option params (see Ably::Models::CipherParams#initialize)
+    #
+    # @return [Ably::Util::Crypto]
+    #
+    # @example
+    #    key = Ably::Util::Crypto.generate_random_key
+    #    crypto = Ably::Util::Crypto.new(key: key)
+    #    encrypted = crypto.encrypt('secret text')
+    #    crypto.decrypt(decrypted) # => 'secret text'
+    #
+    def initialize(params)
+      @fixed_iv = params[:fixed_iv]
+      @cipher_params = Ably::Models::CipherParams(params)
+    end
+
+    # Returns a {Ably::Models::CipherParams} object, using the default values for any fields not supplied by the `Hash` object.
+    #
+    # @spec RSE1, RSE1b, RSE1b
+    #
+    # @param [Hash]  params  a Hash used to configure the Crypto library's {Ably::Models::CipherParams}
+    # @option params  (see {Ably::Models::CipherParams#initialize})
+    #
+    # @return [Ably::Models::CipherParams]   Configured cipher params with :key, :algorithm, :mode, :key_length attributes
+    #
+    def self.get_default_params(params = {})
+      Ably::Models::CipherParams(params)
+    end
+
+    # Generates a random key to be used in the encryption of the channel. If the language cryptographic randomness
+    # primitives are blocking or async, a callback is used. The callback returns a generated binary key.
+    #
+    # @spec RSE2, RSE2a, RSE2b
+    #
+    # @param  [Integer]  key_length  The length of the key, in bits, to be generated. If not specified, this is equal to the default keyLength of the default algorithm: for AES this is 256 bits.
+    # @return   Binary   The key as a binary, for example, a byte array.
+    #
+    def self.generate_random_key(key_length = DEFAULTS.fetch(:key_length))
+      params = DEFAULTS.merge(key_length: key_length)
+      OpenSSL::Cipher.new(cipher_type(params)).random_key
+    end
+
+    # The Cipher algorithm string such as AES-128-CBC
+    # @api private
+    def self.cipher_type(options)
+      Ably::Models::CipherParams.cipher_type(options)
+    end
+
+    # Encrypt payload using configured Cipher
+    #
+    # @param [String] payload           the payload to be encrypted
+    # @param [Hash]   encrypt_options   an options Hash to configure the encrypt action
+    # @option encrypt_options [String]  :iv optionally use the provided Initialization Vector instead of a randomly generated IV
+    #
+    # @return [String] binary string with +Encoding::ASCII_8BIT+ encoding
+    #
+    def encrypt(payload, encrypt_options = {})
+      cipher = openssl_cipher
+      cipher.encrypt
+      cipher.key = key
+      iv = encrypt_options[:iv] || fixed_iv || cipher.random_iv
+      cipher.iv = iv
+      iv << cipher.update(payload) unless payload.empty?
+      iv << cipher.final
+    end
+
+    # Decrypt payload using configured Cipher
+    #
+    # @param [String] encrypted_payload_with_iv  the encrypted payload to be decrypted
+    #
+    # @return [String]
+    #
+    def decrypt(encrypted_payload_with_iv)
+      raise Ably::Exceptions::CipherError, 'iv is missing or not long enough' unless encrypted_payload_with_iv.length >= BLOCK_LENGTH*2
+
+      iv = encrypted_payload_with_iv.slice(0...BLOCK_LENGTH)
+      encrypted_payload = encrypted_payload_with_iv.slice(BLOCK_LENGTH..-1)
+
+      decipher = openssl_cipher
+      decipher.decrypt
+      decipher.key = key
+      decipher.iv = iv
+
+      decipher.update(encrypted_payload) << decipher.final
+    end
+
+    # Generate a random IV
+    # @return [String]
+    def random_iv
+      openssl_cipher.random_iv
+    end
+
+    private
+    # Used solely for tests to fix the IV instead of randomly generate one
+    attr_reader :fixed_iv
+
+    # Generate a random key
+    # @return [String]
+    def random_key
+      openssl_cipher.random_key
+    end
+
+    def key
+      cipher_params.key
+    end
+
+    def openssl_cipher
+      @openssl_cipher ||= OpenSSL::Cipher.new(cipher_params.cipher_type)
+    end
+  end
+end

data/lib/ably/util/pub_sub.rb

@@ -0,0 +1,45 @@
+require 'ably/modules/event_emitter.rb'
+
+module Ably::Util
+  # PubSub class provides methods to publish & subscribe to events, with methods and naming
+  # intentionally different to EventEmitter as it is intended for private message handling
+  # within the client library.
+  #
+  # @example
+  #   class Channel
+  #     def messages
+  #       @messages ||= PubSub.new
+  #     end
+  #   end
+  #
+  #   channel = Channel.new
+  #   channel.messages.subscribe(:event) { |name| puts "Event message #{name} received" }
+  #   channel.messages.publish :event, "Test"
+  #   #=> "Event message Test received"
+  #   channel.messages.remove :event
+  #
+  class PubSub
+    include Ably::Modules::EventEmitter
+
+    # Ensure new PubSub object does not share class instance variables
+    def self.new(options = {})
+      Class.new(PubSub).allocate.tap do |pub_sub_object|
+        pub_sub_object.send(:initialize, options)
+      end
+    end
+
+    def inspect
+      "<#PubSub: @event_emitter_coerce_proc: #{self.class.event_emitter_coerce_proc.inspect}\n @callbacks: #{callbacks}>"
+    end
+
+    def initialize(options = {})
+      self.class.instance_eval do
+        configure_event_emitter options
+
+        alias_method :subscribe, :unsafe_on
+        alias_method :publish, :emit
+        alias_method :unsubscribe, :unsafe_off
+      end
+    end
+  end
+end

data/lib/ably/util/safe_deferrable.rb

@@ -0,0 +1,44 @@
+module Ably::Util
+  # SafeDeferrable class provides a Deferrable that is safe to use for for public interfaces
+  # of this client library. Any exceptions raised in the success or failure callbacks are
+  # caught and logged to the provided logger.
+  #
+  # An exception in a callback provided by a developer should not break this client library
+  # and stop further execution of code.
+  #
+  class SafeDeferrable
+    include Ably::Modules::SafeDeferrable
+
+    attr_reader :logger
+
+    def initialize(logger)
+      @logger = logger
+    end
+
+    # Create a new {SafeDeferrable} and fail immediately with the provided error in the next eventloop cycle
+    #
+    # @param error [Ably::Exceptions::BaseAblyException, Ably::Models::ErrorInfo]   The error used to fail the newly created {SafeDeferrable}
+    #
+    # @return [SafeDeferrable]
+    #
+    def self.new_and_fail_immediately(logger, error)
+      new(logger).tap do |deferrable|
+        EventMachine.next_tick do
+          deferrable.fail error
+        end
+      end
+    end
+
+    # Create a new {SafeDeferrable} and succeed immediately with the provided arguments in the next eventloop cycle
+    #
+    # @return [SafeDeferrable]
+    #
+    def self.new_and_succeed_immediately(logger, *args)
+      new(logger).tap do |deferrable|
+        EventMachine.next_tick do
+          deferrable.succeed *args
+        end
+      end
+    end
+  end
+end

data/lib/ably/version.rb

@@ -0,0 +1,7 @@
+module Ably
+  VERSION = '0.0.1.pre'
+  # The level of compatibility with the Ably service that this SDK supports.
+  # Also referred to as the 'wire protocol version'.
+  # spec : CSV2
+  PROTOCOL_VERSION = '2'
+end

data/lib/ably.rb

@@ -0,0 +1,16 @@
+require 'addressable/uri'
+
+require 'ably/version'
+require 'ably/agent'
+
+%w(modules util).each do |namespace|
+  Dir.glob(File.expand_path("ably/#{namespace}/*.rb", File.dirname(__FILE__))).sort.each do |file|
+    require file
+  end
+end
+
+require 'ably/auth'
+require 'ably/exceptions'
+require 'ably/logger'
+require 'ably/realtime'
+require 'ably/rest'