ably 0.1.5 → 0.1.6

data/lib/ably/models/token.rb

@@ -0,0 +1,74 @@
+module Ably::Models
+  # Authentication token issued by Ably in response to an token request
+  class Token
+    include Ably::Modules::ModelCommon
+
+    DEFAULTS = {
+      capability: { "*" => ["*"] },
+      ttl:        60 * 60 # 1 hour
+    }
+
+    # Buffer in seconds given to the use of a token prior to it being 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
+
+    def initialize(attributes)
+      @hash_object = IdiomaticRubyWrapper(attributes.clone.freeze)
+    end
+
+    # @!attribute [r] id
+    # @return [String] Unique token ID used to authenticate requests
+    def id
+      hash.fetch(:id)
+    end
+
+    # @!attribute [r] key_id
+    # @return [String] Key ID used to create this token
+    def key_id
+      hash.fetch(:key)
+    end
+
+    # @!attribute [r] issued_at
+    # @return [Time] Time the token was issued
+    def issued_at
+      as_time_from_epoch(hash.fetch(:issued_at), granularity: :s)
+    end
+
+    # @!attribute [r] expires_at
+    # @return [Time] Time the token expires
+    def expires_at
+      as_time_from_epoch(hash.fetch(:expires), granularity: :s)
+    end
+
+    # @!attribute [r] capability
+    # @return [Hash] Capabilities assigned to this token
+    def capability
+      hash.fetch(:capability)
+    end
+
+    # @!attribute [r] client_id
+    # @return [String] Optional client ID assigned to this token
+    def client_id
+      hash.fetch(:client_id)
+    end
+
+    # @!attribute [r] nonce
+    # @return [String] unique nonce used to generate Token and ensure token generation cannot be replayed
+    def nonce
+      hash.fetch(:nonce)
+    end
+
+    # Returns true if token is expired or about to expire
+    #
+    # @return [Boolean]
+    def expired?
+      expires_at < Time.now + TOKEN_EXPIRY_BUFFER
+    end
+
+    # @!attribute [r] hash
+    # @return [Hash] Access the token Hash object ruby'fied to use symbolized keys
+    def hash
+      @hash_object
+    end
+  end
+end

data/lib/ably/modules/channels_collection.rb

@@ -0,0 +1,49 @@
+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
+      @channels       = {}
+    end
+
+    # Return a Channel for the given name
+    #
+    # @param name [String] The name of the channel
+    # @param channel_options [Hash] Channel options, currently reserved for Encryption options
+    #
+    # @return Channel
+    def get(name, channel_options = {})
+      @channels[name] ||= channel_klass.new(client, name, channel_options)
+    end
+    alias_method :[], :get
+
+    # Return a Channel for the given name if it exists, else the block will be called.
+    # This method is intentionally similar to {http://ruby-doc.org/core-2.1.3/Hash.html#method-i-fetch Hash#fetch} providing a simple way to check if a channel exists or not without creating one
+    #
+    # @param name [String] The name of the channel
+    #
+    # @yield [options] (optional) if a missing_block is passed to this method and no channel exists matching the name, this block is called
+    # @yieldparam [String] name of the missing channel
+    #
+    # @return Channel
+    def fetch(name, &missing_block)
+      @channels.fetch(name, &missing_block)
+    end
+
+    # Destroy the Channel and releases the associated resources.
+    #
+    # Releasing a Channel is not typically necessary as a channel consumes no resources other than the memory footprint of the
+    # Channel object. Explicitly release channels to free up resources if required
+    def release(channel)
+      @channels.delete(channel)
+    end
+
+    private
+    attr_reader :client, :channel_klass
+  end
+end

data/lib/ably/modules/conversions.rb

@@ -1,4 +1,6 @@
 module Ably::Modules
+  # Conversions module provides common timestamp and variable naming conversions to Ably classes.
+  # All methods are private
   module Conversions
     extend self
 

data/lib/ably/modules/event_emitter.rb

