ably 0.1.6 → 0.2.0

data/lib/ably/models/token.rb

@@ -4,7 +4,7 @@ module Ably::Models
     include Ably::Modules::ModelCommon
 
     DEFAULTS = {
-      capability: { "*" => ["*"] },
+      capability: { '*' => ['*'] },
       ttl:        60 * 60 # 1 hour
     }
 
@@ -49,7 +49,7 @@ module Ably::Models
     # @!attribute [r] client_id
     # @return [String] Optional client ID assigned to this token
     def client_id
-      hash.fetch(:client_id)
+      hash[:client_id]
     end
 
     # @!attribute [r] nonce

data/lib/ably/modules/channels_collection.rb

@@ -2,9 +2,6 @@ module Ably::Modules
   # ChannelsCollection module provides common functionality to the Rest and Realtime Channels objects
   # such as #get, #[], #fetch, and #release
   module ChannelsCollection
-    # Initialize a new Channels object
-    #
-    # {self} provides simple accessor methods to access a Channel object
     def initialize(client, channel_klass)
       @client         = client
       @channel_klass  = channel_klass

data/lib/ably/modules/conversions.rb

@@ -12,7 +12,7 @@ module Ably::Modules
       when Numeric
         time
       else
-        raise ArgumentError, "time argument must be a Numeric or Time object"
+        raise ArgumentError, 'time argument must be a Numeric or Time object'
       end.to_i
     end
 
@@ -23,7 +23,7 @@ module Ably::Modules
       when Time
         time
       else
-        raise ArgumentError, "time argument must be a Numeric or Time object"
+        raise ArgumentError, 'time argument must be a Numeric or Time object'
       end
     end
 
@@ -34,7 +34,7 @@ module Ably::Modules
       when :s # seconds
         1.0
       else
-        raise ArgumentError, "invalid granularity"
+        raise ArgumentError, 'invalid granularity'
       end
     end
 

data/lib/ably/modules/encodeable.rb

@@ -0,0 +1,68 @@
+require 'base64'
+
+module Ably::Modules
+  # Provides methods to allow this model's `data` property to be encoded and decoded based on the `encoding` property.
+  #
+  # This module expects the following:
+  # - A #hash method that returns the underlying hash object
+  # - A #set_hash_object(hash) method that updates the underlying hash object
+  # - A #raw_hash_object attribute that returns the original hash used to create this object
+  #
+  module Encodeable
+    # Encode a message using the channel options and register encoders for the client
+    # @param channel [Ably::Realtime::Channel]
+    # @return [void]
+    # @api private
+    def encode(channel)
+      apply_encoders :encode, channel
+    end
+
+    # Decode a message using the channel options and registered encoders for the client
+    # @param channel [Ably::Realtime::Channel]
+    # @return [void]
+    # @api private
+    def decode(channel)
+      apply_encoders :decode, channel
+    end
+
+    # The original encoding of this message when it was received as a raw message from the Ably service
+    # @return [String,nil]
+    # @api private
+    def original_encoding
+      raw_hash_object['encoding']
+    end
+
+    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('/')
+      end
+    end
+
+    def apply_encoders(method, channel)
+      max_encoding_length = 512
+      message_hash = hash.dup
+
+      begin
+        if message_hash[:encoding].to_s.length > max_encoding_length
+          raise Ably::Exceptions::EncoderError("Encoding error, encoding value is too long: '#{message_hash[:encoding]}'", nil, 92100)
+        end
+
+        previous_encoding = message_hash[:encoding]
+        channel.client.encoders.each do |encoder|
+          encoder.send method, message_hash, channel.options
+        end
+      end until previous_encoding == message_hash[:encoding]
+
+      set_hash_object message_hash
+    rescue Ably::Exceptions::CipherError => cipher_error
+      channel.client.logger.error "Encoder error #{cipher_error.code} trying to #{method} message: #{cipher_error.message}"
+      if channel.respond_to?(:trigger)
+        channel.trigger :error, cipher_error
+      else
+        raise cipher_error
+      end
+    end
+  end
+end

data/lib/ably/modules/event_emitter.rb