@@ -39,24 +39,47 @@ module Ably
       end
 
       # On receiving an event matching the event_name, call the provided block
-      def on(event_name, &block)
-        callbacks[callbacks_event_coerced(event_name)] << block
+      #
+      # @param [Array<String>] event_names event name
+      #
+      # @return <void>
+      def on(*event_names, &block)
+        event_names.each do |event_name|
+          callbacks[callbacks_event_coerced(event_name)] << proc_for_block(block)
+        end
+      end
+
+      # On receiving an event maching the event_name, call the provided block only once and remove the registered callback
+      #
+      # @param [Array<String>] event_names event name
+      #
+      # @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)
+        end
       end
 
       # Trigger an event with event_name that will in turn call all matching callbacks setup with `on`
       def trigger(event_name, *args)
-        callbacks[callbacks_event_coerced(event_name)].each { |cb| cb.call(*args) }
+        callbacks[callbacks_event_coerced(event_name)].delete_if { |proc_hash| proc_hash[:trigger_proc].call(*args) }
       end
 
       # Remove all callbacks for event_name.
       #
       # If a block is provided, only callbacks matching that block signature will be removed.
       # If block is not provided, all callbacks matching the event_name will be removed.
-      def off(event_name, &block)
-        if block_given?
-          callbacks[callbacks_event_coerced(event_name)].delete(block)
-        else
-          callbacks[callbacks_event_coerced(event_name)].clear
+      #
+      # @param [Array<String>] event_names event name
+      #
+      # @return <void>
+      def off(*event_names, &block)
+        event_names.each do |event_name|
+          if block_given?
+            callbacks[callbacks_event_coerced(event_name)].delete_if { |proc_hash| proc_hash[:block] == block }
+          else
+            callbacks[callbacks_event_coerced(event_name)].clear
+          end
         end
       end
 
@@ -65,6 +88,18 @@ module Ably
         klass.extend ClassMethods
       end
 
+      # Create a Hash with a proc that calls the provided block and returns true if option :delete_once_run is set to true.
+      # #trigger automatically deletes any blocks that return true thus allowing a block to be run once
+      def proc_for_block(block, options = {})
+        {
+          trigger_proc: Proc.new do |*args|
+            block.call *args
+            true if options[:delete_once_run]
+          end,
+          block: block
+        }
+      end
+
       def callbacks
         @callbacks ||= Hash.new { |hash, key| hash[key] = [] }
       end

data/lib/ably/modules/event_machine_helpers.rb

@@ -1,4 +1,5 @@
 module Ably::Modules
+  # EventMachineHelpers module provides common private methods to classes simplifying interaction with EventMachine
   module EventMachineHelpers
     private
 

data/lib/ably/modules/http_helpers.rb

@@ -1,10 +1,12 @@
 require 'base64'
 
 require 'ably/rest/middleware/external_exceptions'
+require 'ably/rest/middleware/fail_if_unsupported_mime_type'
 require 'ably/rest/middleware/parse_json'
 require 'ably/rest/middleware/parse_message_pack'
 
 module Ably::Modules
+  # HttpHelpers provides common private methods to classes to simplify HTTP interactions with Ably
   module HttpHelpers
     protected
     def encode64(text)
@@ -15,11 +17,16 @@ module Ably::Modules
       "Ably Ruby client #{Ably::VERSION} (https://ably.io)"
     end
 
-    def setup_middleware(builder)
+    def setup_outgoing_middleware(builder)
       # Convert request params to "www-form-urlencoded"
       builder.use Faraday::Request::UrlEncoded
+    end
 
-      # Parse JSON / MsgPack response bodies.  ParseJson must be first (default) parsing middleware
+    def setup_incoming_middleware(builder, options = {})
+      # 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/message_pack.rb

@@ -0,0 +1,14 @@
+require 'msgpack'
+
+module Ably::Modules
+  # MessagePack module adds #to_msgpack to the class on the assumption that the class
+  # supports the method #as_json
+  #
+  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
+    end
+  end
+end

data/lib/ably/modules/model_common.rb

@@ -0,0 +1,29 @@
+module Ably::Modules
+  # Common model functionality shared across many {Ably::Models}
+  module ModelCommon
+    include Ably::Modules::Conversions
+    include Ably::Modules::MessagePack
+
+    # Provide a normal Hash accessor to the underlying raw message object
+    #
+    # @return [Object]
+    def [](key)
+      hash[key]
+    end
+
+    def ==(other)
+      other.kind_of?(self.class) &&
+        hash == other.hash
+    end
+
+    # Return a JSON ready object from the underlying #hash using Ably naming conventions for keys
+    def as_json
+      hash.as_json.dup
+    end
+
+    # Stringify the JSON representation of this object from the underlying #hash
+    def to_json(*args)
+      as_json.to_json(*args)
+    end
+  end
+end

data/lib/ably/modules/{state.rb → state_emitter.rb}

@@ -1,7 +1,7 @@
 module Ably::Modules
-  # State module adds a set of generic state related methods to a class on the assumption that
+  # StateEmitter module adds a set of generic state related methods to a class on the assumption that
   # the instance variable @state is used exclusively, the {Enum} STATE is defined prior to inclusion of this
-  # module, and the class is an {EventEmitter}
+  # module, and the class is an {EventEmitter}.  It then emits state changes.
   #
   # @example
   #   class Connection
@@ -12,7 +12,7 @@ module Ably::Modules
   #       :connecting,
   #       :connected
   #     )
-  #     include Ably::Modules::State
+  #     include Ably::Modules::StateEmitter
   #   end
   #
   #   connection = Connection.new
@@ -24,7 +24,7 @@ module Ably::Modules
   #   connection.trigger :invalid        # raises an Exception as only a valid state can be used for EventEmitter
   #   connection.change_state :connected # emits :connected event via EventEmitter, returns STATE.Connected
   #
-  module State
+  module StateEmitter
     # Current state {Ably::Modules::Enum}
     #
     # @return [Symbol] state
@@ -42,11 +42,12 @@ module Ably::Modules
     # Set the current state {Ably::Modules::Enum}
     #
     # @return [Symbol] new state
-    def state=(new_state)
+    # @api private
+    def state=(new_state, *args)
       if state != new_state
-        logger.debug("#{self.class}: State changed from #{state} => #{new_state}") if respond_to?(:logger, true)
+        logger.debug("#{self.class}: StateEmitter changed from #{state} => #{new_state}") if respond_to?(:logger, true)
         @state = STATE(new_state)
-        trigger @state
+        trigger @state, *args
       end
     end
     alias_method :change_state, :state=

data/lib/ably/realtime.rb

@@ -4,22 +4,52 @@ require "websocket/driver"
 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/models/shared"
-require "ably/realtime/models/error_info"
-require "ably/realtime/models/message"
-require "ably/realtime/models/nil_channel"
-require "ably/realtime/models/protocol_message"
+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"
 
 module Ably
+  # Realtime provides the top-level class to be instanced for the Ably Realtime library
+  #
+  # @example
+  #   client = Ably::Realtime.new("xxxxx")
+  #   channel = client.channel("test")
+  #   channel.subscribe do |message|
+  #     message[:name] #=> "greeting"
+  #   end
+  #   channel.publish "greeting", "data"
+  #
   module Realtime
-    def self.new(*args)
-      Ably::Realtime::Client.new(*args)
+    # Convenience method providing an alias to {Ably::Realtime::Client} constructor.
+    #
+    # @param (see Ably::Realtime::Client#initialize)
+    # @option options (see Ably::Realtime::Client#initialize)
+    #
+    # @yield (see Ably::Realtime::Client#initialize)
+    # @yieldparam (see Ably::Realtime::Client#initialize)
+    # @yieldreturn (see Ably::Realtime::Client#initialize)
+    #
+    # @return [Ably::Realtime::Client]
+    #
+    # @example
+    #    # create a new client authenticating with basic auth
+    #    client = Ably::Realtime.new('key.id:secret')
+    #
+    #    # create a new client authenticating with basic auth and a client_id
+    #    client = Ably::Realtime.new(api_key: 'key.id:secret', client_id: 'john')
+    #
+    def self.new(options, &auth_block)
+      Ably::Realtime::Client.new(options, &auth_block)
     end
   end
 end