@@ -42,7 +42,7 @@ module Ably
       #
       # @param [Array<String>] event_names event name
       #
-      # @return <void>
+      # @return [void]
       def on(*event_names, &block)
         event_names.each do |event_name|
           callbacks[callbacks_event_coerced(event_name)] << proc_for_block(block)
@@ -53,7 +53,7 @@ module Ably
       #
       # @param [Array<String>] event_names event name
       #
-      # @return <void>
+      # @return [void]
       def once(*event_names, &block)
         event_names.each do |event_name|
           callbacks[callbacks_event_coerced(event_name)] << proc_for_block(block, delete_once_run: true)
@@ -72,9 +72,15 @@ module Ably
       #
       # @param [Array<String>] event_names event name
       #
-      # @return <void>
+      # @return [void]
       def off(*event_names, &block)
-        event_names.each do |event_name|
+        keys = if event_names.empty?
+          callbacks.keys
+        else
+          event_names
+        end
+
+        keys.each do |event_name|
           if block_given?
             callbacks[callbacks_event_coerced(event_name)].delete_if { |proc_hash| proc_hash[:block] == block }
           else

data/lib/ably/modules/event_machine_helpers.rb

@@ -10,11 +10,13 @@ module Ably::Modules
     #   non_blocking_loop_while(less_than_3) do
     #     x += 1
     #   end
-    def non_blocking_loop_while(lambda, &execution_block)
-      if lambda.call
-        yield
+    def non_blocking_loop_while(lambda_condition, &execution_block)
+      if lambda_condition.call
         EventMachine.next_tick do
-          non_blocking_loop_while(lambda, &execution_block)
+          if lambda_condition.call # ensure condition is still met following #next_tick
+            yield
+            non_blocking_loop_while(lambda_condition, &execution_block)
+          end
         end
       end
     end

data/lib/ably/modules/http_helpers.rb

@@ -1,7 +1,9 @@
 require 'base64'
 
+require 'ably/rest/middleware/encoder'
 require 'ably/rest/middleware/external_exceptions'
 require 'ably/rest/middleware/fail_if_unsupported_mime_type'
+require 'ably/rest/middleware/logger'
 require 'ably/rest/middleware/parse_json'
 require 'ably/rest/middleware/parse_message_pack'
 
@@ -19,14 +21,17 @@ module Ably::Modules
 
     def setup_outgoing_middleware(builder)
       # Convert request params to "www-form-urlencoded"
-      builder.use Faraday::Request::UrlEncoded
+      builder.use Ably::Rest::Middleware::Encoder
     end
 
-    def setup_incoming_middleware(builder, options = {})
+    def setup_incoming_middleware(builder, logger, options = {})
+      builder.use Ably::Rest::Middleware::Logger, logger
+
       # Parse JSON / MsgPack response bodies. ParseJson must be first (default) parsing middleware
       if options[:fail_if_unsupported_mime_type] == true
         builder.use Ably::Rest::Middleware::FailIfUnsupportedMimeType
       end
+
       builder.use Ably::Rest::Middleware::ParseJson
       builder.use Ably::Rest::Middleware::ParseMessagePack
     end

data/lib/ably/modules/model_common.rb

@@ -1,3 +1,5 @@
+require 'base64'
+
 module Ably::Modules
   # Common model functionality shared across many {Ably::Models}
   module ModelCommon

data/lib/ably/modules/state_emitter.rb

@@ -3,6 +3,9 @@ module Ably::Modules
   # the instance variable @state is used exclusively, the {Enum} STATE is defined prior to inclusion of this
   # module, and the class is an {EventEmitter}.  It then emits state changes.
   #
+  # It also ensures the EventEmitter is configured to retrict permitted events to the
+  # the available STATEs and :error.
+  #
   # @example
   #   class Connection
   #     include Ably::Modules::EventEmitter
@@ -54,7 +57,13 @@ module Ably::Modules
 
     private
     def self.included(klass)
-      klass.configure_event_emitter coerce_into: Proc.new { |event| klass::STATE(event) }
+      klass.configure_event_emitter coerce_into: Proc.new { |event|
+        if event == :error
+          :error
+        else
+          klass::STATE(event)
+        end
+      }
 
       klass::STATE.each do |state_predicate|
         klass.instance_eval do