data/lib/ably/realtime/channel.rb

@@ -40,16 +40,22 @@ module Ably
         :detached,
         :failed
       )
-      include Ably::Modules::State
+      include Ably::Modules::StateEmitter
 
       # Max number of messages to bundle in a single ProtocolMessage
       MAX_PROTOCOL_MESSAGE_BATCH_SIZE = 50
 
-      attr_reader :client, :name
+      attr_reader :client, :name, :options
 
-      def initialize(client, name)
+      # 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
+      def initialize(client, name, channel_options = {})
         @client        = client
         @name          = name
+        @options       = channel_options.clone.freeze
         @subscriptions = Hash.new { |hash, key| hash[key] = [] }
         @queue         = []
         @state         = STATE.Initialized
@@ -59,54 +65,137 @@ module Ably
 
       # Publish a message on the channel
       #
-      # @param event [String] The event name of the message
+      # @param name [String] The event name of the message
       # @param data [String,ByteArray] payload for the message
-      # @yield [Ably::Realtime::Models::Message] On success, will call the block with the {Ably::Realtime::Models::Message}
-      # @return [Ably::Realtime::Models::Message]
-      #
-      def publish(event, data, &callback)
-        Models::Message.new({
-          name: event,
-          data: data,
-          timestamp: as_since_epoch(Time.now),
-          client_id: client.client_id
-        }, nil).tap do |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
+      #
+      # @example
+      #   channel.publish('click', 'body')
+      #
+      #   channel.publish('click', 'body') do |message|
+      #     puts "#{message.name} event received with #{message.data}"
+      #   end
+      #
+      #   channel.publish('click', 'body').errback do |message, error|
+      #     puts "#{message.name} was not received, error #{error.message}"
+      #   end
+      #
+      def publish(name, data, &callback)
+        create_message(name, data).tap do |message|
           message.callback(&callback) if block_given?
           queue_message message
         end
       end
 
-      def subscribe(event = :all, &blk)
-        event = event.to_s unless event == :all
+      # Subscribe to messages matching providing event name, or all messages if event name not provided
+      #
+      # @param name [String] The event name of the message to subscribe to if provided.  Defaults to all events.
+      # @yield [Ably::Models::Message] For each message received, the block is called
+      #
+      def subscribe(name = :all, &blk)
         attach unless attached? || attaching?
-        @subscriptions[event] << blk
+        subscriptions[message_name_key(name)] << blk
       end
 
-      def attach
-        unless attached? || attaching?
-          change_state STATE.Attaching
-          send_attach_protocol_message
+      # Unsubscribe the matching block for messages matching providing event name, or all messages if event name not provided.
+      # If a block is not provided, all subscriptions will be unsubscribed
+      #
+      # @param name [String] The event name of the message to subscribe to if provided.  Defaults to all events.
+      #
+      def unsubscribe(name = :all, &blk)
+        if message_name_key(name) == :all
+          subscriptions.keys
+        else
+          Array(message_name_key(name))
+        end.each do |key|
+          subscriptions[key].delete_if do |block|
+            !block_given? || blk == block
+          end
         end
       end
 