data/lib/ably/realtime.rb

@@ -1,22 +1,29 @@
-require "eventmachine"
-require "websocket/driver"
+require 'eventmachine'
+require 'websocket/driver'
 
-require "ably/modules/event_emitter"
+require 'ably/modules/event_emitter'
 
-require "ably/realtime/channel"
-require "ably/realtime/channels"
-require "ably/realtime/client"
-require "ably/realtime/connection"
-require "ably/realtime/connection/connection_state_machine"
-require "ably/realtime/connection/websocket_transport"
-require "ably/realtime/presence"
+require 'ably/realtime/channel'
+require 'ably/realtime/channels'
+require 'ably/realtime/client'
+require 'ably/realtime/connection'
+require 'ably/realtime/connection/connection_manager'
+require 'ably/realtime/connection/connection_state_machine'
+require 'ably/realtime/connection/websocket_transport'
+require 'ably/realtime/presence'
 
 Dir.glob(File.expand_path("models/*.rb", File.dirname(__FILE__))).each do |file|
   require file
 end
 
-require "ably/realtime/client/incoming_message_dispatcher"
-require "ably/realtime/client/outgoing_message_dispatcher"
+Dir.glob(File.expand_path("realtime/models/*.rb", File.dirname(__FILE__))).each do |file|
+  require file
+end
+
+require 'ably/models/message_encoders/base'
+
+require 'ably/realtime/client/incoming_message_dispatcher'
+require 'ably/realtime/client/outgoing_message_dispatcher'
 
 module Ably
   # Realtime provides the top-level class to be instanced for the Ably Realtime library

data/lib/ably/realtime/channel.rb

@@ -25,6 +25,12 @@ module Ably
     #
     # @!attribute [r] state
     #   @return {Ably::Realtime::Connection::STATE} channel state
+    # @!attribute [r] client
+    #   @return {Ably::Realtime::Client} Ably client associated with this channel
+    # @!attribute [r] name
+    #   @return {String} channel name
+    # @!attribute [r] options
+    #   @return {Hash} channel options configured for this channel, see {#initialize} for channel_options
     #
     class Channel
       include Ably::Modules::Conversions
@@ -49,9 +55,12 @@ module Ably
 
       # 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 future Encryption options
+      # @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
+      #
       def initialize(client, name, channel_options = {})
         @client        = client
         @name          = name
@@ -120,6 +129,7 @@ module Ably
       # to need to call attach explicitly.
       #
       # @yield [Ably::Realtime::Channel] Block is called as soon as this channel is in the Attached state
+      # @return [void]
       #
       def attach(&block)
         if attached?
@@ -136,6 +146,7 @@ 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]
       #
       def detach(&block)
         if detached? || failed?
@@ -172,7 +183,7 @@ module Ably
       # @api private
       def __incoming_msgbus__
         @__incoming_msgbus__ ||= Ably::Util::PubSub.new(
-          coerce_into: Proc.new { |event| Models::ProtocolMessage::ACTION(event) }
+          coerce_into: Proc.new { |event| Ably::Models::ProtocolMessage::ACTION(event) }
         )
       end
 
@@ -181,6 +192,8 @@ module Ably
 
       def setup_event_handlers
         __incoming_msgbus__.subscribe(:message) do |message|
+          message.decode self
+
           subscriptions[:all].each         { |cb| cb.call(message) }
           subscriptions[message.name].each { |cb| cb.call(message) }
         end
@@ -224,18 +237,18 @@ module Ably
 
       def send_messages_within_protocol_message(messages)
         client.connection.send_protocol_message(
-          action:   Models::ProtocolMessage::ACTION.Message.to_i,
+          action:   Ably::Models::ProtocolMessage::ACTION.Message.to_i,
           channel:  name,
           messages: messages
         )
       end
 
       def send_attach_protocol_message
-        send_state_change_protocol_message Models::ProtocolMessage::ACTION.Attach
+        send_state_change_protocol_message Ably::Models::ProtocolMessage::ACTION.Attach
       end
 
       def send_detach_protocol_message