-      def __incoming_protocol_msgbus__
-        @__incoming_protocol_msgbus__ ||= Ably::Util::PubSub.new(
+      # Attach to this channel, and call the block if provided when attached.
+      # Attaching to a channel is implicit in when a message is published or #subscribe is called, so it is uncommon
+      # to need to call attach explicitly.
+      #
+      # @yield [Ably::Realtime::Channel] Block is called as soon as this channel is in the Attached state
+      #
+      def attach(&block)
+        if attached?
+          block.call self if block_given?
+        else
+          once(STATE.Attached) { block.call self } if block_given?
+          if !attaching?
+            change_state STATE.Attaching
+            send_attach_protocol_message
+          end
+        end
+      end
+
+      # 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
+      #
+      def detach(&block)
+        if detached? || failed?
+          block.call self if block_given?
+        else
+          once(STATE.Detached, STATE.Failed) { block.call self } if block_given?
+          if !detaching?
+            change_state STATE.Detaching
+            send_detach_protocol_message
+          end
+        end
+      end
+
+      # Presence object for this Channel.  This controls this client's
+      # presence on the channel and may also be used to obtain presence information
+      # and change events for other members of the channel.
+      #
+      # @return {Ably::Realtime::Presence}
+      #
+      def presence
+        @presence ||= Presence.new(self)
+      end
+
+      # Return the message history of the channel
+      #
+      # @param (see Ably::Rest::Channel#history)
+      # @option options (see Ably::Rest::Channel#history)
+      def history(options = {})
+        rest_channel.history(options)
+      end
+
+      # @!attribute [r] __incoming_msgbus__
+      # @return [Ably::Util::PubSub] Client library internal channel incoming message bus
+      # @api private
+      def __incoming_msgbus__
+        @__incoming_msgbus__ ||= Ably::Util::PubSub.new(
           coerce_into: Proc.new { |event| Models::ProtocolMessage::ACTION(event) }
         )
       end
 
       private
-      attr_reader :queue
+      attr_reader :queue, :subscriptions
 
       def setup_event_handlers
-        __incoming_protocol_msgbus__.subscribe(:message) do |message|
-          @subscriptions[:all].each         { |cb| cb.call(message) }
-          @subscriptions[message.name].each { |cb| cb.call(message) }
+        __incoming_msgbus__.subscribe(:message) do |message|
+          subscriptions[:all].each         { |cb| cb.call(message) }
+          subscriptions[message.name].each { |cb| cb.call(message) }
         end
 
-        on(:attached) do
+        on(STATE.Attached) do
           process_queue
         end
+
+        connection.on(Connection::STATE.Closed) do
+          change_state STATE.Detached
+        end
+
+        connection.on(Connection::STATE.Failed) do
+          change_state STATE.Failed unless detached? || initialized?
+        end
       end
 
       # Queue message and process queue if channel is attached.
@@ -129,7 +218,7 @@ module Ably
       def process_queue
         condition = -> { attached? && messages_in_queue? }
         non_blocking_loop_while(condition) do
-          send_messages_within_protocol_message(queue.shift(MAX_PROTOCOL_MESSAGE_BATCH_SIZE))
+          send_messages_within_protocol_message queue.shift(MAX_PROTOCOL_MESSAGE_BATCH_SIZE)
         end
       end
 
@@ -142,16 +231,50 @@ module Ably
       end
 
       def send_attach_protocol_message
+        send_state_change_protocol_message Models::ProtocolMessage::ACTION.Attach
+      end
+
+      def send_detach_protocol_message
+        send_state_change_protocol_message Models::ProtocolMessage::ACTION.Detach
+      end
+
+      def send_state_change_protocol_message(state)
         client.connection.send_protocol_message(
-          action:  Models::ProtocolMessage::ACTION.Attach.to_i,
+          action:  state.to_i,
           channel: name
         )
       end
 
-      # Used by {Ably::Modules::State} to debug state changes
+      def create_message(name, data)
+        model = {
+          name: name,
+          data: data
+        }
+        model.merge!(clientId: client.client_id) if client.client_id
+
+        Models::Message.new(model, nil)
+      end
+
+      def rest_channel
+        client.rest_client.channel(name)
+      end
+
+      # Used by {Ably::Modules::StateEmitter} to debug state changes
       def logger
         client.logger
       end
+
+      def connection
+        client.connection
+      end
+
+      def message_name_key(name)
+        if name == :all
+          :all
+        else
+          name.to_s
+        end
+      end
     end
   end
 end