-        send_state_change_protocol_message Models::ProtocolMessage::ACTION.Detach
+        send_state_change_protocol_message Ably::Models::ProtocolMessage::ACTION.Detach
       end
 
       def send_state_change_protocol_message(state)
@@ -246,13 +259,13 @@ module Ably
       end
 
       def create_message(name, data)
-        model = {
-          name: name,
-          data: data
-        }
-        model.merge!(clientId: client.client_id) if client.client_id
+        message = { name: name }
+        message.merge!(data: data) unless data.nil?
+        message.merge!(clientId: client.client_id) if client.client_id
 
-        Models::Message.new(model, nil)
+        Ably::Models::Message.new(message, nil).tap do |message|
+          message.encode self
+        end
       end
 
       def rest_channel

data/lib/ably/realtime/client.rb

@@ -16,6 +16,12 @@ module Ably
     #   @return [Ably::Rest::Client] The {Ably::Rest::Client REST client} instantiated with the same credentials and configuration that is used for all REST operations such as authentication
     # @!attribute [r] echo_messages
     #   @return [Boolean] If false, suppresses messages originating from this connection being echoed back on the same connection.  Defaults to true
+    # @!attribute [r] encoders
+    #   (see Ably::Rest::Client#encoders)
+    # @!attribute [r] protocol
+    #   (see Ably::Rest::Client#protocol)
+    # @!attribute [r] protocol_binary?
+    #   (see Ably::Rest::Client#protocol_binary?)
     class Client
       extend Forwardable
 
@@ -23,8 +29,9 @@ module Ably
 
       attr_reader :channels, :auth, :rest_client, :echo_messages
       def_delegators :auth, :client_id, :auth_options
-      def_delegators :@rest_client, :environment, :use_tls?, :protocol
-      def_delegators :@rest_client, :logger, :log_level
+      def_delegators :@rest_client, :encoders
+      def_delegators :@rest_client, :environment, :use_tls?, :protocol, :protocol_binary?
+      def_delegators :@rest_client, :log_level
       def_delegators :@rest_client, :time, :stats
 
       # Creates a {Ably::Realtime::Client Realtime Client} and configures the {Ably::Auth} object for the connection.
@@ -49,10 +56,11 @@ module Ably
       #    client = Ably::Realtime::Client.new(api_key: 'key.id:secret', client_id: 'john')
       #
       def initialize(options, &auth_block)
-        @rest_client    = Ably::Rest::Client.new(options, &auth_block)
-        @auth           = @rest_client.auth
-        @channels       = Ably::Realtime::Channels.new(self)
-        @echo_messages  = @rest_client.options.fetch(:echo_messages, true) == false ? false : true
+        @rest_client        = Ably::Rest::Client.new(options, &auth_block)
+        @auth               = @rest_client.auth
+        @channels           = Ably::Realtime::Channels.new(self)
+        @echo_messages      = @rest_client.options.fetch(:echo_messages, true) == false ? false : true
+        @custom_socket_host = @rest_client.options[:ws_host]
       end
 
       # Return a {Ably::Realtime::Channel Realtime Channel} for the given name
@@ -84,7 +92,7 @@ module Ably
       def endpoint
         URI::Generic.build(
           scheme: use_tls? ? "wss" : "ws",
-          host:   [environment, DOMAIN].compact.join('-')
+          host:   custom_socket_host || [environment, DOMAIN].compact.join('-')
         )
       end
 
@@ -93,6 +101,22 @@ module Ably
       def connection
         @connection ||= Connection.new(self)
       end
+
+      # @!attribute [r] custom_socket_host
+      # @return [String,nil] Returns the custom socket host that is being used if it was provided with the option :ws_host when the {Client} was created
+      def custom_socket_host
+        @custom_socket_host
+      end
+
+      # (see Ably::Rest::Client#register_encoder)
+      def register_encoder(encoder)
+        rest_client.register_encoder encoder
+      end
+
+      # (see Ably::Rest::Client#logger)
+      def logger
+        @logger ||= Ably::Logger.new(self, log_level, rest_client.logger.custom_logger)
+      end
     end
   end
 end